The crate map

This page is the reference for the workspace: fifty-three crates under crates/, plus the xtask gate runner. It assumes the architecture overview, which gives the pipeline these crates implement. None of it is needed to write an application — an application names one crate.

The nine layers

A layer is a position in the dependency graph. A crate may depend on crates in the same layer or in a lower layer. It must not depend on a crate in a higher layer.

The names come from xtask/src/new_crate/layer.rs, which is also what cargo xtask new-crate stamps into a new manifest.

Every crate

How a layer is declared

As a comment above the manifest's [dependencies] table. The first line states the layer and its name; a second paragraph states why the crate's dependency list looks the way it does.

[package]
name = "zgui-layout"
version.workspace = true
edition.workspace = true
license.workspace = true

# L4 — engines. External dependencies are inherited: `foo.workspace = true`.
[dependencies]
taffy.workspace = true
zgui-css = { path = "../zgui-css", version = "0.1.0" }

cargo xtask new-crate <name> --layer L4 stamps that manifest and a crate root that already carries #![deny(missing_docs)] and #![forbid(unsafe_code)] (xtask/src/new_crate/template.rs). The layer argument refuses anything outside L0 through L8.

How the rule is checked

cargo xtask ledger runs fourteen checks. It is a gate, not a convention: any violation fails the build, and cargo xtask ledger <name> runs one of them alone.

Three of them hold the crate graph in place.

topo — the direction of every edge

No check parses the layer number. The layer comment is documentation and review discipline. What is enforced mechanically is a finer record: docs/PHASES.md, the build schedule. Each crate is assigned to the earliest phase whose Creates paragraph names it, and a crate may not depend on one that arrives in a later phase (xtask/src/ledger/check/topo.rs).

That is a weaker statement than the layer rule and a stronger one to test against: the schedule is only a schedule if it is buildable in order, and every crate arrives after the crates it needs. A new upward edge is almost always an edge to a crate that arrived later, and it fails here. The edges the architecture cares about most are pinned by name in the two checks below.

Two escape lists, both exact and both short:

• UNSCHEDULED — probe and xtask.
• DRIVEN — five named edges, each from one named crate to one named crate. Four are zgui-runtime to zgui-scroll, zgui-anim, zgui-edit and zgui-a11y: the frame loop is built before the systems it runs, because a system with no loop to run it cannot be tested at all. The fifth is zgui-testkit-view to zgui-edit, because typing is a framework default and a harness that does not perform it passes components that do not work in a window.

The map is parsed out of docs/PHASES.md rather than kept beside it. A second copy of the schedule would drift.

pinned — two lists and one forbidden edge

Most crates may grow a dependency without anyone thinking hard. Two may not.

The view layer is what a different backend is substituted underneath, and it can be substituted only underneath something that cannot see a document, a style engine, a layout engine, a renderer or a window system. One added dependency and that stops being true, silently.

zgui-vocab exists so the view layer and the document can name the same event kinds, roles and states without either depending on the other. A fourth dependency would make it a bridge that carries something, which is a different crate with a different name.

Both lists are pinned across all sections, development dependencies included. A test that reached for a document would be evidence that the seam had stopped being sufficient. The check also names fourteen packages — stylo, taffy, parley, wgpu, vello, winit, zgui-dom, zgui-layout, zgui-style, zgui-render, zgui-scene, zgui-platform and their satellites — that neither crate may see in any section.

The forbidden edge: no crate below zgui-view may name it. Thirteen crates are listed by name as being below it. The temptation is event dispatch. Resolving which listeners an event reaches is a job for the layer that owns hit testing; calling one is a job for the layer above. A crate that named the view layer to call a handler directly would invert the whole graph, in one line that reviews easily.

engines — which crate may name which library

Every external engine is reachable from a bounded, enumerable set of crates, and that table is the architecture (xtask/src/ledger/check/engines.rs). The consequence is that replacing, patching or dropping any one of them is a change to a named set of manifests that can be counted before the work starts.

cargo xtask ledger --self-test aims every check at a planted-violation fixture. A check nobody has ever seen fail is a check nobody should trust.

What the rule buys

It costs real ergonomics. A stage that wants one fact from a stage above it has to be handed that fact rather than fetching it: a new parameter, sometimes a new trait, occasionally a value type invented to sit between two crates that must not see each other. What the repository claims in return, in docs/guide/layering.md:

