The document
The zgui-dom node arena, stable addresses, the two sibling chains, interned names, lock-free parallel reads, the Dom and ViewHost seams, mutation batches, removed nodes, and the document-language seams.
The document is the retained node tree that every stage below the view layer reads. It lives in
zgui-dom: one arena of node records, written through batched edits, and safe to read from every
style worker at once while the cascade runs. Views reach it only through the Dom trait.
Document structure
- Document
crates/zgui-dom/src/arena/document.rs- *mut DocumentStore
One heap allocation that never moves.
- DocumentStore
crates/zgui-dom/src/arena/store.rs- ChunkArena<NodeInner>
Node records with stable addresses.
- Vec<NodeKey>
Slot number to the key of its current occupant.
- ClassPool
Every class name, split and interned once.
- IdentTable
Resolves id values to borrowed atoms.
- Vec<Namespace>
Indexed by a one-byte namespace id.
- Columns
Fourteen side tables keyed by NodeKey.
- SharedRwLock
Shared by every sheet in this document.
- HostSeams
The four document-language hooks.
- Cell<OptIndex> root
The document's root element.
- EditState
Write token, poison flag, frame flags, batch scratch.
Document owns the store through a raw pointer, so moving a Document does not move the store.
This matters because every node record holds a back-pointer to its store. With that back-pointer, a
node handle can be a single reference: Node<'doc> wraps a &NodeInner, and everything a style
worker needs (classes, attributes, the shared lock, the host hooks) is reached through it.
Node kinds
NodeKind | Meaning | Matched by selectors | In element order |
|---|---|---|---|
Document | The document node. Always slot zero; its only child is the root element. | no | no |
Element | An element. The only kind selectors match. | yes | yes |
Text | A run of text. The content lives in the text column. | no | no |
Marker | An invisible position holder. | no | no |
A marker records where dynamic content goes before that content exists. Show, For,
Dynamic and Portal each mount a marker where they were written and insert their content next to
it. Markers take part in sibling order but not in element order, so content that appears and
disappears never changes what :nth-child or + match on its neighbours. A hidden element would
not work here: display does not affect selector matching.
The node record
The record is NodeInner (crates/zgui-dom/src/node/inner.rs). Its first 64 bytes are exactly the
fields that selector matching and ancestor walks read, so they fill one cache line. A unit test
asserts that parent sits at offset 64.
| Group | Fields |
|---|---|
| Hot set (first cache line) | store back-pointer, NodeKey, NodeKind, NamespaceId, NodeFlags, ClassSpan, local name, id, interaction-state word, invalidation word |
| Links and ordinals | parent, first/last child, previous/next sibling, previous/next element sibling, first element child, sibling ordinal, child count, two ordinal epochs |
| Engine bookkeeping | dirty-children record, selector flags, bookkeeping bits, post-order counter, per-element style data |
const _: () = assert!(size_of::<NodeInner>() == 168); fixes the record size in release builds.
Every field costs memory on every node, so adding one fails this assertion until the size is
updated deliberately.
Columns
Anything about a node that is not Copy lives in a column: a side table keyed by NodeKey.
crates/zgui-dom/src/arena/columns.rs declares fourteen.
| Column | Storage | Holds |
|---|---|---|
attrs | sparse | attributes other than id and class |
inline_style | sparse | the parsed style attribute |
custom_states | sparse | author-defined states matched by :state(name) |
text | sparse | text content of text nodes |
boxes | sparse | the boxes the node generated |
semantics | sparse | the node's accessibility description |
listeners | sparse | listener registrations (event kind and identity) |
props | sparse | imperative properties, invisible to selectors |
observed | sparse | which measurements are observed and the last delivered values |
anim | sparse | private values of a running cheap animation |
state_mask | sparse | cached interaction-state bits that any active selector could match |
paint_key | dense | identity of everything the painted appearance depends on |
a11y_key | dense | identity of everything the accessible description depends on |
readers | dense | Bloom sets of the custom properties read by the element and its subtree |
Sparse is PagedVec: pages of 1024 entries, each allocated on first write. Dense is
SlotVec: one entry per slot. The choice depends on how many nodes have a value. A dense attribute column would cost its
value size on every node, and crates/zgui-dom/tests/memory.rs asserts that one dense column of the
widest sparse value type costs more than twenty times as much as ten empty sparse columns.
readers lets a custom-property change skip subtrees that never read the changed name; see
the style engine. Drawn outlines (path data, canvas view
transforms) have no column of their own. crates/zgui-dom/src/side/drawing.rs reads them out of the
props column, so every stage asks the same bytes.
listeners and observed hold only registrations and last values. The handler closures and the
delivery channels are reference-counted, so they cannot live in a structure that worker threads
share; the view backend keeps them.
Stable addresses
The document is stored in zgui-arena, which makes three guarantees:
- Addresses never move.
ChunkArena<T>stores values in blocks of 512 (BLOCK_LEN) that are never moved or resized. A&Tstays valid while other values are inserted and removed. - Keys are checked.
Key<T>packs a slot number, a generation and the arena's identity into a non-zerou64. A key to a removed value resolves to nothing, never to the slot's new occupant. - Removal is deferred to the end of the frame.
ChunkArena::removemarks a value dead.ChunkArena::recycle, called once per frame, drops it and frees the slot.
NodeId, the opaque handle a view holds, also keeps the document in its top twelve bits and leaves
the other 52 to the backend. crates/zgui-view-dom/src/id.rs therefore converts between NodeKey
and NodeId without a lookup table: the bits are identical.
Why the cascade needs stable addresses
The style engine matches selectors in parallel, one element per worker. Each worker walks outward
from its element: up to the parent for descendant combinators, back along siblings for +, down for
:empty. Each guarantee covers one part of that:
- A worker holds a
&NodeInnerfor its whole match while other threads read the document. A growableVeccould reallocate and invalidate every such reference. - A node removed during a frame stays readable through its key until the frame ends. The accessibility walk, pending observations and the style engine's record map may still name it.
- A freed slot is not reused until the frame ends, so a slot number cannot change meaning inside a
frame. That is what makes
NodeIndex(four bytes, no generation) safe in per-frame walks.
crates/zgui-dom/tests/workers.rs runs eight threads that each walk one document 64 times, and
checks that the address of a record held by a worker never changes.
Tree links
Every node is on two child lists:
- the plain chain, which contains every child (elements, text and markers);
- the element chain, which contains only element children.
| Field | Chain | Used by |
|---|---|---|
parent | — | ancestor walks, invalidation marking |
first_child, last_child | plain | style traversal, box-tree construction, text collection |
prev_sibling, next_sibling | plain | insertion, removal, paint order |
prev_element, next_element | element | + and ~ |
first_element_child | element | :first-child, :empty, root election |
sibling_ordinal | element | :nth-child and related selectors |
child_count | plain | number of children of any kind |
Both chains are maintained together at insertion and removal, in crates/zgui-dom/src/node/links/.
Deriving the element chain at match time would mean scanning past text nodes for every candidate on
the hottest path in the engine. With the stored chain, each step of + is one pointer read.
use zgui_dom::{Document, NodeKind};
use zgui_interned::{ClassName, ElementName};
let mut document = Document::new();
let root = document.append(document.document_index(), NodeKind::Element, ElementName::new("root"));
let item = document.append(root, NodeKind::Element, ElementName::new("item"));
document.append(root, NodeKind::Text, ElementName::new("#text"));
let last = document.append(root, NodeKind::Element, ElementName::new("item"));
document.set_classes(item, &[ClassName::new("selected")]);
// The element chain skips the text node.
let store = document.store();
assert_eq!(store.core(item).next_element(), Some(last));Sibling positions
:nth-child needs each element's position among its element siblings. Renumbering on every insert
would make building an n-item list quadratic. Instead, a structural change bumps the parent's
ordinal epoch, and DocumentStore::ordinal_of renumbers the child list once, the first time a
position is read afterwards. Always read positions through ordinal_of; the stored number is stale
after any insertion or removal.
Renumbering runs on a shared borrow, so two readers may do it at once. That is safe because it is idempotent: both compute the same numbers, every write is atomic, and the epoch that publishes the result is stored last with release ordering.
Interned names
Interning keeps one shared copy of each string and hands out handles to it. Equal strings get
the same handle, so comparing two names is a pointer comparison regardless of length.
zgui-interned provides the name types every layer above the document uses.
| Type | Names |
|---|---|
ElementName | an element's local name |
AttrName | an attribute's local name |
ClassName | one class in a class list |
Ident | an identifier written in a style sheet |
CustomPropertyName | a custom property, stored without -- |
NamespaceId | a namespace, as a one-byte index |
Atom | the interned string the types above wrap |
Each is eight bytes and Copy. Atom equality is core::ptr::eq. Hash hashes the text rather
than the address, so name-keyed maps iterate in the same order on every run.
Interning is exact and case-sensitive: ElementName::new("DIV") and ElementName::new("div")
differ. A case-insensitive document language should normalise names before interning. Interned
strings are never freed, which is fine for a small, fixed vocabulary and wrong for untrusted text.
zgui-interned does not depend on any style engine. The document converts its names to the style
engine's atom types at its own boundary, in one place.
Name storage in the document
| Name | Stored as | Reason |
|---|---|---|
| local name | a web_atoms::LocalName wrapper, by value in the record | the engine borrows it from the record instead of building an atom per selector test |
| class list | ClassSpan: two u32 offsets into the document's ClassPool | eight bytes, Copy, readable through a plain cell |
id | an Ident, resolved through IdentTable | the record needs Copy; the engine wants a borrowed atom |
| other attributes | a SmallVec in the sparse attrs column | values are strings, and most nodes have none |
class="btn btn-primary large" is split and interned when it is written
(crates/zgui-dom/src/arena/class_pool.rs). The record only holds the range of its names in the
pool, so selector matching never splits strings, allocates or compares characters.
The pool is append-only. So that toggling a class on and off does not grow it forever, the store
keeps an index of every run it has interned and reuses an identical one. tests/memory.rs checks that ten
thousand nodes sharing two class names leave two entries in the pool.
Attribute selectors also see id and class. Node::attr_text answers for them from the record
(the class list joined by single spaces), so [class*=card] and attr(id) read the same values
as .card and #id.
Parallel reads during the cascade
Every field of NodeInner must have one of these shapes, and the compiler checks it:
| Shape | Examples | Why it is safe |
|---|---|---|
| Plain data | back-pointer, key, kind, local name | written only under &mut Document, so a traversal only reads it |
Cell<T> with T: Copy + Sync | links, flags, class span | get is a load and set a store; stores happen only between traversals |
| Atomic | state word, selector flags, sibling ordinal | fields the style engine writes from workers |
RefCell | — | forbidden: borrow updates a non-atomic counter, so two workers reading the same ancestor would race |
The node_inner! macro declares the record and emits one const assertion per field requiring the
CellDisciplined marker trait (crates/zgui-dom/src/node/discipline.rs). A RefCell added to the
record is a compile error on that line. The store makes the matching check on itself:
pub const fn assert_sync<T: Sync>() {}
const _: () = crate::assert_sync::<DocumentStore>();assert_sync is public, so code adding its own side table can make the same assertion.
What this allows:
- The style engine's whole DOM interface (seven traits, all implemented on
Nodeincrates/zgui-dom/src/stylo/) can be called from every worker at once. - Two of those methods write:
insert_selector_flags, which records on an element and its parent that a selector depended on it, and the bookkeeping-bit setters. Both usefetch_or.tests/workers.rshas eight threads each write a distinct flag and checks that every write survives on both nodes. DocumentisSendandSync.
The rule that keeps cell writes out of traversals: no &mut Document may be held across a style
traversal. The frame enforces it. Views build and listeners dispatch through a shared reference; the
restyle and the end-of-frame recycle take the document exclusively when neither is running.
The view-layer seams
The view layer (zgui-view) never touches a node tree directly. It is written against three traits.
Dom
Dom (crates/zgui-view/src/dom/mod.rs) is the node-tree interface. It has 24 small, imperative
methods: create a node, put it somewhere, change one thing about it.
| Group | Methods |
|---|---|
| Create | create_element, create_text, create_marker |
| Structure | insert, detach, parent, is_live, set_text |
| Visible to selectors | set_attribute, set_classes, toggle_class, set_style_text, set_style_property, set_custom_property, set_ui_state, set_custom_state |
| Invisible to selectors | set_property, set_semantics |
| Listeners | add_listener, remove_listener |
| Window anchors | root, overlay_root |
| Reading back | text_content, observe |
An implementation must:
- return
NodeIds that carry its ownDocumentId(a handle from another document is a programming error); - move an already-attached node on
insert, never duplicate it; - leave a node usable after
detach, because views detach and reattach subtrees; - treat
Nonein a setter as "remove"; - answer
is_livewith whether a node still exists (a detached node exists until the document drops it).
Other contract details:
set_ui_stateaccepts only control states that mirror an accessibility property. Hover, focus and active state come from the input system.set_style_propertytakes the property name as&strbecause the backend resolves it against its own property table. Unknown names are dropped with a diagnostic.observedelivers after layout and before paint, so a view that repositions itself from an observation is painted in its final place in the same frame.ObservedisBorderBox(device pixels, window-relative),BorderSize(size only; a node that only moves delivers nothing),ContentSizeorScrollPosition. Only quantities that changed are delivered. Dropping theObservationHandlederegisters.rootexists so a view can listen on the whole document, for example to dismiss a menu on a press outside it.overlay_rootis described below.
| Implementation | Crate | Purpose |
|---|---|---|
DocumentDom | zgui-view-dom | drives a real zgui-dom document |
StubDom | zgui-view | in-memory tree for the view layer's own tests, and a small reference backend |
RecordingDom | zgui-testkit-view | a StubDom that records every change, for transcript assertions |
Views hold the backend as DomHandle, a newtype over Rc<dyn Dom>. Reactive bindings capture one,
because they re-run long after the build that created them returned.
ViewHost
ViewHost (crates/zgui-view/src/host/mod.rs) answers questions that need the laid-out window
rather than the node tree. Its 28 methods cover:
| Area | Methods |
|---|---|
| Geometry | border_box, window_box, scale |
| Scrolling | scroll_position, scroll_to, freeze_scrolling |
| Tree queries | contains, precedes |
| Focus | focus, focused, focusables, focus_move, push_focus_trap, pop_focus_trap, add_window_shortcut, remove_window_shortcut |
| Text entry | is_text_entry, selection, set_selection, select_all, set_value |
| Animation and time | running_animations, schedule, cancel_timer, request_frame_callback, cancel_frame_callback |
| Style sheets | install_stylesheet, remove_stylesheet |
Geometry answers are from the last completed frame. Reading fresh layout during a build cannot be
both correct and cheap; a view that must follow geometry uses Dom::observe. Keeping ViewHost
separate from Dom lets a new backend bring up its node tree first and add layout later.
EventSink
EventSink (crates/zgui-view/src/event/sink.rs) receives the commands a listener issues:
pub trait EventSink {
fn capture_pointer(&mut self, node: NodeId);
fn release_pointer(&mut self, node: NodeId);
fn request_focus(&mut self, node: NodeId);
fn synthesize(&mut self, node: NodeId, event: EventKind);
}Listeners run while the document may be mid-mutation, so commands are queued and carried out after
the current dispatch completes. The runtime implements this trait. Tests implement it to assert on
what a component asked for, or use DiscardCommands to ignore commands.
Node handles
NodeRef (crates/zgui-view/src/node_ref/mod.rs) is the Copy handle a component uses to reach
an element it built. It reads None before the element is built and after its view is gone, never
panicking. Points that matter for the document:
- When an element is dropped it calls
NodeRef::release(node). The handle is unbound only if it still points at that node, so the order in which an old build is dropped and a new one bound does not matter. - A handle whose node the document has already dropped reads as unbound (checked with
Dom::is_live), so no imperative call passes the backend a dead node. contains(other)andis_within(ancestor)test tree containment throughViewHost::contains, andprecedes(other)tests tree order. An unbound handle answersfalse, which is what an outside-press check on a closed overlay needs.
Overlay roots
Each window starts with six nodes, created in crates/zgui-view-dom/src/dom/build.rs through a
normal edit batch:
- #document
- root
The window's root element.
- overlay_root
position: fixed · z-index: 1000 · pointer-events: none- content
data-layer=content · z-index: 10 - popover
data-layer=popover · z-index: 20 - modal
data-layer=modal · z-index: 30 - toast
data-layer=toast · z-index: 40
The user-agent sheet (crates/zgui-style/src/sheets/ua.rs) is written against this exact shape.
Creating the layers up front fixes their order: a toast always paints above a dialog, whichever
opened first.
The overlay root is one stacking context at z-index: 1000, sized to the window. The band values
only order content inside it. An application can still cover all overlays with a higher author
z-index. Layers carry pointer-events: none and their direct children pointer-events: auto, so
an empty band does not swallow input.
OverlayLayer is an ordered enum (Content, Popover, Modal, Toast) whose declaration order
is the paint order. Popover is the default.
A portal leaves a marker where it was written and mounts its content under the layer node:
impl Anchor for PortalState {
fn mount(&mut self, dom: &DomHandle, parent: NodeId, before: Option<NodeId>) {
dom.insert(parent, self.marker, before);
let overlay = dom.overlay_root(self.marker, self.layer);
self.overlay = Some(overlay);
self.content.mount(dom, overlay, None);
}
}The portal's first_node is the marker, so its siblings never see the content.
Mutation batches
Document has two write paths.
- Construction (
append,detached,set_classes,set_id,set_attribute,set_state) writes directly and records nothing. It is for documents nothing has styled yet, such as tests and conformance fixtures.DocumentDomnever uses it. - Editing is for a document that has been styled. Every change also owes bookkeeping for the style engine, and leaving any of it out fails silently. So editing is a single batch API rather than a set of setters. Both paths maintain the two child chains with the same code.
pub fn edit<R>(
&self,
filter: &dyn StyleFilter,
body: impl FnOnce(&mut Edit<'_>) -> R,
) -> Result<R, Poisoned>;edit takes &self because every caller has only a shared reference, including a listener that
edits during a dispatch inside another batch. Three mechanisms in
crates/zgui-dom/src/mutate/edit/session.rs make that sound:
| Mechanism | Effect |
|---|---|
| Single-writer token | The first thread to open a batch owns it. Another thread's attempt panics instead of interleaving. |
| Depth counter held by a guard | A batch opened inside an open one joins it. End-of-batch work runs once, when the outermost batch closes. The guard keeps the counter correct when a body unwinds. |
| Poison flag | A batch body that panicked leaves records that describe neither the old nor the new state. The document then rejects every later batch with Poisoned, instead of silently never updating. |
Poisoning has two refinements:
- A batch opened while the thread is already unwinding (for example by a
Dropimpl running during a panic) does not poison the document when it completes. Only a body that itself panicked does. - On a poisoned document,
DocumentDomturns teardown edits (removing a node, removing a listener) into no-ops instead of panicking. Scopes still dispose their views while a panic unwinds, and a second panic inside that cleanup would abort the process before the first report was printed.
Document::guarded applies the same poisoning to non-batch work, such as a style traversal whose
worker panics.
What one write records
Each Edit method applies a change and the bookkeeping it owes:
- A snapshot, the first time an element changes in a batch. The style engine finds what a change can affect by comparing the element against its previous state. A snapshot holds the old state word and attributes, and marks which of class, id and attributes changed. Whether a snapshot exists is read from the element's own bookkeeping bits, not from the map.
- Marks on the ancestors. The traversal only descends where something below has work.
- A restyle hint saying how much work is needed: re-match this element, re-match its subtree, or skip matching and re-run only the cascade (enough for a custom-property change on the root). Each write records the narrowest hint that is provably sufficient.
- A structural entry when a child list changes. Inserting or removing a child changes what
:nth-child,:empty,+and~match on other children.
Closing a batch
Document::close_batch runs when the outermost batch closes, in a fixed order:
- Expand structural entries into hints for the affected siblings.
- Apply every element's hint.
- Request a frame.
Structural expansion waits for the close so that each parent's child list is renumbered once per
batch, not once per change. That keeps a thousand-row reorder linear. An entry tracks up to four
anchors (the earliest affected child of each change); a fifth anchor degrades it to "every child"
(crates/zgui-dom/src/mutate/structure.rs).
Style filters
StyleFilter tells a batch whether a change can affect any computed style. It is passed to each
edit call rather than stored, because it is answered from a compiled rule set that cannot cross
threads.
| Method | Answers | Default |
|---|---|---|
states_for(element) | interaction-state bits any selector that could match element depends on | all bits |
names_class(class) | whether any selector mentions this class | true |
names_attr(attr) | whether any selector mentions this attribute, or matches attributes without naming one | true |
is_disabled() | whether the answers are unusable this frame because the sheet set just changed | true |
EverythingMatters keeps all defaults: correct, but it filters nothing. A change the filter rejects
is applied without any bookkeeping and never reaches the style engine.
states_for is cached per element in the state_mask column. A document-wide answer would be
useless: some rule styles :hover somewhere, so every hover would take the slow path. The cache
depends on the element's identity and is dropped inside the write that changes it (class, id, or a
move that changes whether it is the root). A sheet-set change drops every cached entry. While
is_disabled holds, the cache is neither read nor written.
From a signal write to the restyle
Joins any batch already open.
Runs once, when the outermost batch closes.
At the restyle stage; the restyle owns the snapshots.
Clears the snapshot bit on every element that had one.
The restyle takes the snapshots (crates/zgui-style/src/driver/snapshots.rs), so a change made
during the restyle starts a new set for the next one. Snapshots are cleared as soon as the restyle
finishes; a leftover snapshot would make the next change compare against the wrong previous state.
Frame bookkeeping
A change requests a frame through EditState. While a frame is running (Document::begin_frame), a
change sets "another frame is owed" instead. The frame calls Document::changes_serviced at the
point where the stages that produce changes (events, timers, reactive flush) end and the stages that
consume them begin (crates/zgui-runtime/src/window/frame.rs). Changes made earlier in the frame are
shown by that same frame and do not cost a second one. Changes made later, such as an observation
handler writing a signal, still schedule another frame.
End of frame
zgui_dom::arena::end_frame drops the subtrees that were removed during the frame and are still
detached, recycles their slots, and frees sparse column pages that no longer hold anything. A subtree
re-inserted before the frame ends (as a keyed list does when it moves a row) is kept.
tests/memory.rs mounts and unmounts a hundred rows two hundred times, then checks that no node from
an ended round remains, the slot high-water mark stopped growing after the first round, and no column
page is still allocated.
Removed nodes
A removed node stays in the arena until end_frame, but it is no longer connected. The runtime
handles such nodes as follows:
| Situation | Behaviour |
|---|---|
| An event was queued for an element that has since been removed (for example, a press that triggered a rebuild before its click dispatched) | The dispatch is dropped; the element's listeners belong to a disposed scope. |
| The focused element is removed | The frame moves focus back to the window, so window shortcuts keep working. |
A NodeRef is bound to the removed element | The element releases the handle when it is dropped; a handle to a node the document dropped reads as unbound. |
| The document is poisoned while views are torn down | Node and listener removals are skipped without a second panic. |
Document-language seams
zgui-dom has no markup language, URL loader, security policy or browsing history. Four traits in
crates/zgui-dom/src/host/ cover the decisions those would make. Each is Send + Sync + 'static
because it is reached from node handles on worker threads, and each has a do-nothing default.
| Seam | Consulted by | Default | Installed with |
|---|---|---|---|
PresentationalHints | the style engine, per restyled element | no hints (NoPresentationalHints) | Document::install_presentational_hints |
LinkResolver | refresh_link_state, on attribute writes | nothing is a link | Document::install_link_resolver |
ReplacedContent | Document::intrinsic_of, for replaced nodes | no intrinsic size | Document::install_replaced_content |
SheetLoader | the sheet parser's @import handling | every request rejected | Document::install_sheet_loader |
SheetLoader — fn load(&self, base: &str, href: &str) -> SheetRequest, where SheetRequest is
Ready(SharedString), Pending or Rejected. Ready continues parsing in the same call, because
imported rules must take the position of the @import. load runs on the parsing thread, never on
a style worker. zgui-style ships EmbeddedSheets and FilesystemSheets.
LinkResolver — is_link(element) and is_visited(element) (default false). These decide
:link, :visited and :any-link. The resolver is consulted when attributes change, not during
matching, and its answer is folded into the element's interaction-state word. The style engine
invalidates :link by comparing state words, so an answer computed only inside the matcher would
leave stale styles. install_link_resolver re-checks every element already in the document.
ReplacedContent — fn intrinsic(&self, id: ReplacedId) -> Intrinsic. A node is replaced when
its record has NodeFlags::IS_REPLACED. Intrinsic has three independent optional fields: size
(CSS pixels), ratio and baseline. A decoded image has a size; a stream may know its ratio first;
a surface with no frame yet has neither. Report only what is known, because layout resolves auto
sizes from whichever fields are present. This seam covers sizing only. Painting replaced content is
a separate scene-side hook keyed by the same ReplacedId, because paint sources hold device
resources that cannot be shared with layout workers.
PresentationalHints — hints_for(element, visited, out) pushes declarations a document
language derives from attributes other than style (HTML's width, bgcolor, align). They
cascade in their own origin, below author rules and above the user-agent origin. zgui has no markup
language, so the default contributing nothing is correct.
The standard app installs only one of these: a ReplacedContent multiplexer
(crates/zgui-runtime/src/window/mod.rs) that merges the image loader's and the surface host's
intrinsic tables. The other three keep their defaults, so @import is rejected unless a lower-level
host installs a sheet loader. Hooks that cannot live in zgui-dom (painting replaced content, custom
element layout and paint, script-engine hooks such as animation-frame callbacks) are installed on
the runtime instead.
Next
Invalidation
The dirty bits a node carries, how they propagate, and how damage rectangles merge.
The style engine
How the traversal uses the snapshots, hints and marks this page produces.
The frame
Where each stage named here runs in the frame loop.
Crate map
Every crate, its layer, and the dependency rules between them.
The frame
The frame loop step by step, what each step reads and writes, the reactive flush, observation delivery, when the loop parks, what wakes it, and the counters to read.
Invalidation and damage
The fifteen dirty bits a node can owe, how marks propagate and walks clear them, how style changes become obligations, and how damage rectangles are collected and merged.