Module node_query 

Host-neutral read side of the dynamic DOM API: query / get_by_id / traversal over the per-tick lumen_core::node::DomIndex snapshot. Host-neutral read side of the dynamic DOM API: selector queries, get_by_id, and traversal over the per-tick [DomIndex] snapshot.

Script hosts and the C-ABI all funnel through these functions. Handles cross the boundary as a packed u64 ([NodeHandle::pack]); candela, whose value type is i32, interns the handle into the process-global side-table instead (see lumen_core::node::intern_node).

Selector matching reuses the cascade matcher in lumen-ir; there is no second selector engine. A query walks each snapshot record’s ancestor chain (root-first) and applies lumen_ir::css::selector_matches. Sibling combinators (+, ~) inherit the matcher’s conservative-fail behavior.

Structs

DomDetails

Snapshot of per-node details plus the cascade inputs computed_style needs. Rebuilt and published by the runtime each tick.

NodeDetail

Per-node detail carried in the snapshot, keyed by packed handle.

NodeQueryResult

Materialized query result: packed handles in document order. Mirrors the Bevy-flavored NodeQuery consumers the host types wrap.

NodeRef

Host-neutral packed node handle. 0 is reserved for “no node”.

Functions

attributes_of_handle

The generic attribute map (attrs with no typed component) published for handle, ordered. Backs the introspection attrs() getter.

build_clone

source.clone_deep(): mint a reserved token for the clone root and the backing ScriptCommand.

build_spawn

create(tag): mint a reserved token and the backing ScriptCommand. Returns (handle, command); the handle is valid for the whole tick.

build_spawn_fragment

Instantiate the fragment key: mint a reserved token for the instance root and the backing ScriptCommand. args binds parameters, children fills slots with nodes that already exist.

closest_entity

Walk from start up the ancestor chain (including start) and return the nearest element matching selector (node.closest(sel)).

dom_details_snapshot

Read the current detail snapshot (cheap Arc clone).

drain_external_dom_commands

Drain all queued external DOM commands (FIFO). Called by the runtime once per tick.

focused_node

document.focused(): the focused node handle, or None.

hovered_node

document.hovered(): the hovered node handle, or None.

node_children

node.children(): packed handles in document order.

node_class_contains

node.class_list().contains(class).

node_closest

node.closest(sel): nearest matching ancestor-or-self, packed handle.

node_computed_style

node.computed_style(prop): the value of prop after the full cascade (stylesheet + inherited + inline). Reflects the last committed tick; an inline write issued this tick is visible next tick (commands apply at drain). Returns None for an unmodeled property or an unknown node.

node_first_child

node.first_child().

node_get_attr

node.get_attr(name). KNOWN attrs resolve from the index (id, class, text); everything else from the generic attribute map.

node_id

node.id(): the node’s stable id, or None.

node_last_child

node.last_child().

node_next

node.next().

node_parent

node.parent().

node_prev

node.prev().

node_style_get

node.style_get(prop): the inline-style override for prop, or None.

node_text

node.text(): the node’s current text content, or None.

node_valid

node.exists() / node_valid(h): whether the handle is present in the current snapshot. The snapshot rebuilds each tick, so a despawned node drops out; this is the read-side liveness check without a live world.

publish_dom_details

Publish a freshly-built detail snapshot for cross-thread readers. The runtime calls this each tick from the same system that publishes the DomIndex.

publish_focus

Publish the current focus / hover targets (packed handles). The runtime calls this each tick.

push_external_dom_command

Enqueue a mutation command from a non-script surface (C-ABI / SDK). Returns false only if the process-global lock is poisoned.

query_entities

Run a selector query against index, returning matched entities in document order. Errors carry the selector parse message.

resolved_attributes

The fully-cascaded Attributes for handle: the element resolved from scratch the way a restyle resolves it, from its tag, classes and id, its place in the live tree, and its own markup and inline-style declarations, which outrank every rule. Shared by computed_style(prop) and the full-map computed_style() introspection getter. Reflects the last committed tick.

run_document

document(): the root element as a packed handle.

run_get_by_id

get_by_id(id): fast id path, packed handle or None.

run_query

query(sel): run against the current snapshot, packed handles.