Architecture overview
The stages of the zgui pipeline, what one frame does, the design principles behind them, how the crates are layered, and a map of the architecture pages.
This section describes how zgui works inside. You do not need it to write an application, but it explains rules the guide states without justifying them: why a component runs once, why a signal write settles at the end of the frame, and why changing a colour costs less than changing a width.
The pipeline
zgui is retained. It keeps the document, the computed styles, the box tree, the shaped paragraphs, the per-fragment paint recordings and the rendered pixels between frames. Each stage receives a description of what became invalid and rebuilds only that.
zgui-view · zgui-view-macro · zgui-elements · zgui-reactivezgui-domzgui-style · zgui-csszgui-layout (Cephal) · zgui-text · zgui-text-parleyzgui-paintzgui-render · zgui-render-wgpuThe renderer contract, a GPU implementation, and a vector rasteriser.
zgui-platform · zgui-platform-wayland · zgui-platform-winit · zgui-platform-headlessData flows one way. Each stage reads the output of the stage above it and never calls back into it: the paint crate does not depend on the style engine, and the renderer knows nothing about elements.
Three external engines do the heaviest work. Styles are computed by Stylo, text is shaped with Parley, and layout runs on Cephal, a retained, incremental layout engine published on crates.io.
One frame
zgui-runtime runs the pipeline. A frame has these phases, in order:
Accept work. Dispatch queued platform events, fire due timers, advance scrolling and gestures, reconfigure the surface, and sample running animations. Hit testing for an event uses the previous frame's fragments. Between two queued events, reactive work is settled so the second event sees the document changes made by the first.
Settle reactive work. Listeners, timers and completed tasks write signals. A write marks
observers but does not run them. The frame then flushes the reactive graph, runs the script-engine
checkpoint, and applies queued view commands. Effects change the document through the same Dom
seam a view is built with.
Restyle. The style engine visits only elements that owe a restyle and turns each change into work for later stages. A colour change becomes repaint damage. A width change becomes relayout.
Layout. Patch the changed parts of the box tree, then run Cephal over the boxes its scheduler queued. Paragraphs are shaped or re-broken only when their content, style or available width changed. Geometry observations are delivered next; they can trigger at most two more flush-restyle-layout passes. Hit targets under a stationary pointer are updated and the caret is planned.
Paint. Walk the fragments in stacking order. Unchanged fragments replay their recordings; changed ones are recorded again. Everything is culled against the damage rectangles.
Draw. The renderer receives the display list and the damage set and composes into a target it keeps between frames. Pixels outside the damage keep their previous values.
Publish and schedule. Publish the accessibility update, recycle frame-local document data, apply the renderer's pacing information, and call the frame probe with the final window state.
After the frame, the loop parks and uses no CPU until something requests another frame:
- a queued platform event (input, resize, a surface change);
- a wake from another thread, such as a finished task;
- the earliest deadline: an animation, a timer, a held gesture, a paced resize, a caret blink, a held presentation or a renderer retry.
Requests are coalesced, so many requests before the next frame starts cost one frame. Reactive work woken during a frame's flush is settled in that same flush (it polls up to three rounds) instead of scheduling a new frame. The frame covers each phase in detail.
Design principles
Invalidation as obligations
Each node records what it owes: restyle, relayout, repaint, and the subtree variant of each. Each stage clears the obligations it services as it walks, so no stage has to ask globally whether anything changed. Invalidation lists the bits and the propagation rules.
Stage outputs as values
The display list contains no renderer. Elements that cascade to the same result share one computed style. A fragment tree is plain data. Anything that crosses a stage boundary can be printed, compared and asserted on without a device or a window. This is why most of zgui's tests run headless and why testing an application is practical.
Cost proportional to the change
A signal write invalidates only its observers. A restyle visits only elements that owe one. Paint emits only primitives the damage reaches. No stage walks the whole tree every frame.
Wide changes, such as a window resize or a theme switch, still reach many nodes. zgui exposes counters and headless probes so you can measure the cost; the cost model has the numbers.
Windows
The application owns one reactive scope. Each window below it has its own document and its own frame pipeline.
- Signals and application-level contexts are shared across windows.
- Node handles and window-local contexts are tied to one document and cannot be used in another.
- Windows are created and destroyed on an event-loop turn that has a platform context.
- The default graphics setup shares the device and compiled pipelines between windows where the adapter allows it. Window-sized targets, buffers and atlases are per window.
See Windows for the API and The frame for the lifecycle.
Crates by layer
Every crate declares its layer in a # L<n> — … comment at the top of its manifest's dependency
list. A crate may depend on crates in its own layer or a lower one, never a higher one.
cargo xtask ledger layers checks this against the real manifests.
| Layer | Crates | Role |
|---|---|---|
| L0 foundation | zgui-geom, zgui-color, zgui-arena, zgui-interned, zgui-bits, zgui-profile | Coordinate spaces, colour, stable-address storage, interned names, invalidation bits, counters. No policy. |
| L1 contracts | zgui-vocab, zgui-css, zgui-scene, zgui-render, zgui-atlas, zgui-platform, zgui-reactive, zgui-image, zgui-wgsl | Traits and value types the other crates agree on. |
| L2 backends | zgui-render-wgpu, zgui-render-vector-vello, zgui-render-vector-coverage, zgui-platform-wayland, zgui-platform-winit, zgui-platform-headless, zgui-tokio | Implementations of L1 contracts against real libraries. |
| L3 document | zgui-dom | The node arena. Safe to read from many threads while the cascade runs. |
| L4 engines | zgui-style, zgui-layout, zgui-text, zgui-text-style, zgui-text-parley, zgui-paint, zgui-svg, zgui-canvas | The stages that turn a document into a display list. |
| L5 systems | zgui-input, zgui-scroll, zgui-a11y, zgui-anim, zgui-edit | Behaviour over a laid-out document: hit testing and dispatch, scrolling, accessibility, animation, text editing. |
| L6 frontend | zgui-view, zgui-view-dom, zgui-view-macro, zgui-elements, zgui-custom, zgui-shader-macro | How an interface is described: views, macros, the element vocabulary, custom elements. |
| L7 runtime and tooling | zgui-runtime, zgui, zgui-shader, zgui-wgpu, zgui-testkit-scene, zgui-testkit-view, zgui-conformance | The frame pipeline, the umbrella crate, shader and external-texture integration, test instruments. |
| L8 product | zgui-ui, zgui-ui-primitives, zgui-ui-tokens, zgui-ui-icons, zgui-devtools, zgui-bench, zgui-examples | The component library, the inspector, the benchmark harness, example applications. They use only the public API. |
Applications depend on zgui (cargo add zgui), which re-exports what an application needs. An
application that only describes an interface never names another crate.
The experimental Linux console backend (zgui-console, zgui-platform-drm, zgui-drm,
zgui-seat, zgui-evdev, zgui-libinput, zgui-xkb) follows the same layering but is not
published to crates.io. The crate map describes every crate.
Seams
A seam is a trait that separates two parts of the system. These are the ones you are most likely to implement or replace:
| Seam | Crate | What plugs in |
|---|---|---|
Renderer | zgui-render | A device that puts a display list on a screen. |
VectorRaster | zgui-render | A path rasteriser whose output the renderer composites. |
Surface, AppHandler, Clock, Waker, Clipboard | zgui-platform | A windowing system, or none (headless). |
Dom, ViewHost, EventSink | zgui-view | The node tree, the engine that laid it out, and where handler commands go. |
SheetLoader, ReplacedContent, LinkResolver, PresentationalHints | zgui-dom | Behaviour a document language supplies that the document core cannot define. |
FontSource, FontMetricsSource, ParagraphShaper, GlyphRaster | zgui-text | A font engine, or a fixed-metrics stand-in for tests. |
MeasureContent | zgui-layout | Measurement for content layout cannot size itself. |
CustomElement | zgui-custom | A retained widget that measures, places its children and paints its own primitives. |
HostBinding | zgui-runtime | Event, frame and shutdown hooks for an embedded script engine. |
FrameProbe | zgui-runtime | A reader of the window state after each frame. |
Most seams have two implementations in the repository. HostBinding is the exception: zgui ships
only the no-op binding.
Pages in this section
The first three pages cover what every stage shares. The rest follow the pipeline from top to bottom.
| Page | Covers |
|---|---|
| The frame | The frame loop step by step, the reactive flush, observation delivery, parking, wakes, timers and animation pacing. |
| The document | The zgui-dom node arena, the Dom and ViewHost seams, mutation batches, and the document-language seams. |
| Invalidation and damage | The dirty bits, how they propagate and are cleared, how style changes become obligations, and how damage rectangles merge. |
| Reactive internals | Signal storage, subscriptions, the flush, cross-thread wakes, owners and task cancellation. |
| The style engine | How zgui drives Stylo: selector matching, style sharing, the restyle pass and animations. |
| The layout engine | The box tree, Cephal, parallel layout, fragments, the hit index and paint order. |
| The text engine | Fonts, shaping and line breaking, glyph rasterisation, and the text caches. |
| Paint and the scene | How fragments become a display list: primitives, clips, culling, replay, batching and vector routes. |
| The renderer | The Renderer and VectorRaster contracts, the wgpu backend, partial redraw, presentation and atlases. |
| The platform layer | The platform contract and its backends, frame pacing, scale, clipboard, accessibility and IME. |
| The crate map | Every crate, its layer, the dependency checks, and how a release is made. |
Next
Custom shaders and corner shapes
Write WGSL effects with shader!, bind them from CSS or a custom element, and cut squircle and other corner shapes with --zgui-corner-shape.
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.