A backend's next major version reaches one crate. A windowing library that renames its size accessors, splits its lifecycle callbacks and removes its user-event payload touches every crate in a framework that names it directly. Behind zgui-platform it touches zgui-platform-winit and nothing else.

Every stage is testable without the one below it. The style engine is exercised over a document with no layout engine. Layout is exercised with a fixed-metrics text source and no fonts. Paint is exercised with no graphics device. The frame loop is exercised with no display server. None of that is a special test mode.

A second implementation is an implementation, not a fork. There are two platform backends, two vector rasterisers, two text metric sources, and a capture renderer beside the real one. Each exists because the boundary above it names no library.

When the rule is in the way, three moves cover almost every case: invert it (the lower crate declares a trait, the higher crate implements it and hands it in), push the type down (zgui-vocab is exactly this), or add a facade (zgui-css is that for the style engine — sixteen crates read computed styles and exactly one names the engine). A feature flag that turns an upward edge on is not an answer, and neither is a development-only dependency across a seam. Both fail the build.

What is published, and what it promises

Forty-nine of the fifty-three crates publish. Four do not, and each says why in its manifest:

xtask also carries publish = false and is not a member of crates/.

Published is not the same as intended for direct use. The surface an application writes against is zgui and what it re-exports. zgui-testkit-view, zgui-testkit-scene and zgui-platform-headless publish and are meant to be named directly — by a test, in [dev-dependencies]. None of the three is re-exported by zgui; zgui names zgui-platform-headless only in its own development dependencies.

Three rules govern what is visible and what may change.

#[non_exhaustive] where the set is expected to grow without a change in this workspace. Error enums, the reasons a frame did not reach the screen, the answers a host hook may give, and the parity vocabulary. Adding a variant to one of those is a normal consequence of learning something new about a device, a platform or a style engine, and it should not cost a consumer a major version.

It deliberately does not mean the enums that enumerate the framework's own content. PrimitiveKind, Batch and Filter in crates/zgui-scene/src/ carry no such attribute, and the CSS keyword types do not either. Adding a member to one of those is a change that has to be made everywhere in this tree at once, and the compiler refusing every non-exhaustive match is the mechanism that finds those places.

Traits extend the other way. A method added later arrives with a default body, so an existing implementation keeps compiling. HostBinding in zgui-runtime is the worked example: every one of its methods has a do-nothing default.

#[doc(hidden)] on anything that exists only so one crate can reach another. The typestate markers that turn a missing required prop into a named compile error, and the inference markers that let one setter take a literal, a closure or a signal, are mechanism. Nothing is written by hand against them. The macro-expansion roots are the exception and stay visible, because a crate writing views without the umbrella crate over it has to know they exist.

cargo semver-checks against the previous release tag, run as a gate. cargo xtask release runs the lockstep check and then the compatibility gate (xtask/src/release/).

Versions

Every member inherits one version from [workspace.package] and is released with the others. There is no crate at 0.3 while another is at 0.1. A consumer who has zgui 0.1.0 knows exactly which zgui-render is underneath it, and a compatibility matrix between the framework's own crates never comes into existence.

Two things have to hold, and xtask/src/release/lockstep.rs checks both on every run:

• a member writes version.workspace = true rather than spelling a version;
• every non-development dependency on another member carries a version requirement beside its path. A bare path is a fact about one checkout; a package whose dependencies are only paths publishes to no registry at all.

Changing· The workspace is at 0.1.0 and no v* tag exists yet. The compatibility gate reports no baseline rather than passing quietly, because a gate that says "ok" when it did not run is worse than no gate (xtask/src/release/semver.rs).

One dependency

An application normally names zgui and nothing else. The examples package proves that all view, canvas, surface, custom-element, and application APIs are available through the umbrella crate. An application also names zgui-image when it registers encoded image bytes from memory. File-path image sources need only zgui.

The component library obeys the same rule. zgui-ui-tokens, zgui-ui-icons and zgui-ui-primitives each name zgui and nothing else, and zgui-ui names those three and zgui. Anything a component needs, an application author needs too, so a further edge into the framework's own crates would be a hole in the public API rather than a convenience.

crates/zgui/src/lib.rs re-exports each lower crate under a short name:

pub use crate::app::{App, app};
pub use crate::error::Error;

