duck.html.components.core.sync

Sync-now module for Lively.

Provides sync_now(), a way for an event handler to push an immediate, diffed update for a single descendant component mid-handler — without waiting for the dispatch loop’s final diff, and without re-rendering or re-diffing the ancestor (e.g. page) that component lives under.

This matters when a handler needs the client to reflect an intermediate state change before later restoring that state for the final VDOM diff (which would otherwise see old == new and skip sending a patch). Rather than force-pushing an update unconditionally, sync_now() diffs the component against its own last checkpoint and sends only real changes, scoped to that component’s subtree.

Module Contents

Classes

Entry	Registry entry for a single indexed VDomNode.
SyncNowState	Lazily-built sync_now state for a single event dispatch.

Functions

flatten_vdom	Recursively index a VDomNode tree by key (component uid).
sync_now	Diff a component against its last checkpoint and push the difference immediately. Scoped to component’s own subtree only.
track_sync_now_checkpoints	Expose the dispatch loop’s pre-handler vdom snapshots to sync_now() calls made from inside the event handler.

Data

_sync_now_state

API

class duck.html.components.core.sync.Entry

Registry entry for a single indexed VDomNode.

Variables:

• node – The indexed node’s last known snapshot.

• parent – The node’s parent in the vdom tree, or None if this node is itself a root (an update_target).

• index – The node’s position in parent.children, or None if this node is a root.

index: Optional[int]

None

node: duck.html.components.core.vdom.VDomNode

None

parent: Optional[duck.html.components.core.vdom.VDomNode]

None

class duck.html.components.core.sync.SyncNowState

Lazily-built sync_now state for a single event dispatch.

Variables:

• old_vdoms – Root checkpoint vdoms keyed by update_target component, as built by the dispatch loop before the handler ran.

• registry – Flattened uid -> Entry index. The flatten walk only runs the first time this is accessed, so handlers that never call sync_now() pay zero indexing cost.

__post_init__()

_build_registry() → dict

Flatten every update_target’s checkpoint vdom into one registry.

old_vdoms: dict

None

registry: duck.utils.lazy.Lazy

‘field(…)’

duck.html.components.core.sync._sync_now_state: contextvars.ContextVar[Optional[duck.html.components.core.sync.SyncNowState]]

‘ContextVar(…)’

duck.html.components.core.sync.flatten_vdom(vdom: duck.html.components.core.vdom.VDomNode, parent: Optional[duck.html.components.core.vdom.VDomNode] = None, index: Optional[int] = None, registry: Optional[dict] = None) → dict

Recursively index a VDomNode tree by key (component uid).

Records each node’s parent VDomNode and its position in the parent’s children list, so a descendant can be diffed and swapped back in without rebuilding the tree it belongs to.

Parameters:

• vdom – The vdom node to index, along with its subtree.

• parent – The node’s parent, or None if root.

• index – The node’s position in parent.children.

• registry – Registry to populate; created if None.

Returns:

Mapping of component uid to Entry.

Return type:

dict

async duck.html.components.core.sync.sync_now(ws, component: HtmlComponent) → None

Diff a component against its last checkpoint and push the difference immediately. Scoped to component’s own subtree only.

Parameters:

• ws – The active lively websocket connection.

• component – The descendant component to sync.

Raises:

ForceUpdateError – If component isn’t a descendant of any update_target for this event, or if called outside an active event handler.

duck.html.components.core.sync.track_sync_now_checkpoints(old_vdoms: dict)

Expose the dispatch loop’s pre-handler vdom snapshots to sync_now() calls made from inside the event handler.

The registry itself is a Lazy — flattening only happens on first access from within sync_now(), not here.