Mutation ops

Five record types describe every change to the native view tree: create, update, insert, destroy, and set frame. The Reconciler emits them; the view backend from get_backend applies them in one apply_mutations call per commit.

Batched mutation protocol between the reconciler and native backends.

Every commit pass produces an ordered list of small mutation ops referencing integer tags (stable per-view identifiers), and the whole list is applied in a single apply_mutations call. This mirrors React Native's Fabric mounting layer: the diff phase is pure, and the native side sees one coherent transaction per commit.

Why tags instead of view objects?

• The diff phase runs before any native view exists, so ops cannot reference views directly.
• Tags give the native side a stable identity to key its own view registry, event routing, and animation bookkeeping on.
• A flat list of (op, tag, payload) tuples serializes directly into the bridge's transaction envelope, so one commit is one crossing.

Op ordering rules (the reconciler guarantees these):

1. A CreateOp for a tag precedes any other op referencing that tag.
2. InsertOp ops appear after both the parent and child exist.
3. DestroyOp ops are emitted children-first; handlers detach the view from its parent as part of destruction.
4. SetFrameOp ops are only emitted for frames that actually changed since the last layout pass (frame diffing).

Classes:

Name	Description
UnsetType	The explicit absence of a native property, distinct from null.
CreateOp	Create a native view for tag of element type type_name.
UpdateOp	Apply changed_props to the view registered under tag.
InsertOp	Ensure the child view sits at index inside the parent view.
DestroyOp	Release the native view registered under tag.
SetFrameOp	Position and size the view registered under tag.

Attributes:

Name	Type	Description
UNSET		Remove a property and restore its native default on the next commit.
Mutation		Union of every op type carried by a commit transaction.

UNSET module-attribute

UNSET = UnsetType.VALUE

Remove a property and restore its native default on the next commit.

Mutation module-attribute

Mutation = Union[
    CreateOp, UpdateOp, InsertOp, DestroyOp, SetFrameOp
]

Union of every op type carried by a commit transaction.

UnsetType

Bases: Enum

The explicit absence of a native property, distinct from null.

CreateOp dataclass

CreateOp(
    tag: int, type_name: str, props: Dict[str, Any] = dict()
)

Create a native view for tag of element type type_name.

Attributes:

Name	Type	Description
tag	int	Unique integer identity assigned by the reconciler.
type_name	str	Element type name (e.g. "Text").
props	Dict[str, Any]	Initial clean props; callables have already been routed to the EventRegistry and replaced by the _pn_events name set.

UpdateOp dataclass

UpdateOp(tag: int, changed_props: Dict[str, Any] = dict())

Apply changed_props to the view registered under tag.

Removed props are signaled with UNSET. None sets a nullable property to an explicit native null value.

Attributes:

Name	Type	Description
tag	int	Unique integer identity of the target view.
changed_props	Dict[str, Any]	Mapping of modified prop names to their new values. Removed props appear with the UNSET sentinel.

InsertOp dataclass

InsertOp(parent_tag: int, child_tag: int, index: int)

Ensure the child view sits at index inside the parent view.

Handlers must treat this as move-aware: if the child is already attached to the parent at a different position, it is moved rather than duplicated. index is clamped by handlers to the current child count.

Attributes:

Name	Type	Description
parent_tag	int	Integer tag of the container view.
child_tag	int	Integer tag of the child view to insert or move.
index	int	Zero-based insertion index, clamped by handlers to the current child count.

DestroyOp dataclass

DestroyOp(tag: int)

Release the native view registered under tag.

The backend drops its tag record and the native component manager releases platform resources (listeners, timers, image loads) eagerly instead of waiting for GC.

Attributes:

Name	Type	Description
tag	int	Unique integer identity of the view to destroy.

SetFrameOp dataclass

SetFrameOp(
    tag: int,
    x: float,
    y: float,
    width: float,
    height: float,
)

Position and size the view registered under tag.

Coordinates are points relative to the parent's content origin, exactly as computed by the layout engine.

Attributes:

Name	Type	Description
tag	int	Unique integer identity of the target view.
x	float	Horizontal origin offset in points relative to the parent.
y	float	Vertical origin offset in points relative to the parent.
width	float	View width in points.
height	float	View height in points.

frame property

frame: Tuple[float, float, float, float]

Return (x, y, width, height) as a tuple.

Next steps

• See where the callables stripped from these payloads go in Events.
• See how each op is applied to a concrete widget in Native views.
• Read what component managers size themselves against in Platform metrics.
• Read the diffing pass that produces these lists in Reconciliation.