pub use zgui_view_macro::{component, css, slot, style, variants, view};
pub use zgui_elements::expansion;

pub use zgui_atlas as atlas;
pub use zgui_bits as bits;
pub use zgui_canvas as canvas;
pub use zgui_custom as custom;
pub use zgui_elements as elements;
pub use zgui_geom as geom;
pub use zgui_platform as platform;
pub use zgui_reactive as reactive;
pub use zgui_reactive::task;
pub use zgui_render as render;
pub use zgui_runtime as runtime;
pub use zgui_scene as scene;
pub use zgui_text as text;
pub use zgui_wgpu as surface;
#[cfg(feature = "tokio")]
pub use zgui_tokio as tokio;
pub use zgui_view as view;
pub use zgui_vocab as vocab;

zgui::runtime reaches the frame pipeline, zgui::render the renderer contract, zgui::platform the windowing contract. zgui-image is the one direct addition for registered in-memory sources.

zgui::expansion

view! expands to ordinary calls on the view layer and on the element vocabulary. Those calls have to name the crates they come from, and a macro cannot know what the caller called them. So the expansion names exactly one path — ::zgui::expansion::view::… and ::zgui::expansion::elements::… — and zgui offers that root.

The whole of crates/zgui-elements/src/expansion.rs:

/// The element vocabulary.
pub use crate as elements;
/// The view layer.
pub use zgui_view::expansion::view;

Nothing in the module is written by hand. It is public because the generated code says ::zgui::expansion::…, which is what lets a crate that writes views depend on zgui alone rather than on every crate an expansion happens to touch.

A crate writing views with no umbrella over it supplies the root itself:

extern crate zgui_elements as zgui;

zgui-elements and zgui-view each carry an expansion module for that case.

The workspace dependency ledger

Every external dependency is declared once, in [workspace.dependencies] in the root Cargo.toml, and inherited with foo.workspace = true. A version, a feature set and a default-features decision therefore exist in exactly one place in the tree.

cargo xtask ledger versions enforces both halves. A member that spells a version for an external package instead of inheriting it is reported by name, and the workspace declaration itself is checked against the pins below.

Four feature sets that fail silently

cargo xtask ledger versions pins these because getting them wrong produces a wrong answer rather than an error (xtask/src/ledger/check/versions.rs):

stylo, reactive_graph, reactive_stores and any_spawner are pinned to an exact patch release. skrifa may resolve to two copies — the text engine and the vector rasteriser are on different releases — and linebender_resource_handle to exactly one, which is what makes the two font-data types the same type and the glyph bridge free.

Replacing a backend

Each seam names the crate to depend on, the traits to implement, and where the implementation is handed in.

Three notes the source is explicit about.

A platform backend does not implement AppHandler — it calls one. zgui_runtime::Runtime is the implementation, and the driver is handed it boxed. zgui_platform_winit::run is the shipped one, and zgui::app::desktop() returns it.

A renderer with no vector rasteriser attached plans a display list's vector passes, counts them, and composites a scratch nothing ever wrote. That is not an error, not a warning and not a wrong colour, but an empty rectangle where a drawing should be. zgui_render_vector_vello::attach is one call, and every path that opens a renderer makes it.

The umbrella App deliberately does not expose the three text factories. It installs them from zgui::app::Fonts, which serves every window and all three text seams, so a face registered once is visible to all of them. Replacing the text engine wholesale means building through zgui_runtime::App directly.

Feature flags

The whole workspace has five, and every one is off by default.

Features are additive, so naming zgui-testkit-view in [dev-dependencies] turns on zgui-view/stub-backend for that test build. zgui-testkit-scene names zgui-profile/counters as a normal dependency feature, not a development one: the crate exists to read those counters, and a build that compiled them out would make every assertion written against them pass while measuring nothing.

Lints, workspace-wide

[workspace.lints] in the root manifest denies missing_docs and unsafe_code, denies broken intra-doc links, and warns on unreachable_pub and all of clippy. Every member writes [lints] workspace = true.

cargo xtask ledger unsafe requires #![forbid(unsafe_code)] in the crate root of every member outside a six-entry allowlist, and each allowlist entry names what the crate needs unsafe for:

Every hand-written unsafe impl Send or unsafe impl Sync in the workspace must carry a // SAFETY: comment directly above it. A crate that needs unsafe for something not on its row needs a new entry, and the review that comes with it.

Next