kithara ui

kithara-ui

Contract reviewed from PR #445, source revision e07c17b42. This records that branch contract, not merged release status or 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/ - serde document types and validation. render/ - the iced and Masonry hosts and skin resolution. solve/ - the neutral layout vocabulary and distribution shared by both hosts. backends/ - one module per rasteriser.
• 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.
• solve holds the single layout answer because Masonry cannot express per-child minimums through its native flex protocol. Each host supplies measurement and placement only.
• 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 are the reason for code that would otherwise look arbitrary, and none of them can be read off our own sources.

• 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 has no radial gradient at any layer. IcedBackend::CAPS sets radial_gradient: false, so a list holding Paint::Radial reaches the Vello host only, and 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 and bitmap 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.