Module node 

Node handles and the per-tick DOM index for the dynamic query API.

The read side of the scripting DOM surface (query, get_by_id, traversal) addresses live elements through a NodeHandle: an Entity plus its generation, so a stale handle resolves to nothing instead of aliasing a recycled entity. DomIndex is an immutable per-tick snapshot of the selector-reachable tree that the runtime rebuilds each frame and publishes into a process-shared cache; script hosts and the C-ABI read that snapshot without touching the live world.

Selector matching itself lives in lumen-ir (the cascade matcher) and is driven from lumen-script, which can depend on both this crate and lumen-ir. This module holds only the handle types, the pure snapshot data, and the traversal that needs no selector engine.

Structs

DomIndex

Immutable per-tick snapshot of the selector-reachable element tree. Traversal and get_by_id read this directly; selector queries run in lumen-script over the same records.

DomRecord

One selector-reachable element in a DomIndex snapshot. Positional fields (child_index, sibling_count, doc_order) are computed by DomIndex::build from the hierarchy; callers constructing records leave them at zero.

NodeHandle

Opaque handle to a live element: an Entity plus the generation it carried when the handle was minted. Resolving a handle validates the generation, so a handle to a despawned entity returns None rather than addressing whatever entity later reused that index.

NodeHandles

Side-table mapping small i32 ids to node handles, for script hosts whose value type cannot hold a 64-bit handle (candela’s Value is internally i32). intern is idempotent per entity, so a handle keeps the same id across a tick; the sentinel id 0 means “no node”.

Constants

RESERVED_TOKEN_FLAG

Top bit marking a u64 as a reserved spawn token rather than a packed NodeHandle. A real Entity::to_bits sets this bit only after a single index is recycled ~2^31 times, which does not happen in a UI session; handles are opaque and round-trip only through the provided helpers, per the wire-format contract.

Functions

dom_index_snapshot

Read the current snapshot. Returns a cheap Arc clone so the caller drops the lock immediately. Script hosts and the C-ABI read here; they hold no &World at call time.

intern_node

Intern a handle in the process-global side-table, returning its i32 id. Used by the candela host, whose closures have no &World.

intern_node_raw

Intern any packed handle (real or reserved token) in the process-global side-table, returning its i32 id. Used by the candela host, whose values cannot carry a 64-bit handle.

is_reserved_token

Whether handle is a reserved spawn token (top bit set) rather than a packed live-element handle.

publish_dom_index

Publish a freshly-built snapshot for cross-thread readers. The runtime calls this each tick from build_dom_index, before event dispatch, so a query issued inside a handler sees the current tree.

reserve_node_token

Mint a fresh reserved spawn token. Unique within the process for the life of the run; consumed by the runtime’s command applier, which maps it onto the entity it spawns.

resolve_node

Resolve an i32 id against the process-global side-table.

resolve_node_raw

Resolve an i32 id to its packed bits (real handle or reserved token) against the process-global side-table.