Reconciler¶

Diffs successive virtual trees and applies the smallest set of native mutations that bring the on-screen view tree in line with the new description. The reconciler is platform-agnostic; it talks to native widgets exclusively through the NativeViewRegistry.

Virtual-tree reconciler.

Maintains a tree of VNode objects (each wrapping a native view) and diffs incoming Element trees to apply the minimal set of native mutations.

Supports:

Native elements (type is a string like "Text").
Function components (type is a callable decorated with component). Their hook state is preserved across renders.
Provider elements (type == "__Provider__"), which push and pop context values during tree traversal.
Error boundary elements (type == "__ErrorBoundary__"), which catch exceptions in child subtrees and render a fallback.
Key-based child reconciliation for stable identity across re-renders.
Post-render effect flushing. After each mount or reconcile pass, all queued effects are executed so they see the committed native tree.
Layout pass: after every commit, a parallel LayoutNode tree is built from the committed VNodes and fed through calculate_layout; the resulting per-node frames are applied via the backend's set_frame. The viewport size is supplied by the screen host via set_viewport_size.

Classes:

Name	Description
`VNode`	A mounted `Element` plus its native view.
`Reconciler`	Create, diff, and patch native view trees from `Element` descriptors.

VNode ¶

VNode(element: Element, native_view: Any, children: List[VNode])

A mounted Element plus its native view.

The reconciler walks parallel trees of VNode and incoming Element to compute the minimal set of native mutations.

Attributes:

Name	Type	Description
`element`		The `Element` last rendered into this slot.
`native_view`		The platform-native view (e.g., an Android `View` or an iOS `UIView`). May be `None` for purely virtual wrappers such as providers and error boundaries.
`children`		Ordered list of child `VNode` instances.
`hook_state`	`Any`	The component's `HookState` when the node wraps a function component, otherwise `None`.

Reconciler ¶

Reconciler(backend: Any)

Create, diff, and patch native view trees from Element descriptors.

After each mount or reconcile call the reconciler walks the committed tree and flushes all pending effects so effect callbacks run after native mutations are applied.

Parameters:

Name	Type	Description	Default
`backend`	`Any`	An object implementing the native-view protocol (`create_view`, `update_view`, `add_child`, `remove_child`, `insert_child`). PythonNative ships an Android backend and an iOS backend; tests can pass a mock.	required

Methods:

Name	Description
`mount`	Build native views from `element` and return the root native view.
`reconcile`	Diff `new_element` against the current tree and patch native views.
`set_viewport_size`	Update the viewport size and re-run layout if it changed.
`compute_layout_for_test`	Build and compute a layout tree without touching the backend.

mount ¶

mount(element: Element) -> Any

Build native views from element and return the root native view.

Parameters:

Name	Type	Description	Default
`element`	`Element`	The root `Element` to render.	required

Returns:

Type	Description
`Any`	The platform-native view that represents the root of the
`Any`	mounted tree.

reconcile ¶

reconcile(new_element: Element) -> Any

Diff new_element against the current tree and patch native views.

Parameters:

Name	Type	Description	Default
`new_element`	`Element`	The desired root element after a state change.	required

Returns:

Type	Description
`Any`	The (possibly replaced) root native view.

set_viewport_size ¶

set_viewport_size(width: float, height: float) -> None

Update the viewport size and re-run layout if it changed.

Called by the screen host whenever the platform reports a new container size (Android: onLayoutChange; iOS: viewDidLayoutSubviews). The first call after mount triggers the initial layout pass; subsequent identical sizes are no-ops.

Parameters:

Name	Type	Description	Default
`width`	`float`	Viewport width in points.	required
`height`	`float`	Viewport height in points.	required

compute_layout_for_test ¶

compute_layout_for_test(viewport_width: float, viewport_height: float) -> Optional[LayoutNode]

Build and compute a layout tree without touching the backend.

Test helper that returns the synthetic viewport LayoutNode with all descendants positioned. Returns None if no tree has been mounted yet.

Next steps¶

Read the high-level walkthrough in Reconciliation.
See how native widgets are registered in Native views.