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.
`parent`	`Optional[VNode]`	The owning `VNode`, or `None` for the tree root. Used by local (component-scoped) re-renders to bubble a changed native view up to the nearest native container.
`hook_state`	`Any`	The component's `HookState` when the node wraps a function component, otherwise `None`.
`mounted`	`bool`	`False` once the node has been destroyed, so stale entries in the reconciler's dirty set are skipped.

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.
`root_view`	Return the current root native view, or `None` before mount.
`mark_dirty`	Queue `vnode` (a function component) for a local re-render.
`flush_dirty`	Re-render only the component subtrees marked dirty since the last pass.
`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.

root_view ¶

root_view() -> Any

Return the current root native view, or None before mount.

mark_dirty ¶

mark_dirty(vnode: VNode) -> None

Queue vnode (a function component) for a local re-render.

Called by a component's use_state / use_reducer setter when its own state changes. The node is re-rendered on the next flush_dirty pass, which the screen host schedules. Marking is idempotent and cheap; the actual render is deferred so several setters (e.g. inside batch_updates) coalesce into a single pass.

flush_dirty ¶

flush_dirty() -> Any

Re-render only the component subtrees marked dirty since the last pass.

This is the hot path for state-driven updates: instead of re-running the whole app from the root, each dirty function component re-runs its own body (reusing its HookState) and reconciles just its subtree. Nodes are processed shallowest-first so that when a dirty ancestor's re-render already covers a dirty descendant, the descendant is skipped (its _dirty flag is cleared by the ancestor pass).

Returns:

Type	Description
`Any`	The (possibly replaced) root native view, so the host can
`Any`	re-attach it if the root changed.

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.