│ NodeData { ... } │ 2 │ parent: 1 │ │ NodeData { ... } │ 3 │ parent: 0 │

│ NodeData { ... } │ 4 │ parent: 3 │ "text" │ NodeData { ... } │ └───────────────┘ └──────────────────────┘ ``` Indices into both arrays match. The layout engine traverses by index, not by pointer, and reads from compact arrays whose memory layout it controls. ## Cache hierarchy Layout itself isn't algorithmically hard. It's a tree walk plus a lot of if/else. The expensive part isn't the math; it's pulling each node's properties out of memory. A modern CPU has a tiered memory hierarchy. Cycle counts are approximate but the order of magnitude is right: - **L1 data cache** — 32 to 128 KB per core. ~4 cycles to read. - **L2** — 256 KB to several MB per core. ~12 cycles. - **L3** — 4 to 32 MB shared. ~30 to 60 cycles. Doesn't exist on embedded targets. - **Main RAM** — gigabytes. ~100 to 300 cycles. A full miss costs more than running 100 instructions. Layout reads the same per-node fields once per relayout pass. If the working set fits in L2, the second pass is essentially free. If it spills to RAM, every node fetch stalls the pipeline. The relevant per-node sizes in the layout hot path: ```text NodeHierarchyItem 32 B parent + 3 sibling/child indices StyledNodeState 10 B :hover / :focus / :active per node NodeFlags 4 B contenteditable, tab index, anonymous compact-cache tier 1 8 B display/position/float/etc bit-packed compact-cache tier 2 (hot) 68 B width, height, margin, padding, ... compact-cache tier 2 (cold) 28 B paint-only properties (color, opacity) compact-cache tier 2b (text) 24 B text-related layout per-node total (hot) ~150 B per-node total (warm) ~170 B add cold + text tiers NodeData (cold during layout) 152 B read once for inline CSS, classes ``` For 1,000 nodes the layout-hot working set is ~150 KB. That fits in L2 on every desktop chip and most embedded ones. For 10,000 nodes it's ~1.5 MB, still L2 on a modern Apple/Intel core. For 100,000 nodes it's ~15 MB, which is L3 on desktop and main memory on embedded. The numbers indicate when virtual views, lazy panels, and other ways to keep the rendered subtree small start to matter. See [Virtual Views](dom/virtual-views.md). ## What's in a node Each node is split across the two parallel arrays. `NodeHierarchyItem` carries four indices into the same array — the node's parent, its previous and next siblings, and its last descendant: ```rust,ignore pub struct NodeHierarchyItem { pub parent: usize, // 0 means "no parent" pub previous_sibling: usize, pub next_sibling: usize, pub last_child: usize, // index of last descendant } ``` Because children sit contiguously after their parent in tree order, `data[self_idx ..= last_child]` is the whole subtree rooted at `self_idx`. No pointer-chasing, no recursion needed to copy a subtree. `NodeData` carries everything that defines a single node: ```rust,ignore pub struct NodeData { pub node_type: NodeType, // HTML tag or leaf (Text/Image/Icon/VirtualView) pub callbacks: CoreCallbackDataVec, // event handlers; empty for ~80% of nodes pub style: Css, // inline CSS with implicit :scope, INLINE priority pub flags: NodeFlags, // tab index, contenteditable, anonymous pub accessibility: Option>, // ARIA, only on accessible nodes pub extra: Option>, // attributes, dataset, menus, virtual view, ... } ``` `style: Css` is the same struct the cascade uses everywhere else; inline rules carry their conditions (`:hover`, `:focus`, `@theme dark`, `@os macos`) directly. The two `Option>` fields keep the common case small — a typical paragraph or div pays nothing for the accessibility or extras boxes. About 95% of nodes never trigger the `extra` allocation. ## A function of state It helps to remember what the browser DOM was originally for. In the 1990s, web pages arrived over slow modems as a stream of HTML, and the browser had to render *while* the document was still being received. `document.write` injected new nodes mid-parse; `appendChild`, `removeChild`, and the rest of the mutation API let scripts patch the tree as more bytes arrived. Mutability wasn't a design goal — it was a constraint of streaming over a 14.4k modem. When SPAs took over, the streaming use case mostly went away, but the mutation API stayed. React's contribution was to talk users out of using it: model the UI as a function of state, render the whole tree on every change, and let a reconciler diff old against new. Vue, Solid, Svelte, and Elm all converged on the same shape. The browser's imperative DOM became an implementation detail the framework hid. Azul has no streaming parser to support and no legacy mutation API to preserve, so it makes "UI is a function of state" the rule from the start. The `Dom` returned from `layout()` becomes the framework's copy: 1. A callback returns `Update::RefreshDom`. 2. The framework re-invokes the layout function. 3. A fresh `Dom` is built from the application data. 4. The framework diffs the new tree against the previous one and migrates focus, scroll, dataset, and merge-callback state across matched nodes. There is no handle to the live tree, no `insertChild` / `setAttribute` / mutation observer surface. Removing the mutation API has two payoffs: half the bugs that show up in any non-trivial UI come from "this listener saw stale state because something else mutated the tree first," and a tree the framework *owns* is far easier to lay out incrementally than a tree the application can change at any time. The reconciliation algorithm — what counts as "matching" old and new nodes, what migrates, what fires lifecycle events — is documented in [Reconciliation](dom/reconciliation.md). State that has to survive a tree rebuild (a video decoder, a GL texture, the cursor inside a focused input) doesn't live in the tree shape. It hangs off the node as a dataset. See [Datasets](dom/datasets.md) and [Merge Callbacks](dom/merge-callbacks.md). ## Building DOMs ### The recursive Dom value `Dom` is the form actually constructed in user code: ```rust,ignore pub struct Dom { pub root: NodeData, pub children: DomVec, pub css: CssVec, pub estimated_total_children: usize, } ``` A `Dom` is a subtree: a root `NodeData`, its children, and any component-level stylesheets attached via `.with_component_css(Css)`. The framework flattens the recursive form into the parallel `NodeHierarchyItem` / `NodeData` arrays once, at the start of the cascade. Every builder method on `Dom` (`with_class`, `with_callback`, `with_css`) is a shorthand that delegates to the same method on `self.root`. ### Node constructors Each HTML element has a `Dom::create_()` constructor. Most are `const fn` and don't allocate until a child is added: ```rust,no_run use azul::prelude::*; let _ = Dom::create_div(); let _ = Dom::create_section(); let _ = Dom::create_article(); let _ = Dom::create_main(); let _ = Dom::create_nav(); let _ = Dom::create_header(); let _ = Dom::create_footer(); ``` Text-bearing constructors take a string and wrap a `Text` child inside the element: ```rust,no_run use azul::prelude::*; let _ = Dom::create_h1_with_text("Title"); let _ = Dom::create_h2_with_text("Section"); let _ = Dom::create_p_with_text("A paragraph."); let _ = Dom::create_span_with_text("inline"); let _ = Dom::create_strong_with_text("important"); let _ = Dom::create_code_with_text("println!()"); let _ = Dom::create_text("standalone text node"); ``` `NodeType` (in `core/src/dom.rs`) lists every variant. The set covers all HTML elements plus the SVG subset plus four leaf types: `Text`, `Image`, `Icon`, and `VirtualView`. For elements with non-trivial accessibility surface, the primary constructor takes an a11y struct as a required argument. There's a matching `_no_a11y` variant that opts out explicitly. The longer name on the opt-out is the point: it signals that a11y was skipped on purpose, and it makes the absence visible during code review — the *soft-force* pattern. ```rust use azul::prelude::*; // Primary form: a11y is part of the call signature. let save = Dom::create_button("Save", SmallAriaInfo::label("Save document")); // Explicit opt-out, longer name. let ok = Dom::create_button_no_a11y("OK".into()); ``` Most interactive elements use the generic `SmallAriaInfo` (label, role, description). A few (``, ``, `