kithara-ui

Contract reviewed from PR #565, source revision 75dc5f981. This records the documented contract at that revision; it is not a new runtime validation. API and usage · All crates.

What the code cannot say for itself. An entry belongs here only when it is neither expressed by the shape of the code nor pinned by a test: an upstream defect, a version pin with a reason outside this crate, or a boundary that no single file owns. Everything else is in the code, and the code is the contract.

Boundaries

• doc/ defines serialised documents; validate/ checks them. render/ owns the neutral document walk and skin resolution. iced/ and masonry/ own their toolkit hosts; hosts/ holds their shared code, including layout distribution in hosts/solve/. backends/ encodes neutral draw lists.
• Hostless builds with render or vello compile no host code. Host implementation gates sit at module boundaries. A control's mount file separates the shared size data read by Control::size from host-only data; the controls registry names both.
• The mechanisms both hosts share are leaf crates this one composes: the neutral picture is kithara-ui-draw's, shaping is kithara-ui-shaping's, event recognition is kithara-ui-input's, Lottie emission is kithara-ui-lottie's, and photographing and comparing page sets is kithara-ui-capture's, which this crate reaches only under its capture feature.
• render::document owns the compiled-document walk; a host owns only its toolkit tree, measurement, placement, paint replay, and event delivery. A host never re-walks the compiled document and never retains a parallel layout tree. The iced LayoutPreview still walks the document and splits by weight on its own; that is a known defect, #648.
• hosts/solve holds the single layout answer because Masonry cannot express per-child minimums through its native flex protocol. Each host supplies measurement and placement for layout.
• The skin belongs to the application, not to the host that draws it. A document is compiled against a skin, so a host turning to another skin builds its pages again rather than repainting them.
• InternId is valid only within the CompiledUi that produced it. Never persist one in application messages or state; host-facing paths stay owned Strings.
• DrawBuffers belongs to the host through UiConfig, not to the document. A configuration built per compile gives each document an empty pool family and throws the filled one away with the document.

Dependency Constraints

These are facts about our dependencies. They explain code that would otherwise look arbitrary.

• Vello is pinned at 0.6 because masonry 0.4 hands a widget a Scene from that release, and a Scene from another Vello version is an unrelated type. The direct Vello dependency keeps its wgpu feature off; the backend only encodes commands.
• wgpu 26 and 27 coexist on purpose. Masonry brings Vello's wgpu 26 and iced brings wgpu 27. Cargo keeps the majors distinct and deny.toml reports the duplicate as a warning.
• iced 0.14's built-in gradient types are linear-only. IcedBackend::CAPS sets radial_gradient: false, so iced rejects a list holding Paint::Radial; style() answers None rather than substituting a colour that appears nowhere in the document.
• vello#1198 is open. In Vello 0.6, blend layers opened beneath Scene::push_clip_layer - including those used by COLR/CPAL colour glyphs - may compose incorrectly before the outer clip is popped. Vello 0.9 does not resolve it, and the 0.6 pin is required independently. Every Vello clip whose nested tree contains GlyphFace::System text emits one tracing::warn! naming the issue. That warning is the whole mitigation: replacing the clip, narrowing text to outline-only faces, or routing colour text around the clip would each invent a local rendering contract.
• Text dependency constraints — the shared skrifa instance, the Fontique CJK fallback defect on macOS, and embedded face coverage — belong to kithara-ui-shaping.