Teksilo Documentation

Teksilo is a pure-Rust GUI framework for serious desktop applications: a retained widget tree with SwiftUI-style layout, AccessKit accessibility, and a wgpu renderer.

This site has two layers:

• Widget Catalog — a per-widget discovery page for every shipped widget (its abilities, an example, and a deep link to the full rustdoc API). Start here if you are exploring what Teksilo can draw.
• Reference & design docs — the focused subsystem documents below (layout, styling, events, accessibility, data, …). Start here if you are building.

The catalog pages are generated from the widget source by python3 tools/extract_widget_api.py --md-dir docs/widgets; the same tool prints any widget's API to the terminal (python3 tools/extract_widget_api.py Button).

Architecture & roadmap

• architecture.md — framework-internals reference: scrolling, arena, Canvas API, rendering pipeline, HiDPI, threading, testability, crate dependency graph, design comparisons, open questions. Per-subsystem APIs live in the focused docs below.
• teksilo-milestones.md — the demo-driven milestone roadmap; each milestone produces a runnable example exercising one slice of the architecture.

Widget catalog

• widgets-overview.md — every shipped widget categorized (layout / visual / containers / buttons / inputs / text family / menus / overlays / data-driven / charts / animations / settings) with a one-line description and source-file link. Pair with python3 tools/extract_widget_api.py <Widget…> for the full API surface of any widget.

Authoring widgets

• layout-primitives.md — HStack / VStack / ZStack, Grid, Wrap, MasonryLayout, FormLayout, Switcher, and the size wrappers (Expand, FixedSize, MinSize, MaxSize, AspectRatio, Center, Padding, Spacer, Divider).
• events-and-gestures.md — preview/bubble dispatch, attached handlers (.on_tap, .on_hover, …), on_key_preview, focus_within / hover_within, FocusScope Tab-traversal scopes, gesture recognizers.
• styling-system.md — the four-tier styling ladder (tokens → variants → recipes → style protocols); Theme aggregator, ThemeAppearance, per-widget *Variant enums and *Style traits, per-call vs theme-wide style installation, writing a custom preset.
• reactive-theme.md — Signal<Theme>, role-driven colors (ColorProp, TextStyleProp), reactive switching without rebuild.
• animation.md — Signal<f32>::animate_to, MotionTokens, AnimationSpec builder, the animated wrapper widgets (Fade, Pulse, Crossfade, Scale, Blur, …).
• idle-and-animation.md — the zero-frame rule; how next_timer_deadline() keeps the event loop asleep when nothing is moving.
• accessibility-overrides.md — builder-level .access_* modifiers (label, description, subtree merge/exclude, custom actions, shortcut binding) for the cases widget-emitted a11y misses.
• text-scale.md — the global "grow all text" accessibility setting: the TextScaleControl widget, persistence + startup restore, the effective_theme blanket mechanism, ctx.text_scale / text_scale_signal, the per-engine font_scale for editable text, and the follow_text_scale opt-in/opt-out surfaces (icons, RichTextEditor, scene text).

teksu! DSL & formatting

• teksu-macro-reference.md — user-facing reference for the teksu! block-DSL (parse → IR → builder calls).
• teksu-language-spec-v3.md — design spec with full grammar, structural forms, and worked translations of catalog examples.
• teksilo-fmt.md — cargo teksilo-fmt, the formatter for teksu! blocks (rustfmt skips macro bodies).
• teksilo-fmt-vscode.md — wiring teksilo-fmt-lsp into VS Code for in-editor formatting.

Input, navigation, chrome

• shortcut-intent-action.md — Shortcut / Intent / Action pipeline, #[derive(IntentKind)], rebindable keystrokes via ShortcutRegistry.
• tooltips.md — plain TooltipWidget, registry-driven RichTooltipWidget, sticky-on-dwell promotion, focus-driven a11y promotion, attach helpers.
• toast.md — Toast floating notifications (info / success / warning / error / loading severities, link + button actions, Toast::id update-in-place) + ToastHost queue + persistent NotificationArchiveModel + NotificationLog / bell NotificationCenterButton / NotificationLogDialog UI; TeksiloAppBuilder::install_toast_default() one-line install.
• native-menu.md — declarative MenuModel shared by the in-window MenuBar and the macOS native menu bar (NSMenu); MenuBar::from_model(..).native_on_macos(..), TeksiloAppBuilder::install_native_menu(), reactive checks, ⌘ key equivalents, focus-follows-window.
• web-view.md — embeddable WebView widget (native OS subview on top of wgpu), pluggable WebViewBackend (wry default / Servo additive for Wayland / headless), the dormancy→set_visible activation bridge, JS↔Rust IPC, install_web_view_default().
• drag-and-drop.md — drag payloads, drop targets, hit testing, the three user stories that share the underlying machinery.
• multi-window.md — WindowConfig, signal-driven multi-window orchestration, modal dialogs, restore-from-state.
• title-bar.md — custom widget-level title bar plus the per-OS PlatformTitleBarHost for drag / zoom / close / inset.
• toolbar.md — Toolbar command bar with automatic overflow: actions (priority / always_overflow / toggle), pinned + collapsible custom widgets (overflow_as menu row, overflow_widget live embedded control, the ToolbarOverflow trait), the MenuList-backed chevron menu, display modes / orientation, and the ARIA roving-tabindex pattern.

Data, persistence, telemetry

• data-models.md — ListModel, TreeModel, SelectionModel, CheckedModel / TreeCheckedModel (per-row checkbox state with optional descendant→ancestor tristate aggregation), sort/filter projections; the model layer that sits above the widget tree.
• data-source.md — the ListDataSource / TreeDataSource read-and-command interface every data view talks to: the capability protocol (identity, DnD validation via can_accept/accept_drop, lazy/windowed loading), keyed selection, and how an external source of truth drives a view without a mirror model.
• settings.md — reactive end-to-end persistence: SettingsStore, SettingsFile<T>, MruList<T>, window-state auto save/restore.
• telemetry.md — consent-gated event reporting, the teksilo-collector / Plausible / OTLP adapters, the events.yaml schema pipeline.

Async & concurrency

• async.md — the optional main-thread async executor (teksilo-async): install_async(), ctx.spawn_local(...) / spawn_local_with, spawn_blocking, the async-agnostic on_loop_tick hook, and the teksilo-tokio / teksilo-async-std reactor adapters for awaiting native runtime futures. Off by default; complements the reactive subscribe_event data path.

Specialized widgets

• splitter.md — N-pane Splitter with draggable, collapsible dividers, per-pane stretch, animated collapse (four triggers), a shared serializable SplitterModel, and a Tier-3 SplitterStyle. The building block for DockingLayout.
• docking.md — VS Code-style DockingLayout: a centre slot + four collapsible/splittable/draggable side regions, per-corner ownership, an activity rail, drag-to-dock five-zone overlay, and a cloneable serializable DockingModel with export_state/import_state.
• table-view.md — virtualized TableView and TreeTableView (multi-column, sort/filter, drag-resize, drag-reorder, full keyboard navigation).
• tab-widget.md — TabBar<T> and TabWidget (static + dynamic tabs, Signal<Option<TabId>> selection, pinned tabs, drag reorder, overflow dropdown, horizontal + vertical orientations).
• charts.md — BarChart / LineChart / PieChart (shared axis / palette / legend / tooltip infrastructure).
• teksilo-scene.md — the pannable, zoomable scene viewport (canvases, board layouts, diagram editors), including magnetism (typed snap-and-connect between item anchors).
• teksilo-scene-a11y.md — shaping the accessibility tree of a teksilo-scene viewport, including synthetic magnet nodes and the roving active_descendant keyboard connect flow.

Visuals & resources

• icons-and-resources.md — res!()-embedded SVG / PNG / WebP icons with theme-aware tinting.

Tooling

• inspector.md — teksilo-inspector, the in-app debug surface (Tree / Properties / Accessibility / Theme / Models tabs; picker + bounds overlay; debug-only).

Teksilo Architecture Document

Version: 0.3 — slim refresh Date: May 6, 2026 Author: Cyril Jacquet, with Claude (Anthropic) and Mistral Medium as sounding boards and formatting help. Status: Living reference — framework-internals doc; companion focused docs in this directory own the per-subsystem API surface

Document scope. This document covers the framework-internals topics that have no dedicated home elsewhere: scrolling, arena state, Canvas, rendering pipeline, HiDPI, threading, testability, crate structure, and the comparative-design rationale. Every subsystem with a dedicated reference doc in this directory has been collapsed here to a one-paragraph pointer; section numbers are preserved so external links by §N and heading-slug anchors continue to resolve.

If you are looking for how to use a subsystem, the focused doc is the right entry point. Read this doc when you are debugging the engine, porting to a new platform, writing a custom widget that needs the Canvas escape hatch, or onboarding to maintain the framework itself.

Where the per-subsystem references live:

• Layout: layout-primitives.md
• Events / gestures / focus / DnD lifecycle: events-and-gestures.md
• Animation: animation.md
• Idle / zero-frame rule: idle-and-animation.md
• Reactivity & theming: reactive-theme.md
• Shortcuts / intents / actions: shortcut-intent-action.md
• i18n: i18n.md
• Accessibility overrides: accessibility-overrides.md
• Drag and drop: drag-and-drop.md
• Data models: data-models.md
• Settings and persistence: settings.md
• Telemetry: telemetry.md
• Multi-window: multi-window.md
• Custom title bar: title-bar.md
• Tooltips and overlays: tooltips.md
• teksu! DSL: teksu-macro-reference.md, teksu-language-spec-v3.md
• Inspector: inspector.md
• Widget catalog snapshot: teksilo-milestones.md, tools/extract_widget_api.py --all
• Per-widget reference docs: table-view.md, tab-widget.md, charts.md, teksilo-scene.md

1. Vision and Positioning

Teksilo is a pure-Rust GUI framework for serious desktop applications — the kind of software where a user sits down for hours at a time and reaches for the keyboard first. A writing tool for novelists, an IDE, a dispatch console, a course manager for a taxi company's driver training. Teksilo is infrastructure for professional desktop software that needs native look and feel, full keyboard and screen-reader accessibility, and a rich text surface built from the ground up.

Teksilo's thesis rests on three pillars. First, accessibility is a structural requirement, not an afterthought — AccessKit is integrated at the trait level, not bolted on. Second, rich text is a first-class concern — the text-document and text-typeset crates provide a complete document model and typesetting engine covering shaping, bidi, line-breaking, and atlas rasterization. Third, the framework is designed to be consumed by applications with structured architecture (Clean Architecture, MVVM), providing a typed Shortcut / Intent / Action pipeline and reactive data-model crate (teksilo-data) rather than leaving application structure as an exercise for the developer.

1.1 Relationship to structured application architectures

Teksilo is the outermost layer of an application — the "Frameworks & UI" ring in Clean Architecture's concentric circles. It has no dependency on any particular application framework. A Qleany-structured application is one supported integration path and was the stress test that shaped several of Teksilo's architectural choices (typed intents for command flow, view-models over raw entities, data sources for paged external collections), but nothing in Teksilo requires Qleany.

The integration surface is the typed intent system (Teksilo widgets emit application-defined intent variants that ancestor Actions consume — see shortcut-intent-action.md) and the reactive data models in teksilo-data (application-written view-models hold entity collections as ListModel<EntityVM> / TreeModel<EntityVM> that widgets bind to — see data-models.md).

Teksilo splits internally into focused crates (see §25) each with a single concern, rather than imposing a Clean-Architecture split on its own internals. Layout, rendering, and event dispatch have fundamentally different performance characteristics from transactional domain operations; the useful seams fall in different places.

1.2 Reuse Strategy

Teksilo builds on established crates rather than reinventing solved problems. winit for windowing and HiDPI; wgpu for GPU rendering; text-document + text-typeset for the rich text model and typesetting (harfrust shaping, swash rasterization, etagere atlas, unicode-linebreak, unicode-bidi); AccessKit for cross-platform a11y; fluent-rs for i18n; tiny-skia for Tier 3 path rasterization.

2. Layout Model

Full reference: layout-primitives.md. The protocol is SwiftUI-style negotiation — the parent proposes a size, the child responds with LayoutResponse { size, flex, min, shrink }, the parent decides the main axis (grow via flex, shrink via shrink/min), measures the cross axis at each child's final main size (height-for-width), and places. Slack distribution, the shrink/over-constraint model, the Shrinkable wrapper, zero-basis vs respect_intrinsic, container/per-child alignment, and the size-wrapper primitives (Expand, Shrinkable, FixedSize, MinSize, MaxSize, Center, Padding, Spacer, Divider) all live there. A per-pass memoization cache (WidgetArena::cached_layout_response, keyed (id, proposal), cleared each pass) keeps the main-then-cross queries O(n); widgets that mutate state in layout_response opt out via Widget::cacheable_layout() -> false.

What's not in the focused doc and stays here:

2.1 Binding Levels and Dirty Propagation

Some property changes affect only a widget's visual appearance (a color change). Others affect the widget's size (a text change, a constraint change). The binding system distinguishes these two cases because they trigger different dirty-tracking responses.

Repaint-level bindings (color, background, border_color) mark the widget for repaint only when the bound state changes. The layout pass is skipped — the widget's position and size are unchanged. This is the fast path, used for interaction-driven visual state changes (hover color, pressed color, enabled/disabled appearance).

Relayout-level bindings (text, width, height, min_width, max_height) mark the widget for relayout when the bound state changes. The layout pass reruns on the affected subtree, and the dirty flag propagates upward to ancestors because a child's size change may affect its parent's size, which may affect the grandparent's size, and so on. Propagation stops at an ancestor whose own size is not affected by its children (for example, a FixedSize wrapper with a static width).

The classification is determined by the primitive widget's binding method implementation, not by the consumer. A TextWidget implementor knows that text is relayout-level because changing the text changes the widget's layout_response result. A composite widget author or application developer does not need to think about this distinction — they call text(state) and the framework handles the rest.

Layout utility widgets with dynamic constraints. The size constraint widgets (MinSize, MaxSize, FixedSize) accept state bindings for their constraint values, enabling dynamic resizing from application state changes, user-driven splitter interactions, or animation ticks. FixedSize::width(state) registers a relayout-level binding — when the state changes, the widget's constraint changes, triggering relayout of the affected subtree.

Relayout propagation. When a widget is marked for relayout, the framework marks the widget and all its ancestors up to the root as needing relayout. During the layout pass, it starts from the highest dirty ancestor and works downward, re-running layout_response and place_children for each dirty node. Clean subtrees are skipped. This is the same incremental layout approach used by web browsers and by Qt's layout system. A relayout always implies a repaint for the affected widgets.

3. Scrolling and Viewports

A scroll area is a container whose content may be larger than the visible space. The scroll area acts as a viewport — a window into a potentially large content region. Only the visible portion of the content is rendered, clipped to the viewport boundary.

Scrolling is designed to require minimal changes to the framework. The scroll offset is encoded through the existing layout placement mechanism, not as a separate coordinate transformation layer. Hit testing, event dispatch, and the state system require no modifications. The changes are confined to the arena (one new flag), the paint pass (clip rect support), the renderer (scissor rects), focus management (scroll-into-view), and the scroll area widget itself.

3.1 Layout: Unbounded Proposals and Offset Placement

A scroll area participates in layout like any other container widget. In layout_response, it claims the space its parent offers — this becomes the viewport size. In place_children, it proposes an unbounded size on the scroll axis to its content child. For a vertical scroll area, the content receives SizeProposal { width: Some(viewport_width), height: None } — "use the viewport width, but be as tall as you need." The content child responds with its natural height (potentially thousands of logical pixels).

The scroll area then positions its content child at (viewport.x, viewport.y - scroll_offset.y). This encodes the scroll offset as a position offset within the normal placement system. No special coordinate transformation infrastructure is needed — the existing place_children / WidgetPlacement mechanism handles it. The recursive layout function processes the content child and its descendants with the offset origin, and all bounds stored in the arena end up in correct screen-space positions.

SizeProposal already supports None values for unbounded dimensions. No changes to the SizeProposal type or to layout_widget_recursive are required.

3.2 Hit Testing: No Changes Required

The existing hit_test_recursive provides viewport clipping implicitly. It checks bounds.contains(point) on the parent before recursing into children. A point outside the scroll area's viewport bounds is rejected at the scroll area's bounds check, and no child is tested. Children scrolled above the viewport have negative screen-space y coordinates that no in-viewport point would match. Children within the viewport have correct screen-space bounds (computed from the offset placement) that match pointer positions directly.

No changes to the hit testing code are needed. The scroll offset encoded in placement positions and the existing parent-bounds containment check together provide correct viewport-clipped hit testing.

3.3 Clipping in the Paint Pass

The paint pass requires one new capability: clipping child rendering output to the scroll area's viewport bounds. Without clipping, children positioned near the edge of the viewport would render partially outside it.

The arena's WidgetNode gains a clips_children: bool flag (default false). The scroll area widget sets this flag to true on its own arena node. When paint_widget enters a node with clips_children: true, it pushes a clip rect (the node's own bounds, which represent the viewport) onto the Canvas before recursing into children, and clears the clip after all children are painted.

The Canvas already provides set_clip(Rect) and clear_clip() methods that produce DrawCommand::SetClip and DrawCommand::ClearClip entries in the RenderFrame. The change to paint_widget is approximately five lines: check the flag, push clip, recurse, pop clip.

3.4 Renderer: Scissor Rect Implementation

The SetClip and ClearClip draw commands exist in the RenderFrame but are currently no-ops in the renderer. The implementation maps directly to wgpu's scissor rect API: render_pass.set_scissor_rect(x, y, width, height) for SetClip (coordinates in physical pixels, multiplied by scale factor), and resetting the scissor to the full surface dimensions for ClearClip. This is approximately ten lines of code in the renderer.

Nested scroll areas (rare but valid — a scrollable sidebar inside a scrollable page) require a clip rect stack. Each SetClip pushes a rect, and the effective clip is the intersection of all rects in the stack. ClearClip pops the top rect and restores the previous intersection.

3.5 Focus and Scroll-Into-View

When Tab navigation moves focus to a widget that is inside a scroll area but outside the current viewport, the scroll area must scroll to make the focused widget visible. Without this, keyboard users cannot see what they have focused.

After focus_with_origin sets focus to a widget, the framework walks up the ancestor chain. If any ancestor has clips_children: true, the framework checks whether the focused widget's bounds are fully within that ancestor's viewport bounds. If not, the framework dispatches a WidgetEvent::ScrollIntoView { target_bounds: Rect } to the clipping ancestor. The scroll area handles this event by adjusting its scroll offset to bring the target bounds into view, using the minimum scroll change needed to make the widget fully visible (or centering it if the widget is larger than the viewport).

3.6 The ScrollBar Widget

The scroll bar is a standalone Level 2 widget in teksilo-widgets, not a rendering detail inside ScrollArea. A standalone widget participates in the framework's hit testing, event dispatch, focus, and accessibility systems. Its thumb is a region within its bounds that the framework's existing pointer routing handles. Its accessibility node declares Role::ScrollBar with set_numeric_value, set_min_numeric_value, set_max_numeric_value, and Action::SetValue.

The ScrollBar stores the current scroll position and the content-to-viewport ratio (both provided by the ScrollArea via shared Signal<f32>). It computes thumb position and size from these values. It handles PointerDown on the thumb (start drag), PointerMove during drag (update position), PointerUp (end drag), and PointerDown on the track (page-scroll toward click position). It supports both vertical and horizontal orientations.

3.7 ScrollArea and ScrollBar Interaction

The ScrollArea owns the scroll state (Signal<f32> for each axis). The ScrollBar reads from and writes to this shared state. The ScrollArea and ScrollBar communicate through the reactive binding system, not through events or callbacks.

The ScrollArea supports two scroll bar display modes via ScrollBarStyle.

Overlay mode (default, matching macOS and modern Linux). The ScrollArea's viewport occupies the full available width — the scroll bar does not reduce the content area. A thin passive scroll indicator (a few semi-transparent pixels at the trailing edge) is painted directly by the ScrollArea during scrolling as a visual hint. When the pointer enters the scroll bar activation zone (a region at the trailing edge wider than the thin indicator), the ScrollArea shows the full interactive ScrollBar widget as an overlay using the existing overlay system (OverlayPlacement::NearAnchor, DismissBehavior::PointerLeave). The overlay ScrollBar appears on top of the content, receives pointer events for thumb drag and track click, and dismisses when the pointer leaves. The viewport width never changes. The transition from thin indicator to full scroll bar can be animated using the animation scheduler.

Permanent mode (matching traditional Windows/GTK style, or when the user's accessibility preferences request always-visible scroll bars). The ScrollBar is a layout sibling of the content viewport. The ScrollArea's internal structure becomes an HStack of [clipping viewport] + [ScrollBar]. The viewport is narrower by the scroll bar's width. The scroll bar is always visible and always interactive. The viewport width is constant (reduced by the scroll bar width but never changing dynamically).

The mode is selected via ScrollArea::new(content).scroll_bar_style(ScrollBarStyle::Overlay) or ScrollBarStyle::Permanent. The application or the theme can set a default. An accessibility preference for "always show scroll bars" overrides to Permanent mode.

3.8 The Scroll Area Widget

The ScrollArea is a Level 2 (Widget trait) widget in teksilo-widgets. It is the viewport container — it owns the clipping behavior, the layout negotiation with unbounded proposals, and the content offset placement described in Sections 3.1–3.5.

The scroll offset for each axis is stored as a Signal<f32> (not a raw Vec2), because the ScrollBar widget needs to read and write the position through the reactive binding system. When the ScrollBar's thumb is dragged, it sets the shared Signal<f32>. The ScrollArea's binding on that state triggers a relayout, which re-runs place_children with the updated offset. When the user scrolls via mouse wheel or trackpad (WidgetEvent::Scroll), the ScrollArea updates the Signal<f32> directly, and the ScrollBar's thumb position updates via the same binding path.

The ScrollArea creates and manages a ScrollBar widget according to the active ScrollBarStyle (Section 3.7). In overlay mode, the ScrollArea paints a thin passive indicator during its own paint() pass and shows the interactive ScrollBar as an overlay on pointer proximity. In permanent mode, the ScrollBar is a layout child positioned as a sibling of the content viewport. The ScrollArea sets clips_children: true on its arena node so the paint pass clips content to the viewport bounds.

The ScrollArea handles WidgetEvent::ScrollIntoView to support focus-driven scrolling (Section 3.5) — it adjusts the Signal<f32> offset to bring the target bounds into view.

For accessibility, the ScrollArea declares Role::ScrollView with scroll position properties (set_scroll_x, set_scroll_y and their min/max ranges) and page-level scroll actions (Action::ScrollDown, Action::ScrollUp, Action::ScrollLeft, Action::ScrollRight). The ScrollBar declares its own Role::ScrollBar with set_numeric_value, set_orientation, and Action::SetValue for direct position control. These are two separate AccessKit nodes with complementary roles.

3.9 Interaction with Virtualized Lists

The ListView widget (backed by ListModel<T> or ListDataSource) depends on scrolling. The scroll offset determines which items are visible. The ListView only instantiates widget subtrees in the arena for visible items plus a small buffer above and below the viewport. As the user scrolls, items leaving the viewport have their subtrees destroyed and items entering the viewport have new subtrees created.

The ListView does not need a general-purpose "scroll area wrapper" — it implements the scrolling behavior internally, because it needs tight control over which items have widget subtrees. It uses the same mechanisms as the scroll area (offset placement, clips_children: true, WidgetEvent::Scroll handling) but also manages the item lifecycle in the arena.

3.10 Accessibility for Scroll Areas and Lists

The scroll system produces two AccessKit nodes with complementary roles. The ScrollArea declares Role::ScrollView with scroll position properties (set_scroll_x, set_scroll_y and their min/max ranges), set_clips_children(true), and page-level scroll actions (Action::ScrollUp, Action::ScrollDown, Action::ScrollLeft, Action::ScrollRight). The ScrollBar declares Role::ScrollBar with set_numeric_value (the current scroll position), set_min_numeric_value, set_max_numeric_value, set_orientation, and Action::SetValue for direct position control by assistive technologies. Screen readers use the ScrollView node to announce the scrollable region and the ScrollBar node to present the scroll position as an adjustable value.

For lists, AccessKit provides Role::List with Role::ListItem for static lists, and Role::ListBox with Role::ListBoxOption for interactive selectable lists. The critical properties for virtualized lists are set_position_in_set(index) on each visible item and set_size_of_set(total_count) on the list container. These tell screen readers the logical position of each item ("item 5 of 200") even when the AccessKit tree only contains the items currently visible in the viewport. Items outside the viewport do not exist in the arena and therefore do not appear in the AccessKit tree — no special mechanism is needed to exclude them.

4. Widget State Ownership

Teksilo uses a retained widget tree with arena-backed flat storage, following the approach proven by Masonry's TreeArena.

All widgets live in a flat SlotMap-like arena. Parent-child relationships are stored as ID references within the arena. The tree structure is explicit (unlike a pure ECS where relationships are implicit), but the flat storage avoids Rust's borrow-checker challenges with recursive mutable tree traversal.

The framework processes the tree through well-defined passes (event, layout, accessibility, paint), each of which traverses the arena without holding multiple mutable references simultaneously. This is the key insight from Masonry: separate the passes so that no pass needs to mutate a widget while reading another widget's state.

5. Widget Extensibility

The unified Widget trait has a single build(&mut self, ctx) for composition, a single paint() for own-visuals, and both are optional with sensible defaults. Leaf widgets implement layout_response + paint; container widgets implement layout_response + place_children + children; composing widgets implement build + layout_response (delegating to the child); hybrid widgets (Card, ScrollArea) implement build + paint. Reference: CLAUDE.md "Unified Widget Trait" and crates/teksilo-widgets/src/button.rs.

5.1 The Slot System

Standard widgets ship with named extension points — slots — at structural boundaries where extension is anticipated. A slot is an optional placeholder that takes zero space when empty and accommodates arbitrary widget content when filled. Slots are part of a widget's public API contract; standard composites in teksilo-widgets ship with leading_slot, trailing_slot, header_slot, footer_slot at positions where extension is commonly needed.

#![allow(unused)]
fn main() {
TabWidget::new()
    .tab("Chapter 1", || chapter_editor(1))
    .trailing_slot(|ctx| {
        HStack::new()
            .child(Button::icon_only(Icon::Plus).on_activate_fn(|ctx| ctx.send_intent(AppIntent::AddChapter)))
            .child(Button::icon_only(Icon::ChevronDown).on_activate_fn(|ctx| ctx.send_intent(AppIntent::OpenChapterMenu)))
    })
}

6. UI Construction Patterns

The framework provides three child-addition methods on container builders — add_child(WidgetId) for pre-registered children, child(impl IntoWidgetTree) for inline insertion, and children(iter) / child_opt(Option<_>) for iterator and conditional shapes — plus the Repeater for dynamic non-virtualized collections driven by ListModel<T> change notifications. Composites use the static child() chain when content structure is fixed for the lifetime of the widget; visible_when(Signal<bool>) toggles individual subtrees between active and dormant without reconstruction; the Repeater handles small collections that change during interaction; ListView virtualizes large collections. The teksu! DSL desugars to these same builder calls.

References: CLAUDE.md "Widget Construction Patterns", teksu-macro-reference.md, data-models.md (Repeater vs ListView).

7. Reactivity Model

Signal<T> is the only reactive primitive. Signal::new(x) is mutable; signal.map(f) is read-only and derived; multi-source combinators (a.zip(&b), a.and(&b) / a.or(&b) / s.not()) compose, and selector.flat_map(|t| inner_signal(t)) switches the result to follow a dynamically-selected inner signal (reactive "switchLatest", O(1) binding). Prop<T> is the widget-property wrapper accepting either a static T or a signal-bound value. ObserverHandle provides RAII cleanup; WeakSignal<T> breaks reference cycles. Builders accept impl Into<Prop<T>> for properties and impl Into<ColorProp> / impl Into<TextStyleProp> for theme-aware colors and typography.

The division of labor: simple property reactivity is declarative (the widget declares a binding, the framework reacts); structural changes (switching tabs, adding/removing children, activating/dormant-ing subtrees) are imperative, requested from a handler via EventContext (ctx.set_dormant, ctx.activate, ctx.destroy, and ctx.with_widget_mut::<W>(id, level, |w| …) for a typed by-id mutation of any mounted widget that opts into Widget::as_any_mut — e.g. reaching SceneView::scene_mut()). These are deferred and applied after the handler returns, when the framework holds &mut arena access. This split is what lets Teksilo avoid both full view diffing and ad-hoc observer soup.

References: CLAUDE.md "Signals & Reactivity", reactive-theme.md, events-and-gestures.md (deferred operations).

8. Conditional Rendering and Dormancy

The widget arena supports three activation states for widget subtrees.

Active — fully operational. Participates in layout, receives events, paints, has AccessKit nodes, holds rendering resources.

Dormant — state preserved, rendering resources released. Does not participate in layout, receives no events, has no AccessKit nodes. The widget data and state values remain in the arenas. Reactivation triggers relayout and repaint, but no reconstruction.

Destroyed — removed from the arena entirely. State is gone. Must be rebuilt from scratch.

Three construction strategies control the memory/responsiveness tradeoff for multi-pane widgets:

Eager — all subtrees built at construction time, inactive ones set to Dormant. Switching is instant. Suitable for tab widgets with a small number of tabs.

Lazy — subtrees built on first activation, then preserved as Dormant. Suitable when building a subtree is expensive and the user may never visit all tabs.

Transient — subtrees built on activation, destroyed on deactivation. Lowest memory, highest switch cost. Suitable for browser-like scenarios where each tab is independent.

Rebuild and child reconciliation

When a widget's build() re-runs (a BindingLevel::Rebuild signal fired, or an explicit rebuild request), the framework reconciles the widget's children against what the new build() returned. Widget::preserves_children_on_rebuild() selects the policy:

• false (default) — re-derive. Every old child subtree is destroyed up front, then build() produces a fresh set. Correct for data-driven widgets (Repeater, ListView) that reconstruct children from current model state with fresh WidgetIds. A false widget must not re-attach an old child id — it is already gone.
• true — reconcile. build() re-attaches (by id) the children it keeps and drops the rest. The framework keeps every re-attached child's subtree intact — focus, scroll offset, text contents, signal subscriptions all survive — and destroys only the children the new build dropped and did not re-parent elsewhere. This is the mode for widgets that memoize stateful children across rebuilds: Switcher pages, TabWidget / DockingLayout panes, the CompositeTooltip body, SceneView's heavyweight scene widgets, and MenuBar's leading/trailing slot widgets (re-derived menu triggers reaped, memoized slots kept — so a stateful slot control survives a model-version rebuild).

The reconcile is scoped (it only considers the rebuilt widget's own direct children, so floating retained nodes held outside the child tree — e.g. dormant menu/popover content registered via ctx.add — are never touched) and parent-authoritative: a kept subtree that the rebuild re-parents out of a dropped sibling and into the new tree survives, because the destroy walk follows live parent pointers rather than the dropped sibling's now-stale children list. The per-node teardown frees the arena slot via a single-node removal (Arena::remove_node), so the recursion the destroy walk already performed is not duplicated by the arena. Net effect: a preserve = true widget that removes a child (a closed tab, a superseded tooltip chrome) genuinely reaps it — it does not leave a stranded, still-Active orphan in the arena.

9. Event System

Full reference: events-and-gestures.md. Preview pass (root → strict ancestors of target) plus bubble pass (target → root); attached handlers stored on WidgetNode (.on_tap / .on_hover / .on_key / .on_key_preview / .on_focus / .on_scroll / .on_pointer_event / .on_access_action); auto-wired gesture recognizers; EventContext API including deferred mutations (set_dormant / activate / destroy / with_widget_mut::<W> / request_focus / request_accessibility_update / dismiss_all_overlays); subtree state signals (.focus_within(Signal<bool>) / .hover_within(Signal<bool>)); AccessAction routing through the same dispatch machinery. request_accessibility_update() (also on BuildContext) forces an AccessKit re-walk after a handler/build restructures its subtree in a way a relayout wouldn't otherwise surface to AT.

Backend events (database change notifiers, file watchers, message buses) plug in via the EventSource trait — widgets subscribe from build() via BuildContext::subscribe_event, and cross-thread forwarding goes through winit's EventLoopProxy. Per-widget lifetime cleanup: when the widget is destroyed, the subscription handle drops and the source unsubscribes. A rebuild is not a destroy: build() re-runs and re-subscribes, and the SubscriptionId it gets back is the one the previous build used at that same position (BuildContext::reusable_sub_ids). That identity has to span rebuilds because it is what crosses the thread boundary — a publisher captures the id and posts it, the UI thread dispatches it frames later, and minting a fresh id in between would strand every event already in flight. Matching is positional: the Nth subscribe call of one build inherits the Nth of the last, a build that subscribes fewer times leaves the surplus torn down, and a build that subscribes more allocates fresh ids for the extras.

10. Gesture Recognition

Full reference: events-and-gestures.md. UIKit-style state machines (TapRecognizer, DoubleTapRecognizer / TripleTapRecognizer, LongPressRecognizer, DragRecognizer) with a GestureArena for competition. Recognizers are auto-wired from attached handlers — the framework instantiates a TapRecognizer when a node has an on_tap handler, a DragRecognizer when it has on_drag, and so on. Tap-family callbacks receive &TapEvent { position, button, modifiers }; default acceptance is ButtonMask::PRIMARY only (right-click never spuriously fires on_tap), widened via .accept_tap_buttons(...) and friends.

11. Actions, Intents, and Shortcuts

Full reference: shortcut-intent-action.md. The three-layer pipeline: Shortcut (rebindable keystroke → intent name) → Intent (runtime DTO with optional typed payload) → Action (ancestor-registered handler keyed by intent name). #[derive(IntentKind)] with #[name = "..."] provides the typed-enum DTO bridge (unit, tuple, and struct variants). ShortcutRegistry holds two layers (declared defaults + persisted user overrides with graveyard semantics) and exposes a Signal<u64> version so menu labels and tooltips re-render on rebinds.

12. Internationalization

Full reference: i18n.md. Fluent-rs runtime (I18nManager, LocalizedString, locale resolution, .ftl file watcher, fallback chains, LayoutDirection signal); compile-time-validating macros tr! / tr_widget! / tr_signal! / tr_signal_widget! that read .ftl files at expansion and validate every call against the parsed key map; locale-aware formatters (NumberFormatter, TeksiloDateTimeFormatter, TeksiloDateTime) backed by ICU4X (icu_decimal / icu_datetime / icu_calendar) with a custom DATETIME() Fluent function and bundle set_formatter callback so { NUMBER(...) } / { DATETIME(...) } inside .ftl messages render correctly across locales. Framework-string registration for teksilo-widgets is explicit: applications call .framework_locales(teksilo_widgets::framework_locales()) on the I18nConfig builder chain.

13. Overlay System

Full reference: tooltips.md for tooltips (plain + rich + registry, sticky-on-dwell, focus-driven a11y promotion). Multi-window modal flow lives in multi-window.md.

Engine internals: OverlayManager per WidgetTree. Two rendering layers — OverlayLayer::InTree (drawn into the same RenderFrame as the host) and OverlayLayer::NativePopup (separate winit window, used for menus that must escape the host window's bounds); OverlayLayer::Auto picks based on placement and platform. OverlayPlacement covers Below / Above / BelowPreferred (auto-flips on insufficient space) / TrailingEdge / AtPointer / NearAnchor / BottomCenter. DismissBehavior::ClickOutside | PointerLeave | Manual plus an Escape-cascade root handler. Delayed-open overlays (submenu hover delays) cancel via EventContext::cancel_delayed_overlay(id). Overlay anchor positions invalidate on host relayout. AccessKit nodes for overlay content cascade under their logical parent, not the geometric root, so tooltips DescribeBy their anchor and menus Owned-By their menu bar item.

OverlayRequest::with_fade(duration) wires the framework-managed opacity tween at show/dismiss — caller specifies the duration, framework handles the signal, the set_opacity scope, and the deferred dormant-set after the dismiss tween completes.

14. Drag and Drop

Full reference: drag-and-drop.md. Three scenarios (intra-widget reorder, inter-widget transfer, external/OS drops) share one machinery: typed DragPayload, source/target traits, hit testing under the cursor, drop-zone preview overlay, edge auto-scroll during hover, spring-load on dwell, full keyboard equivalence (Cut / Copy / Paste actions on a focused list/tree). Inbound external drops (files / text / URLs dragged from the OS into a window) are implemented via the ExternalDndBackend per-OS backends (macOS NSDraggingDestination verified; Windows OLE, Wayland wl_data_device, X11 XDND via an XdndProxy helper window) and reuse the same machinery — see drag-and-drop.md §11 and the DropZone widget. Outbound drags (Teksilo window → another app) are implemented on every desktop target (macOS NSDraggingSource + Wayland wl_data_source verified; Windows OLE IDropSource; X11 XDND source) — a MIME-carrying start_drag auto-escalates at the window boundary, with typed re-entry enabling cross-window DnD. See drag-and-drop.md §11.5.

15. Data Model

Full reference: data-models.md. The teksilo-data crate sits between the widget tree and application view-models, providing ListModel<T>, TreeModel<T> + TreeSlice<T>, SelectionModel, and the ListDataSource trait for paged/external collections. SortFilterListModel<T> and SortFilterTreeModel<T> are projection wrappers that sort and filter without copying the source. DataChange / TreeChange notifications drive Repeater, ListView, TreeView, TableView, TreeTableView updates.

The crate is separate from teksilo-core because collections are a higher layer than the widget tree — view-models live in the application, hold these models as fields, and bind widgets to them. Qleany integration (generated EntityListModel / EntityTreeModel typed against entity DTOs) is one supported path; nothing in teksilo-data requires it.

16. Canvas API

16.1 Purpose

The Canvas is the high-level drawing API that widget authors program against. It replaces direct RenderFrame manipulation with operations that match how developers think about graphics — shapes, colors, text, transforms.

#![allow(unused)]
fn main() {
fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext) {
    canvas.fill_rounded_rect(bounds, CornerRadius::uniform(6.0), theme.colors.primary);
    canvas.draw_text(&self.label, bounds.center(), &theme.typography.label);
}
}

16.2 Three-Tier Rendering

The Canvas internally classifies each drawing operation and routes it to the appropriate rendering tier.

Tier 1 — Axis-aligned rectangles. fill_rect, stroke_rect, simple draw_line. Translated directly to DecorationRect entries. Zero rasterization cost. Covers the majority of UI drawing.

Tier 2 — SDF shader shapes. Rounded rectangles, circles, ellipses, gradients. Rendered as quads with a specialized fragment shader computing signed distance fields. Smooth antialiasing at any resolution without rasterization. The RenderFrame gains ShapeQuad entries for this tier.

Tier 3 — Arbitrary paths. Complex shapes, custom curves, SVG icons. Rasterized on CPU via tiny-skia, cached in a shape atlas, rendered as textured quads. Rasterization is amortized by caching — static paths rasterize once.

16.3 Path Builder

The Path type provides a builder for arbitrary shapes:

#![allow(unused)]
fn main() {
let star = Path::star(center, outer_radius, inner_radius, 5);
canvas.fill_path(&star, Color::GOLD);
}

16.4 Text Integration

The Canvas delegates text rendering to the shared Typesetter instance from text-typeset. draw_text handles simple single-line text. draw_text_layout renders pre-measured text for cases where layout measurement and painting are separated. The RichTextEditor widget uses draw_render_frame to embed a complete text-typeset RenderFrame at a specific position, sharing the same glyph atlas.

16.5 Paint Types

Beyond solid colors, the Canvas supports Paint types: LinearGradient, RadialGradient, ConicGradient, and Image. Gradients are rendered in the SDF fragment shader (Tier 2). Widgets carry a fill as a PaintProp (a flat ColorProp or a gradient, in teksilo-core); RectWidget resolves it to a Paint at paint time (gradient endpoints are rect-local, computed from the widget's size). Anything Into<ColorProp> is also Into<PaintProp> as a solid, so the common case is unchanged.

17. Rendering Pipeline

17.1 Frame Lifecycle

A frame is produced only when something has changed. Between frames, the application is idle and the GPU is quiescent. The frame lifecycle has five phases executing sequentially on the main thread.

Phase 1: Event processing. Raw input from winit is translated and dispatched through the widget tree. State changes from property bindings are resolved. Widgets are marked dirty.

Phase 2: Layout. SwiftUI-style negotiation runs only on dirty subtrees. Output: positioned rectangle for every active widget.

Phase 3: Accessibility sync. The AccessKit tree is updated incrementally — only changed nodes are pushed.

Phase 4: Paint. Each dirty widget's paint() is called with a Canvas. The Canvas accumulates drawing operations and produces a merged RenderFrame.

Phase 5: GPU submission. Atlas textures are uploaded, vertex buffers are built, draw calls are issued through wgpu. The surface presents.

17.2 RenderFrame

The RenderFrame is the boundary between platform-independent logic (teksilo-core, teksilo-canvas) and GPU-specific code (teksilo-render). It contains five drawable types: GlyphQuad (textured from glyph atlas), ImageQuad (textured from image), DecorationRect (untextured colored rectangle), ShapeQuad (SDF-rendered shape), and RasterizedQuad (textured from shape atlas). A draw_order array records painter's order (back-to-front) for correct occlusion across all drawable types.

17.3 GPU Pipeline

Three shader pipelines in teksilo-render: the quad pipeline (textured quads for glyphs, images, rasterized paths), the rect pipeline (untextured colored quads for decorations), and the SDF pipeline (signed distance field shapes with optional gradient fills). A typical frame produces five to six draw calls total.

17.4 Atlas Management

Three atlas textures serve different purposes. The glyph atlas is owned by the shared Typesetter (from text-typeset), containing rasterized glyph bitmaps. The shape atlas stores Tier 3 rasterized path results from tiny-skia. The image atlas (or texture array) stores application images. All use LRU eviction — dormant widgets' entries age out naturally.

Glyph atlas lifecycle and the eviction contract

Glyph quads bake atlas pixel coordinates at paint time, and the framework retains painted output at several layers (per-widget cached_paint / cached_post_paint, the assembled cached_frame, the scene per-item cache). LRU eviction can therefore invalidate quads that are still being replayed — the contract that keeps this sound has three legs:

1. Keep-alive. Every replay of a retained frame calls TextBackend::touch_layout for each of the frame's layout_keys (per-widget cache hits, post-paint cache hits, and the full-frame early-out in rendering_impl.rs), refreshing the glyphs' LRU timestamps so on-screen glyphs never age out.
2. Eviction reporting. TextFontService::eviction_epoch is the single source of truth: it is bumped by every eviction path — the atlas_snapshot scan, the scan at the start of every rich-text render() (build_render_frame), and the wholesale reset on scale-factor change. TypesetterBridge::atlas_info compares it against a last-seen value and reports glyphs_evicted; the app-level recovery in teksilo-app then clears the bridge caches and calls invalidate_all_paints on every window (the bridge and atlas are shared process-wide), requesting redraws. Caches living outside the widget arena (the scene ItemCoordinateCache) instead self-gate on TextBackend::glyph_epoch at paint time.
3. Versioned uploads. Each window's renderer owns its own GPU atlas texture. atlas_info(seen_version) carries a monotonic content version; a window uploads (and receives pixels) only when its recorded atlas_uploaded_version lags. This replaces consume-once dirty semantics, so several windows all converge on the same atlas content instead of the first caller consuming the upload for everyone.

Debug-build corruption catcher. In debug builds, every evicted atlas rectangle is poison-filled magenta (text-typeset), so any stale-UV sampling is visually unmistakable; and every retained-frame replay validates its layouts via TextBackend::debug_validate_layout — a glyph whose live atlas rect no longer matches the baked quads aborts with a diagnostic (RectMismatch), and a layout the backend no longer knows logs a loud warning (StaleKey). Release builds compile all of this out.

17.5 Dirty Tracking

Each widget has a dirty flag at two granularities: needs relayout (size may have changed) and needs repaint (appearance changed, size unchanged). Clean widgets replay cached Canvas output without recomputation.

18. HiDPI and Scaling

Layout works in logical pixels. Rendering works in physical pixels. The conversion happens at the boundary between Phase 4 (paint) and Phase 5 (GPU submission).

SizeProposal, widget dimensions, spacing, padding, and font sizes are all logical. The Canvas also works in logical coordinates — canvas.fill_circle(center, 10.0, color) draws a circle with a 10-logical-pixel radius regardless of display density.

The scale factor is applied in two places: text-typeset rasterizes glyphs at physical pixel size (logical × scale factor), and teksilo-render multiplies screen coordinates by the scale factor when building vertex buffers.

When the scale factor changes (window dragged to a different monitor), the glyph and shape atlases are invalidated and a full relayout is triggered.

19. Theming — the four-tier styling ladder

Full references: styling-system.md (the four-tier ladder — tokens → variants → recipes → style protocols) and reactive-theme.md (the Signal<Theme> reactive layer).

Theme lives in teksilo-core::styles (not teksilo-tokens) so the per-widget style trait protocols and the typed Rc<dyn FooStyle> slot bag can sit on the same struct. It carries a required appearance: ThemeAppearance ({Light, Dark} — drives shadow density, OS-theme matching, asset selection), five token groups (ColorTokens, LayoutTokens, TypographyTokens, ShapeTokens, MotionTokens), ComponentStyles (dimension data for the not-yet-themable widgets), ComponentStyleSlots (typed style-trait overrides), and a ThemeExtensions registry. There is no Theme::default() / Theme::*_default() — apps pick a preset explicitly (teksilo_core::presets::intui::{light, dark}).

Every themable widget composes its chrome through a Tier-3 style trait (ButtonStyle, ToggleStyle, …) rather than self-painting: the widget builds its parts, hands a *StyleConfig to the active style, and uses the returned WidgetId as its root child. The style is resolved per-call (.style(...)) → theme-wide (theme.style_slots.<widget>) → Recipe*Style default. Signal<Theme> reactivity — set_theme updates the signal and dirty-marks every node, no rebuild; focus, scroll, text-input cursor, expanded sections all survive a switch. Role-based widget surface (TextRole, SurfaceRole, BorderRole, TextStyleRole) plus ColorProp / TextStyleProp wrappers; widgets resolve roles against the current theme at paint/layout time. Subtree theme overrides via set_theme_override(id, |theme| …). Themes derive Serialize + Deserialize for user-loadable theme files (the style_slots and extensions fields are #[serde(skip)]).

20. Threading Model

20.1 Single UI Thread

All five phases of the frame lifecycle run sequentially on the main thread. The widget tree, state arena, overlay manager, Canvas, and all contexts are non-Send types — the compiler prevents accidental access from background threads.

This matches Qleany's synchronous model. A Qleany controller call from a Teksilo command handler executes synchronously. No async/await, no tokio, no runtime.

20.2 Background Work

Long operations use Qleany's LongOperationManager, which runs use cases on background threads. The background thread communicates with the UI thread through winit's EventLoopProxy — a unidirectional channel that wakes the event loop and delivers custom events. The UI thread processes these events like any other input, triggering data source refreshes and widget repaints.

20.3 Incremental Work

Operations that take 5–50ms (too short for a background thread, too long for a single frame) are broken into chunks via request_idle_callback. The event loop runs idle work during gaps between frames, respecting a time budget.

20.4 Event Loop

The winit event loop uses ControlFlow::Wait — it sleeps when no events are pending and no widgets are dirty. CPU and GPU consumption is near-zero when the user is not interacting. Full rationale and the four enforcement gates: idle-and-animation.md.

20.5 Animation

Teksilo does not ship a separate animation subsystem. Animation is a thin layer over Signal<f32>: signal.animate_to(target, duration, easing) asks the tree's AnimationScheduler to smoothly interpolate the value over time, and any widget bound to the signal re-paints on each tick as the value slides. The scheduler integrates with the frame lifecycle (pause when the window is occluded, rebase on resume, skip offscreen ticks, cancel animations on widget rebuild/destroy), so widgets never own animation lifetime manually.

The design intent is narrow: motion is reserved for a small set of floating transitions — dialog appearance, snackbar slide-in, accordion expansion, toggle thumb motion, indeterminate progress, smooth programmatic scroll. Hover, press, and focus state changes are explicitly instant in Int UI's vocabulary; they are expressed as Signal<Role> mapped from an interaction signal and resolved per-frame through the theme, not through the animation scheduler. Looping animations respect ctx.prefers_reduced_motion().

Full rationale, API, worked examples, and testing patterns: animation.md.

21. Accessibility

Full reference: accessibility-overrides.md. AccessKit is integrated at the Widget trait level — every widget's accessibility(builder) declares role, name, state, and available actions. AT actions flow through the same dispatch as pointer/keyboard input via WidgetEvent::AccessAction. Builder-level .access_* modifiers (access_label, access_description, access_hidden, access_role, access_disabled, access_controls / described_by / labelled_by, access_live, access_shortcut_id / access_shortcut_literal, access_action / access_remove_action / access_custom_action, access_exclude_subtree / access_merge_subtree, access_customize) let app authors augment, replace, or annotate any widget's accessibility info from the outside.

Dormant subtrees produce no AccessKit nodes (screen readers only see active content). Overlay content generates correct AccessKit tree structures — tab lists have Role::TabList and Role::Tab nodes, menus have Role::Menu and Role::MenuItem nodes, tooltips are linked to their anchor widget via DescribedBy. Scene-content a11y customization (off-screen modes, logical groups) lives in teksilo-scene-a11y.md.

22. Window Management

Full reference: multi-window.md. Each window owns its own independent WidgetTree, layout pass, paint pass, RenderFrame, and wgpu surface. Application-level context (theme, locale, ShortcutRegistry, data-model handles, app-scoped backend wiring) is shared across windows. WindowConfig is the single creation entry point for both initial and runtime-opened windows; WindowState is the per-window cloneable signal handle (placement, title, size, position, focused, resizable, always_on_top). Two-way OS↔state sync uses an applying_from_os re-entrancy guard to prevent observer→OS→observer loops.

Custom window chrome (drag region, resize strip, window controls, per-OS title bar host backends): title-bar.md.

23. Settings and Persistence

Full reference: settings.md. In-memory is the source of truth — Signal<T> and *Model<T> handles drive both UI and disk; the disk side is a debounced atomic projection (write-temp + rename, single shared I/O thread per process). Three persistence shapes: SettingsStore (dotted-key K/V for scalars), SettingsFile<T> (typed single-struct with Versioned + Migrator<T> migrations on raw toml::Value), and PersistedListModel<T> / PersistedTreeModel<T> (bridges from ListModel<T> / TreeModel<T>). Built-in services: MruList<T: MruEntry> for generic dedupe + pin + LRU-cap recents; WindowStateService with framework-driven auto-save/restore for any WindowConfig carrying id(...). Saved geometry is sanitized on restore against the current monitor's work area. Wayland ignores window position by protocol design (size and WindowPlacement round-trip).

24. Testability

24.1 Headless by Design

The widget tree runs without a window, without GPU, and without winit. All five phases (minus GPU submission) execute in pure Rust with no platform dependencies. Tests use teksilo-core's WidgetTree directly:

#![allow(unused)]
fn main() {
#[test]
fn button_click_fires_action() {
    use std::cell::Cell;
    use std::rc::Rc;
    let mut tree = WidgetTree::new();
    let clicked = Rc::new(Cell::new(false));
    let clicked_flag = clicked.clone();
    let root = tree.add(FillWidget::new());
    tree.push_action(
        root,
        Action::new("app.save").on_invoke(move |_i, _c| clicked_flag.set(true)),
    );
    let button = tree.add_child(
        root,
        Button::new(lit!("Save")).on_activate_fn(|ctx| ctx.send_intent(AppIntent::Save)),
    );
    tree.layout(SizeProposal::exact(200.0, 40.0));
    tree.click(button);
    assert!(clicked.get());
}
}

24.2 What Is Testable

Layout (given a widget tree, do children end up at the right positions), event dispatch (does the right widget receive events, does focus cycle correctly), state transitions (hover/pressed/disabled), accessibility (correct AccessKit role, name, actions), render output (expected quads/shapes in the RenderFrame), theming (palette swap produces correct colors), gesture recognition (pure state machine tests), overlay behavior (tooltip timing via simulated clock), drag-and-drop (payload transfer, insertion indicator rendering), and composition (multiple widgets interacting correctly).

24.3 Mock Backend

Cargo feature flags (mock-backend) swap Qleany controller implementations with mock modules providing static data. Same API surface, zero backend. Familiar to the developer from Qleany's C++/Qt mock system for QtQuick.

24.4 CI Friendly

No Xvfb, no GPU, no display server required. Pure logic tests run in cargo test in milliseconds. The simulated clock (tree.advance_time()) enables deterministic testing of time-dependent behavior.

25. Crate Structure

Full per-crate descriptions live in CLAUDE.md "Crate Architecture". The dependency graph is the part that belongs here.

25.1 Dependency Graph

teksilo-tokens
    ↑
teksilo-canvas ← tiny-skia
    ↑           ↑
teksilo-core    teksilo-text ← text-typeset
    ↑ ← accesskit
    │
    ├── teksilo-data
    │       ↑
    │   teksilo-settings ← serde, toml, directories, tempfile
    │       ↑
    │   teksilo-telemetry ← uuid
    │
    ├── teksilo-widgets
    │   └── teksilo-text ← text-document, text-typeset
    │
    │   teksilo-i18n ← fluent-rs, icu_decimal, icu_datetime, icu_calendar
    │
teksilo-render ← wgpu
    ↑
teksilo-platform ← winit, accesskit-winit
    ↑
teksilo-app (wires teksilo-text into Canvas, teksilo-widgets, teksilo-i18n,
          teksilo-settings — auto-restores/saves window geometry,
          optionally teksilo-text)
    ↑
teksilo (umbrella, re-exports)

teksilo-text depends only on teksilo-canvas (for the TextBackend trait) and text-typeset. It does not depend on teksilo-core, text-document, or any platform crate. The TextBackend trait is defined in teksilo-canvas so that the Canvas can call text rendering methods without knowing which backend implementation is active.

The RichTextEditor widget (in teksilo-widgets) depends directly on text-document and text-typeset. The application owns the TextDocument instance and passes it to the widget — Teksilo never owns or wraps the document model. The application depends on text-document directly for model access (highlighter, cursors, import/export). Cargo deduplicates the shared dependency automatically.

Platform-specific code (winit, wgpu, accesskit-winit) is confined to teksilo-render and teksilo-platform. Everything above them is platform-independent and headlessly testable.

25.2 The teksilo Umbrella

The standard application developer depends on a single crate: teksilo. It re-exports the public API and controls feature flags. text, i18n, and rich-text are default features (opt-out, not opt-in), because the kinds of applications Teksilo targets — writing tools, editors, IDEs, content managers, long-running desktop apps — routinely need text rendering, translations, and rich text editing. TextInput itself derives from the rich-text widget, so anything with an editable text field pulls in rich-text anyway. Sub-crates remain independently publishable for advanced users (custom widget authors, custom renderer implementors).

26. Button — Reference Widget Design

The button serves as the reference implementation exercising most architectural features: composition of primitives, interaction state as a Signal<InteractionState>, role-based color resolution per visual state, attached handler activation from multiple input paths, AccessKit role and actions. A new widget author implementing their first custom widget should read crates/teksilo-widgets/src/button.rs — it's the authoritative exemplar, and concrete code is more useful than prose at this point. See also reactive-theme.md for the Signal<Role> pattern Button uses for its visual states.

What Button exercises:

• Composition. A RectWidget (background, border, corner radius) wrapping an internal HStack or VStack (by IconPosition) containing an optional IconWidget and a TextWidget label. Leading/Trailing positions respect locale LayoutDirection.
• Visual states. Five (idle, hovered, pressed, focused, disabled) × seven variants (Filled, Tinted, Outlined, Plain, Ghost, Link, Destructive) → (background role, border role, text role) resolved at paint time via Signal<InteractionState> mapped to Signal<Role>.
• Behavior. Pointer enter/leave/down/up drives interaction state; keyboard Space/Enter triggers activation; cursor is Pointer on hover; TapRecognizer commits the click.
• Accessibility. Role::Button, name from label (resolved via tr! / tr_widget!), disabled state, actions (Click, Focus). Focus ring painted only on keyboard focus (origin-aware).

27. Architectural Comparisons

27.1 vs. QPalette → Design Tokens

QPalette covers color roles across three interaction groups. Teksilo's design token system extends that scope to spacing, typography, and shape, uses typed Rust structs, and supports subtree overrides through environment propagation.

27.2 vs. QAbstractItemModel → ListModel<T> and TreeModel<T>

Qt's QAbstractItemModel uses a role-based, type-erased data access protocol (QVariant). Teksilo's ListModel<T> and TreeModel<T> are concrete generic types: the delegate closure receives &T directly, with compile-time type safety. The ListDataSource trait provides an escape hatch for large/external datasets, also with an associated Item type.

27.3 vs. Existing Rust GUI Frameworks

Teksilo's focus areas are accessibility (AccessKit at the trait level, tested by every test), text rendering (text-document + text-typeset), and widget extensibility (unified Widget trait with slots). Its layout and event design are comparable to Xilem/Masonry. It is currently weaker on rendering sophistication (quad-based vs. Vello's GPU compute renderer) and much younger than established frameworks.

The primary reference point for Teksilo's feature scope is Qt Widgets — the framework most commonly used for the kind of professional desktop applications Teksilo targets.

28. Widget Catalog

The current widget inventory is no longer maintained as prose in this document — it drifted faster than it could be edited. The authoritative sources are:

• tools/extract_widget_api.py --all — emits the public surface (struct, builder methods, enums, module doc) of every widget in teksilo-widgets. Run python3 tools/extract_widget_api.py --list to see the full file list, or pass widget names to extract just those.
• teksilo-milestones.md — the "Current State: What Exists" section enumerates every widget currently shipped, grouped by category, and tracks remaining milestone work.
• CLAUDE.md — the "Implementation Status" block and the per-widget reference docs (table-view.md, tab-widget.md, charts.md, tooltips.md, teksilo-scene.md) cover the widgets with the deepest API surface.

For a one-shot dump suitable for downstream tooling: python3 tools/extract_widget_api.py --all -f json -o widgets.json.

29. V2 Widget Authoring Model

The unified Widget trait, Signal<T> reactivity, attached handlers, BuildContext::signal / effect / animated_signal / app_state / subscribe_event, the four widget shapes (leaf / container / composing / hybrid), and the take_widget / restore_widget arena extraction pattern that makes build(&mut self) borrow-safe — all documented in CLAUDE.md "Unified Widget Trait" plus the focused docs (events-and-gestures.md, reactive-theme.md, animation.md). The V2 model is what the entire widget library is written against; reading crates/teksilo-widgets/src/button.rs is the fastest way to see all of it together in one ~200-line widget.

The teksu! DSL desugars to V2 builder calls one-to-one at macro-expansion time — no runtime, no virtual tree. References: teksu-macro-reference.md (user-facing) and teksu-language-spec-v3.md (grammar and desugaring spec).

30. Open Questions (Current, May 2026)

The bulk of the original post-milestone question list has landed. The short list below is what remains actively open; see teksilo-milestones.md for detailed status and the Next-candidates roadmap.

External (OS) drag-and-drop. Intra-app DnD works everywhere (Milestone 6). Inbound OS drops — files / text / URLs dragged from a file manager or another app into a Teksilo window — are implemented through the ExternalDndBackend trait in teksilo-platform (install_external_dnd()): macOS via a NSDraggingDestination overlay view (verified), Windows via OLE RegisterDragDrop/IDropTarget, Wayland via wl_data_device, X11 via XDND v5 (an XdndProxy helper window on its own connection — winit owns the toplevel's X connection and consumes XDND messages itself; see drag-and-drop.md §11.3.1). They reuse the in-app pipeline — an OS drop is a DragPayload with origin() == External. winit's own DroppedFile/HoveredFile are not used (no position, files-only, no Wayland). Outbound drags (Teksilo window → another app) are now implemented on every desktop target (macOS NSDraggingSource + Wayland wl_data_source, both verified; Windows OLE DoDragDrop; X11 an XDND source that polls the pointer rather than grabbing it): a normal start_drag whose payload carries MIME data auto-escalates to a native OS drag when the pointer leaves the window, completion is reported via on_drag_ended(DropOutcome), and the typed payload is recovered on re-entry (enabling drag-and-drop between two windows of the same app). See drag-and-drop.md §11.5.

Native menu bar on macOS. Done (on-device macOS validation still pending). A widget-free MenuModel is the single declarative source of truth, routed two ways: the in-window widget MenuBar on Windows/Linux (where menus live in the window chrome), and the global NSMenu on macOS via the NativeMenuBackend trait in teksilo-platform (install_native_menu() + MenuBar::from_model(..).native_on_macos(..)). Item clicks route back through the Intent/Action pipeline; the trait + plain NativeMenuSnapshot boundary are platform-neutral for future Windows HMENU / Linux DBus backends (currently a no-op). See native-menu.md.

Virtualized dropdowns. ComboBox now virtualizes via ListView under max_visible_items: lists beyond the cap materialize only the visible rows (plus ListView's small buffer) instead of building every DropdownItem eagerly. The searchable filtered path shares the same virtualized renderer. MenuList grew a max_visible_items builder that caps panel height and wraps the item column in a ScrollArea, but does not virtualize — its API still takes arbitrary impl Widget children, so true virtualization would require a model-driven MenuList rewrite (tracked as follow-up). The eager build is cheap enough that capped 100+ item menus are fine in practice.

31. First Milestone: Button in a Window

Status of every milestone (M1 through current) lives in teksilo-milestones.md. M1 — a window displaying a single themed button with click handling, hover/press states, text rendering, AccessKit accessibility, and keyboard activation — landed as the simple_button example. It exercised the full vertical slice (teksilo-tokens for theme, teksilo-canvas for the SDF rounded rect, teksilo-core for arena/layout/events/focus/a11y, teksilo-text for the label, teksilo-render for the wgpu pipeline, teksilo-platform for the winit window + AccessKit adapter, teksilo-app for the event loop) and proved the end-to-end stack before any further widget work.

Property-Based Testing Reference

Proptest was introduced to the workspace on the branch that produced this document, into a codebase that had zero property tests before it. There are now ~92 properties across teksilo-tokens, teksilo-data, teksilo-scene, and teksilo-widgets, and they found eight real bugs (see What this found below) — including one that exhausted 61 GiB of RAM and forced three hard reboots of the developer's workstation before it was diagnosed. That incident is itself part of what this document exists to prevent from happening again.

Mental model in one line:

proptest generates hundreds of inputs per property and shrinks any failure to a minimal counterexample — cargo-fuzz's coverage, on stable, in `cargo test`

The convention below is not invented for Teksilo. It is carried over unchanged from the author's sibling repos ../text-typeset and ../text-document, which have run proptest for longer; this document writes that convention down for this workspace so it applies uniformly here too, rather than living only as tribal knowledge.

Convention

File placement. Two shapes, chosen by the tested item's visibility — never by convenience:

• tests/*.rs integration test when the target is pub and reachable from outside the crate. Example: crates/teksilo-tokens/tests/prop_color.rs tests Color, a public type re-exported at the crate root.

• Inline #[cfg(test)] mod proptests, placed as a sibling of the existing #[cfg(test)] mod tests in the same file, when the target is pub(crate) or otherwise unreachable from tests/. The module doc must say why it lives inline rather than assume the reader can tell. Three worked examples, each stating a different reason:

  • crates/teksilo-widgets/src/splitter/distribute.rs: distribute is pub fn, but its declaring module (mod distribute; in splitter.rs) is private and not re-exported, so the function is unreachable from an external test crate even though the fn signature itself says pub.
  • crates/teksilo-scene/src/index.rs: GridHashIndex is declared pub struct, but it lives inside pub(crate) mod index; in lib.rs — the module's visibility caps the struct's, regardless of the pub on the struct itself. Reading a pub keyword on the item is not sufficient to decide placement; check the declaring module's visibility too.
  • crates/teksilo-widgets/src/primitives/column_flow.rs: ColumnFlow itself is public, but balance_columns — the pure function the suite actually targets — is pub(crate).

  Never widen an item's visibility to make it reachable from tests/. If the item is pub(crate), the test lives inline; that is the whole decision procedure.

One property per proptest! {} block, each preceded by a numbered banner comment stating the exact claim under test:

#![allow(unused)]
fn main() {
// ── 12. for_inactive_window desaturates exactly the accent family and
//      leaves everything else (except chart_palette) untouched, for an
//      arbitrary accent color — not just the two shipped IntUI presets ──
proptest! {
    #[test]
    fn for_inactive_window_desaturates_only_the_accent_field(accent in arb_color()) {
        // ...
    }
}
}

Forbidden, deliberately, so every suite reads the same way: the #[proptest] attribute macro, prop_compose!, #[derive(Arbitrary)], a manually driven TestRunner, or a hand-rolled RNG. Strategies are built by hand from proptest::prelude combinators (prop_oneof!, .prop_map, .prop_flat_map, prop::collection::vec, …).

Hand-written local fn arb_x() -> impl Strategy<Value = X> generators, one set per file. There is no shared generator module, and that is a deliberate choice, not an oversight: arb_parent_sel/arb_insert_ops appear near-verbatim in both prop_tree_slice.rs and prop_tree_checked.rs rather than being factored out — per-file duplication is the accepted cost of keeping each suite's generators legible and independently auditable without chasing a shared abstraction across files.

Case counts are the only tuning knob, set per block:

#![allow(unused)]
#![proptest_config(ProptestConfig { cases: 512, ..ProptestConfig::default() })]
fn main() {
}

There is no proptest.toml anywhere in this workspace. The default (256, proptest's own default) is left alone for ordinary properties; blocks that are cheap and unusually valuable (an oracle-vs-brute-force check, a panic-freedom sweep over malformed input) opt into 512 or 1024 explicitly, with the reason stated next to the override — see from_hex_never_panics_and_stays_in_range (1024, attacker-adjacent hex parsing) or the oracle properties in prop_sort_filter.rs (512, cheap per-case). The manual override for a one-off deeper run is PROPTEST_CASES=N cargo test -p <crate> ... — every suite's module doc states the exact invocation.

Assertions are prop_assert!/prop_assert_eq! only, and always carry a format-string message citing the actual values that failed, never a bare condition:

#![allow(unused)]
fn main() {
prop_assert!(
    from_brute.is_subset(&from_index),
    "cell_size={} query={:?}: index missed true intersections {:?} (model={:?})",
    cell_size, q, from_brute.difference(&from_index).collect::<Vec<_>>(), model,
);
}

A bare assert!(x) inside a proptest! block is a debugging dead end: the shrinker hands you a minimal failing case, and a bare assertion throws that context away at the exact moment it matters most.

Test names read as English claims describing the property, never test_-prefixed: hex_roundtrip_is_stable_after_one_quantization, selection_indices_never_dangle_past_the_end_of_the_list, reorder_within_stays_acyclic_and_conserves_the_node_set, a_single_items_cell_footprint_never_exceeds_the_per_item_cap.

.proptest-regressions files are committed, never gitignored — proptest reruns every recorded seed before generating novel cases, so a shrunk counterexample stays a permanent regression check once found. Two on-disk shapes, matching the two file-placement shapes above:

• tests/*.rs suites: the regressions file sits next to the test file, e.g. crates/teksilo-data/tests/prop_sort_filter.proptest-regressions.
• Inline mod proptests suites: proptest names the file after the module path and roots it at the crate, e.g. crates/teksilo-widgets/proptest-regressions/splitter/distribute.txt and .../proptest-regressions/common/row_offsets.txt.

A suite with no regressions file (prop_tree_slice.rs, column_flow.rs, column_geometry.rs in this workspace today) simply never shrank a failure — that is a legitimate outcome, not a sign the suite is incomplete.

Stated rationale (from the workspace Cargo.toml, next to the proptest = "1" dependency line): cargo-fuzz needs a nightly toolchain (libfuzzer-sys links against compiler-rt's fuzzing runtime), which isn't a guaranteed CI dependency. Proptest gives the same "never panics on weird input" coverage plus shrinking, on stable, as a plain [dev-dependencies] entry — no separate fuzzing job, no nightly pin. Every crate with a suite re-states this in its own Cargo.toml next to proptest = { workspace = true } rather than assuming the reader finds the workspace manifest.

Scope — what belongs here, what does not

Proptest owns relational properties: statements that must hold between an input and an output, or between two independent ways of computing the same thing, for every input in a domain — not statements about one exact rendered result.

It does not own exact pixel or glyph output. A rendered bitmap is font-version- and shaper-version-dependent, so pinning one down as a property assertion means the property breaks on every font update rather than on a real regression — that is insta snapshot territory in ../text-typeset, which owns real shaping/bidi/line-break/raster coverage against real fonts. Proptest here never touches a GPU, a display server, or real font shaping; every suite in this workspace runs against pure data (Color, ListModel, TreeModel, GridHashIndex, PrefixSumOffsets, distribute, …), headless, with no rendering in the loop.

The test for a candidate: can you state it as "for every valid x, f(x) relates to x (or to g(x), an independently written second computation) in such-and-such a way" — without needing to look at a rendered frame to know if it passed? If yes, it is proptest's. If the honest assertion is "this exact bitmap" or "this exact glyph outline", it belongs in a snapshot test instead.

Generator cost discipline

This is the section that matters operationally. A generator explores a product space, and proptest will find the worst corner of that space within a few hundred cases — including corners the author never considered reachable.

Cost the most expensive combination before writing the generator, and record that reasoning in a comment next to it. Every generator in this workspace carries one; see the cost comment on arb_list_op in prop_list_and_selection.rs or on arb_pane_with_wild_bounds in distribute.rs — each states the worst-case element count and the worst-case per-op cost before the strategy is defined, not after a failure.

Bound every prop::collection::vec length. Keep the modeled state small — a tree of 20–30 nodes, an op sequence of 30 steps, a pane list of 8. Properties find bugs through many small cases, not a few large ones; a generator that can build a 10,000-node tree buys nothing over one capped at 30 except CI time and a harder-to-read shrunk counterexample.

Couple dependent inputs. Drawing two related quantities from two independent strategies is the specific trap that caused the incident this document opened with. GridHashIndex's generator originally drew a rect's extent and the grid's cell_size from two separate arb_cell_size() calls: a rect sized for a 256 px grid (extent up to 256 * 64) inserted into an unrelated 1 px grid spans roughly 268 million cells. Separately, cell_size: 1.0 paired with the incident's own 1e6 extent asked for (1e6+1)² ≈ 1e12 cells — about 8 TB for the Vec<(i32, i32)> alone. That exhausted 61 GiB of RAM and forced three hard reboots before it was diagnosed as a generator bug compounding a real one.

The fix is prop_flat_map, so the dependent quantity is derived from the one it depends on rather than drawn independently. The worked example is arb_grid_and_two_rects in crates/teksilo-scene/src/index.rs:

#![allow(unused)]
fn main() {
fn arb_grid_and_two_rects() -> impl Strategy<Value = (f32, Rect, Rect)> {
    arb_cell_size().prop_flat_map(|cs| (Just(cs), arb_rect(cs), arb_rect(cs)))
}
}

arb_rect(cs) bounds its extent to at most cs * MAX_CELLS_PER_AXIS cells for that specific cs, so no generated pair can ever reproduce the mismatch. Every property in that suite that builds a grid and inserts into it draws its rects from here — never from two independent calls.

When a suite OOMs, the unbounded allocation in the production code is usually the real finding — fix or report that, not just the generator. That is exactly what happened here: cells_for_rect computed (width / cell_size) * (height / cell_size) cells and reserved that many (i32, i32) slots before the fill loop ran, with no upper bound and with i32 arithmetic that could itself overflow. A single oversized item — a scene backdrop, a full-document canvas rect, both reachable in production, not exotic — could OOM or crash a real app with no adversarial input required. The fix (b7f6e066, see What this found below) added MAX_CELLS_PER_ITEM and an always-scanned oversized: HashMap<ItemId, Rect> side list for any item whose AABB would exceed it. Shrinking the generator down to the smallest range that doesn't crash would have silenced the finding without touching the actual bug.

The safe run protocol

Never execute a suite's binary directly under cargo test. A bare cargo test runs every generator unbounded — exactly the condition that caused the incident. Always build and run separately, with a hard memory cap on the run:

cargo test -p <crate> --lib --no-run
BIN=$(cargo test -p <crate> --lib --no-run --message-format=json 2>/dev/null \
  | jq -r 'select(.executable != null) | .executable' | tail -1)
( ulimit -v 6000000 -t 300; "$BIN" <filter> --test-threads=1 )

• --no-run builds the test binary without executing anything, so a pathological generator can't run before you've had a chance to cap it.
• --message-format=json on the same --no-run build reports the exact binary path (.executable) without guessing at target/debug/deps/... hashes.
• ulimit -v 6000000 caps the subshell's virtual address space at ~6 GB (adjust to the machine); ulimit -t 300 caps CPU time at 5 minutes as cheap insurance against a runaway loop that isn't merely allocating. --test-threads=1 keeps the cap meaningful — proptest's own case parallelism would otherwise multiply the peak by however many threads are live.

This turns what would otherwise be a machine-killing OOM (invisible until the OS starts swapping and the desktop freezes) into a clean, immediate memory allocation of N bytes failed from the process itself — a report you can read, not a hard reboot.

Working with a property that fails

Never weaken a property to make it green. Do not relax the assertion, narrow the generator to dodge the failing input, add a prop_assume! that filters the failing case out, or delete the property. Any of those hides the finding instead of resolving it.

Instead: record the shrunk counterexample verbatim (proptest already does this in the .proptest-regressions file — e.g. cc 48dc58d1... # shrinks to ops = [InsertRoot(0, 0), InsertRoot(1, 3), SetSort(Some(Descending)), Update(7, 3)], mode = HideNonMatching in prop_sort_filter.proptest-regressions), read the implementation the property targets, and decide honestly which of the following applies.

A property that merely restates the implementation is worthless. prop_list_and_selection.rs's property 5 (single_mode_never_holds_more_than_one_selected_index) notes in its own comment that select_all "does not appear to special-case Single mode in the source (it unconditionally selects 0..count)" — i.e. its first draft was paraphrasing what the code did rather than stating a contract. Worse, an earlier draft of the neighbouring property 7 (select_all_replaces_rather_than_unions_the_previous_selection) generated SelectionMode::Single too and expected 0..second_count there — which directly contradicts property 5's own invariant (0..second_count holds more than one index whenever second_count > 1). Two properties in the same file, each individually plausible, asserting incompatible things. The resolution recorded in property 7's comment: narrow it to Multi-only, with the reasoning why written down — "whether select_all should no-op or collapse to one index in Single mode is that [other] property's business, not this one's." Property 5 turned out to state the real contract; property 7 was fixed to stop overreaching into it.

The same shape recurs in prop_sort_filter.rs's property 6: a brute-force "matches ∪ descendants" oracle agrees with SortFilterTreeModel for HideNonMatching and KeepAncestors, but not for KeepDescendants — traced by hand (not by running anything) to flatten_visible starting its walk at each top-level root and bailing out immediately if the root itself isn't visible, so a matching descendant under a non-matching root is never reached even though the brute-force definition says it should be visible. tree_row_filter.rs's own module doc already calls this divergence deliberate. The property was narrowed to the two modes the crate itself claims are equivalent (arb_ancestor_preserving_filter_mode), with the reasoning recorded in the property's comment, rather than asserting a stricter promise than the type actually makes.

When it is a real bug but the fix is a design decision, park it — #[ignore], the counterexample, and a "do NOT weaken this assertion" note — never delete it silently. Two properties in this workspace went through exactly that arc and were later resolved; both are worth reading as a pair, before-and-after, in git history:

• distribute.rs's NaN-bound property was committed as #[ignore = "unresolved: NaN min/max panics inside f32::clamp — see comment"] with a comment explaining the panic, why it is reachable (PaneDescriptor bounds are app-supplied; a min derived from a 0/0 ratio is NaN), and explicitly declining to guess at the right normalization without owner review. It was later un-ignored once 03341d1f (see below) picked a resolution.
• row_metrics.rs's uniform-vs-exact agreement property was committed #[ignore = "unresolved: uniform and exact modes disagree on all-zero heights — see comment"], again with the reasoning ("touches every PrefixSumOffsets consumer, so it is left for review") and was later un-ignored by a788e191.

Both comments, while parked, state outright: "Do NOT weaken this assertion."

Pin a shrunk counterexample as a named #[test] when it represents a bug worth remembering permanently, alongside — not instead of — the proptest! property that found it: oversized_1e6_extent_at_cell_size_one_never_allocates_the_pathological_cell_count is the literal incident input (Rect::new(0.0, 0.0, 1_000_000.0, 1_000_000.0) at cell_size: 1.0) pinned as a plain, deterministic #[test] in mod tests — so the exact input that took a workstation down three times stays a permanent regression check independent of proptest's own seed file.

What this found

Eight bugs across four crates. The pattern is worth stating plainly: with one exception (the GridHashIndex unbounded allocation, a missing resource bound rather than a disagreement between two things), every one was an inconsistency — one code path failing to honor an invariant a sibling path already upheld — not a wrong formula. That is the class example-based tests structurally cannot reach, because writing an example that exercises it requires already suspecting the specific pairing that diverges.

Two of these — the Color::mix NaN hole and the distribute NaN hole — are literally the same defect shape (f32::clamp panics or propagates NaN; a hand-written > guard doesn't catch NaN because every NaN comparison is false) found independently in two unrelated crates by two unrelated suites. Not one bug in this list is a case of the underlying formula itself being wrong.

Where the suites live

Each file's own module doc states its case-count defaults, its PROPTEST_CASES override invocation, and — where relevant — the specific regression it was written against. Read the target file's doc comment before adding a property to it; the conventions above are enforced by precedent, not by a lint.

Teksilo Widget Catalog

A categorized index of every widget that ships in the workspace. One line per widget; the source link is the authoritative reference. For full public API surfaces (struct, builder methods, enums, module doc) of one or more widgets, run python3 tools/extract_widget_api.py <Widget…> or --all for everything.

For per-subsystem docs (data binding, accessibility overrides, animation, drag-and-drop, multi-window, settings, i18n, theming, shortcuts/intents/actions), see SUMMARY.md.

Styling status

All 33 themable widgets are on the four-tier styling system (docs/styling-system.md): each ships a *Style trait in teksilo-core::styles::* plus a default Recipe*Style impl in teksilo-widgets/src/styles/*. The widget builds its parts, hands a *StyleConfig to the active style, and uses the returned WidgetId as its root child — no themable widget self-paints. Style resolution is per-call .style(impl FooStyle) → theme-wide theme.style_slots.<slot> → recipe default.

The 17 legacy per-widget dimension structs in teksilo-tokens::components were deleted; their IntUI constants now live in the matching teksilo-widgets/src/styles/recipe_*_style.rs modules. The dimension data for non-themable widgets (toolbar, status bar, dialog, accordion, badge, progress bar, table, …) lives directly in those same recipe_*_style.rs modules as pub const blocks. Three sibling preset crates ship — Material 3 (theme-material3), Fluent / Windows 11 (theme-fluent) and macOS Aqua (theme-macos). Image-backed styles, the ImageTheme TOML loader, and a GTK4-Adwaita preset are still pending.

End-to-end demo of the slot bag + per-call override: see examples/theme_styles/.

Layout primitives — crates/teksilo-widgets/src/primitives/

The composable building blocks of every widget tree. See layout-primitives.md for the layout protocol, slack distribution math, and worked examples.

• HStack — horizontal stack with cross-axis alignment, spacing, and slack distribution.
• VStack — vertical stack; same model.
• ZStack — overlay stack at a shared origin with two-axis alignment.
• Grid — fixed/fr/auto track grid (TrackSize); explicit cell placement.
• Wrap — flow layout that wraps to new rows when out of width.
• MasonryLayout — variable-height grid packing into the shortest column (Pinterest-style).
• ColumnFlow — newspaper columns whose count follows the available width: drops a column and re-partitions every child as the width shrinks. Contiguous source-order runs, so reading and focus order stay correct at every count; min/max_column_width, max_columns, column_rule, opt-in semantic_list, reactive column_count_signal(). Pair with a ScrollArea for vertical overflow.
• FormLayout — labelled rows with column alignment for settings panels.
• Center — centers a single child within the space it is given (fills a bounded axis, shrink-wraps an open one; flex = 0, so it does not claim stack slack — wrap in Expand for that).
• Expand — flex-basis-zero workhorse for ratio splits and full-bleed children.
• Shrinkable — shrink counterpart to Expand: opts a child into compression (down to a min floor) when a stack is over-constrained. Native shrink covers single-line / ellipsis text; controls (Button etc.) stay rigid and overflow via Toolbar.
• Padding — uniform or per-edge inset around a single child (propagates flex/shrink/min).
• Spacer — flexible empty space that consumes slack via flex = 1.0.
• Divider — 1 dp themed line, horizontal or vertical.
• FixedSize — pins width/height regardless of parent proposal.
• MinSize — clamps response to a floor (touch-target enforcement, etc.).
• MaxSize — clamps response to a ceiling.
• AspectRatio — constrains a child to a fixed width-to-height ratio.
• Switcher — shows one of N children, driven by Signal<usize>.
• DeadZone — layout-transparent gesture dead zone: a press inside it never arms a drag/swipe on an ancestor. Wrap interactive controls (buttons, a ⋮ menu) inside a draggable/swipeable container (a dock-panel header, a card, a list row) so clicking them — even with click jitter — can't start the ancestor's drag. The framework counterpart of Electron's -webkit-app-region: no-drag; backed by the node-level gesture_dead_zone flag (robust by construction, not a recognizer-timing race).
• FocusScope — layout-transparent Tab traversal boundary (lives at crate root). Scopes its descendants' tab_index so sibling regions don't interleave, and traps or passes Tab via TraversalScopePolicy::{Cycle, Continue}. See events-and-gestures.md §6.1.

Visual primitives

Direct draw surfaces with no internal composition.

• RectWidget — themed rectangle (background, border, corner radius); reactive bindings.
• TextWidget — single-line text via the TextBackend; reactive content + color.
• IconWidget — vector icon rendered through the path atlas; IconMode for tinted vs. raw.
• ImageWidget — bitmap with ImageFit (fill / contain / cover / none / scale-down).
• ImageMask — CPU-side anti-aliased alpha mask (ImageMaskShape); used by Avatar and other shaped-image patterns.
• ValidationStrip — inline error/warning/success strip under a field.
• TextInputField — primitive single-line editable text used inside the higher-level field widgets.
• TwistArrow — small chevron that indicates and toggles a tree node's expansion (used by TreeView / TreeTableView).

Containers and chrome

Themed framing, sectioning, and window-level structure.

• Panel — themed background + border + corner radius + padding.
• Card — elevated panel with shadow and optional header/footer slots.
• GroupBox — labelled bordered group for related controls.
• GroupHeader — section header (label + trailing rule line) for settings forms.
• Toolbar — command bar (ToolbarAction/ToolbarItem) with automatic overflow: excess actions collapse into a ⌄ MenuList popover (Qt extension / NSToolbar overflow / WinUI CommandBar). Per-action overflow priority, always_overflow, toggle, pinned custom widgets, collapsible custom widgets (overflow_as menu row / overflow_widget live embedded control / the ToolbarOverflow trait), separators, flexible space, display mode, orientation, is_overflowing(). Full ARIA toolbar a11y (Role::Toolbar + orientation, roving tab-index + arrow nav, chevron HasPopup::Menu, no AT duplication of overflowed items). Built on LayoutContext::measure_intrinsic. Reference: docs/toolbar.md.
• StatusBar — bottom-of-window status text strip with Role::Status.
• Banner — persistent inline info / success / warning / error strip (BannerSeverity); Role::Status + Live::Polite.
• DropZone — standalone "drop files here" target for external (OS) drag-and-drop; accept_extensions filter, allow_multiple, on_files_dropped / on_text_dropped / on_urls_dropped, keyboard Browse fallback; Tier-3 DropZoneStyle, Role::Group + Live::Polite. See drag-and-drop.md §11.4.
• DropTarget — wrapping drop container: turns any child into a drop target without hiding it (the child stays fully visible; the highlight is a border, not a fill). Reacts to internal (typed DragPayload) and external drops; optional centered hint popup; accept_external_* / accept_typed::<T> / accept_when filters, on_drop / on_drop_typed::<T>, targeted_signal (SwiftUI isTargeted pattern); Tier-3 DropTargetStyle, Role::Group. See drag-and-drop.md §11.6.
• Accordion — vertically stacked collapsible sections, multiple-open allowed.
• ToolBox — vertically stacked collapsible pages, exactly one expanded (Qt QToolBox analog).
• ScrollArea — viewport with overlay or permanent scrollbars (ScrollBarMode, ScrollBarPolicy).
• ScrollBar — standalone scrollbar, drag/track-click/keyboard.
• Splitter — N-pane resizable splitter with draggable, collapsible dividers, per-pane stretch, and a serializable SplitterModel. See docs/splitter.md.
• DockingLayout — VS Code-style dockable layout: a centre slot + 4 collapsible/splittable/draggable side regions (leading/trailing/top/bottom), per-corner ownership, activity rail, drag-to-dock five-zone overlay, and a serializable DockingModel. See docs/docking.md.
• TabWidget — tab bar + content switcher; data-source-driven TabBar<T> underneath. See tab-widget.md.
• Stepper — embeddable step-flow widget (Material / Ant / Flutter "stepper"): horizontal or vertical, linear or non-linear, per-step completion state.
• Wizard — thin modal launcher built on Stepper: a multi-step flow with header, footer, and step switching.
• Breadcrumb — clickable path segments with chevron separators (BreadcrumbItem). Automatic overflow: when too narrow the middle crumbs collapse into a trailing-of-root … MenuList dropdown (Windows Explorer / web breadcrumb pattern) while the root + current crumb stay; is_overflowing() signal. RTL-aware separators (chevron mirrors). Built on measure_intrinsic + MenuList::item_when.
• TitleBar — custom window title bar with drag region, resize strip, and window controls. See title-bar.md.

Buttons

• Button — seven ButtonVariants (Filled / Tinted / Outlined / Plain / Ghost / Link / Destructive) × five interaction states; IconLocation for leading/trailing icon; chrome via the ButtonStyle trait (see Styling status above). Reference exemplar — read the source.
• IconButton — square icon-only button at five IconButtonSize steps (Compact / Default / Toolbar / Large / Hero). .embedded() mode for trailing-slot use inside fields. Includes BuiltInIcons factory.
• CommandLinkButton — large two-line CTA: leading icon + bold title + secondary description; flat surface.
• PopoverButton — Button preset that opens a Popover when activated.
• PopoverIconButton — IconButton variant of the same.
• SplitButton — main action region + chevron region that opens a related-actions menu.

Inputs and indicators

• Checkbox — two-state and tristate (CheckState).
• RadioButton — single radio, bound to a shared value via RadioGroup for mutual exclusion.
• RadioTile / RadioTileGroup — "selectable card" radios: icon + title + inline radio + wrapping description. N-ary group with TileLayout::{Row, Grid, Column, Vertical} (equal-size cards, adaptive wrapping grid, or a compact settings list with trailing meta), a WAI-ARIA roving radiogroup keyboard, and Role::RadioGroup + per-tile Role::RadioButton.
• Toggle — on/off control; four ToggleVariants (Switch / Pill / Square / Inset) via the ToggleStyle trait.
• Slider — horizontal or vertical, optional stepping.
• SegmentedControl — segmented chooser keyed by SegmentId (so a contributed segment can't re-point the selection); segments that don't fit overflow into a chevron menu, with the selected one always visible; RadioGroup AT role. See segmented-control.md.
• ComboBox — selection-only dropdown; virtualized via ListView past max_visible_items.
• FontPicker — lists/searches/filters all installed fonts with per-row in-font samples; spacing + writing-system filters (off-thread coverage index). See font-picker.md.
• ProgressBar — determinate or indeterminate; linear.
• Spinner — circular-arc loading indicator on the shader-driven AnimatedQuadKind::SpinnerArc pipeline; honours prefers-reduced-motion.
• Link — typographic hyperlink with hover and visited states.
• Badge — passive count/label pill.
• Avatar — user identity (image / initials fallback / hash-derived tint); circular / rounded-square / square shapes; presence indicator with corner positioning.

Text input family

• TextInput — styled single-line input on top of TextInputField; ValidationState.
• RichTextEditor — full editing surface with IME, formatting commands, undo/redo, intrinsic-mode sizing (min_lines / max_lines); also runs read-only as the rich-text viewer (ScrollPolicy).
• CodeEditor / PlainTextEditor — multi-line source / plain-text editors over one core: gutter, current-line band, injected language-agnostic indentation / comment / bracket handling, multiple carets, caret-anchored completion, paragraph/run accessibility. See docs/code-editor.md.
• LogView — read-only, append-only, tail-following streaming view scaling to 100k+ lines via windowed layout; derived follow-tail, scrollback cap, injected per-line severity colour, windowed accessibility. See docs/log-view.md.
• SpinBox — numeric input with WrapMode, StepType, ButtonLayout, WheelMode, WidthPolicy.
• SearchField — TextInput preset with leading magnifier glyph and clear-X; Role::SearchInput.
• PasswordField — secure entry with an embedded reveal toggle, character masking, Caps Lock warning, and clipboard protection. EchoMode (Masked / NoEcho / RevealWhileTyping), RevealMode (Toggle / Hold / None), AtRevealPolicy (SwapRole / AlwaysProtected). Masks at the text-engine layer (Role::PasswordInput; plaintext never reaches the shaper, glyph atlas, or AT value while masked). Demo: cargo run -p password-field.
• FilePickerField — TextInput + Browse button wired to the native file dialog; FilePickerKind::OpenFile / PickFolder / SaveFile.
• InputDialog — single-field input modal: title + prompt + TextInput + Cancel/OK; on_result delivers Some(value) / None.

Date and time

• Calendar — month grid with WAI-ARIA grid keyboard pattern; CalendarMode::Single / Range (DateRange); WeekNumberDisplay toggle. Locale-derived first day of week and format pattern.
• DateEdit — date input with trailing calendar-icon trigger; WidthPolicy, ValidationBehavior.
• TimeEdit — time input; TimeFormat, SecondsMode.
• DateTimeEdit — combined date + time input.
• DateRangeEdit — two-date range input.

Color

• HexColorInput — hex code text input with live swatch.
• ColorEdit — compact color editor with swatch trigger.
• ColorPicker — full HSV picker; ColorPickerLayout controls panel arrangement.

Menus

• MenuBar — top-of-window menu strip; widget-based on Windows/Linux. On macOS it mirrors a declarative MenuModel into the system NSMenu — MenuBar::from_model(..).native_on_macos(..) + install_native_menu(), see native-menu.md (on-device validation pending). MenuBar::build installs an Rc<dyn MenubarDispatcher> into WindowState on every platform so the framework can intercept F10, Alt+<letter>, and bare-Alt-tap before focus-based key dispatch — matching Win32's WM_SYSKEYDOWN semantics. Returns MenubarAction::{OpenMenu, FocusTrigger, Intercept}. Alt-tap is detected on the WindowState::alt_down falling edge with other_key_pressed_during_alt == false. Mnemonic-derived chords NEVER enter ShortcutRegistry — by construction ShortcutSettings cannot list them, which is the correct behaviour (mnemonics are derived from labels, change with locale, and are not user-rebindable per Win32 / GNOME HIG).

  macOS-specific behaviour: the dispatcher's Alt+<letter> branch is compiled out on macOS because the OS rewrites Option+letter into accented characters (Option+E → ´, Option+F → ƒ) before winit hands the keystroke to the app — the chord can never match the mnemonic table, and intercepting would silently break accented text input. F10, bare-Alt-tap → focus menubar, and bare-letter activation inside an open menu all continue to work on macOS (none involves a transformed letter key). Mnemonic underlines are also hidden on macOS via cfg!(target_os = "macos") in MenuLabel::paint so the UI doesn't promise a chord that won't fire. Use F10 + arrows + Enter for keyboard menu navigation, and the existing Shortcut system for Cmd+? accelerators.

• MenuList — overlay menu panel; accepts arbitrary impl Widget children. MenuSeparator for inline rules. Full keyboard suite: ArrowUp/Down + wrap, Home/End, Enter/Space activates the focused item, ArrowRight opens submenus, ArrowLeft/Esc bubble. Type-ahead with 500 ms default reset (.type_ahead_timeout(d) override), ASCII case-fold, separators skipped. In-menu mnemonic activation: bare letter (no modifiers) inside an open menu activates the item whose &-marker matches; mnemonic wins over type-ahead when both could fire.

• MenuItem — keyboard-highlightable menu row with for_shortcut(id) for live-rebinding labels. Three modes via builder methods:

  • .checked(Signal<bool>) → Role::MenuItemCheckBox, checkmark glyph in the leading slot, click flips the bound signal.
  • .check_state(Signal<CheckState>) → tri-state checkbox; click cycles Unchecked↔Checked (Indeterminate is external-source-only per Windows convention); rendered glyph: check / dash / spacer.
  • .radio(value, Signal<usize>) → Role::MenuItemRadio, filled-dot glyph when selected == value. Radio items in the same MenuList auto-group via Signal::same and announce "2 of N" via push_to_radio_group.

  All four (icon / check / tristate / radio) are mutually exclusive — a debug_assert! fires if both .icon(...) and a check/radio mode are set. AT state mirrors Checkbox exactly: set_toggled(bool) for binary, inner_mut().set_toggled(Toggled::Mixed) for Indeterminate.

• Mnemonics use the in-string Windows / Qt & convention: &Save underlines 'S' when Alt is held; && produces a literal &. MenuLabel (private leaf widget) renders the underline via canvas.draw_underline gated on WindowState::alt_down; the AT name strips the &, and the mnemonic letter is written to inner_mut().set_access_key("S") for Windows Narrator. Parser at mnemonic.rs.

• Safe-triangle submenu hover gate: when a submenu opens, the trigger MenuItem stamps a shared anchor (cursor position at open) into the enclosing MenuList's SafeTriangleState; sibling items, before firing their hover-switch, call point_in_safe_triangle(cursor, anchor, submenu_bounds). The triangle's near edge is inferred from anchor.x vs submenu.x — the algorithm is RTL-symmetric automatically. EventContext exposes tree_pointer_position() + overlay_bounds_for_content(content_id) (snapshotted per dispatch). The existing 150 ms PointerLeave close stays as a graceful fallback.

Overlays and dialogs

See tooltips.md for the tooltip system.

• TooltipWidget — plain, rich, or composite tooltips (three tiers, per-anchor mutual exclusion); sticky-on-dwell promotion to non-modal Role::Dialog; TooltipRegistry for app-wide reuse. Rich tier carries inline markup + shortcut chip + "more" disclosure; composite tier (CompositeTooltipWidget) hosts an arbitrary widget tree (CK3-style: tabbed sections, charts, progress bars).
• Popover — anchored overlay accepting arbitrary impl Widget content; configurable placement, dismissal, optional caret.
• Dialog — modal dialog frame; DialogContent / ModalContainer for content + presentation.
• MessageBox — predefined info/warning/error/question modals (MessageBoxSeverity); semantic-role buttons (ButtonRole, StandardButton, MessageBoxButton, MessageBoxButtons) with platform-aware ordering; result via MessageBoxResult.
• Snackbar — queued auto-dismissing toast with animated slide-in.
• Toast — stackable, action-rich, severity-aware floating notification (info / success / warning / error / loading); link + button actions; Toast::id update-in-place; persistent archive backing; corner-anchored hover-pause stack. The "upgrade path" from Snackbar. Full reference: toast.md.
• ToastHost — per-window invisible widget owning the toast queue + per-frame timer + hover-pause; mounted by install_toast.
• NotificationLog — archive UI: mark-all-read / clear toolbar + day-bucket section headers (Today / Yesterday / This week / Earlier) + replayable action buttons.
• NotificationCenterButton — bell icon + live unread-count badge + popover containing a NotificationLog. Marks-all-read on popover open.
• NotificationLogDialog — one-liner ::show(archive, ctx) modal preset.
• Shadow — drop-shadow primitive used by elevated surfaces (AttachedSide for one-sided shadows).

Data-driven widgets

Backed by the teksilo-data reactive collections. See data-models.md for the underlying ListModel<T> / TreeModel<T> / SelectionModel / sort-filter projections.

• Repeater — non-virtualized siblings driven by ListModel<T> change notifications; for small bounded collections.
• ListView — virtualized vertical list for large/unbounded collections.
• GridView — virtualized 2D tile grid (photo-gallery / icon-view / collection-view) bound to ListModel<T> / ListDataSource. Pluggable GridLayoutStrategy: UniformGrid (fixed size / fixed column count / adaptive min-width), VariableRowGrid (rows sized to tallest tile, auto-measure + scroll-anchoring or exact .item_height), VirtualizedMasonry (Pinterest waterfall). Flat SelectionModel (Single/Multi) with click/Ctrl/Shift + rubber-band marquee, full 2D keyboard nav (arrows / Home-End / PageUp-Down / type-ahead / Alt+Arrow reorder), drag-to-reorder routed through the source's drag/can_accept/accept_drop (+ on_item_drop escape hatch for foreign payloads), per-tile activation + context menu, sections (grouping_sections) with sticky pinned headers, empty/loading states, source-driven lazy loading (request_window + can_fetch_more/fetch_more + placeholder rows), and Role::Grid > Role::GridCell accessibility. See grid-view.md; demo cargo run -p grid-view.
• TreeView — hierarchical list with twist-arrow expand/collapse. The 4-arg new_with_context variant passes a TreeRowContext carrying a one-line toggle_callback() for chevron wiring.
• StandardListItem — canonical row layout for ListView delegates: [checkbox?] [leading_slot?] [center_slot?] [label] [Spacer] [trailing_slot?], plus an optional subtitle line with its own [subtitle_leading_slot?] [subtitle] [Spacer] [subtitle_trailing_slot?]. Selection / hover / pressed background routes through SurfaceRole::Selected / AccentSubtle / Pressed (theme-driven, rounded item_corner_radius: 8.0, mirrors MenuItem / ComboBox). Optional two-state (Signal<bool>) or tri-state (Signal<CheckState>) checkbox at the start of the row, independent of row selection. See the worked example in examples/data_collections/src/main.rs.
• StandardTreeItem — StandardListItem plus depth-driven indent and a chevron column (always reserved, even for leaves, so labels at the same depth align). .from_entry(&FlatEntry) sets depth + has_children + is_expanded in one call; .on_toggle(...) / .on_toggle_rc(...) wires the chevron tap to a TreeSliceHandle::toggle_expand callback (cleanest with TreeView::new_with_context).
• TableView — multi-column, virtualized; sort/filter via SortFilterListModel, drag-resize and drag-reorder columns, pinned Leading/Trailing, cell + row selection, edit hooks, row drag-drop reorder, full Role::Table AT tree. See table-view.md.
• TreeTableView — hierarchical multi-column variant of TableView; Role::TreeGrid.

Worked TreeView delegate using both new pieces:

#![allow(unused)]
fn main() {
let tree_checks: TreeCheckedModel<Item> = state.app_state();
TreeView::new_with_context(model, move |item, entry, selected, ctx| {
    let mut row = StandardTreeItem::new(lit!(&item.title))
        .from_entry(entry)
        .selected(selected)
        .on_toggle_rc(ctx.toggle_callback());
    if entry.has_children {
        row = row.tristate_checkbox(tree_checks.signal_for(entry.node_id));
    }
    Box::new(row)
})
}

Charts — crates/teksilo-charts/src/

Sits at the same tier as teksilo-widgets (no dep on widgets). Series data is a ChartModel<T> (teksilo-data, see data-models.md), not a Prop/ Signal-bound Vec. See charts.md.

• BarChart — vertical or horizontal bars; single or grouped series; optional value labels, axis labels, grid lines, hover tooltips.
• LineChart — points connected by polylines; single or multiple series; optional area fill; hover tooltips on data points.
• PieChart — pie + donut variants; donut variant has a center slot.

All three sit on the Tier-3 styling ladder via ChartStyle (.style(...) / theme.style_slots.chart) — an all-recipe trait distinct from the widget world's make_*(cfg, ctx) -> WidgetId traits; its default RecipeChartStyle lives in teksilo-charts itself, not teksilo-widgets/src/styles/* (see styling-system.md). Gridlines support dashed/dotted patterns (theme-wide via a custom ChartStyle, or per-axis via AxisConfig::gridline_dash); area and donut fills support gradients. Full reference: charts.md §11.

Shared infrastructure (axis.rs, legend.rs, palette.rs, layout.rs, hit.rs) is reused across all three; ChartSeries<T> / ChartDatum<T> construction DTOs live in teksilo-data and are re-exported from teksilo_charts.

Animation wrappers — crates/teksilo-widgets/src/animations/

Wrappers that animate a child subtree without the caller managing scheduler state. See animation.md for Signal<f32>::animate_to and the underlying scheduler.

• Fade — opacity tween 0↔1; layout-transparent.
• Pulse — sine-driven looping opacity oscillation (recording-indicator pattern).
• Cycle — cycles through children on a fixed period.
• Crossfade — keyed builder; old fades to new on key change.
• Collapse — height-collapse tween used by Accordion and disclosure patterns.
• Unroll — the horizontal sibling of Collapse: a width-unroll tween for side panels and inline reveals.
• SmoothSize — auto-sizes to the child's intrinsic size and animates every change (SmoothSizeAxes).
• Slide — slides a child in/out from a chosen edge (SlideEdge); layout-stable.
• Shake — damped horizontal oscillation triggered by a Signal<u32> bump (invalid-input feedback).
• Scale — uniform 2D scale 0↔1 (ScaleOrigin); visual-only by default, optional layout-driving mode.
• Rotate — rotates a child subtree by a Prop<f32> angle in radians.
• Blur — Gaussian-equivalent blur on the child subtree via dual-Kawase chain; sub-perceptual radii are zero-cost.

Settings widgets

Pre-built UI for common app-level concerns.

• ShortcutSettings — full keyboard-shortcut rebind UI (Rebind / Reset / conflict auto-unbind / key capture). See shortcut-intent-action.md.
• PrivacySettings (telemetry feature) — consent toggles for telemetry adapters; ties into the telemetry.md consent gate.
• TextScaleControl — a specialized SpinBox (80 %–200 %) for the global "grow all text" accessibility setting; binds the persisted TEXT_SCALE_KEY, applies app-wide on edit. See text-scale.md.
• ThemeSwitcher — drop-in app-theme picker for settings screens & toolbars (native / OS-follow themes, persistence); applies app-wide on select.
• LanguageSwitcher — drop-in UI-language picker for settings screens; switches the active locale app-wide. See i18n.md.

Cross-references

• Layout protocol and slack distribution: layout-primitives.md
• Events, gestures, focus, attached handlers: events-and-gestures.md
• Accessibility overrides on every widget: accessibility-overrides.md
• Animation scheduler and MotionTokens: animation.md
• Theming and role-based color resolution: reactive-theme.md
• Drag and drop integration: drag-and-drop.md
• Settings persistence (SettingsStore, SettingsFile<T>, MruList<T>): settings.md
• Global text-scale accessibility setting (TextScaleControl, ctx.text_scale, follow_text_scale): text-scale.md
• i18n (tr!, tr_signal!, locale-aware formatting): i18n.md
• Shortcuts / intents / actions: shortcut-intent-action.md
• Multi-window orchestration: multi-window.md
• Inspector for runtime introspection: inspector.md
• Framework internals (Canvas, rendering pipeline, threading, testability): architecture.md
• Full per-widget API extraction: python3 tools/extract_widget_api.py <Widget…> or --all

Layout Primitives

Companion to: architecture.md §2 (Layout Model) Scope: Reference for the layout primitives in crates/teksilo-widgets/src/primitives/ — the containers and size wrappers every other widget composes against.

This document is a working reference: each primitive comes with a one-line summary, the public surface as you'd actually call it, the rule the layout engine applies, and at least one runnable example. Where two primitives can express the same intent, the trade-off is called out explicitly.

1. Mental model

Teksilo layout is a SwiftUI-style two-phase negotiation, recursive over the widget tree:

1. The parent calls child.layout_response(proposal, ctx). The child returns a LayoutResponse { size, flex, min, shrink } — the size it wants (a floor for growth), a flex weight for positive-slack distribution, a min compression floor, and a shrink weight for over-constraint deficits. flex and shrink are independent (CSS-flexbox grow vs shrink); From<Size> defaults to fully rigid (flex = 0, shrink = 0, min = size).
2. The parent decides each child's main-axis size (grow on surplus, shrink on a deficit), then measures each child's cross axis at its final main size (height-for-width), then calls child.place_children(bounds, …) to position them.

SizeProposal { width: Option<f32>, height: Option<f32> } is the parent's offer. Some(_) means use this exact value; None means measure yourself, this axis is open. Stacks pass None on their main axis to let children declare their wanted size, and Some(bounds.cross) on the cross axis to let children fill it.

Three rules underlie every primitive in this document:

• Honest sizing. A widget that knows its size returns it. A widget that wants slack returns flex > 0. The parent makes the placement decision; the child does not place itself.
• Slack is a single rule. In an HStack/VStack, slack = bounds.main − Σ wanted − Σ spacing. When slack ≥ 0 each child's final size is wanted + (flex / Σ flex) × slack. When slack < 0 (over-constraint) the deficit is distributed across children with shrink > 0 proportional to their shrink weight, never below min (iterative clamp-and-redistribute). There is no special "spacer"/"expand"/"shrinkable" branch in the engine — they are ordinary widgets that report flex > 0 / shrink > 0.
• Logical pixels, Leading / Trailing. All values in f32 logical px; the renderer multiplies by scale factor at the boundary. Leading / Trailing flip with LayoutDirection::RightToLeft.

Everything in the rest of this document follows from those three rules.

Stacks (HStack/VStack)              ZStack                  Grid
┌─ HStack ───────────────────────┐  ┌─ ZStack ─────────┐    ┌─ Grid ────────┐
│ A │ B │     slack     │ C │    │  │ ┌───────┐         │    │ A │ B │ C │
│   │   │  ←→ via flex  │   │    │  │ │  bg   │ ┌─fg─┐ │    ├───┼───┼───┤
└─  └─  └─────────────  └─  └─  │  │ └───────┘ └────┘ │    │ D │ E │ F │
                                   │   align=center      │    └───┴───┴───┘
                                   └────────────────────┘

2. The stack containers

Three containers cover almost everything: VStack, HStack, ZStack. They share the deferred children idiom — .child(widget) queues an inline child, .add_child(id) references a pre-registered WidgetId, .children(iter) adds many at once, .child_opt(opt) is a no-op when None. Pick whichever fits the call site; you can mix them on one builder.

2.1 VStack — vertical stack

crates/teksilo-widgets/src/primitives/vstack.rs

Lays children top-to-bottom. Cross-axis (horizontal) alignment is HAlignment — default Leading. Spacing accepts a static f32 or a Signal<f32>.

#![allow(unused)]
fn main() {
use teksilo::prelude::*;

VStack::new()
    .spacing(8.0)
    .alignment(HAlignment::Center)
    .child(TextWidget::new(lit!("Title")).style(TextStyleRole::BodyBold))
    .child(TextWidget::new(lit!("Subtitle")))
    .child(Button::new(lit!("Save")))
}

Sizing rule: wants Σ heights + spacing on the main axis, max(width) on the cross axis. If any child reports flex > 0 and the parent bounds the height, the VStack greedily claims the offered height so slack exists.

Cross-axis floor. Every child receives the VStack's full width as its proposal.width. A TextWidget in TextOverflow::Wrap will measure-and-wrap against that width; an HStack child fills that width.

2.2 HStack — horizontal stack

crates/teksilo-widgets/src/primitives/hstack.rs

Mirror of VStack. Cross-axis (vertical) alignment is VAlignment — default Center. RTL-aware: in LayoutDirection::RightToLeft, children are placed right-to-left automatically. There is no manual mirroring.

#![allow(unused)]
fn main() {
// Inside build(): bind spacing reactively to a theme token.
let gap = ctx.theme_signal().map(|t| t.layout.control_gap);

HStack::new()
    .spacing(gap)
    .alignment(VAlignment::Center)
    .child(IconWidget::checkmark(16.0))
    .child(TextWidget::new(lit!("Save")))
    .child(Spacer::new())
    .child(Button::new(lit!("Cancel")))           // pushed to trailing edge
}

2.3 ZStack — overlay stack

crates/teksilo-widgets/src/primitives/zstack.rs

Children overlap; later children paint on top. Size is the max of children's intrinsic sizes; the proposal is only used as a fallback when no child has a queryable size. Container-level alignment is a full Alignment (both axes); per-child override via tree.set_alignment(id, …).

#![allow(unused)]
fn main() {
ZStack::new()
    .alignment(Alignment::TOP_TRAILING)
    .child(image_view)                              // the background
    .child(                                          // close button in the corner
        Button::new(lit!("×"))
            .on_activate_fn(|ctx| ctx.send_intent(AppIntent::Close)),
    )
}

A common pattern: full-bleed background + foreground. Background widgets that report 0×0 for an unspecified proposal (e.g. RectWidget::new()) do not inflate the stack — only children with non-zero intrinsic size do. The place_children call then proposes the full ZStack bounds to every child, so an unsized background fills it.

2.4 Per-child alignment override

Container-level alignment applies uniformly. To diverge for one child, call tree.set_alignment(child_id, Alignment::BOTTOM_TRAILING). The override always takes a full two-axis Alignment; an HStack reads only the vertical axis, a VStack reads only the horizontal axis, a ZStack reads both. The override lives on the arena node, so it survives reactive theme switches, language flips, and reordering.

3. Slack and flex

Slack is the leftover space inside a stack after every child's wanted size and the inter-child spacing have been honored. It's distributed proportionally to each child's flex weight. Default flex is 0 (rigid). Two primitives ship flex > 0:

3.1 Spacer — fills available space

crates/teksilo-widgets/src/primitives/spacer.rs

Returns LayoutResponse::flexible(Size::new(min, min), 1.0). The min-length is a floor on the main axis (default 0); the parent stack adds slack share on top.

#![allow(unused)]
fn main() {
HStack::new()
    .child(label)
    .child(Spacer::new())
    .child(button)                                  // pushed to trailing

HStack::new()
    .child(Spacer::new())
    .child(label)
    .child(Spacer::new())                           // centers `label`

HStack::new()
    .child(a)
    .child(Spacer::new().min_length(20.0))           // ≥ 20 px gap, more if available
    .child(b)
}

3.2 Expand — claim space and fill a child

crates/teksilo-widgets/src/primitives/expand.rs

Expand is the workhorse. It returns flex (default 1.0) and stretches its single child to its allocated bounds. Unlike Spacer, it has a child.

#![allow(unused)]
fn main() {
// Single panel filling the rest of the row:
HStack::new()
    .child(sidebar)
    .child(Expand::new().child(main_panel))

// Ratio splits — Category-A flex layouts:
HStack::new()
    .child(Expand::new().flex(1.0).child(left))     // 1/3 of slack
    .child(Expand::new().flex(2.0).child(right))    // 2/3 of slack

// Single-axis variants — name the axis you compete for slack on:
VStack::new()
    .child(header)                                   // intrinsic height
    .child(Expand::vertical().child(content))        // takes remaining vertical
    .child(footer)

// Opt out of fill — align the child at its natural size in claimed space:
Expand::new()
    .align_child(Alignment::CENTER)                  // == Center::new()
    .child(label)
}

Zero-basis vs auto-basis (CSS analog)

By default Expand reports wanted = 0 on its flex axes. That's CSS flex-basis: 0 — slack divides cleanly by weight, regardless of the child's natural size. [Expand::flex(1).child(60), Expand::flex(2).child(40)] in 300 px splits exactly 100 / 200.

Switch with .respect_intrinsic() (CSS flex-basis: auto) when the parent is unconstrained on the flex axis. The child's natural size acts as a floor and slack is added on top. Use this inside an outer VStack with height = None, where zero-basis would let the child overflow because the parent has no bound to share.

Trade-off (called out at expand.rs:130): with respect_intrinsic, exact ratios bend by content. The same [1, 2] split inside a 300 px parent now gives 60 + 66 = 126 and 40 + 133 = 173 rather than 100 / 200. Keep zero-basis for ratio layouts and reach for respect_intrinsic only when you actually need the floor.

horizontal() / vertical() semantics

The named axis is the one the wrapper competes for slack on. Cross-axis behavior depends on whether the parent bound that axis:

• Expand::vertical() inside a VStack (parent binds width, distributes height) — fills the VStack's full width AND distributes vertical slack.
• Expand::horizontal() inside a VStack — claims the VStack's full width, but reports flex = 0 on the open vertical axis. It does not steal vertical slack from siblings — height stays at child intrinsic.

Symmetric for HStack. The behavior is documented and tested at expand.rs:25-41.

3.3 Center — center a child within given space

crates/teksilo-widgets/src/primitives/center.rs

Centers a single child within the space Center is given. Per axis: it fills an axis the parent bounded and shrink-wraps to the child on an axis the parent left open. It reports flex = 0 — a pure alignment wrapper, not a space-claiming one.

#![allow(unused)]
fn main() {
Center::new().child(spinner)
}

Consequence: a bare Center inside an HStack / VStack does not grab the stack's slack — a stack leaves its main axis open, so Center sizes to its child there (like Flutter's Center / Align, or Compose's Box), rather than collapsing to zero. To center a child within the leftover space of a stack, give it flex with Expand: Expand::horizontal { Center { w } } (the analogue of Flutter's Expanded(child: Center(...))).

The child is measured under the constraint Center received (a loose-but-bounded proposal, like Flutter's loose constraints): rigid children keep their natural size and are centered; adaptive children respond to the bound — an ellipsis TextWidget truncates at the slot width instead of overflowing symmetrically around the center, and wrapping text reports its real wrapped height. Expand's .align_child(...) mode measures its child the same way.

3.4 Shrinkable — opt a child into compression

crates/teksilo-widgets/src/primitives/shrinkable.rs

The shrink counterpart to Expand. By default widgets are rigid: when a stack is over-constrained they keep their wanted size and overflow. Wrap a child in Shrinkable to let it absorb a share of the deficit, down to a floor:

#![allow(unused)]
fn main() {
// The label yields space before the (rigid) icon when the row is narrow:
HStack::new()
    .child(Shrinkable::new().min_width(40.0).child(long_label))
    .child(icon) // rigid — shrink == 0, never compresses
}

Shrinkable preserves its child's flex (so a child can both grow and shrink) and forwards the proposal unchanged; when the stack compresses it, the child re-lays-out at the smaller size (a wrapped-text child re-wraps and reports its taller height via the height-for-width pass). The floor defaults to 0 on both axes — set .min_width / .min_height. Set .shrink(w) to weight how much of the deficit this child takes relative to siblings; .shrink(0.0) makes it rigid again.

"Compress A before B" = give A shrink > 0 and B shrink = 0: A absorbs the entire deficit (down to its floor) before B is touched.

Native shrink (no wrapper needed). Single-line / ellipsis TextWidget opts in for you: it reports shrink = 1 with a min of the ellipsis-glyph width, so display labels truncate-to-fit (tune with .min_shrink_width, disable with .no_shrink). Controls (Button, IconButton, Badge, ComboBox) are deliberately rigid — a truncated action reads poorly, so the desktop convention is to overflow excess actions into a menu rather than shrink them (see Toolbar). The wrappers Padding / ZStack / MinSize propagate flex + shrink + min, so a shrinkable child stays shrinkable through them, and a stack advertises its aggregate grow/shrink to its parent only on its own main axis.

3.5 Height-for-width

A stack decides each child's main-axis size first, then measures the cross axis at that final size. So a child whose height depends on its width — wrapped text, an AspectRatio image — reports the correct height for the width it actually got, and that height propagates up the tree (a wrapped paragraph in a narrowed Shrinkable grows taller, and its row grows with it).

To keep the resulting main-then-cross queries linear, layout_response is memoized per (widget, proposal) for the duration of a layout pass (WidgetArena::cached_layout_response, cleared each pass). A widget that deliberately writes state from layout_response (e.g. a debug probe) opts out via Widget::cacheable_layout() -> false.

Debugging over-constraint. When children still spill past their distributing parent (nothing left to shrink), the debug inspector paints Flutter-style yellow/black hazard stripes on the overhang — on by default, F12. See docs/inspector.md. Demo: cargo run -p over-constraint.

4. Size wrappers

Five primitives constrain what their child can be:

4.1 FixedSize

crates/teksilo-widgets/src/primitives/fixed_size.rs

#![allow(unused)]
fn main() {
// Static width, child decides height:
FixedSize::new().width(280.0).child(content)

// Reactive — animated sidebar:
let sidebar_width = ctx.animated_signal(280.0);
let sidebar = FixedSize::new()
    .width(sidebar_width.clone())
    .child(sidebar_content);

// Later, on toggle:
ctx.animate().normal().standard().to_or_snap(&sidebar_width, 0.0);
}

Both width and height accept impl Into<Prop<f32>> — pass an f32 for static, a Signal<f32> for reactive. The bound proposal is forwarded to the child, so wrap-aware children (TextWidget in TextOverflow::Wrap, ScrollArea, etc.) measure against the right constraint.

Without any binding, FixedSize just reports the child's natural size and ignores the parent proposal. That's how you opt a widget out of stretching inside an HStack where siblings expand.

4.2 MinSize

crates/teksilo-widgets/src/primitives/min_size.rs

#![allow(unused)]
fn main() {
// 48×48 minimum touch target — the Button composite uses this internally:
MinSize::new(48.0, 48.0).child(content)

// Single axis:
MinSize::width(120.0).child(label)
MinSize::height(36.0).child(row)

// Reactive:
MinSize::width(0.0).min_width(min_w_signal).child(text)
}

The proposal forwarded to the child is clamped upward to the minimum. A wrapping TextWidget inside MinSize::width(100) measures against width >= 100, so its wrapped height reflects the minimum width — not the unconstrained natural width. Tested at min_size.rs:230-258.

4.3 MaxSize

crates/teksilo-widgets/src/primitives/max_size.rs

#![allow(unused)]
fn main() {
// Reading-width cap on a long article:
MaxSize::width(640.0).child(article_text)

// Both axes — modal content with hard ceiling:
MaxSize::new(800.0, 600.0).child(dialog_content)

// Reactive — user-resizable panel:
MaxSize::width(9999.0).max_width(panel_width).child(content)
}

Symmetric to MinSize: proposal clamped downward, wanted size clamped downward. Sets clips_children: true when any constraint is active — content that exceeds the cap is scissored, not bled. Hidden from the accessibility tree (builder.set_hidden()).

4.4 AspectRatio

crates/teksilo-widgets/src/primitives/aspect_ratio.rs

#![allow(unused)]
fn main() {
AspectRatio::widescreen().child(video_thumbnail)     // 16:9
AspectRatio::square().child(avatar)                  // 1:1
AspectRatio::new(4.0 / 3.0).child(legacy_photo)
}

Picks the largest size matching the ratio that fits the proposal. Given width = Some(w), height is w / ratio. Given height = Some(h), width is h × ratio. Given both, fits within both. Given neither, returns 0×0 — always wrap an unconstrained AspectRatio in a parent that bounds at least one axis.

The child fills the resolved bounds.

4.5 Padding

crates/teksilo-widgets/src/primitives/padding.rs

#![allow(unused)]
fn main() {
// All four insets:
Padding::new(16.0, 24.0, 16.0, 24.0).child(content)  // top, right, bottom, left

// Symmetric — vertical and horizontal pairs:
Padding::symmetric(12.0, 16.0).child(content)

// Uniform:
Padding::uniform(16.0).child(content)

// Reactive — track a theme-derived inset:
let pad = ctx.theme_signal().map(|t| t.layout.section_gap);
Padding::uniform(pad).child(content)
}

All four arguments accept impl Into<Prop<f32>> — static or reactive. The child is proposed parent − insets; the wrapper reports child + insets. No alignment — the child is anchored to the inner top-leading corner and stretched to fill the inner rect.

5. The grid and flow containers

For tables of mixed-size content, multi-column flow, and form-style label/field pairs.

5.1 Grid — explicit row and column tracks

crates/teksilo-widgets/src/primitives/grid.rs

Children are placed in row-major order — child i goes to row i / cols, column i % cols. Tracks come in three sizing modes:

#![allow(unused)]
fn main() {
use teksilo::widgets::{Grid, TrackSize};

// 3 columns: [auto | 1fr | 80px], 2 rows of intrinsic height
Grid::new()
    .columns(vec![
        TrackSize::Auto,
        TrackSize::Fractional(1.0),
        TrackSize::Fixed(80.0),
    ])
    .rows(vec![TrackSize::Auto, TrackSize::Auto])
    .column_gap(8.0)
    .row_gap(4.0)
    .child(label_a)
    .child(field_a)
    .child(unit_a)
    .child(label_b)
    .child(field_b)
    .child(unit_b)
}

• Fixed(px) — exactly that many logical pixels.
• Auto — sized to the largest child intrinsic size in that track.
• Fractional(weight) — splits remaining space (after Fixed and Auto are claimed) by weight.

Two-pass layout. Auto tracks are resolved against children's unspecified-proposal width. Fractional tracks then take the remainder. Children that landed in Fractional columns narrower than their intrinsic single-line width are re-measured at the resolved column width — wrapping content reports its actual wrapped height instead of bleeding outside its cell. See grid.rs:159-223 for the reasoning.

Both column_gap and row_gap accept impl Into<Prop<f32>>.

5.2 Wrap — line-breaking flow

crates/teksilo-widgets/src/primitives/wrap.rs

A horizontal flow that wraps to the next line when a child won't fit. Each child keeps its intrinsic size; lines are packed greedily.

#![allow(unused)]
fn main() {
Wrap::new()
    .spacing(8.0)                  // between items on a line
    .line_spacing(4.0)              // between lines
    .children(tag_strings.iter().map(|t| Badge::new(lit!(t.clone()))))
}

Reports total height = Σ line heights + line gaps, where each line's height is the max child height on that line. Width reports the longest line (so an unconstrained Wrap collapses to its widest single-line case — wrap it in something that bounds width to actually trigger wrapping).

Use cases: tag clouds, toolbar overflow, chip lists, breadcrumb segments that fold to a second line on narrow windows.

5.3 MasonryLayout — Pinterest-style packing

crates/teksilo-widgets/src/primitives/masonry.rs

Variable-height grid where each child slots into the shortest column at the time. Column count is fixed; column width is (available_width − gaps) / columns. RTL-aware (column 0 is the rightmost in RTL).

#![allow(unused)]
fn main() {
MasonryLayout::new(3)               // 3 columns
    .column_spacing(12.0)
    .item_spacing(8.0)
    .children(photos.iter().map(|p| PhotoCard::new(p.clone())))
}

Each child is queried at column-width to get its real height, then placed under the shortest column. Ties break leftmost-first. Used for heterogeneous-height cards where you want dense packing without the rigid row breaks of a grid.

When to choose: masonry over grid when item heights vary a lot and you don't mind that the visual row alignment is broken; grid over masonry when columns must align horizontally.

5.4 ColumnFlow — responsive columns that reflow

crates/teksilo-widgets/src/primitives/column_flow.rs

The newspaper model. Content runs down column 0, then down column 1. The column count is derived from the available width and min_column_width; when the width no longer affords N columns the layout drops to N−1 and every child is re-partitioned across the survivors. Children are atomic — one child never straddles a column boundary.

#![allow(unused)]
fn main() {
ScrollArea::new().child(
    ColumnFlow::new()
        .min_column_width(240.0)   // as many ≥240 dp columns as fit
        .max_columns(4)            // …but never more than 4
        .column_spacing(16.0)
        .item_spacing(12.0)
        .children(articles.iter().map(|a| ArticleCard::new(a.clone()))),
)
}

Pair it with a ScrollArea for vertical overflow: ColumnFlow reports its true content height (the tallest column), so the scroll extent comes out right.

Reading order is the whole design

Children are distributed as contiguous runs in source order — column 0 takes children 0..i, column 1 takes i..j. So source order, visual reading order, and focus order are the same thing at every column count:

 wide                            narrower
┌────┐ ┌────┐ ┌────┐            ┌────┐ ┌────┐
│ 1  │ │ 3  │ │ 5  │            │ 1  │ │ 4  │
├────┤ ├────┤ ├────┤            ├────┤ ├────┤
│ 2  │ │ 4  │ │ 6  │    ───►    │ 2  │ │ 5  │
└────┘ └────┘ └────┘            ├────┤ ├────┤
                                │ 3  │ │ 6  │
                                └────┘ └────┘
reading order: 1..6             reading order: 1..6

This is why ColumnFlow does not reuse MasonryLayout's shortest-column packing: masonry interleaves children (child 4 may land above child 3), which divorces the visual order from the source order. Teksilo's focus traversal and its AccessKit walk both derive from tree order, so an interleaving layout would read out of order. WCAG 1.3.2 Meaningful Sequence names multi-column text as its first example and blesses exactly this column-major order.

Because the order is right by construction, no aria-flowto is needed — that attribute is an advisory fallback for when the logical order is wrong, and it doesn't affect Tab order anyway.

Balancing

The partition minimises the tallest column, subject to keeping runs contiguous, and uses exactly k columns when there are at least k children. Six equal cards in three columns give [2, 2, 2]; four equal cards in three columns give [2, 1, 1] rather than [2, 2, ∅] — both have the same tallest column, but stranding a trailing column looks broken.

Internally this bisects the column extent (greedy fill is the feasibility oracle) over a fixed iteration count. layout_response and place_children each run the search from scratch — there is no persisted partition state, following MasonryLayout — so the search is deterministic by construction and both hooks agree.

Column width

Set max_column_width when few columns fit a large display — two columns on a 4K monitor are otherwise ~1900 dp wide and unreadable. It's the same reason KDE's Kirigami.CardsLayout pairs minimumColumnWidth with maximumColumnWidth.

Reacting to the count

column_count_signal() -> Signal<usize> publishes the live count, written from the layout pass behind an equality guard so it only fires on a real change.

Binding contract. Safe for RepaintOnly / AccessibilityOnly consumers, and for Relayout consumers that do not feed back into this widget's own width. The count is a pure function of the width ColumnFlow is given — it never changes its own width, so it cannot oscillate on its own. But a Relayout consumer that resizes something which in turn resizes the ColumnFlow closes a feedback loop through the layout pass, which is what Widget::place_children's own documentation warns against.

Accessibility

By default ColumnFlow emits a bare Role::GenericContainer carrying no properties, and the accessibility walker prunes it, promoting the children to its parent in source order. That is the right outcome: a layout primitive contributes geometry, not meaning, and the reading order is already correct. Setting any property here — even an orientation — would keep the node alive as AT noise. For a layout, maximum accessibility means being invisible to assistive tech while preserving order.

Add semantics from the outside with the usual overrides:

#![allow(unused)]
fn main() {
ColumnFlow::new()
    .children(cards)
    .access_role(Role::Region)          // a landmark users can jump to
    .access_label(tr!(latest_stories()))
}

Or opt into list semantics when the children genuinely are a list of peers:

#![allow(unused)]
fn main() {
ColumnFlow::new().semantic_list(true).children(cards)
// container → Role::List; each child → Role::ListItem with
// position_in_set / size_of_set, so AT announces "list, 30 items",
// "item 5 of 30". Costs one node per child.
}

It is deliberately not Role::Grid: the ARIA grid pattern mandates arrow-key cell navigation and roving focus, which GridView implements and ColumnFlow does not. Claiming the role without the contract would lie to AT.

Column rule

.column_rule(width, color) draws a hairline centred in every inter-column gap — CSS column-rule. Decorative only; it emits no accessibility node. Pass BorderRole::Divider to track the theme.

Two limitations worth knowing

• ColumnFlow is rigid (flex = 0, shrink = 0). It adapts when width is decided for it — as a VStack child, inside a ScrollArea, at a window root. As an HStack main-axis child it gets its natural width and won't reflow; wrap it in Expand to claim main-axis width. Same as Wrap.
• It is not a CSS multicol port. CSS column-fill: balance balances within a column height it computes from a bounded block size. ColumnFlow derives the column count from the width and lets the height run free. No CSS column-fill mode does that.

When to choose: ColumnFlow when the column count should follow the width and items must read in order (article lists, card collections, settings panels). MasonryLayout when the count is fixed and dense packing beats reading order. Grid when cells must align in rows and columns. GridView when the items come from a ListModel and you need virtualization or cell-level keyboard navigation.

5.5 FormLayout — two-column label / field

crates/teksilo-widgets/src/primitives/form_layout.rs

A specialized two-column layout: label column auto-sizes to the widest label, field column takes the rest. Supports full-width rows for separators or wide inputs.

#![allow(unused)]
fn main() {
// host, port, timeout are Signal<String> / Signal<u16> / Signal<u32>.
FormLayout::new()
    .label_gap(12.0)
    .row_spacing(8.0)
    .label(tr!(connection_settings()))           // emits Role::Form landmark
    .line(TextWidget::new(tr!(host())), TextInput::new(host))
    .line(TextWidget::new(tr!(port())), SpinBox::new(port, 0u16, 65535u16))
    .full_width(Divider::new())
    .full_width(GroupHeader::new(tr!(advanced())))
    .line(TextWidget::new(tr!(timeout_ms())), TextInput::new(timeout))
}

• .line(label, field) adds a paired row.
• .full_width(widget) adds a row spanning both columns — sections, dividers, full-width inputs.
• .label(LocalizedString) opts in to the Role::Form accessibility landmark with that name. Without a label, the layout demotes to GenericContainer — an unnamed landmark hurts AT users more than it helps. Pass tr!(…) directly.

Row height is max(label.height, field.height). The label column width is the widest label intrinsic — every row's label cell is sized to that uniform width, so the field columns line up vertically across all rows.

5.6 Switcher — show one child at a time

crates/teksilo-widgets/src/primitives/switcher.rs

Internally a ZStack where each child has a visible_when binding derived from selected.map(|i| i == index). Layout is the size of the active child.

#![allow(unused)]
fn main() {
let page = Signal::new(0_usize);

Switcher::new(page.clone())
    .child(welcome_view)
    .child(settings_view)
    .child(about_view)

// Elsewhere: page.set(2);   // jumps to about_view
}

Use for tab content, wizard pages, or any "one of N visible" pattern. Hidden from the accessibility tree itself — the visible child supplies the AT presentation. Switcher::capture_child_ids_into(rc) exposes child IDs to callers that need to wire AT relationships (TabWidget does this for the Tab → TabPanel controls link).

6. Spacers and visual separators

6.1 Divider — themed separator line

crates/teksilo-widgets/src/primitives/divider.rs

A 1 px (theme-tokenable) line. Horizontal by default, fills the proposal's main axis, claims thickness on the cross axis.

#![allow(unused)]
fn main() {
VStack::new()
    .child(header)
    .child(Divider::new())                          // full-width horizontal rule
    .child(body)

HStack::new()
    .child(left_pane)
    .child(Divider::vertical().thickness(2.0).color(BorderRole::Strong))
    .child(right_pane)
}

color() accepts the full ColorProp range — Color, a role (typically BorderRole), or Signal<Color>. Defaults to BorderRole::Divider. Emits Role::Splitter to AT.

Note: Divider is a visual separator, not a draggable splitter — for drag-to-resize panes, use SplitView from teksilo-widgets.

6.2 Spacing summary

7. When to use which

When two primitives could express the same thing, prefer the more specific one — the name is a hint to the next reader. Spacer::new() instead of Expand::new() when you mean "empty pushable region." MinSize::new(48, 48) instead of FixedSize::width(48.0).height(48.0) when you mean "at least," not "exactly." (Note Center is not a synonym for Expand::new().align_child(CENTER) — it reports flex = 0 and shrink-wraps an open axis, so it does not claim stack slack; see §3.3.)

8. Reactive sizing

Every size constraint that takes an impl Into<Prop<f32>> is reactive. Pass an f32 for a static value, a Signal<f32> for reactive, or use BuildContext::animated_signal(value) for an animatable one.

Whenever a bound size value changes, the framework dirty-marks the wrapper for relayout (not just repaint). The relayout starts at the highest dirty ancestor and runs layout_response + place_children for each dirty subtree; clean subtrees are skipped. This is the same incremental-layout model browsers and Qt use.

#![allow(unused)]
fn main() {
// Animated drawer:
let drawer_w = ctx.animated_signal(0.0);
let drawer = FixedSize::new()
    .width(drawer_w.clone())
    .child(drawer_content);

let toggle = Button::new(lit!("Open"))
    .on_activate_fn({
        let drawer_w = drawer_w.clone();
        move |ctx| {
            let target = if drawer_w.get() > 0.0 { 0.0 } else { 280.0 };
            ctx.animate().normal().standard().to_or_snap(&drawer_w, target);
        }
    });
}

Behavior under prefers-reduced-motion: to_or_snap snaps the value instead of tweening. The relayout still fires, just once instead of per-frame.

9. Composing your own

A custom layout container is an ordinary Widget that returns children from build(), picks a wanted size in layout_response, and places its children in place_children. The layout engine doesn't care whether a widget is shipped in teksilo-widgets or written in your app crate.

#![allow(unused)]
fn main() {
use teksilo_canvas::{Point, Rect, Size, SizeProposal};
use teksilo_core::widget::{LayoutContext, LayoutResponse, Widget, WidgetPlacement};
use teksilo_core::widget_id::WidgetId;

#[derive(Debug)]
struct StaggeredColumn {
    child_ids: Vec<WidgetId>,
    offset: f32,
}

impl Widget for StaggeredColumn {
    fn layout_response(&self, proposal: SizeProposal, ctx: &LayoutContext) -> LayoutResponse {
        let child_proposal = SizeProposal { width: proposal.width, height: None };
        let mut total_h = 0.0;
        let mut max_w = 0.0_f32;
        for &id in &self.child_ids {
            if let Some(s) = ctx.child_size(id, child_proposal) {
                total_h += s.height;
                max_w = max_w.max(s.width + self.offset);
            }
        }
        Size::new(proposal.width.unwrap_or(max_w), total_h).into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        ctx: &LayoutContext,
    ) {
        let mut y = bounds.y;
        for (i, child) in children.iter_mut().enumerate() {
            let s = ctx.child_size(child.id, SizeProposal::with_width(bounds.width))
                .unwrap_or(Size::ZERO);
            let dx = self.offset * (i as f32);
            child.origin = Point::new(bounds.x + dx, y);
            child.size = Size::new(s.width.min(bounds.width - dx), s.height);
            y += s.height;
        }
    }

    fn children(&self) -> Vec<WidgetId> { self.child_ids.clone() }
}
}

Three things to remember:

• Don't close over bounds.width for the child proposal in layout_response. That measures children against the parent's offered width, not the wrapper's bounds. Use proposal.width.
• Match place_children's child query to your sizing policy. If layout_response queried with SizeProposal::with_width(w), query the same way in place_children — otherwise wrapping children measure twice with different results.
• Honor flex. If your layout wants stacks-style slack distribution, sum child_layout_response(...).flex and apply the standard rule. If your layout doesn't distribute slack, ignore flex; that's fine.

For testing, crates/teksilo-core/src/test_widgets.rs ships FillWidget and StackWidget (pub(crate)); for end-to-end layout tests use WidgetTree directly with tree.layout(SizeProposal::exact(w, h)) and assert tree.bounds(id).

10. References

• Architecture: architecture.md §2 Layout Model
• Reactive layer: reactive-theme.md, Signal<T> / Prop<T> in crates/teksilo-core/src/signal.rs
• Animation tied to layout: animation.md
• Custom widget patterns: Widget trait, BuildContext
• Visual tour: cargo run -p widget-catalog, cargo run -p text-and-layout, cargo run -p data-grid

Events and Gestures

Companion to: architecture.md Scope: How input becomes widget behavior in Teksilo — attached handlers, preview/bubble dispatch, gesture recognizers, and the EventContext deferred-operations pattern.

1. What we designed for

The event system has to handle three unrelated things cleanly:

1. Raw input from the platform — pointer moves, key presses, scroll, IME composition, trackpad pinch.
2. Recognized gestures composed from raw events — tap, double-tap, long-press, drag, swipe.
3. Accessibility actions — a screen reader or automation tool asking the widget to do something (click, set value, set selection) without any pointer or keyboard at all.

The V1 design unified these behind a single fn event(&mut self, event: &WidgetEvent, ctx: &mut EventContext) -> EventResponse method on every Widget. Every widget wrote one giant match statement on the event enum. This worked, but it forced a pile of incidental complexity:

• Gesture recognizers had to be instantiated per-widget by hand.
• The RefCell<Option<State<T>>> pattern was mandatory to mutate state created during build() from inside event().
• Composition was painful: wrapping a widget and also listening for taps meant the wrapper had to re-dispatch the inner's events manually.
• Unused handler slots still cost the dispatcher a virtual call per widget per event.

V2 replaces the single method with attached handlers. Widget builders register typed closures for the specific events they care about; the framework stores those closures on the arena node and dispatches them automatically. The Widget trait itself has no event() method anymore.

2. Preview and bubble — the two-pass model

Every event that targets a specific widget (via hit testing for pointer events, via the focused widget for keyboard events, via the target node for AccessKit actions) travels through the tree twice:

• Preview pass: root → target. Each ancestor gets a chance to consume the event before the target sees it. A MenuList overlay uses the preview pass to intercept Arrow keys before any menu item sees them; a modal scrim uses it to swallow pointer events that fall outside the modal. Preview handlers return EventResponse::Handled to stop the pass.
• Bubble pass: target → root. The target handles the event first; if it returns Ignored, the event walks up the parent chain until something handles it or the root is reached. This is how a Button's .on_key(Key::Space) handler can be registered on the button itself, but Ctrl+S falls through to a root-level Action.

     root
      │   preview: root first
      ↓
   ancestor
      │
      ↓
    parent
      │
      ↓
   target ← event fires here
      │   bubble: target first
      ↑
    parent
      │
      ↑
   ancestor
      │
      ↑
     root

Implementation is a single walk per pass in widget_tree/event_dispatch_impl.rs: dispatch_to_widget_returning_handled(target, &event) collects ancestors, runs preview top-down, then runs bubble target-up, returning on the first Handled.

The framework decides what "target" means per event type:

• Pointer events (PointerDown, PointerMove, PointerUp, PointerEnter, PointerLeave) — hit-tested against layout bounds. The deepest hit wins. Preview runs from the root to that hit; bubble walks back up.
• Scroll events — hit-tested at the pointer position; bubble to the nearest on_scroll that returns Handled (a scroll container typically).
• KeyDown / KeyUp / IME — routed to the focused widget. Preview from root down, bubble focused-widget up.
• AccessKit actions — routed to the target node directly. No pointer, no focus — the platform's AccessKit request carries a NodeId. No preview pass; handler runs on the target only, then bubbles.

There is no "capture phase" distinct from preview, no event replay, no explicit listener list. The tree structure is the listener list.

3. Attached handlers

Widget builders register event handlers via blanket-implemented methods on the WidgetBuilder trait. Every widget gets them for free:

#![allow(unused)]
fn main() {
ctx.add(
    MinSize::new(48.0, 48.0).child(content)
        .on_tap(|event, ctx| {
            // event is &TapEvent { position, button, modifiers }
            ctx.send_intent(AppIntent::Clicked);
        })
        .on_hover(move |entered, _ctx| {
            interaction.set(if entered {
                InteractionState::Hovered
            } else {
                InteractionState::Idle
            });
        })
        .focusable(true)
        .cursor(CursorIcon::Pointer)
);
}

Under the hood, the builder wraps the widget in a WidgetWithHandlers<W> that carries a HandlerSet. On arena insertion the handlers are moved onto the WidgetNode; the wrapper evaporates. At dispatch time the framework looks up the relevant closure on the node and calls it with the event data and an EventContext. Absent handlers are None and cost nothing.

3.1 Handler catalogue

event_handlers.rs defines the full set. Summarized:

3.1.1 TapEvent — button + modifiers in the callback

The four click-style handlers (on_tap / on_double_tap / on_triple_tap / on_long_press) all receive a borrowed TapEvent:

#![allow(unused)]
fn main() {
#[non_exhaustive]
pub struct TapEvent {
    pub position: Point,         // widget-local coords
    pub button: PointerButton,   // which button finalised the gesture
    pub modifiers: Modifiers,    // held at the finalising event
}
}

This lets a single handler discriminate by mouse button and modifier without falling back to on_pointer_event:

#![allow(unused)]
fn main() {
.on_tap(|event, ctx| match (event.button, event.modifiers) {
    (PointerButton::Primary, Modifiers::SHIFT) => extend_selection(ctx),
    (PointerButton::Primary, Modifiers::CTRL)  => toggle_selection(ctx),
    (PointerButton::Primary, _)                => set_selection(ctx),
    (PointerButton::Secondary, _)              => show_quick_actions(ctx),
    _ => {}
})
}

Modifiers come from the finalising event — Up for on_tap / on_double_tap / on_triple_tap, the held Down for on_long_press (which recognises on a timer before any Up). The struct is #[non_exhaustive] so future fields don't break match patterns or constructors.

Coordinate space (framework invariant). Every pointer / gesture position delivered to a handler — on_tap / on_double_tap / on_triple_tap / on_long_press, on_drag (DragPhase), and on_pointer_event (PointerDown / Move / Up) — is in that handler's widget-local space (relative to the node's top-left, with any ancestor Scale / Rotate transform undone). The framework converts once at dispatch via WidgetArena::local_pointer_position; widgets must not subtract their own bounds origin. (A content_transform node such as SceneView is the one exception: it owns its view transform and receives positions in its parent-effective space.) The drag-and-drop drop callbacks (on_drop / on_drag_hover / on_drag_tick) and the context_menu factory are dispatched on a separate path and likewise receive widget-local / window-local positions as documented at their own call sites.

3.1.2 Button-acceptance filter — default Primary, opt-in to more

Each of the four recognizers defaults to [ButtonMask::PRIMARY] — left-click only. A right-click on a Button, Checkbox, MenuItem, etc. does not activate the widget; it can still open a context menu via .context_menu(...) or be handled directly via on_pointer_event. Multi-tap recognizers further require every tap in the sequence to use the same button — mixed-button sequences fail rather than spuriously firing.

To opt a handler into a wider button set, call the matching accept_*_buttons(...) knob:

#![allow(unused)]
fn main() {
Button::new(lit!("Action"))
    .accept_tap_buttons(ButtonMask::PRIMARY | ButtonMask::SECONDARY)
    .on_tap(|event, ctx| match event.button {
        PointerButton::Primary   => primary_action(ctx),
        PointerButton::Secondary => alt_action(ctx),
        _ => {}
    });
}

ButtonMask exposes the obvious constants and bitwise operators; ButtonMask::ALL is the catch-everything shorthand and accept_any_button() on the recognizer types is the equivalent. The same family of knobs exists for double-tap (accept_double_tap_buttons), triple-tap (accept_triple_tap_buttons), and long-press (accept_long_press_buttons).

The PointerButton enum covers Primary, Secondary, Middle, plus Back and Forward (mouse 4 / 5). Platforms that don't surface the auxiliary buttons simply never emit them.

3.1.3 Other flag-like attachments

Plus a handful of flag-like attachments that don't take event-data closures:

3.1.4 Context-menu factory — Fn(Point, &mut EventContext) -> Option<Box<dyn Widget>>

Right-click handling lives at a different tier from the four tap-family hooks. Instead of a recognizer-driven callback, the framework wires a single factory that produces the menu widget on demand. When the user right-clicks, the framework's show_context_menu_for walks up the parent chain looking for the nearest ancestor with a factory installed, calls it with the click position (widget-local) plus a full EventContext, and:

• Mounts the returned widget as an OverlayLayer::InTree overlay anchored at the factory-owning widget, placed at the click position.
• Dismisses pre-existing overlays first.
• Saves the previously-focused widget for restoration when the menu dismisses.
• Focuses the menu content so keyboard navigation works immediately.

#![allow(unused)]
fn main() {
.context_menu(|position, ctx| {
    // Use `position` to identify what was right-clicked (a row in a
    // list, a node in a tree, an item under a hit-test).
    let row = pick_row_at(position.y)?;
    // Use `ctx` to read window state, query app-state, send intents,
    // or update Signals before the menu mounts.
    ctx.send_intent(AppIntent::TelemetryRightClick { row_id: row.id });
    Some(Box::new(build_menu_for(row)))
})
}

The factory is Fn (re-entrant) and called fresh on every right-click — the menu's enabled / disabled flags read live state at the moment it opens, so a "Paste" item correctly greys out when the clipboard becomes empty between two right-clicks.

Returning None declines the click and the framework continues walking up the parent chain to the next ancestor with a factory. This lets a widget conditionally suppress its own menu without uninstalling the factory:

#![allow(unused)]
fn main() {
.context_menu(|_, _| if disabled.get() { None } else { Some(build_menu()) })
}

A factory that always returns None produces no menu and no fall-through visible effect — the right-click is consumed silently.

3.2 HandlerSet — handlers from inside build()

Attached handlers via WidgetBuilder methods only work on child widgets (ctx.add(MinSize::new().on_tap(...))). A composite widget that wants to install handlers on itself (typical for focusable containers that should swallow keyboard events) uses HandlerSet + ctx.apply_self_handlers:

#![allow(unused)]
fn main() {
fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
    let handlers = HandlerSet::new()
        .focusable(self.enabled)
        .cursor(CursorIcon::Pointer)
        .on_tap(move |_event, ctx| { /* ... */ })
        .on_key(move |event, ctx| {
            if let WidgetEvent::KeyDown { key: Key::Space, .. } = event {
                // handle activation
                return EventResponse::Handled;
            }
            EventResponse::Ignored
        });
    ctx.apply_self_handlers(handlers);
    // ... then add children ...
}
}

Multiple apply_self_handlers calls across a widget's build() chain merge via HandlerSet::merge; two on_tap closures both run. This lets a composite widget compose its own behavior with a base trait's contributed handlers.

3.3 Why attached handlers won

The event()-method vs attached-handlers tradeoff flipped once three things became clear:

• Gesture auto-wiring. When a widget attaches on_tap, the framework instantiates a TapRecognizer in the node's gesture arena on the fly. The widget author never touches the recognizer. Under the V1 model, every tappable widget had to declare the recognizer by hand.
• Cheap composition. Wrapping a widget inside a MinSize and also listening for taps on the outer wrapper used to require a second widget with a custom event() impl. Now it's .child(content).on_tap(...) — the MinSize doesn't need to know its parent wrote a tap handler, because the handler is on the wrapper's node, not inside MinSize.
• Mutation without RefCell<Option<State>>. V1's event(&mut self, ...) required &mut access to state built in build(&self), forcing the RefCell<Option<State<T>>> pattern. Attached handlers close over Signal<T> clones — the signal itself is clone-friendly and internally cells its own storage, so the handler closure doesn't need &mut self.

4. Gesture recognizers — composition with backpressure

gesture.rs defines the recognizer state machines. Each is a pure, platform-free value type that consumes RawPointerEvent::{Down, Move, Up} and emits GestureResult::{Pending, Recognized(GestureEvent), Failed}.

Built-in recognizers (the four click-style ones default to ButtonMask::PRIMARY — call .accept_buttons(...) / .accept_any_button() to widen):

• TapRecognizer — fires on a down-up without movement past the tap-slop threshold. Down/Up button must match.
• DoubleTapRecognizer — two taps within 300 ms. Both taps must use the same button.
• TripleTapRecognizer — three. Same button across all three.
• LongPressRecognizer — pointer held past ~500 ms. Modifiers are captured at Down.
• DragRecognizer — emits DragStarted once the pointer moves past the drag-start threshold, then DragMoved per move, then DragEnded on pointer-up.
• SwipeRecognizer — pointer moves fast enough to qualify as a swipe in one of four cardinal directions.

PinchRecognizer is not in the list because on desktop the OS delivers TouchpadMagnify / RotationGesture events directly (winit passes them through); the framework turns those into PinchPhase events without needing a recognizer.

4.1 GestureArena — cooperating and competing

When a widget attaches multiple gesture handlers (on_tap + on_long_press), both recognizers run in parallel on the same event stream via GestureArena. The arena's rules:

• Each recognizer sees every raw event until it returns Recognized or Failed.
• When one recognizes, competing recognizers whose resets_on_peer_recognition flag is set get reset (DoubleTapRecognizer peers-reset when TapRecognizer alone fires — so a single tap doesn't arm a phantom "missing second tap" in the double-tap recognizer).
• Cooperative recognizers (tap and triple-tap, for instance) run to completion side-by-side.

Widget authors never touch the arena directly. Attaching handlers via WidgetBuilder or HandlerSet auto-wires the recognizers and the arena on the node.

4.2 Cross-widget tap/drag disambiguation — drag observers

The GestureArena is per-widget; there is no cross-widget arena. That leaves one gap: a descendant's on_tap installs a TapRecognizer that captures the pointer on PointerDown, which would otherwise route every following PointerMove/PointerUp to the descendant alone — so an ancestor that wants to start a drag (a SceneView behind tappable cards, a draggable container wrapping tappable rows) would never see the move and could never begin its drag.

The framework closes this without cross-arena arbitration, by leaning on the existing active_drag takeover (an in-flight start_drag is consulted before capture routing). On PointerDown, after the normal dispatch, if a descendant captured the pointer the framework arms drag observers: it walks the captured widget's strict ancestors and, for each one that carries an on_drag / on_swipe recognizer, feeds the down event into that ancestor's own gesture arena (no on_pointer_event, no second capture). On each subsequent PointerMove (while no drag is yet active) it advances those observers; the moment one recognizes a drag it calls start_drag, and the active_drag takeover pulls the pointer away from the descendant. If no ancestor drag fires, the descendant's tap completes normally on PointerUp.

Two consequences worth knowing:

• A widget that has its own on_drag (a slider, a DnD row) is left untouched — the arming step skips a captured widget that already carries a drag recognizer, so only pure-tap descendants inside a draggable ancestor change behavior.
• A quick press-release on the card is still a tap (no move crossed the drag threshold); only a press-and-drag escalates to the ancestor. This is exactly what makes "drag from on top of a select-only scene card starts a marquee, click selects it" work (see teksilo-scene.md "Drag mode").

5. EventContext — the deferred-operations pattern

Handlers don't mutate the tree directly. They request mutations on their EventContext and the framework applies them after the dispatch finishes:

#![allow(unused)]
fn main() {
pub struct EventContext {
    // tree structure
    tree_mutations: Vec<TreeMutation>,        // SetDormant / Activate / Destroy
    // focus
    focus_requests: Vec<WidgetId>,
    // overlays
    overlay_requests: Vec<OverlayRequest>,
    overlay_dismissals: Vec<OverlayId>,
    delayed_overlay_requests: Vec<...>,
    timed_overlay_requests: Vec<...>,
    dismiss_all_overlays: bool,
    dismiss_top: bool,
    // modals
    modal_requests: Vec<ModalRequest>,
    dismiss_modal: bool,
    // repaint / layout
    repaint_requests: Vec<WidgetId>,
    // intents + shortcuts
    pending_intents: Vec<Intent>,
    pending_key_capture: Option<KeyCaptureSlot>,
    pending_shortcut_mutations: Vec<ShortcutMutation>,
    // window-level
    theme_request: Option<Theme>,
    locale_request: Option<String>,
    close_window_requested: bool,
    // cursor
    cursor_request: Option<CursorIcon>,
    // frame loop
    frame_requested: bool,
    // ...
}
}

This single-pass deferral matters for two reasons:

• Safety. A handler that destroys its own widget, then inspects state on that widget, would crash. Deferring the destroy until after the handler returns avoids use-after-free without runtime cost.
• Ordering. Multiple handlers along the bubble path can each queue mutations; the framework applies them in a well-defined order (intents first, then tree mutations, then repaints). A widget author doesn't have to reason about mid-handler tree shape changes.

5.1 Ambient ops available from any handler

Via EventContext, any handler can:

• ctx.set_theme(theme) — swap the app theme; all windows rebuild.
• ctx.set_locale(id) — switch i18n locale; dirty-marks locale-bound signals.
• ctx.close_window() — request the owning window close.
• ctx.request_focus(widget_id) — programmatic focus transfer (overlay content on open, first error field on submit).
• ctx.dismiss_all_overlays() — useful after menu item activation.
• ctx.send_intent(AppIntent::X) — fire a typed intent; framework walks source → root invoking any matching Action. See shortcut-intent-action.md.
• ctx.request_frame() — ask the event loop to pump one more frame (caret blink restart, drag auto-scroll, pending document events).
• ctx.app_state::<T>() — look up an app-scoped value registered on TeksiloAppBuilder by TypeId.

These are the methods that make it possible to build app-level behavior (menu routing, theme switching, shortcut rebind UIs) without any global statics or hardcoded backchannels.

6. Focus management

Focus is a single Option<WidgetId> stored on the tree. Tab / Shift+Tab moves it across widgets whose node has focusable = true. The framework publishes three signals that widgets can observe:

• The currently focused node id (read via tree.focused()).
• Focus origin — Keyboard (tab/shift-tab/programmatic) or Pointer (tap) or Programmatic. Used to paint a focus ring only on keyboard focus by default; pointer focus typically omits the ring per Int UI style.
• Focus-gained / focus-lost events dispatched to widgets via on_focus(gained: bool, ctx).

Programmatic focus transfer goes through ctx.request_focus(id). The framework also exposes first_focusable_descendant(id) for modal openers (dialogs that should land focus on the primary action button — it returns the widget Tab would land on first, respecting the scope rules below) and ScrollIntoView synthesized on focus change so that tab-focusing an offscreen widget scrolls the nearest clipping ancestor to reveal it.

Focus cleanup on destroy is automatic: destroying a focused widget clears focus; the next input event that requires focus routes to the nearest focusable ancestor or root.

6.1 Traversal scopes (FocusScope)

Tab order is not one flat global ring — it is a tree of traversal scopes. Every focusable widget belongs to its nearest enclosing FocusScope; the whole window (or, while a centered modal is open, that modal's content) is an implicit root scope. Within a scope, members — focusable leaves and nested scopes, each counted as one unit — are ordered by scoped tab_index (then document order). Because tab_index is compared only among siblings of the same scope, two sibling scopes that both number their children 1, 2, 3 never interleave. This is Teksilo's analogue of Flutter FocusTraversalGroup / WPF KeyboardNavigation.TabNavigation.

A scope is declared by wrapping a subtree in the layout-transparent FocusScope wrapper, which carries a TraversalScopePolicy governing what Tab does at the scope's ends:

#![allow(unused)]
fn main() {
// teksu!: a modal dialog whose Tab order is confined to its own content
FocusScope(TraversalScopePolicy::Cycle) {
    Button::new(lit!("OK"))
    Button::new(lit!("Cancel"))
}
// builder form
FocusScope::new(TraversalScopePolicy::Cycle).child(dialog_body)
}

Not for popovers or menus. A non-modal overlay is dismissed when keyboard focus leaves it (see Overlays follow focus out, below) — the behaviour ARIA's Disclosure and Menu patterns call for, and what stops an open panel from covering the focus ring that just left it (WCAG 2.2 SC 2.4.11). Cycle-wrapping one traps focus so that dismissal never fires.

The root scope is implicitly Cycle (whole-tree last↔first wrap, the historical behavior). A centered modal overlay folds into the same mechanism: its content subtree becomes the root Cycle scope, so Tab is confined to the modal with no special-case code. The FocusScope node itself is forced non-focusable (it is a boundary, never a Tab stop). A subtree with no FocusScope behaves exactly like the old flat wrapping ring.

Not to be confused with view_focus_*. BuildContext::begin_view_focus / view_focus_active (formerly the focus_scope chrome API) is an unrelated build-time mechanism that tracks "does this data view's subtree hold focus" to drive selection chrome and focus rings. It has nothing to do with Tab traversal. Traversal scopes are the FocusScope widget + set_traversal_scope.

Implemented in cycle_focus (the recursive scope-tree walk) and set_traversal_scope (the node marker, directly usable from headless tests).

Overlays follow focus out

A non-modal overlay is dismissed when keyboard focus leaves it. Menus, popovers, dropdown panels and suggestion lists do not contain focus; Tab is an exit gesture for all of them, and the panel goes when focus does. Widgets get this for free — there is nothing to wire, and nothing to wrap.

This is what the patterns those surfaces implement actually specify. ARIA APG's Menu pattern is unqualified: Tab "moves focus out of the menu or menubar, and closes all menus and submenus" — only the arrows navigate within. A popover implements Disclosure, which mandates no containment. The alternative, trapping, is legal (WCAG 2.1.2 is satisfied by Escape alone) but unsupported by any of those patterns, and it leaves the real defect in place: an open panel sitting over the focus ring that just left it, which is WCAG 2.2 SC 2.4.11 Focus Not Obscured (Minimum), Level AA.

An overlay is eligible when it is positioned at its anchor — Below, Above, TrailingEdge, AtPointer, NearAnchor, BelowPreferred. Those hang off a control, so "focus left that control" means something. The viewport-placed variants are excluded, and deliberately: Centered is the modal (the one surface whose pattern does contain focus), FullViewport is its scrim, and BottomCenter / ViewportCorner are notifications. A snackbar is shown from a focused button and leaves it focused — an anchor-aware rule that did not exclude it would tear the snackbar down on the user's very next keystroke, overriding both its timer and .persistent(). A toast's lifetime belongs to its timer, never to where the keyboard happens to be.

Two further exclusions: an overlay already fading out (dismissing it again collapses the tween it is mid-way through), and tooltips, which tooltip_focus_leave_outside owns end-to-end with a deliberately wider test — it keeps a tip alive while focus rests on its anchor, the normal state of a focus-promoted tip.

DismissBehavior is not consulted. It selects which of Escape / click-outside / hover-out apply, an orthogonal axis: a popover that opted out of click-outside did not thereby ask to survive being tabbed away from.

An overlay's anchor counts as part of it. A non-searchable ComboBox keeps focus on its trigger the whole time its dropdown is open, and a SearchField keeps it in the text input while suggestions float below — focus is never inside the overlay, so a content-only test would conclude nothing was ever open. Arriving on the anchor still counts as leaving, though, so Shift+Tab off the front of a popover closes it and lands on the trigger, where Escape would have left you.

Nested overlays close as a cascade: the walk goes up parent_overlay and dismisses the outermost eligible level, which takes every level below it — APG's plural "all menus and submenus" — while stopping at a host surface so a menu never drags its hosting dialog, composite tooltip or revealed menubar down with it.

Implemented in dismiss_overlays_left_by_focus, called from focus_with_origin_ops — the single funnel every focus change passes through, so Tab, click-to-focus, AccessKit and ctx.request_focus are all covered by one mechanism.

6.5 Drag-and-drop lifecycle

Target-side handlers fire in a strict order. A widget that accepts drops should assume this sequence and own the cleanup of any feedback state it sets:

1. on_drag_hover(payload, pos, ctx) -> DropFeedback — fires on every PointerMove while this widget is the drop target (pointer inside its bounds and the framework picked it via find_drop_target_at_or_above). The widget typically stashes its own feedback state (an insertion line y, a highlight rect) and returns the matching DropFeedback descriptor. pos is in target-local coordinates — origin at the target widget's top-left — so drop-index math can reuse the same coordinate system as the target's own bounds and paint layout.
2. on_drag_tick(local_pos, ctx) — fires once per layout pass while the widget is the current drop target. Use for per-frame behaviours that must keep progressing when the pointer is stationary: viewport-edge auto-scroll (linear ramp inside an edge zone), spring-loaded folder expansion after a dwell time. Receives the pointer position in widget-local coordinates.
3. on_drag_leave(ctx) — fires exactly once when this widget stops being the drop target. The framework emits it for all four leave scenarios: pointer moved to a different target, drop completed (on this or another target), Escape-cancelled, or the drag source was destroyed mid-drag. Widgets MUST clear any feedback state they set in on_drag_hover here — the framework does not touch widget-owned state.
4. on_drop(payload, pos, ctx) -> bool — fires on PointerUp only if this widget is the drop target at the release position. Already preceded by on_drag_leave (so feedback is cleared by the time the drop handler decides acceptance). Returns true if accepted.

Framework guarantees the ordering: on_drag_leave runs before on_drop on the same widget for a successful drop, and before cleanup_drag_preview for cancels. The DragPreview overlay (created via EventContext::start_drag_with_preview) follows the pointer throughout and is dismissed by the framework in all paths — widgets don't manage it.

7. Synthetic events

The framework dispatches a few synthetic events the widget code doesn't see from the platform:

• PointerEnter / PointerLeave. Derived from PointerMove by comparing the hit target frame-over-frame. A widget moving out from under a stationary pointer still gets PointerLeave — the hit target changed even if the pointer didn't.
• FocusGained / FocusLost. Issued when focus moves.
• ScrollIntoView { target }. Issued by the focus system after a focus change to a widget outside the viewport. Nearest clipping ancestor handles it by adjusting its scroll offset.
• Synthetic clicks. ctx.synthetic_click(id) dispatches a simulated tap at the widget's center — used by AccessKit action routing (Action::Click), menu item activation, and some shortcut-triggered activations that want to go through the full tap path.

8. Testing

Events are synthesizable from tests without a real platform:

#![allow(unused)]
fn main() {
let mut tree = WidgetTree::new();
let btn_id = tree.add(Button::new(lit!("OK")).on_activate_fn(|ctx| {
    ctx.send_intent(AppIntent::Confirm);
}));
tree.layout(SizeProposal::exact(200.0, 100.0));

// Synthesize a pointer tap at the button's center:
let bounds = tree.bounds(btn_id);
tree.dispatch_event(WidgetEvent::PointerDown {
    position: bounds.center(),
    button: PointerButton::Primary,
    modifiers: Modifiers::NONE,
});
tree.dispatch_event(WidgetEvent::PointerUp {
    position: bounds.center(),
    button: PointerButton::Primary,
    modifiers: Modifiers::NONE,
});
}

For gesture-level assertions the test_api module on WidgetTree exposes helpers like synthesise_tap(id) that run the preview-bubble walk with a fabricated event. Timing-sensitive recognizers (double-tap, long-press) use the tree's simulated clock — advance_time(Duration) in tests.

No Xvfb, no GPU, no display server required.

9. Design rules in one list

• Widget authors register typed closures per event type; no monolithic event() method.
• Events travel preview (root → target) then bubble (target → root); first Handled stops the pass.
• Attach handlers on children with .on_foo(…) via WidgetBuilder; attach on self with HandlerSet + ctx.apply_self_handlers.
• Gesture recognizers are auto-wired from attached handlers; GestureArena arbitrates cooperation and reset.
• Handlers express mutations by calling methods on EventContext; the framework applies them after dispatch.
• ctx.send_intent(X) is the single way to request app-level behavior from a handler; ctx.set_theme / set_locale / close_window / request_focus / dismiss_all_overlays cover the framework-level ambient ops.
• Focus is a single optional WidgetId; transfers happen via ctx.request_focus(id); Tab/Shift+Tab walks a tree of FocusScopes (scoped tab_index, per-scope Continue/Cycle policy), defaulting to a flat document-order ring when no scopes are present.
• Everything is headless-testable — dispatch synthetic events, advance the simulated clock, inspect the tree.

See also

• animation.md — Signal<f32>::animate_to and the scheduler. Handlers that kick off motion (toggle thumb, accordion height, snackbar slide-in) call animate_to on animation-capable signals; the docs here and there are two halves of the "handler runs → something moves" path.
• shortcut-intent-action.md — how intents travel source → root and fire Actions; rebindable keystrokes via ShortcutRegistry.
• architecture.md §22 Window Management — modal-vs-modeless, window focus routing.
• architecture.md §13 Overlay System — overlay stack, click-outside, Escape cascade, focus-restore on dismiss.
• crates/teksilo-core/src/event_handlers.rs — EventHandlers struct.
• crates/teksilo-core/src/widget_builder.rs — blanket-impl builder methods.
• crates/teksilo-core/src/gesture.rs — recognizer state machines.
• crates/teksilo-core/src/widget_tree/event_dispatch_impl.rs — dispatch walk.
• crates/teksilo-core/src/widget.rs — EventContext.
• crates/teksilo-widgets/src/focus_scope.rs — the FocusScope traversal-scope wrapper (§6.1).
• crates/teksilo-core/src/widget_tree/focus_impl.rs — cycle_focus scope-tree traversal, set_traversal_scope, view_focus_* chrome signals.

Styling System

Teksilo's theming is a four-tier ladder. Each tier is independently opt-in: an app that only needs dark mode never sees the higher tiers; an app shipping a brutalist redesign uses every rung.

Tier 0:  Tokens          (colors, shapes, motion, typography, layout)
Tier 1:  Variants         (per-widget closed enums: Filled / Plain / …)
Tier 2:  Recipes          (paint vocabulary — shape, fill, border, shadow)
Tier 3:  Style protocols  (`trait FooStyle { fn make_body(...) -> WidgetId }`)

The default implementations of Tier 3 (the Recipe*Style types shipped in teksilo-widgets/src/styles/) read Tier 2 recipes; the default recipes read Tier 0 tokens. So Tier 3 contains Tiers 0-2 for the IntUI preset — but the trait protocol at Tier 3 is the escape hatch that lets apps replace the entire chrome of any widget without touching the widget source.

Reference for designers — image-backed themes (Figma / Penpot / Canva exports → 9-slice assets → reskinned app) get their own deep reference at docs/image-themes.md. The image-theme system is a parallel set of impl FooStyle blocks on top of the same Tier-3 surface — same widgets, different chrome.

Mental model — which tier do I use for X?

The cardinal rule: never edit widget source to change a look. If the existing API doesn't get you there, write an impl FooStyle block and install it.

Tier 0 — Tokens

The five token groups (ColorTokens, ShapeTokens, LayoutTokens, TypographyTokens, MotionTokens) live in teksilo-tokens/src/. They're pure data structs with no widget knowledge.

Theme aggregates the five token groups plus appearance, component dimensions, and the typed style-slot bag:

#![allow(unused)]
fn main() {
pub struct Theme {
    pub appearance: ThemeAppearance,        // Light | Dark — required
    pub colors: ColorTokens,
    pub layout: LayoutTokens,
    pub typography: TypographyTokens,
    pub shape: ShapeTokens,
    pub motion: MotionTokens,
    pub style_slots: ComponentStyleSlots,    // typed Rc<dyn FooStyle> slots
    pub extensions: ThemeExtensions,
}
}

There is no Theme::default(). Apps explicitly pick a preset:

#![allow(unused)]
fn main() {
use teksilo::prelude::intui;
let theme = intui::light();   // or intui::dark()
}

Other presets ship as opt-in Cargo features (Material 3, macOS, Fluent); until then only IntUI is bundled.

Reactive. Theme lives behind a Signal<Theme> on WidgetTree — set_theme(...) dirty-marks every widget for repaint without rebuilding the tree. Focus, scroll offsets, and animation state survive theme swaps. See docs/reactive-theme.md.

Extensions. theme.with_extension::<MyPalette>(...) / theme.extension::<MyPalette>() attach app-specific extras that don't fit any of the five token groups. Cheap (TypeId lookup), arbitrary type.

How a widget goes grey when disabled

A widget is disabled when its own enabled prop is false or any ancestor's is — a control inside a disabled form is disabled. Its chrome greys by one of two routes, and there is a trap in each.

Role-driven chrome dims for free. ColorProp::resolve(theme, effective_enabled) — which every role-driven leaf (TextWidget, IconWidget, RectWidget) calls at paint time — substitutes the disabled counterpart of a role in a disabled subtree: any TextRole → TextRole::Disabled; the accent family (SurfaceRole::Accent / AccentHover / AccentPressed, BorderRole::Accent) → their AccentDisabled counterpart; and the neutral interactive SurfaceRole::Field / BorderRole::Field → their Disabled counterpart. This is why most recipes never mention is_disabled.

⚠️ The substitution only reaches roles. ColorProp::Bound(Signal<Color>) resolves to s.get() and ignores enabled entirely — so a recipe that folds per-state colours into a flat reactive colour (as RecipeButtonStyle does via PerStateRecipe + bind_fill) gets no paint-time safety net, and must select its WidgetState::Disabled from cfg.is_disabled.

Neutral controls must opt into a Field role. The substitution deliberately leaves passive surfaces alone — a disabled Panel keeps its surface. It has to: a text field's frame and a passive Panel both painted SurfaceRole::Content, so the hook could not tell them apart, and dimmed neither. That is what Field is for. It resolves identically to Content while enabled and substitutes to Disabled when not, so a field dims and a panel does not:

#![allow(unused)]
fn main() {
// A field's frame. No `is_disabled` needed for the resting case — the role
// dims itself at paint, from the live arena.
let bg = RectWidget::new().background(SurfaceRole::Field);

// The border still consults `is_disabled`, so disabled outranks *focus*.
let border_role = cfg.is_focused.zip(&cfg.is_disabled).map(|(f, d)| {
    if *d { BorderRole::Disabled }
    else if *f { BorderRole::Focused }
    else { BorderRole::Field }
});
}

SurfaceRole::Disabled / BorderRole::Disabled resolve to the neutral surface_disabled / border_disabled tokens. Do not reach for AccentDisabled here: it is a washed-out accent (pale cyan in IntUI), right for an accent-filled Button and wrong for a grey field.

Getting the signal. ctx.effective_enabled_signal(self_id).map(|on| !*on) ANDs the widget's own enabled prop with every ancestor's. It is a node-resident signal that the framework refreshes from the live arena each state-change pass, so it may be bound to a prop and passed to ctx.effect.

It is deliberately not a signal derived by walking ancestors at call time. A widget's parent is still None while its own build() runs — insert_widget inserts the node parentless and wires the parent only after build() returns — so such a walk sees an empty chain and captures the widget's own enabled prop as the whole answer, permanently. Prefer a Field role over the signal where you can: the paint-time route reads the live tree and cannot go stale.

Raw-colour widgets bypass all of this. Anything shaping through a RichTextEngine (e.g. TextInputField) hands GPU colours straight to the engine, so no ColorProp is involved. Resolve against ctx.effective_enabled in paint instead.

Color::mix and non-finite factors

darken, lighten, desaturated, and ColorTokens::for_inactive_window (the window-deactivation accent projection — see window-activation.md) all bottom out in Color::mix(other, t). t is clamped to [0, 1] before use, but a bare t.clamp(0.0, 1.0) is not enough on its own: f32::clamp returns NaN for a NaN input rather than saturating it, so a NaN factor used to poison every channel and produce an unrenderable colour. Color::mix now maps a NaN factor to 0.0 (returning self unchanged) before clamping — the safest reading of an undefined mix. ±inf needs no such special case: the clamp already maps them to 1.0 / 0.0 correctly. A caller deriving t from a ratio that can legitimately divide by zero no longer needs to guard it before calling mix.

Tier 1 — Variants

Each themable widget exposes a closed *Variant enum naming its design-language presentations. The variant is a hint: the active Tier-3 style decides what it means.

#![allow(unused)]
fn main() {
ButtonVariant    { Filled, Tinted, Outlined, Plain, Ghost, Link, Destructive }
ToggleVariant    { Switch, Pill, Square, Inset }
CheckboxVariant  { Square, Rounded, Circle }
RadioVariant     { Circle, Square, Rounded }
IconButtonSize   { Compact, Default, Toolbar, Large, Hero }  // size = variant for IconButton
CardVariant      { Plain, Elevated*, Outlined, Filled }       // * = #[default]
PanelVariant     { Plain, Sunken, Raised, Highlighted }
PopoverVariant   { Default, Menu, Tooltip }
SliderVariant    { Continuous, Discrete, Range }
TextInputVariant { Outlined, Filled, Underline, Bare }
ComboBoxVariant  { Outlined, Filled, Underline, Plain }
ScrollBarVariant { Permanent, Overlay, Thin }
AvatarShape      { Circle, Square, Rounded }                  // and AvatarSize, AvatarCorner, AvatarPresence
}

Card defaults to Elevated (shadow + surface_main) — the "just works" Card that matches pre-refactor behaviour. Use .variant(CardVariant::Plain) for a flat surface.

The remaining themable widgets are variant-free: MenuItem, StandardListItem / StandardTreeItem, TabBar, TooltipWidget, Dialog, Snackbar, Banner, SegmentedControl, ProgressBar, Link, Badge, SearchField, SpinBox, DateEdit, ColorPicker, Calendar, RichTextEditor, ListView / TreeView (via ListContainerStyle), TableView / TreeTableView (via TableStyle). Their style traits take a *StyleConfig with no variant field — the design language has a single canonical shape, or the variant distinction lives elsewhere (e.g. ProgressBarKind for determinate vs indeterminate).

Slider and ScrollBar additionally carry an orientation enum (SliderOrientation, ScrollBarOrientation) alongside the variant, since orientation changes layout, not just paint.

Several widgets have multi-method style traits where chrome decomposes into named slots (e.g. TabStyle::make_body + make_bar). See Multi-method styles below for the full list.

Set per-call: Button::new(lit!("Save")).variant(ButtonVariant::Outlined). Set per-app via a custom Tier-3 style that defaults a variant for unspecified callers.

IntUI variant policy. Int UI is intentionally minimalist about button styling — destructive actions live in confirmation dialogs where the body carries the warning, not the button. So the IntUI RecipeButtonStyle collapses several variants: Destructive → Filled, Tinted/Outlined → Plain, Link → Ghost. Other design languages (Material 3 if/when it ships) honour them distinctly.

Tier 2 — Recipes

Recipes are pure data describing paint vocabulary. They live in teksilo-core/src/styles/recipe.rs. Primitive recipe types:

#![allow(unused)]
fn main() {
pub enum ShapeRecipe {
    Rect { corner_radius: CornerRadius },
    Pill,                          // corner = min(w,h)/2
    Circle,
}

pub enum FillRecipe {
    Solid(RecipeColor),
    // overlay composited over base at `alpha` → flat color. The M3 /
    // Fluent "state layer" (hover = 8 %, pressed = 12 % on-color).
    StateLayer { base: RecipeColor, overlay: RecipeColor, alpha: f32 },
    LinearGradient { stops: Vec<GradientStop>, angle_deg: f32 },
    RadialGradient { stops: Vec<GradientStop>, center: (f32, f32), radius: f32 },
    None,
}

pub struct BorderRecipe {
    pub width: f32,
    pub color: RecipeColor,
    pub style: BorderStyle,           // Solid | Dashed { dash, gap } | Dotted
    pub position: BorderPosition,     // Inside | Center | Outside (now honoured)
    pub sides: Option<BorderSides>,   // None = uniform; Some = per-side widths
}
// BorderSides { top, trailing, bottom, leading: f32 } — e.g.
// BorderRecipe::underline(w, color) for an M3/Fluent filled-field underline.

pub struct ShadowRecipe {
    pub offset: Vec2,
    pub blur: f32,
    pub spread: f32,
    pub color: RecipeColor,
}
}

Per-state cascades. Most widgets need different recipes for hover / pressed / focused / disabled. The answer is PerStateRecipe<T> with an explicit fallback chain — Teksilo's take on Flutter's WidgetStateProperty<T>:

#![allow(unused)]
fn main() {
pub struct PerStateRecipe<T> {
    pub idle:     T,
    pub hover:    Option<T>,    // falls back to idle
    pub pressed:  Option<T>,    // falls back to hover, then idle
    pub focused:  Option<T>,    // falls back to hover, then idle
    pub disabled: Option<T>,    // falls back to idle
}
}

PerStateRecipe::resolve(WidgetState) -> &T walks the chain. No closures, fully Serde-serialisable, theme-file-friendly.

Colors in recipes. Recipes hold a RecipeColor enum (not ColorProp) — Static | Surface(SurfaceRole) | Border(BorderRole) | Text(TextRole) — so the full theme cascade still applies but the recipe stays plain data (serializes cleanly for inspector JSON Export and TOML image-theme manifests).

Gradients are rendered. FillRecipe::LinearGradient / RadialGradient paint through the SDF gradient pipeline (via PaintProp, the gradient-or-solid fill prop RectWidget accepts). Anything Into<ColorProp> is also Into<PaintProp> as a solid, so existing fills are unchanged.

Configurable dimensions per widget. Every themable widget now surfaces a public FooRecipe dimension struct, and its RecipeFooStyle carries recipe: FooRecipe with a RecipeFooStyle::new(recipe) constructor. Default fills the recipe from the IntUI pub const dimension block (kept as the default source), so a theme can tweak just the dimensions without writing a new Tier-3 impl:

#![allow(unused)]
fn main() {
let toggle = RecipeToggleStyle::new(ToggleRecipe {
    track_width: 52.0, track_height: 32.0, thumb_diameter: 24.0, thumb_inset: 4.0,
});
theme.style_slots.toggle = Some(Rc::new(toggle));
}

The four multi-method widgets (Tab, Dialog, Table, Calendar) expose a flat recipe each (TabRecipe, DialogRecipe, TableRecipe, CalendarRecipe). A handful with no tunable dimensions (SpinBox, SplitButton, GridView, ListContainer, RichTextEditor) stay unit structs.

Tier 3 — Style protocols

The escape hatch. Each themable widget exposes a trait:

#![allow(unused)]
fn main() {
pub trait ButtonStyle: 'static {
    fn make_body(&self, cfg: &ButtonStyleConfig, ctx: &mut BuildContext) -> WidgetId;
}

pub struct ButtonStyleConfig {
    pub label:       WidgetId,           // pre-built label subtree
    pub is_pressed:  Signal<bool>,
    pub is_hovered:  Signal<bool>,
    pub is_focused:  Signal<bool>,
    pub is_disabled: Signal<bool>,
    pub variant:     ButtonVariant,      // a hint; impl may ignore
}
}

The widget builds the parts (label, optional icon, four state signals), hands the bag to the active style, and uses the returned WidgetId as its root child. Everything else — background, border, focus ring, padding, min size — is the style's responsibility.

The trait is 'static only (not Send + Sync) because all Teksilo trees are single-threaded by construction; Rc<dyn FooStyle> is the public alias (SharedButtonStyle and friends).

Same shape across widgets. All 34 style traits live in teksilo-core/src/styles/, all return WidgetId from their make_* methods, all take a *StyleConfig describing the inputs that vary by widget. The trait is the public API; everything below it is implementation. The full list lives in the migration status table.

Worked example — a Material-3-flavoured Button

#![allow(unused)]
fn main() {
use std::rc::Rc;

use teksilo_core::build_context::BuildContext;
use teksilo_core::styles::{ButtonStyle, ButtonStyleConfig};
use teksilo_core::widget_id::WidgetId;
use teksilo_tokens::{Color, CornerRadius, SurfaceRole};
use teksilo_widgets::primitives::{Padding, RectWidget, ZStack};

struct MaterialFilledButton;

impl ButtonStyle for MaterialFilledButton {
    fn make_body(&self, cfg: &ButtonStyleConfig, ctx: &mut BuildContext) -> WidgetId {
        // Material 3 filled buttons are tall (40 dp), pill-shaped, with
        // a small elevation that lifts on hover. State-driven `Accent` /
        // `AccentHover` / `AccentPressed` cover the surface; disabled
        // collapses to a flat translucent grey.
        let bg = cfg.is_pressed
            .zip3(&cfg.is_hovered, &cfg.is_disabled)
            .map(|(pressed, hovered, disabled)| {
                if *disabled { SurfaceRole::AccentDisabled }
                else if *pressed { SurfaceRole::AccentPressed }
                else if *hovered { SurfaceRole::AccentHover }
                else { SurfaceRole::Accent }
            });

        let rect = ctx.add(
            RectWidget::new()
                .background(bg)
                .corner_radius(CornerRadius::uniform(20.0)),
        );

        let padded_label = ctx.add(
            Padding::symmetric(10.0, 24.0)     // M3 spec: 10×24
                .child_id(cfg.label),
        );

        ctx.add(ZStack::new().add_child(rect).add_child(padded_label))
    }
}
}

Install per-call: Button::new(lit!("Save")).style(MaterialFilledButton). Install theme-wide:

#![allow(unused)]
fn main() {
let mut theme = intui::light();
theme.style_slots.button = Some(Rc::new(MaterialFilledButton));
}

The widget honours this precedence at every build():

per-call .style(...)  >  theme.style_slots.button  >  RecipeButtonStyle::default()

Tested end-to-end in teksilo-widgets/src/button.rs under theme_slot_supplies_button_style_when_no_override / per_call_style_override_wins_over_theme_slot.

Built-in presets

Each preset is just a function returning Theme. Apps can write their own without depending on any sibling crate:

#![allow(unused)]
fn main() {
pub fn brutalist_light() -> Theme {
    let mut theme = intui::light();
    theme.colors.accent     = Color::new(1.0, 0.0, 0.4, 1.0);   // hot pink
    theme.shape.radius_md   = 0.0;                              // sharp corners everywhere
    theme.style_slots.button   = Some(Rc::new(MyBrutalistButton));
    theme.style_slots.checkbox = Some(Rc::new(MyBrutalistCheckbox));
    theme
}
}

Migration status (as of this branch)

Every themable widget is on the Tier-3 trait + recipe-default + slot lookup. No themable widget self-paints anymore. 43 widgets across 38 style traits, spanning seven families (a "trait" can cover more than one widget — e.g. ListContainerStyle styles both ListView and TreeView; ChartStyle styles BarChart, LineChart, and PieChart):

Controls

Inputs

Containers

Overlays

Rows / Items

Chrome

Data Visualization

¹ Multi-method trait — see Multi-method styles below.

² All-recipe trait, no make_* methods — see Data-visualization styling below. Its default impl is the one entry in this table whose Recipe*Style does not live under teksilo-widgets/src/styles/* — teksilo-charts deliberately has no dependency on teksilo-widgets, so its default style has to live where its own dependencies already reach. See charts.md §11 for the full reference.

³ Carries a defaulted label-role hook — StandardItemStyle::selected_label_role and MenuItemStyle::highlighted_label_role, both -> Option<TextRole>, both None by default.

A row builds its label before any style's make_body runs, so a style cannot recolour the text it is about to paint behind. That is fine for a design language whose selection is a pale wash — IntUI and Fluent both keep TextRole::Primary on top of theirs — and impossible for one whose selection is a solid fill: macOS's accent capsule would leave labelColor at roughly 3.5:1. The hook lets the style declare the role and the widget compose it into the label's colour signal (and, for a menu row, its shortcut's), gated on the row actually being emphasised so an unemphasised or window-inactive row keeps its normal label.

Same shape as ButtonStyle::label_text_role, and defaulted for the same reason: every existing style is unchanged.

#![allow(unused)]
fn main() {
impl StandardItemStyle for MyStyle {
    fn make_body(&self, cfg: &StandardItemStyleConfig, ctx: &mut BuildContext) -> WidgetId { … }

    // Only needed when `make_body` fills the selection with a colour
    // the default label cannot read on.
    fn selected_label_role(&self) -> Option<TextRole> {
        Some(TextRole::OnAccent)
    }
}
}

The legacy per-widget dimension structs are gone: the 17 old teksilo-tokens::components::*Style structs were deleted and their IntUI constants folded into the matching teksilo-widgets/src/styles/recipe_*_style.rs modules. The ComponentStyles struct has been fully removed from Theme. Migrated widgets read entirely from theme.style_slots.* plus their Recipe*Style defaults. Dimension data for any remaining non-themable widgets (toolbar, status bar, accordion, …) lives directly in their Recipe*Style modules as pub const blocks.

The teksilo-theme-material3 sibling preset is now a real Material 3 theme (baseline #6750A4 scheme, M3 shape/typography, pill 40 dp buttons with state-layer hover, the M3 switch, 12 dp cards) and the proving ground for the recipe-vocabulary additions above. Its optional bundled-fonts feature embeds Roboto. The framework primitives it needed — FillRecipe::StateLayer, per-side BorderRecipe + BorderPosition, gradient PaintProp, the configurable FooRecipe sweep, the cross-design-language color roles (TextRole::OnError, SurfaceRole::{ErrorContainer, Container, ContainerRaised, ContainerSunken}), Easing::CubicBezier, ToggleStyleConfig::is_pressed, and TeksiloAppBuilder::register_fonts — are all in place, so the -fluent and -macos presets below and a future GTK4-Adwaita one follow the same path.

The teksilo-theme-fluent sibling preset is a full Windows 11 / WinUI 3 theme, transcribed from WinUI's own Common_themeresources_any.xaml and the control theme-resource dictionaries: the light and dark colour dictionaries (exposed in full through the FluentPalette theme extension), the two-radius geometry (ControlCornerRadius 4 dp / OverlayCornerRadius 8 dp), the WinUI type ramp at zero tracking, and the four Control*AnimationDuration steps on ControlFastOutSlowInKeySpline. It installs Tier-3 chrome for 25 style slots: eight are real impl FooStyle blocks where the WinUI control is structurally its own thing — the button's elevation edge (a heavier stroke on the bottom edge in light, the top edge in dark, dropped on press), the two-tone high-contrast focus ring, the ToggleSwitch's off-state outline and morphing knob, the filled unchecked checkbox and radio, the field's accent focus underline, the slider's two-circle thumb, the menu row's neutral hover, and the list row's selection pill — while the rest are the shipped Recipe*Style constructed with Fluent metrics. light_with_accent / dark_with_accent rebuild the whole accent family around a caller-supplied seed, the substitution Windows performs when the user picks an accent colour. Mica and Acrylic resolve to the opaque fallbacks WinUI itself uses when the compositor material is unavailable; Segoe UI Variable cannot be redistributed, so the optional system-fonts feature names it for the text engine to resolve rather than bundling it.

The teksilo-theme-macos sibling preset is a full macOS Aqua / Dark Aqua theme. It is the one preset whose source publishes almost nothing: Apple attaches a standing disclaimer to every colour value it prints, and states no corner radii, no control heights, no focus-ring geometry and exactly one animation duration. Every literal in the crate is therefore tagged at its definition as [HIG] (published — the 13-hue system-colour table and the whole typography ramp), [measured] (a capture of the private NSColor enumeration, or a screen measurement) or [derived] (computed, with the rule given). AppKit's wider vocabulary — four label grades, two independent selection families, the control bezel, the eight System Settings accents — is exposed through the MacOsPalette theme extension.

Geometry is 6 dp in-page / 10 dp floating (menus at their own measured 9 dp) on a 22 dp control height, a third under Fluent's 32. Typography is the published SF ramp — Body 13/16, Callout 12/15, Subheadline 11/14 — carrying Apple's signed tracking: −0.08 pt at 13, exactly 0 at 12, +0.06 at 11. It is the only Teksilo preset that tracks non-uniformly and the only one whose tracking changes sign. Motion is Core Animation's default 0.25 s on kCAMediaTimingFunctionEaseInEaseOut — cubic-bezier(0.42, 0, 0.58, 1), symmetric where Fluent's is decelerate-only.

It installs Tier-3 chrome for 28 style slots; eight are real impl FooStyle blocks: the push button's bezel (shadow, face gradient, hairline, Dark-Aqua catch-light — dropped on press, and deliberately absent from the accent-filled default button), a focus ring that is the accent rather than Fluent's neutral outline, the NSSwitch's 18 dp knob in a 22 dp track, the 14 dp bezelled checkbox and radio, the field's accent focus halo, the slider's plain round knob, the menu row's accent fill with a white label, and the list row's selection capsule. light_with_accent / dark_with_accent and the SystemAccent enum rebuild the accent family; linkColor deliberately does not follow, as on macOS.

Four places deviate from Apple's own numbers to clear WCAG, each documented at its assignment with the measurement that forced it and each pinned by a test that also asserts the premise — so if Apple's value ever starts passing, the deviation can be reverted rather than inherited. Two framework additions came out of it: the defaulted label-role hooks described above, without which a solid-accent selection cannot recolour the text on top of it.

Known limitations are stated rather than deferred: the OS accent is not read (Teksilo's platform layer returns only the light/dark preference on macOS), vibrancy resolves to each material's opaque fallback, the TableView / GridView selection band is an accent wash rather than the capsule (those views paint the shared surface_selected token behind app-supplied cells this preset cannot retint), and San Francisco is named under the optional system-fonts feature rather than bundled.

Still ahead on the styling roadmap: image-backed styles, the ImageTheme TOML manifest loader, and a GTK4-Adwaita sibling preset crate.

Multi-method styles

Most style traits have a single make_body(cfg, ctx) -> WidgetId method. Four widgets need finer granularity — the trait splits chrome into multiple slots so a custom impl can replace one piece without re-implementing the others:

• TabStyle — make_body themes a single tab header (accent indicator + focus ring + label slot composition); make_bar themes the whole strip (optional backdrop fill, content-pane separator, drag-reorder drop indicator). TabStyleConfig carries indicator_position (TabIndicatorPosition::{OuterEdge, InnerEdge}) so the active-tab highlight can hug either edge; the default RecipeTabStyle honours all four edges (outer/inner × horizontal/ vertical, RTL-correct). Per-tab backgrounds, the bar backdrop, inter-tab dividers, and text-colour roles are widget-level TabBar/TabWidget builders rather than part of the trait — see tab-widget.md "Appearance".
• DialogStyle — make_panel themes the modal surface (shadow + corner radius + padding + container chrome); make_scrim themes the full-viewport overlay backdrop (the click-outside-to-dismiss layer). Wired into the in-tree modal pipeline so the scrim is a proper child of the dialog overlay, not a hand-rolled rect.
• TableStyle — make_header_cell (column header chrome: hover tint, resize-handle band, raised background), make_sort_indicator (the up/down arrow), make_row_background (per-row surface, with selection + hover + zebra states). The body cell stays app-controlled — same delegate that produces the cell's content also owns its paint.
• CalendarStyle — make_day_cell, make_zoom_cell (month / year picker grid), make_header (month-year label + nav buttons). Calendar is unusually paint-heavy and the three slots match the three distinct visual modes (day grid, zoom grid, header).

For these traits, a custom impl must implement every method (no default impls beyond the trait's own — the recipe defaults compose the four slots into the IntUI look). Apps that only want to tweak one slot typically forward the others to Recipe*Style::default().

Data-visualization styling

ChartStyle (BarChart / LineChart / PieChart, teksilo-charts) is a third trait shape, distinct from both the single-method make_body traits and the multi-method traits above:

#![allow(unused)]
fn main() {
pub trait ChartStyle: 'static {
    fn bar_fill(&self, cfg: &ChartFillContext) -> FillRecipe;
    fn area_fill(&self, cfg: &ChartFillContext, opacity: f32) -> FillRecipe;
    fn donut_fill(&self, cfg: &ChartFillContext) -> FillRecipe;
    fn gridline(&self, theme: &Theme) -> BorderRecipe;
}
}

Every method returns a Tier-2 recipe (FillRecipe / BorderRecipe) directly — none returns a WidgetId. Charts paint through Canvas calls inside their own paint() instead of composing a child widget subtree, so there is no make_*(cfg, ctx) -> WidgetId step for a custom impl to hook: the widget resolves the active ChartStyle, asks it for a recipe, and paints that recipe's fill/stroke directly. Where TabStyle/DialogStyle/TableStyle/CalendarStyle split chrome into named WidgetId-returning slots because each slot is a distinct sub-tree, ChartStyle splits into named recipe-returning methods because each is a distinct paint operation (bar fill vs. area fill vs. donut fill vs. gridline stroke) inside one widget's own paint pass. Resolution precedence is identical to every other trait: per-call .style(impl ChartStyle) > theme.style_slots.chart > RecipeChartStyle::default(). Full reference: charts.md §11.

Custom widgets and the styling system

Writing your own composing widget? Three steps to make it themable:

1. Declare a closed MyWidgetVariant enum for the design-language presentations users can pick (mirror ButtonVariant's shape).
2. Define a MyWidgetStyle trait in your own crate with a make_body(cfg, ctx) -> WidgetId signature. The cfg struct exposes the inputs that vary by interaction state (Signal<bool>s for hover/pressed/etc.), the variant, and pre-built child subtrees.
3. Ship a RecipeMyWidgetStyle as the default impl. Add a slot to your own slot-bag struct (or attach via theme.extensions if you only need app-internal use).

The trait pattern doesn't require buying into Teksilo's slot bag — you can ship the trait + default impl and let users override via MyWidget::style(...) per call. The slot bag is for theme-wide installation; it's optional, but it's how the framework's themable widgets get reskinned across an app.

See also

• docs/reactive-theme.md — Signal-backed Theme, color signals, theme swaps without rebuild.
• docs/image-themes.md — designer-workflow deep reference (Figma / Penpot / Canva → 9-slice manifest → theme). (Not yet shipped; design pending.)
• docs/widgets-overview.md — per-widget variant + style trait references.
• docs/accessibility-overrides.md — style trait impls do not participate in accessibility; the widget owns its accessibility(builder) regardless of which style is installed.

Reactive Theme Reference

This doc covers the reactive layer — how Theme flows through Signals, roles, and props so a theme swap repaints without a rebuild. For the broader styling picture (the four-tier ladder: tokens → variants → recipes → style protocols, Theme construction, per-widget *Variant enums and *Style traits), see styling-system.md.

Teksilo runs its theme through three layers of reactive primitives:

The rules:

1. set_theme never rebuilds. It updates the signal and dirty-marks every node; the next layout/paint pass reads the new theme and repaints affected widgets. Focus, scroll offsets, expanded panels — all interaction state survives a theme switch.
2. Roles resolve at paint/layout time. A widget that stores ColorProp::TextRole(TextRole::Primary) looks up ctx.theme.colors.text_primary in its paint — never at build time.
3. User code almost never needs to name theme_signal. Builders accept roles directly; Signal<Role> covers the interaction-driven case.

Quick reference

#![allow(unused)]
fn main() {
use teksilo::prelude::*;  // re-exports Color, Role enums, ColorProp, TextStyleProp

// Plain text — default role is TextRole::Primary.
TextWidget::new(lit!("Hello"))

// Role-based color: resolved against current theme, reactive.
TextWidget::new(lit!("Error!")).color(TextRole::Error)

// Role-based typography: same story, but the text style role.
TextWidget::new(lit!("Section")).style(TextStyleRole::BodyBold)

// Static color: frozen literal.
TextWidget::new(lit!("Custom")).color(Color::from_hex("#FF00FF"))

// Reactive signal (usually interaction state): repaints on signal change.
TextWidget::new(lit!("")).text(status).color(hover_color_signal)

// Panel with role-based surface and border.
Panel::new()
    .background(SurfaceRole::Raised)
    .border_color(BorderRole::Default)
    .corner_radius(8.0)

// Reactive SurfaceRole — the role itself depends on interaction state.
let bg_role = interaction.map(|s| match s {
    InteractionState::Hovered => SurfaceRole::Hover,
    InteractionState::Pressed => SurfaceRole::Pressed,
    _                          => SurfaceRole::Transparent,
});
RectWidget::new().background(bg_role)
}

WidgetTree::set_theme

#![allow(unused)]
fn main() {
pub fn set_theme(&mut self, theme: Theme)
}

Declared at crates/teksilo-core/src/widget_tree.rs (around line 1120). Sequence:

1. self.theme = theme.clone() — the cached &Theme accessor still works.
2. self.theme_signal.set(theme) — fires observers (derived Signal<Theme>s, role-carrying ColorProps via their bindings).
3. self.arena.mark_all_dirty() — every node needs layout and paint.

No rebuild_built_widgets call, no focus clearing. set_locale follows the same pattern on locale_signal.

For per-subtree overrides:

#![allow(unused)]
fn main() {
tree.set_theme_override(panel_id, |theme| {
    theme.colors.surface_main = Color::from_hex("#...");
});
}

This only marks the subtree dirty; layout/paint contexts resolve ancestor overrides via WidgetArena::resolve_theme.

Constructing and loading themes

Built-in presets

There is no Theme::default() / Theme::*_default(). Theme lives in teksilo-core::styles and is built through a preset constructor:

#![allow(unused)]
fn main() {
use teksilo::prelude::intui;

let light = intui::light();   // teksilo_core::presets::intui::light
let dark  = intui::dark();
}

Both are neutral Int UI baselines — not visually distinctive, designed to be customized. Apps usually start from one of them and override the slots they care about. For the full styling picture (variants, recipes, style traits) see styling-system.md.

Programmatic customization via struct spread

Theme (teksilo-core::styles) and the token structs ColorTokens, TypographyTokens, ShapeTokens, LayoutTokens, MotionTokens (teksilo-tokens) are plain structs. Override the fields you want and spread the rest from a preset base:

#![allow(unused)]
fn main() {
use teksilo_core::styles::Theme;
use teksilo_tokens::{ColorTokens, TypographyTokens, TextStyle, Color};
use teksilo::prelude::intui;

let editor_light = Theme {
    colors: ColorTokens {
        accent: Color::from_hex("#2E7D32"),
        accent_hover: Color::from_hex("#1B5E20"),
        text_on_accent: Color::WHITE,
        surface_main: Color::from_hex("#FAFAF5"),
        ..ColorTokens::light_default()
    },
    typography: TypographyTokens {
        body: TextStyle {
            family: "Literata".to_string(),
            size: 16.0,
            ..TextStyle::default()
        },
        ..TypographyTokens::default()
    },
    ..intui::light()
};

tree.set_theme(editor_light);
}

ColorTokens::light_default() and the other raw-token defaults still live in teksilo-tokens — only the Theme-level constructor moved.

The same pattern works for sub-trees via set_theme_override(panel_id, |theme| { ... }) (see above).

Loading from a file

Theme and every token struct derive serde::Serialize and serde::Deserialize, so themes round-trip through any serde format the app picks (TOML, JSON, RON, YAML). The style_slots and extensions fields are #[serde(skip)] — a deserialized Theme gets empty defaults for those, so style-trait overrides are re-installed in code, not loaded from the file. The runtime cost is one read + one deserialize + one set_theme call:

#![allow(unused)]
fn main() {
use std::fs;
use teksilo_core::styles::Theme;

let toml = fs::read_to_string("themes/editor-light.toml")?;
let theme: Theme = toml::from_str(&toml)?;
tree.set_theme(theme);
}

Authoring a theme file is the inverse — toml::to_string(&intui::light())? writes a complete starter file the user can edit.

Partial files — current limitation

The token structs do not carry #[serde(default)] on their fields, so a file missing any field fails to deserialize. To accept hand-edited theme files that only specify a few overrides, the app needs to do the merge itself — typically by deserializing into an Option-wrapped or serde_json::Value shape, then folding non-null values onto a base produced by intui::light(). A future change can add #[serde(default)] so partial files merge automatically; until it lands, treat the file format as "all fields required."

Role enums

All defined in crates/teksilo-tokens/src/roles.rs, exported from teksilo_tokens::{TextRole, SurfaceRole, BorderRole, TextStyleRole} and re-exported through teksilo::prelude.

TextRole

Foreground text color.

Primary (default), Secondary, Disabled, OnAccent, Accent, Error, Warning, Success, OnError, OnErrorContainer, Link, LinkHover, LinkVisited, TooltipText, TooltipShortcut, EditorFg, EditorGutterFg.

SurfaceRole

Filled-area color (panel backgrounds, button fills, selection highlights).

Main (default), Content, Raised, Sunken, Hover, Pressed, Selected, SelectedInactive, AltRow, Accent, AccentHover, AccentPressed, AccentDisabled, AccentSubtle, StatusInfo, StatusSuccess, StatusWarning, StatusError, ErrorContainer, Container, ContainerRaised, ContainerSunken, TooltipBg, EditorBg, EditorCaret, EditorCurrentLineBg, EditorSelectionBg, Scrim, Transparent (paints nothing — the "no surface" slot in interaction chains).

The OnError/*Container roles are the cross-design-language slots shared by Material 3 / Fluent / macOS / GTK4-Adwaita; design-language-specific colors (M3 secondary/tertiary triads, full tonal ladder) live in per-theme extensions instead.

BorderRole

Stroke color.

Default (default), Strong, Focused, Error, Warning, Divider, DividerStrong, TooltipBorder, Accent, AccentDisabled, Transparent.

Disabled auto-dim. When a leaf resolves a role-based ColorProp in a disabled subtree (enabled == false), TextRole substitutes Disabled and the accent SurfaceRole/BorderRole family (Accent/AccentHover/AccentPressed, BorderRole::Accent) substitutes its AccentDisabled counterpart — so role-driven accent chrome dims without per-widget handling. Non-accent surfaces/borders pass through.

TextStyleRole

Typography role.

Body (default), BodyBold, Small, SmallBold, Tiny, Mono.

Every role has a resolve(&ColorTokens) (or resolve(&TypographyTokens) for TextStyleRole) method. Paint/layout code already calls those under the hood when reading a ColorProp / TextStyleProp.

Adding a role. Add the variant to the enum, extend resolve(..), re-export from teksilo::prelude. Add a role only when more than one widget repeatedly wants the same token — otherwise a .color(Color::..) literal is fine.

ColorProp

#![allow(unused)]
fn main() {
pub enum ColorProp {
    Static(Color),
    Bound(Signal<Color>),
    TextRole(TextRole),
    SurfaceRole(SurfaceRole),
    BorderRole(BorderRole),
    DynamicTextRole(Signal<TextRole>),
    DynamicSurfaceRole(Signal<SurfaceRole>),
    DynamicBorderRole(Signal<BorderRole>),
}
}

Widget color builders accept impl Into<ColorProp>. Every input shape above implements From, plus From<Prop<Color>> for migrating legacy callers. Call cp.resolve(&theme) in paint and cp.register_if_bound(self_id, registry, level) in build to hook signal-bearing variants into dirty-tracking.

Role variants need no binding registration — the tree-wide mark_all_dirty inside set_theme already forces a repaint.

Which variant to use

TextStyleProp

#![allow(unused)]
fn main() {
pub enum TextStyleProp {
    Static(TextStyle),
    Role(TextStyleRole),
}
}

TextWidget::style(...) and the other style-accepting builders take impl Into<TextStyleProp>. Default is TextStyleRole::Body, so a bare TextWidget::new(lit!("x")) follows the theme typography.

Resolved at paint/layout via prop.resolve(&ctx.theme.typography). Changing Theme::typography on a running tree updates every TextWidget that uses a role; widgets that passed a raw TextStyle stay frozen (that's the user intent — custom fonts stay custom).

Interaction-driven colors: the Signal<Role> pattern

For state-dependent colors (hover, pressed, focus, disabled), emit a Signal<Role> from the interaction signal and pass it as ColorProp directly — the paint layer handles the theme lookup. No explicit theme_signal zip.

Template — Button (canonical example)

#![allow(unused)]
fn main() {
fn resolve_bg_role(style: ButtonVariant, state: InteractionState) -> SurfaceRole {
    match (style, state) {
        (ButtonVariant::Default, InteractionState::Hovered) => SurfaceRole::AccentHover,
        (ButtonVariant::Default, InteractionState::Pressed) => SurfaceRole::AccentPressed,
        (ButtonVariant::Default, _)                          => SurfaceRole::Accent,
        (ButtonVariant::Flat,    InteractionState::Hovered) => SurfaceRole::Hover,
        (ButtonVariant::Flat,    _)                          => SurfaceRole::Transparent,
        // ... Regular variant ...
    }
}

impl Widget for Button {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let interaction = ctx.signal(InteractionState::Idle);
        let style       = self.style;

        let bg_role     = interaction.map(move |s| resolve_bg_role(style, *s));
        let text_role   = interaction.map(move |s| resolve_text_role(style, *s));
        let border_role = interaction.map(move |s| resolve_border_role(style, *s));

        ctx.add(
            RectWidget::new()
                .background(bg_role)
                .border_color(border_role)
                // ...
        );
        // TextWidget inside picks up the text role the same way.
    }
}
}

The interaction signal is the only upstream root the role signals observe. When the user moves the mouse off the button, only interaction fires; when the theme changes, mark_all_dirty triggers the repaint and the paint-time resolve(&theme) picks up the new colors. Two separate triggers, same rendering path.

See crates/teksilo-widgets/src/button.rs for the full widget; menu_list::KeyboardHighlightWrapper and combo_box::DropdownItem are smaller walk-throughs.

When Signal<Role> doesn't fit

Three cases keep an explicit theme_signal:

1. Color transformations (token.with_alpha(0.2) etc.) — no role represents "accent at 12 % alpha"; use theme_signal.map(|t| t.colors.accent.with_alpha(0.12)) to get a Signal<Color>.
2. Effects on external state — the rich-text engine's per-frame palette, for instance. See primitives/text_input_field.rs for the ctx.effect(&theme_signal, move |theme| { ... }) pattern.
3. Layout snapshots — let shape = ctx.theme_signal().get().shape at the top of build() captures corner radii; let layout = ctx.theme_signal().get().layout captures spacing values. These rarely differ across themes; the snapshot is fine.

Dimension props (Prop<f32>)

Layout primitives accept impl Into<Prop<f32>> for dimensions that may come from a theme-derived signal:

Pass a static f32, a Signal<f32>, or a Prop<f32>; the builder registers a BindingLevel::Relayout binding for signal variants so layout re-runs on theme-driven spacing changes.

DX — what developers should write

Good (most common paths):

#![allow(unused)]
fn main() {
// "I want a normal label": zero color code.
TextWidget::new(lit!("Status"))

// "I want an error-colored label": one role.
TextWidget::new(lit!(msg)).color(TextRole::Error)

// "I want a raised panel": one role.
Panel::new().background(SurfaceRole::Raised).child(...)

// "I want a Bold Heading": one style role.
TextWidget::new(lit!("Settings")).style(TextStyleRole::BodyBold)
}

Good (custom / reactive):

#![allow(unused)]
fn main() {
// Frozen brand color.
Panel::new().background(Color::from_hex("#e2007a"))

// Signal-driven non-theme color.
Panel::new().background(animated_banner_color)

// Interaction-driven role (the important pattern for new widgets).
let bg = interaction.map(|s| map_to_surface_role(*s));
RectWidget::new().background(bg)
}

Avoid (legacy pattern — only keep when no role fits):

#![allow(unused)]
fn main() {
// Don't write this for normal theme colors:
.color(ctx.theme_signal().map(|t| t.colors.text_primary))

// Write this instead:
.color(TextRole::Primary)
}

Migration cheat sheet

Files to know

Animation

Companion to: architecture.md Scope: Signal-driven animation in Teksilo — Signal<f32>::animate_to, the scheduler behind it, and the design rules for deciding when (and when not) to animate.

1. Why animation exists in a mostly-instant framework

Teksilo's motion vocabulary is borrowed from JetBrains's Int UI design language: hover and press are instant, and animation is reserved for a narrow set of floating transitions — a dialog appearing, a snackbar sliding in, an accordion expanding, a toggle thumb moving. A serious desktop application that a user drives for hours gets tiring fast if every state change fades or slides; interaction feedback needs to be crisp. Decorative animation is explicitly discouraged.

What's left is the minimum set of places where motion helps a user track a change:

• Transform transitions that would otherwise teleport the eye (toggle thumb 0 → 1, accordion height 0 → full).
• Floating element appearance that should not pop into existence (tooltip fade at ~120 ms, balloon slide at ~200 ms, dialog scale-in at ~300 ms).
• Indeterminate progress where a looping animation communicates "still working" (progress bar indeterminate mode).
• Smooth scrolling when programmatic scroll_to would otherwise jump the viewport.

Everything else — hover color shifts, focus ring appearance, press feedback, checkmark toggles — is instant. The framework's theming pipeline (reactive Signal<Role> → theme lookup per frame) covers "the color changed" without a scheduler at all; see reactive-theme.md.

2. Signal as the animation substrate

The entire animation API is attached to Signal<f32>. There is no separate Animation type for widget authors to manage, no AnimationController, no lifetime tracking by hand:

#![allow(unused)]
fn main() {
// Somewhere in build() or a handler:
knob_position.animate_to(1.0, Duration::from_millis(150), Easing::EaseInOut);
}

The knob_position: Signal<f32> then interpolates from its current value to the target over the given duration. Any widget observing the signal (via Prop<f32>, via observe(), or via binding.bind_to(..., BindingLevel::RepaintOnly)) re-paints on each tick as the value slides. Because animation flows through the same signal plumbing as any other reactive value, animated widgets do not need special awareness of the scheduler.

A signal created with Signal::new(0.0_f32) does not support animation — animate_to panics. Animation-capable signals are created with Signal::new_animated(value), or — the usual path inside a widget's build() — with BuildContext::animated_signal(value), which also registers the signal with the tree's scheduler so the scheduler can cancel the animation if the owning widget is rebuilt or destroyed (see §4 below).

3. Easing and durations live in tokens

Easing curves and standard durations are design tokens, not ad-hoc magic numbers. They live in crates/teksilo-tokens/src/motion.rs:

#![allow(unused)]
fn main() {
pub enum Easing {
    Linear, EaseIn, EaseOut, EaseInOut,
    // General CSS cubic-bezier(x1,y1,x2,y2) — for design-language motion
    // specs that don't reduce to the named curves (M3 emphasized, Fluent).
    // Build via `ctx.animate().cubic_bezier(x1,y1,x2,y2)` / `.m3_emphasized()`.
    CubicBezier { x1: f32, y1: f32, x2: f32, y2: f32 },
}

pub struct MotionTokens {
    pub duration_instant: Duration,             //   0 ms — most state changes
    pub duration_fast:    Duration,             // 120 ms — tooltip fade, interactive feedback
    pub duration_normal:  Duration,             // 200 ms — notification slide
    pub duration_slow:    Duration,             // 300 ms — dialog scale-in
    pub duration_collapse:               Duration, // 200 ms — accordion / disclosure tween
    pub duration_indeterminate_sweep:    Duration, // 900 ms — indeterminate sweep / spinner period
    pub easing_standard:  Easing,               // mild ease-out
}
}

Widgets reach for MotionTokens through the current Theme. Int UI's guidance — one mild ease-out for everything — is the default; a theme can override if a platform target wants a different feel. Avoid hardcoding durations in widget code when a token fits; the tokens are the lever a designer rebrands a theme through.

The Easing::apply(t) method takes a linear parameter t ∈ [0, 1] and returns the eased value in the same range. lerp(a, b, t) in the same file does plain linear interpolation; the scheduler combines the two to produce each frame's value.

4. The scheduler — what the framework owns

AnimationScheduler is the signal-tween scheduler — one of three visibility-aware motion subsystems on WidgetTree. The other two are AnimatedQuadRegistry (shader-driven quad uniforms — Spinner, ProgressBar::indeterminate, animated IconWidget; see idle-and-animation.md) and FrameTickScheduler (per-frame-effect closures — Pulse, Cycle; see §5.6 below). All three share the motion_visibility helpers so the visibility gate is one canonical primitive.

Widget code never constructs AnimationScheduler directly. Its job is small but non-trivial:

• Tick every active animation on each frame the tree pumps. Current value = lerp(start, end, easing.apply(t)); t is elapsed/duration clamped to [0, 1].
• Stop cleanly when an animation reaches its target (set exactly the end value on the terminal tick, regardless of epsilon quantization).
• Pause when the window is occluded or unfocused (set_window_active(false)). The scheduler reports no next deadline to the event loop during pause, so a hidden window doesn't keep the event loop in WaitUntil. On resume, each animation's start time is rebased by the paused duration — a sweep paused at 50% resumes from 50%, phase-continuous, not snapped.
• Cancel when the driving widget disappears. cancel_by_widget(id) runs whenever a widget is rebuilt or destroyed. Otherwise a Signal<f32> clone in the scheduler would outlive its widget, silently ticking a signal whose observers no longer exist.
• Skip offscreen ticks for looping animations. If a widget hasn't painted in the latest paint epoch, the scheduler holds back ticks for any looping animation it owns — keeps the animation alive internally but doesn't drive work through it. This avoids re-paints for spinners and indeterminate progress bars inside a minimized split-view pane or a closed accordion subtree. One-shot animations always tick regardless of paint epoch: a widget like Collapse whose own size depends on the animated value (zero height when collapsed → never painted → never re-stamped) would deadlock if the gate also covered one-shots. The cost is bounded — a one-shot with no observers on screen still completes in duration and then stops itself.

The frame-loop integration point is WidgetTree::process_pending_animations (called from layout()) plus scheduler.tick(now, &arena, paint_epoch) called from the event loop. Widget authors don't invoke either directly.

4.1 Why animated_signal specifically

BuildContext::animated_signal(value) is the one-line way to get an animation-capable Signal<f32> that is correctly tied to the calling widget's lifetime:

#![allow(unused)]
fn main() {
fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
    self.knob_position = ctx.animated_signal(if self.on.get() { 1.0 } else { 0.0 });
    // ...
}
}

The signal it returns supports animate_to, is registered with the scheduler, and has its owner recorded as ctx.self_id(). When the widget is rebuilt (or destroyed), the scheduler cancels all animations on signals owned by that widget — no orphan tickers.

If a widget constructs its Signal<f32> outside build() (a handful of widgets do, to share the signal with callers), it can call ctx.register_animated_signal(&signal) inside build() to associate the signal with the current widget for cancellation purposes. See ScrollArea and TreeView for examples.

4.2 animate_looping for indeterminate work

For animations that should run until explicitly cancelled — spinners, marquee tickers, indeterminate progress bars — Signal::animate_looping(target, period, easing, frame_interval) sets the signal to its start value each time it reaches the target and loops indefinitely. This is the path used by ProgressBar in indeterminate mode:

#![allow(unused)]
fn main() {
self.indeterminate_pos = ctx.animated_signal(0.0);
self.indeterminate_pos.animate_looping(
    1.0,
    ctx.theme().motion.duration_indeterminate_sweep,
    Easing::Linear,
    Some(INDETERMINATE_FRAME_INTERVAL),
);
}

Looping animations respect prefers_reduced_motion: widgets check ctx.prefers_reduced_motion() before starting them and fall back to a static representation when the user has disabled motion. Non-looping transitions typically don't need the check — a one-shot 150 ms ease is below the threshold most accessibility guidance worries about — but looping ones always do.

4.3 AnimationSpec — the recommended façade

Reaching for animate_to(target, Duration::from_millis(150), Easing::EaseInOut) directly works, but it shifts three responsibilities onto the call site: pulling the right MotionTokens constant from the theme, picking pixel-stable epsilon / frame_interval defaults for looping animations, and remembering to honour prefers_reduced_motion. AnimationSpec is a fluent builder that captures all three at construction time:

#![allow(unused)]
fn main() {
// One-shot, theme-aware, accessibility-aware:
let spec = ctx.animate().fast().standard();
spec.to_or_snap(&knob_position, target);
//                ^^^^^^^^^^^^ snaps without tween under prefers-reduced-motion

// Looping with sub-perceptual epsilon and 60 Hz throttle baked in:
ctx.animate().sweep().linear().to(&sweep_pos, 1.0);
//             ^^^^^^^ implies looping(), reads duration_indeterminate_sweep
}

Duration presets (fast() / normal() / slow() / collapse() / sweep() / instant()) all read from the live theme's MotionTokens — no hardcoded Duration::from_millis(...) literals at the call site. Easing presets (standard() / linear() / ease_in_out() / etc.) similarly pull easing_standard from tokens. looping() flips on sub-perceptual ε = 1/255 and a 60 Hz frame interval (16.667 ms) — the safe defaults for paint-bound loops, matching the most common display refresh rate so a continuous loop advances once per vsync; frame_interval(d) overrides for slower loops (e.g. 66 ms = 15 Hz for a wide sweep where the eye can't resolve faster motion). to(&signal, target) always tweens; to_or_snap(&signal, target) snaps without tween when prefers_reduced_motion is true.

AnimationSpec is a thin façade — it constructs an AnimationRequest and calls Signal<f32>::try_animate_with_options. The lower-level animate_to / animate_looping paths remain public; reach for them only when you need control the spec doesn't expose (custom epsilon for non-pixel signals, max_duration for indefinite loops with a bounded budget). Source: crates/teksilo-core/src/animation_builder.rs.

5. Worked examples from the widget tree

5.1 Toggle thumb — the canonical transform transition

crates/teksilo-widgets/src/toggle.rs:

#![allow(unused)]
fn main() {
fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
    let initial = if self.on.get() { 1.0 } else { 0.0 };
    self.knob_position = ctx.animated_signal(initial);
    let knob_spec = ctx.animate().fast().standard();
    // ...
    let toggle = move || {
        let new_on = !on.get();
        on.set(new_on);
        let target = if new_on { 1.0 } else { 0.0 };
        knob_spec.to_or_snap(&knob_position, target);
    };
    // ...
}
}

• knob_position is recreated each build() — not preserved across rebuilds. This is intentional: rebuilds are rare (theme change, structural dirty), and the value is trivially restorable from self.on.
• The paint() method reads knob_position.get() directly and positions the knob at lerp(left_edge, right_edge, position).
• No Signal::map, no Prop::Bound wrapping needed — direct read in paint is fine because the scheduler's signal.set() on each tick already dirty-marks the widget for repaint via the binding registry.
• to_or_snap quietly snaps to the target without tweening when the platform reports prefers_reduced_motion — same handler code, accessible by default.

5.2 Accordion / Collapse — animating a layout dimension

Accordion wraps its content in a Collapse widget — the reusable primitive for the "animate child between hidden and natural height" pattern. Collapse drives an internal Signal<f32> from 0..1 with ctx.animate().collapse().standard().to_or_snap(...), and its layout_response reports natural * progress while place_children always lays the child out at its full natural size. The framework's clip pass crops the overflow during the tween. Effect: the visible height interpolates over the full duration without the child being squashed (which would re-wrap text and produce flicker).

Animating a layout-participating dimension is more expensive than animating a paint-only value — the binding level is Relayout, not RepaintOnly, so the tree dirtys the accordion's ancestor's layout on each tick. Use sparingly. Paint-only targets (offsets, scales, opacities — see §5.6) are cheaper.

5.3 Snackbar slide-in

crates/teksilo-widgets/src/snackbar.rs uses animate_to on a slide-offset signal that the paint phase applies as a y translation. The snackbar is placed via OverlayPlacement::BottomCenter and the animation slides the overlay in from below. At auto-dismiss time, the same signal animates back to its offscreen position before the overlay is removed.

5.4 Smooth programmatic scroll

When ScrollArea receives a ScrollIntoView request (for example after tab-focusing a child that is offscreen), it calls scroll_y.animate_to(target_offset, ...) instead of scroll_y.set(target_offset). The user sees the viewport slide to the new position rather than jumping. See scroll_area.rs.

5.5 Icon widget — sprite-sheet frame animation

icon_widget.rs animates a frame-index signal looping over the frame count for animated WebP icons. Frame interval comes from the asset, not from MotionTokens — this is a content-driven animation, not a UI transition.

5.6 Wrap-and-go animation widgets

Animation wrappers live under crates/teksilo-widgets/src/animations/ and are re-exported flat from teksilo::widgets. They package the common animation patterns so callers don't re-implement them:

• Fade wraps a child and tweens an internal opacity signal between 0 and 1 driven by a Signal<bool>. Layout-transparent: the child reports its full natural size at all opacity values. Built on BuildContext::set_opacity, a node-level opacity scope (parallel to clips_children) emitted by the rendering walker as SetOpacity / RestoreOpacity draw commands wrapping the subtree. Sub-perceptual opacities (< 1/512) are short-circuited — no draw passes.
• Collapse — see §5.2. The accordion-pattern primitive.
• Scale wraps a child and animates a uniform 2D scale on its entire subtree, driven by a Prop<bool>. Built on BuildContext::set_transform (see §5.7) — the renderer composes the scale matrix onto its transform stack so the wrapped subtree's text and shapes visually shrink together. Two modes: visual-only (default, reflow=false) — the slot stays at the child's natural size, only the visual content scales around the chosen origin (use for overlay enter/exit, "boop" feedback); reflow (.reflow(true)) — the wrapper's reported size shrinks with progress so siblings reflow as the wrapped content disappears (use for "card removal", pair with ScaleOrigin::TopLeading so the visual stays anchored at the slot's top-left as it collapses). Distinct from Collapse: Collapse shrinks one axis and "wipes" content via clipping (text inside stays full-size); Scale shrinks uniformly and text/icons visually get smaller.
• Rotate wraps a child and applies a 2D rotation (radians) to its subtree via set_transform. Layout-stable. No internal animation — the caller owns the angle signal and pairs it with Signal::animate_to for animated rotations. Use for animated chevrons (replacing the old "flip-two-static-icons" trick), spinning loaders not covered by Spinner, dial controls.
• Blur wraps a child and applies a Gaussian-equivalent blur to the entire subtree, driven by a Prop<f32> radius (logical pixels). Built on BuildContext::set_blur (see §5.7) — the renderer redirects the subtree's draws into an intermediate texture, runs a dual-Kawase chain at the requested radius, and composites the blurred result back at the widget's bounds. Layout-transparent: the child reports its full natural size at all radii. Sub-perceptual radii (< 0.5) are short-circuited at the walker — no offscreen pass, no allocation. Use for modal backdrops, click-to-reveal sensitive content (numerics / characters obscured by the blur), out-of-focus emphasis, animated frosted glass on modal show. Pair with an animated_signal and animate_to for animated enable/disable. See §5.8 for the offscreen-pass cost model.
• Spinner — circular-arc loading indicator backed by AnimatedQuadKind::SpinnerArc, the shader-driven path (see idle-and-animation.md §"Three animation paths — signal vs shader vs per-frame-effect"). One queue.write_buffer of AnimParams + one draw_indexed per frame; paint() does not run while spinning. Edges are anti-aliased via fwidth smoothstep ramps in the fragment shader. Honours prefers-reduced-motion with a static three-quarter arc fallback.

Pulse and Cycle drive their continuous motion through the per-frame-effect path rather than AnimationScheduler (which only knows linear tweens) or AnimatedQuadRegistry (which is paint-time GPU plumbing). They register a closure on ctx.frame_tick() for the tick action and a ctx.subscribe_frame_tick() RAII guard for visibility-aware chain management — the framework re-arms the frame chain after every render iff at least one subscriber's owner widget was painted in that frame, so a Pulse parked inside a non-selected Switcher branch contributes zero idle frames and resumes phase-continuous on the next show. The chain bootstrap (request_frame on subscription) and resume (post-render arm after the visible_when-driven repaint) are both handled by the framework. Widget code in the new shape:

#![allow(unused)]
fn main() {
pub struct Pulse {
    // …
    frame_tick_sub: Option<FrameTickSubscription>,
}

impl Widget for Pulse {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        // … set_opacity, reduced-motion early-out, … 
        ctx.effect(&ctx.frame_tick(), move |&delta| {
            // mutate opacity from sine of accumulated phase
        });
        self.frame_tick_sub = None;                        // drop old guard first
        self.frame_tick_sub = Some(ctx.subscribe_frame_tick());
        // …
    }
}
}

If you find yourself reaching for ctx.frame_request_handle().set(true) from inside a frame_tick effect for a visual continuous animation, prefer subscribe_frame_tick() instead — the raw handle keeps the event loop pumping regardless of visibility, while the scheduler-backed path auto-pauses on hidden owners. The raw handle is still the right tool for short-lived, owner-driven needs that aren't visibility-bound (caret blink that depends on focus state, drag auto-scroll while the pointer is captured).

Other wrappers in the same module — SmoothSize, Crossfade, Slide, Shake — are documented inline in their source files; run cargo run -p animations-kit for a visual showcase of every wrapper.

5.7 Per-node paint scopes

The framework ships four per-node paint scopes that wrapper widgets attach to themselves:

• BuildContext::set_opacity(id, prop) — the original. Render walker emits SetOpacity(value) / RestoreOpacity around the subtree; renderer maintains a stack and multiplies through. Bound at RepaintOnly. Used by Fade, Pulse, Crossfade, OverlayRequest::with_fade.
• set_clips_children(id, true) — a per-node clip rectangle to the node's own bounds. Used by ScrollArea, Collapse, MaxSize, Slide, Shake, SmoothSize, Scale, Rotate — anything whose subtree may overshoot the slot.
• BuildContext::set_transform(id, prop) — added with Scale and Rotate. Render walker emits PushTransform(matrix) / PopTransform around the subtree; renderer maintains a transform stack. Bound at RepaintOnly by default; reflow-driving wrappers (e.g. Scale::reflow(true)) must additionally bind their driver signal to themselves at Relayout for layout to track the value.
• BuildContext::set_blur(id, prop) — added with Blur. Render walker emits BeginBlurredSubtree { bounds, radius } / EndBlurredSubtree around the subtree; the renderer redirects drawing into an intermediate texture, runs a dual-Kawase blur chain at the requested radius, and composites the blurred result back. Bound at RepaintOnly. The only scope that triggers an offscreen render pass and per-frame texture allocation — see §5.8.

Scope nesting order on a single node, from outermost to innermost: BeginBlurredSubtree → SetOpacity → PushTransform → ...paint.... Reverse on close. The blur scope is OUTER on purpose: it captures the already-faded, already-transformed subtree into the intermediate texture so animated fade-in-and-blur behaves intuitively (the blur is applied to whatever the user would see, post-fade, post-transform).

The transform scope has one non-obvious twist worth pinning down for future widget authors: SetTransform semantics are "compose with stack-top", not "set absolute". A widget's own canvas-level transforms (canvas.translate(5, 5) etc.) emit SetTransform commands relative to the widget's own identity baseline; under a wrapper push, the renderer composes them onto the stack-top transform instead of clobbering it. With an empty stack (the default for any widget not under a transform wrapper), stack_top = identity and composition is a no-op — the change is purely additive and backwards-compatible. Identity-valued transforms are skipped at the walker layer (no push/pop emitted), so wrappers at their rest pose pay zero per-frame cost. Sub-perceptual blur radii (< 0.5 px) are similarly skipped — animated 0 → target_radius enable patterns pay zero cost when fully off.

5.8 Offscreen render passes — when blur breaks the single-pass model

The renderer is single-pass by default: every DrawCommand flows into one wgpu::RenderPass targeting the surface texture. Blur is the exception. A BeginBlurredSubtree { bounds, radius } / EndBlurredSubtree pair carves out a sub-pass that:

1. Allocates an intermediate RGBA8 texture sized to bounds × scale_factor (drawn from a renderer-side recycled pool keyed on power-of-two sizes — no per-frame allocation hot path).
2. Renders the subtree's draw commands into that texture (with a translation pushed onto the transform stack so the subtree paints at (0, 0) of the intermediate).
3. Runs the dual-Kawase chain on it: N = ceil(log2(radius)) downsample passes (each halves the texture, applies a 4-tap bilinear shader), then N upsample passes back to the source size with a different 4-tap shader.
4. Composites the final blurred texture into the parent pass at bounds via the standard quad pipeline (which already samples textures — this is just a textured-quad blit).

Each blur scope = N + N + 1 small render passes per frame for typical UI radii (R = 8–24 → N = 3–5). Cheap individually, but every blur scope opens a new pass on the encoder and breaks batch coalescing on the surrounding draws — don't sprinkle Blur widgets through a list view. Stable layouts (modal backdrops, sensitive-content panels, frosted side panels) are the natural fit.

The reference for this offscreen-render pattern is png_export.rs, which has been creating intermediate RENDER_ATTACHMENT | COPY_SRC textures and routing the renderer at them since the widget previewer shipped — the blur engine generalises that pattern into a recursive sub-pass.

For overlays, OverlayRequest::with_fade(duration) is the recommended path for tooltip / popover / snackbar fade-in / fade-out. The framework wires opacity internally — caller specifies just the duration:

#![allow(unused)]
fn main() {
tree.show_overlay(OverlayRequest {
    content_id, anchor, placement, dismiss,
    layer: OverlayLayer::InTree,
    parent_overlay: None, on_dismiss: None,
    fade_duration: Some(theme.motion.duration_fast),
});
}

When fade_duration is Some, WidgetTree creates an animated Signal<f32>, applies it as an opacity scope on the content (via set_opacity — same primitive Fade uses), kicks off the 0→1 tween at show time, and on dismiss reverses to 0 then defers the actual stack removal by duration so the tween plays out before the content goes dormant. The OverlayManager tracks fade-out state on a dual sim/real clock so headless tests can use tree.advance_time(...) to drive deterministic dismissal.

6. When NOT to use the animation system

Animation via animate_to is for a value that crosses time smoothly. It is not for:

• Color shifts on hover / press. Those are instant in Int UI's vocabulary. Express them as Signal<Role> mapped from the interaction state signal (see reactive-theme.md §"Interaction-driven colors"). No scheduler involved; color resolves from the current theme per frame.
• Caret blink. The caret is either drawn or not, on a cadence. It uses BuildContext::frame_tick() + request_frame() to pump the event loop on a schedule and flips a boolean — no smooth interpolation happens, so animate_to would be the wrong tool.
• Fade-in of a list of items appearing on filter change. Decorative; Int UI's guidance is "don't." If the visual disruption is bad enough to warrant fade, consider whether the list widget itself should not disrupt — for example, a virtualized list that only creates newly-visible items, rather than full remount on filter change.
• Tooltip delay. The opening delay is a timer, not an animation. Once the tooltip appears, its fade-in is driven by OverlayRequest::with_fade(theme.motion.duration_fast) (see §5.6) — the framework owns the opacity tween, callers do not roll their own animate_to on the tooltip content.
• Single-axis disclosure (an accordion section opening, a drawer expanding to a known height). Use Collapse instead of Scale — Collapse clips on one axis without re-running text layout or applying a transform scope, so it's cheaper and the visual ("shutter rolls down, text stays at full size") matches what users expect for disclosure. Scale is for uniform shrink-around-a-pivot ("card disappears", "icon boops"), where the visual content itself should get smaller.
• Per-list-row blur or anything that animates blur radius every frame. Blur is the most expensive scope in the framework — every enabled scope opens a separate render pass and runs 2N+1 Kawase passes per frame. For "fade-blur on reveal" patterns, animate the radius up to a static value and leave it there. For per-row obscuration of sensitive data, prefer a per-row text-redaction primitive over wrapping each row in Blur.

7. Testing animations deterministically

The WidgetTree::advance_time(duration) method on the test_api advances the tree's simulated clock and runs the scheduler with the new now. This makes animation tests deterministic without needing real wall time:

#![allow(unused)]
fn main() {
let mut tree = WidgetTree::new();
let toggle_id = tree.add(Toggle::new(Signal::new(false)));
tree.layout(SizeProposal::exact(200.0, 100.0));

// Trigger the toggle's tap handler:
tree.click(toggle_id);

// Advance past the 150 ms animation:
tree.advance_time(Duration::from_millis(150));

// Assert the knob is fully at position 1.0:
// (read through a test-api accessor, not shown)
}

Headless tests that never call render() have paint_epoch == 0; the scheduler treats that as "all widgets visible" so the per-widget visibility gate doesn't make tests flaky.

AnimationScheduler::active_count() and has_active() are public for tests that want to assert the scheduler is (or isn't) still running.

8. Design rules in one list

• Recommended entry point: ctx.animate().<duration>().<easing>().to_or_snap(&signal, target) (§4.3). Captures MotionTokens, easing presets, and prefers_reduced_motion in one place.
• Lower-level entry points for cases the spec doesn't cover: Signal<f32>::animate_to(...), animate_looping(...), try_animate_with_options(AnimationRequest).
• Create the signal with BuildContext::animated_signal(value) inside build(). That handles scheduler registration and widget-lifetime cancellation.
• Respect ctx.prefers_reduced_motion() before starting a looping animation; to_or_snap already does it for one-shots.
• Durations come from MotionTokens (duration_fast / _normal / _slow / _collapse / _indeterminate_sweep), not from literal constants in widget code. Literal constants are acceptable for one-off durations a designer doesn't plan to retune (icon sprite frame intervals, for example).
• Easing curves come from Easing. EaseInOut for symmetric transitions (toggle thumbs), EaseOut / easing_standard for appearance (snackbar slide-in, dialog fade), Linear for loops and indeterminate work. Easing::CubicBezier { x1, y1, x2, y2 } (via ctx.animate().cubic_bezier(...) or the .m3_emphasized() preset) is the general escape hatch for a design language's own motion curve.
• For common shapes — fade an overlay, collapse a section, show a spinner — reach for Fade / Collapse / Spinner / OverlayRequest::with_fade (§5.6) before hand-rolling a signal-driven path.
• Don't animate colors, hovers, presses, focus states, or anything instant in Int UI's vocabulary — those are reactive theme work, not scheduler work.

See also

• reactive-theme.md — reactive theming for the "it's not really animation, it's just reactive color" path (hover, press, focus).
• architecture.md §20 Threading — where the per-frame tick fits in the event loop.
• crates/teksilo-core/src/animation.rs — scheduler source.
• crates/teksilo-core/src/signal.rs (Signal<f32>::animate_to et al).
• crates/teksilo-tokens/src/motion.rs — Easing and MotionTokens.

Idle and animation — the zero-frame rule

The rule

An idle app must draw zero frames. Not "almost zero". Not "a cheap 60 Hz". Zero — rendered_frames == 0 in the TEKSILO_IDLE_TRACE=1 trace, ControlFlow::Wait in winit, no GPU submit, no CPU wake, no battery drain.

"Idle" means:

• No user input (no cursor move, click, key, scroll, resize).
• No pending tooltip / delayed overlay / gesture deadline.
• No accessibility rebuild in flight.

If those conditions hold and the event loop still wakes up, it is a bug. Track it down.

Why so absolute

Teksilo is meant for long-running desktop apps. A 60 Hz idle pump costs CPU, GPU, battery, fan noise, and — on laptops — holds the package out of deep C-states. Compounded across every running animation, every unfocused window, every background process, it is the difference between "I left it open" and "my battery is dead".

A framework that draws at idle normalises wasted cycles. We refuse.

The machinery that enforces it

Four gates, applied uniformly across three motion subsystems:

• Signal-tween path — Signal<f32>::animate_to / animate_looping, scheduled by AnimationScheduler.
• Shader-quad path — ctx.animated_quad(kind), scheduled by AnimatedQuadRegistry.
• Per-frame-effect path — ctx.subscribe_frame_tick(), scheduled by FrameTickScheduler. Used by widgets whose tick is neither a linear tween nor a quad uniform — Pulse (sine oscillation), Cycle (discrete index step), and any future hand-rolled frame_tick consumer.

All three consult the same visibility primitives in motion_visibility (alive, painted_this_frame, painted_recently) so the "is my owner visible enough to keep waking?" decision has one canonical answer per scheduler shape. Any new source of idle wakes must be designed to respect the gates below — or add its own scheduler that consults the same helpers.

1. Widget-drop / rebuild auto-cancel. The scheduler holds strong Signal<f32> clones; without an explicit cancel on widget death, a rebuilt widget leaks its old animation forever and ticks against an orphaned signal. WidgetTree::rebuild_single_widget and destroy_subtree both call scheduler.cancel_by_widget(id) before reconstructing. If you add a new lifecycle path that replaces widget state, it must do the same. (animation.rs, widget_tree.rs)

2. Per-window active flag. WindowEvent::Focused(false) (and on macOS, Occluded(true)) calls tree.set_window_active(false), which makes AnimationScheduler::tick a no-op and next_deadline return None. The event loop falls through to ControlFlow::Wait. On resume, each animation's start_time is rebased by the paused duration so phase is continuous — a half-swept sweep resumes at 50%, not snapped forward. (app.rs, window_manager.rs)

3. Per-widget paint-epoch visibility. WidgetTree::paint_epoch ticks on every non-cache-hit render(). paint_widget_cached stamps last_painted_epoch on each widget whose bounds survive clip intersection. The shared motion_visibility helpers turn that into a yes/no for each scheduler:

   • Signal-tween path uses painted_recently (last_painted_epoch + 1 >= paint_epoch) — tolerant, because the signal set on each tick dirties its widget, which forces a non-cache-hit paint that bumps both values in lockstep; the +1 slack just rounds out the layout-then-paint adjacency on freshly-visible widgets.

   • Shader-quad path and per-frame-effect path use painted_this_frame (last_painted_epoch == paint_epoch) — strict, because their tick does not dirty the widget. The shader path advances per-slot uniforms in a buffer the fragment shader samples; the per-frame-effect path mutates a signal whose binding may or may not propagate to a paint dirty. Tolerance there would treat a never-painted widget (last_painted_epoch = 0, paint_epoch = 1) as visible forever — the original Pulse / Cycle bug, where a Pulse parked inside a non-selected Switcher branch kept the event loop pumping at full frame rate.

   Result: a scrolled-off spinner, an off-tab Pulse, an oscillating indicator inside a collapsed accordion all stop ticking. When the widget scrolls / switches back in, the resulting paint re-stamps its epoch — update_control_flow re-queries next_deadline in post_event (signal + quad paths) and WidgetTree::render re-arms frame_tick_requested after every visible-subscriber paint (per-frame-effect path) — and motion resumes phase-continuous.

   Signal-path one-shots are not gated by visibility. A widget like Collapse drives a one-shot 0..1 progress signal that determines its own height — so when collapsed, its bounds are zero, it never paints, never re-stamps last_painted_epoch, and a visibility gate would chicken-and-egg the expand: never tick, never grow, never paint. The signal scheduler gates only looping entries; the shader and per-frame-effect schedulers don't ship a one-shot shape, so the loop-only carve-out is signal-only.

   paint_epoch == 0 is the "never rendered" sentinel: always visible, so headless unit tests that only call layout() don't regress. (rendering_impl.rs, arena.rs, animation.rs, animated_quad.rs, frame_tick_scheduler.rs)

4. Pixel-stable ε, mandatory terminal bypass. Each AnimationRequest can carry an epsilon (unit: the signal's own units, so usually logical pixels). Intermediate ticks skip signal.set when the value hasn't moved by at least ε — no dirt, no frame. Terminal ticks (completion, loop restart) always set unconditionally so one-shots land on exactly end_value. Ship ε for any looping animation whose minimum visible delta is known (ProgressBar → 1 px of track width is a safe choice).

The idle-work audit

WidgetTree::needs_redraw() is the predicate the event loop uses to decide between ControlFlow::Wait and ControlFlow::WaitUntil. If it returns true, the app is not idle — even if nothing visible is animating. Any new "is there work pending" signal must be included in this predicate, and paused/hidden variants must be excluded. The scheduler's has_running (pause-aware) rather than has_active (pause-oblivious) is the reference pattern; a paused scheduler that still said has_active == true would defeat every gate above.

Verifying you haven't regressed the rule

Run the catalog with the idle trace. A truly idle app emits no trace line at all (the trace is written on each wake — no wake, no line):

cargo build --profile profiling -p widget-catalog
TEKSILO_IDLE_TRACE=1 timeout 10 ./target/profiling/widget-catalog 2> /tmp/idle.log
wc -l /tmp/idle.log   # expect 0

CPU and GPU deltas can be read from the kernel:

# Process CPU over 10s (see /tmp/measure_idle.sh in the tree for the
# full script — samples /proc/<pid>/stat and sysfs gpu_busy_percent)
/tmp/measure_idle.sh
# Expect: cpu < 0.5%, gpu delta ≈ baseline.

If the numbers are above baseline, something in the tree is waking the loop. Classify it:

• Looping animation not paused? Check tree.is_window_active() and the widget's last_painted_epoch vs. tree.paint_epoch.
• Timer source you forgot? Every timer-backed deadline must flow through next_timer_deadline in overlay_impl.rs. If it doesn't, the event loop can't decide whether to sleep.
• Poll mode forced? ControlFlow::Poll is reserved for the async executor's loop-tick (loop_tick_poll), which must process runnable tasks as fast as possible and is not an animation. The per-frame-effect path (frame_tick_requested: Pulse, Cycle, caret blink, drag auto-scroll) does not force Poll — it publishes a fixed 60 Hz deadline via WidgetTree::frame_tick_deadline, folded into next_timer_deadline, so continuous animations render through ControlFlow::WaitUntil at 60 Hz regardless of the display's refresh rate. (It used to force Poll, which free-ran at the panel's refresh — a single Pulse/Cycle measured 300 fps / ~45 % CPU on a 300 Hz panel vs. 60 fps / ~13 % CPU after the cap.) This matches the signal-tween AnimationScheduler and shader-quad AnimatedQuadRegistry, which already pace at the same 16.667 ms interval. For visual continuous animations (Pulse, Cycle, …), prefer ctx.subscribe_frame_tick() over the raw frame_request_handle().set(true) re-arm — the scheduler-backed path automatically pauses the chain when the owner widget is hidden, while the raw handle keeps the event loop pumping regardless of visibility.

When in doubt, bisect: remove widgets from the scene until the idle returns to zero. The last removal is the culprit.

For widget authors

If your widget schedules anything time-driven — animation, timer, poll, deferred callback — it must have an explicit answer for each of the four gates. ctx.prefers_reduced_motion() is a fifth pre-gate for decorative motion: honor it, and you get the zero-motion accessibility behavior and a free idle win.

Off-thread repaint — RepaintWindowRequest

ctx.request_frame() is the UI-thread way to ask for a redraw. But some widgets have content that changes on a background thread: a terminal emulator's PTY-reader thread, a video decoder, a streaming data source. Those threads can't touch the widget tree, and posting a bare wake-up is not enough — a plain redraw re-presents each node's cached paint frame, so the render walker never re-runs paint() for a node it still thinks is clean. Content that changed off the UI thread would never appear.

teksilo_core::RepaintWindowRequest { window_id } is the off-thread analogue of request_frame. A background thread posts it through the poster:

#![allow(unused)]
fn main() {
// captured once, in `ctx.run_after_mount(...)`, where poster + window are both reachable:
let poster = ectx.poster().cloned();               // Arc<dyn AppEventPoster>, Send
let window_id = ectx.window().map(|w| w.id());      // TeksiloWindowId, Copy

// on the background thread, whenever off-thread content changed:
poster.post_external(Box::new(RepaintWindowRequest { window_id }));
}

teksilo-app routes the request by marking that window's tree paint-dirty (WidgetTree::mark_all_needs_paint_only()) before the redraw, so the changed widget's paint() runs again. It respects the zero-frame rule: nothing is scheduled — a frame is drawn only when an actual off-thread event arrives, so an idle terminal (no output) still draws zero frames. Under a flood of off-thread events (e.g. yes piped into a terminal), coalesce: only post a request when one isn't already outstanding, since each mark-dirty is O(nodes). This mechanism was introduced for teksilo-terminal; see terminal.md.

Three animation paths — signal vs shader vs per-frame-effect

Teksilo carries three motion paths that coexist. Pick by shape:

Use signal when paint() needs the current animated value to compute its draw commands (e.g., scroll offset shifts every child's coordinates). Use shader when the animation's visual is expressible as "draw a quad, let a fragment shader decide pixels from a small state struct." Use per-frame-effect when neither fits and you genuinely need a closure called each visible frame.

The widget-level surface for the third path:

#![allow(unused)]
fn main() {
// On `self`:
frame_tick_sub: Option<FrameTickSubscription>,

// In `build()`:
ctx.effect(&ctx.frame_tick(), move |&delta| {
    // mutate signals, advance phase, …
});
self.frame_tick_sub = None;                        // drop the old guard first
self.frame_tick_sub = Some(ctx.subscribe_frame_tick());
}

The chain auto-arms while at least one subscriber's owner is painted, dies cleanly when all are hidden (parked inside a non-selected Switcher branch, scrolled off-screen, …), and resumes phase-continuous on a hidden→visible transition because the visible_when flip's Relayout dirty triggers a repaint that paints the subscriber, which the post-render arm then detects.

Widget-author surface. In build():

#![allow(unused)]
fn main() {
// Procedural sweep (ProgressBar).
self.handle = Some(ctx.animated_quad(AnimatedQuadKind::IndeterminateSweep {
    period: Duration::from_millis(900),
    sweep_ratio: 0.42,
    track_color: SurfaceRole::Sunken.into(),
    fill_color:  SurfaceRole::Accent.into(),
}));

// Procedural arc (Spinner). Anti-aliased via fwidth smoothstep
// in shaders/anim_procedural.wgsl — soft alpha at radial bounds and
// arc start/end. Pipeline already uses ALPHA_BLENDING, so the soft
// alpha composites correctly.
self.handle = Some(ctx.animated_quad(AnimatedQuadKind::SpinnerArc {
    period: theme.motion.duration_indeterminate_sweep,
    arc_fraction: 0.75,
    stroke_fraction: 0.12,
    color: TextRole::Accent.into(),
}));

// Sprite atlas (animated IconWidget — frames pre-packed into a grid).
self.handle = Some(ctx.animated_quad(AnimatedQuadKind::SpriteCycle {
    image_name: atlas_name.clone(),
    frame_count, cols, rows,
    period: icon.total_duration(),
    tint: Some(TextRole::Primary.into()),  // None for FullColor icons
}));
}

In paint():

#![allow(unused)]
fn main() {
canvas.draw_animated_quad(bounds, handle.slot(), AnimatedQuadClass::Procedural);
// or: AnimatedQuadClass::Sprite { image_name: atlas_name.clone() }
}

The four gates (pause-on-window-unfocused, per-widget paint-epoch visibility, widget-drop/rebuild auto-cancel, prefers_reduced_motion) apply to all three paths in identical shape — they share the motion_visibility helpers and rebuild auto-cancel by RAII (the signal scheduler via scheduler.cancel_by_widget(id), the shader registry via slot deallocation on widget destruction, the frame-tick scheduler via the FrameTickSubscription Drop guard the widget stores on itself). The only difference is where the tick runs: CPU-side through a signal for the tween path, shader-side through a uniform buffer for the quad path, CPU-side through an arbitrary closure for the per-frame-effect path.

Adding a new kind: extend AnimatedQuadKind, add a kind: u32 discriminator branch in shaders/anim_procedural.wgsl (or anim_sprite.wgsl for texture-sampling kinds), and update AnimatedQuadRegistry::compute_params to populate the shared AnimParams struct from the kind's fields.

Framework-level cost at 60 Hz

The shader-driven scenes (examples/animations, examples/animations-kit) measure ~5 % CPU per process. The per-frame-effect scenes (Pulse / Cycle chains in widget_catalog --tab animations) measured ~50 % CPU at first 60 Hz profile — roughly 10× the shader path. The cost was not in the renderer; it was in the widget tree's per-frame infrastructure that runs around it.

Profiling at 60 Hz (perf record -F 999 -g --call-graph fp on a release+debug build) found the framework-level hotspots; the optimisation work brought the catalog scene from ~50 % CPU to ~28 % CPU through:

Total: catalog scene from ~50 % CPU to ~28 % CPU sustained at 60 Hz.

Verification: bench/perf_post_phase4_summary.md (bench directory).

Damage rects — measured, deferred

A natural next optimisation for shader-driven animations would be damage rects: track per-frame dirty regions, set wgpu::RenderPass::set_scissor_rect so the GPU only rasterises the changed pixels, and pass a damage region to the OS compositor so it skips recompositing the rest of the window. Wayland has wl_surface.damage_buffer; macOS has CAMetalLayer dirty rects.

We measured before committing to this. Two profiling rounds:

1. First round (8 s window on the Animated tab of examples/animations, pre-Phase-1 framework code): the process showed ~1.83 % CPU on one core, dominated by wgpu staging-belt activity for queue.write_buffer(anim_uniforms, 8 KiB) and command encoding. None of it was rasterisation time.

2. Second round (60 Hz, full measurement on the catalog --tab animations scene): the framework-level path dominated at 50.7 % CPU, with queue.write_buffer not in the top 22 hotspots — wgpu's per-queue staging belt amortises it completely. The work above (Phases 1-4) addressed the actual bottlenecks. Damage rects would still target a small slice (renderer at 1.5-5 % depending on scene) and remain deferred.

Revisit when any of these trigger:

• 120 Hz looping animations become common (we're 60 Hz).
• Target display resolution goes 4K / multi-monitor.
• Many simultaneous animated widgets (dozens of spinners across a dashboard).
• Battery-sensitive hand-held / laptop deployment where every milliwatt counts.
• Real workload profiling shows rasterisation or compositor cost exceeding the framework / renderer cost.

Cheaper follow-up that would actually help today: the AnimatedQuadRegistry already tracks dirty slot ranges via take_dirty_ranges (Phase 0). A future renderer revision can use that to upload only the changed slots instead of the full scratch_slice — single-call-site change in teksilo-render, useful when many quads idle (e.g. paused indicators).

Accessibility Overrides Reference

Teksilo widgets declare their own a11y info via Widget::accessibility(&self, builder: &mut AccessNodeBuilder) — Button emits Role::Button + label, Slider emits Role::Slider + numeric range, Panel marks itself set_hidden() when it's a11y_presentational, etc. That covers ~95% of cases. The remaining 5% — when an icon-only Button needs an accessible label, when a card composite should read as one AT element, when a status region needs aria-live, when a custom action should appear in VoiceOver's Actions rotor — is where builder-level accessibility overrides come in.

The override layer is a one-method-per-concern surface (.access_label, .access_role, .access_merge_subtree, …) on WidgetBuilder and WidgetWithHandlers, analogous to SwiftUI's .accessibility* modifiers and Flutter's Semantics(...). App authors annotate widgets from the outside without touching widget internals.

#![allow(unused)]
fn main() {
Button::new(tr!(save_icon()))
    .icon(IconWidget::from_svg_icon(save_icon), IconLocation::IconOnly)
    .access_label(tr!(save()))                  // icon-only button needs a name for AT
    .access_shortcut_id("app.save")             // tracks user rebinds via ShortcutRegistry
    .access_action(Action::ShowContextMenu, |ctx| ctx.send_intent(AppIntent::Menu));
}

Mental model in one line:

HandlerSet (carries) → WidgetNode (owns) → tree walker (applies) → accesskit::Node

End-to-end example: examples/widget_catalog/src/main.rs — the icon-only buttons in the Controls section show the canonical pattern in both builder and teksu! macro form.

Where overrides live

The override surface piggy-backs on the existing handler-extraction plumbing — the same path that already mirrors cursor, clips_children, focus_within_signal from HandlerSet onto WidgetNode.

1. Builder chain — Widget::new(...).access_label(...).access_role(...) each return a WidgetWithHandlers<W> whose HandlerSet carries an Option<Box<AccessibilityOverrides>>. The first access_* call lazily allocates the box; subsequent calls extend it.
2. Insertion — WidgetTree::add(...) calls take_handler_set() on the wrapper and apply_handler_set (crates/teksilo-core/src/arena.rs) mirrors the box onto the persistent WidgetNode::access_overrides field. After this point, the wrapper has no override state — the source of truth is on the node.
3. AT tree build — when the framework calls WidgetTree::sync_accessibility(), the walker at crates/teksilo-core/src/widget_tree/accessibility_impl.rs:137 runs node.widget.accessibility(builder) first (so the inner widget emits its defaults), then calls node.access_overrides.apply(builder) to layer the overrides on top.

Subsequent sync_accessibility() calls re-run the walker if the AT cache is dirty — which now also dirties on ShortcutRegistry::version() bumps so access_shortcut_id tracks rebinds (see Shortcuts below).

Method reference

Naming: .access_* prefix throughout. Three tiers by frequency of use.

Tier 1 — labeling and state

Tier 2 — relationships, live regions, identity

Tier 3 — subtree modes, numeric, actions, escape hatch

Subtree modes

By default the AT tree mirrors the widget tree one-to-one — every widget emits one AT node, descendants are visible to AT. access_subtree controls how the walker handles descendants of the annotated node.

Inherit (default)

Normal walk. Descendants emit their own nodes. Used implicitly everywhere.

Exclude — access_exclude_subtree()

Keep the parent in the AT tree, prune all descendants. Equivalent to Flutter's excludeSemantics: true.

#![allow(unused)]
fn main() {
HStack::new()
    .child(IconWidget::from_svg_icon(logo_icon))
    .child(TextWidget::new(lit!("Teksilo")))
    .child(TextWidget::new(lit!("Pure-Rust GUI")))
    .access_label(lit!("Teksilo logo"))
    .access_exclude_subtree();
}

Without access_exclude_subtree, a screen reader would walk all three children individually: "graphic", "Teksilo", "Pure-Rust GUI". With it, AT sees one node named "Teksilo logo".

Use for purely decorative composites: animated logos, icon clusters, splash content.

Merge — access_merge_subtree()

Keep the parent, but lift descendants' a11y info into the parent before pruning. The whole composite reads as one AT element. Equivalent to Flutter's mergeAllDescendants: true and SwiftUI's .accessibilityElement(children: .combine).

#![allow(unused)]
fn main() {
Card::new()
    .child(TextWidget::new(lit!("New message")))
    .child(TextWidget::new(lit!("From Alice")))
    .child(TextWidget::new(lit!("Hey, are we still on for…")))
    .access_merge_subtree();
}

VoiceOver announces the card as one element: "New message · From Alice · Hey, are we still on for…". Tab-stops collapse, so a keyboard user moves card-by-card instead of line-by-line within the card.

Merge accumulator rules:

Nested subtree modes:

• Merge containing Exclude somewhere — Exclude wins for that subtree (descendants of the excluded node contribute nothing to the merge).
• Merge containing Merge — the inner merge runs first into a temp builder, the outer merge then absorbs the inner's already-merged label as one element.
• Exclude containing anything — outer Exclude prunes everything; inner modes never run.

What merge can't reach. Widgets that don't expose their internals to the arena (e.g. a hand-rolled paint()-only widget that draws its own icon + label without inserting child WidgetNodes) have no descendants for the merge walker to find. Those widgets' authors should set accessibility() correctly internally; consumers can still use .access_label(...) to override the parent. This is an inherent property of the arena-based tree, not a deferred feature.

Automatic presentational collapse (no opt-in)

Layout primitives (HStack, VStack, ZStack, Center, Grid, Wrap, Padding, Expand, FixedSize, …) emit empty Role::GenericContainer / Role::Unknown AT nodes purely to carry visual structure. VoiceOver announces a bare GenericContainer as "group", so a composing control whose chrome is built from these primitives (a Button, a Checkbox, …) would otherwise read as "Save, button, group". To prevent that, the walker runs a final pass that collapses semantically-empty container nodes and promotes their children to the parent — the same "ignored / presentational node" pruning browsers do. Chains of nested empty containers collapse in one pass, so a Button → Padding → Center → HStack → (hidden label) subtree becomes a single childless Role::Button leaf.

This is automatic and requires no annotation. A node is collapsed only when, after the framework's structural additions (children, bounds, arena-driven disabled) are set aside, it is a bare node of its role — i.e. role is GenericContainer or Unknown and it carries no name, value, description, live region, popup, relationship, identifier, action, or any other author/widget property. The moment a container gains semantic content it is kept:

• An HStack with .access_label(lit!("Toolbar")) → Role::GenericContainer with a name → kept (a named group).
• A Panel (Role::Group) or GroupBox → non-presentational role → kept.
• The Window root, the currently-focused node, and any node referenced by another node's controls / described_by / labelled_by → always kept.

So you rarely need Exclude just to silence layout scaffolding — that happens for free. Reach for Exclude / Merge only when you want to prune or combine descendants that do carry semantics (decorative icon clusters with labels, multi-line cards, …).

Action callbacks

AT-invoked actions arrive as WidgetEvent::AccessAction { action, target, target_node, data } on the widget's on_access_action handler. The override system layers an additional callback path on top of any user-installed handler.

Standard actions — access_action

#![allow(unused)]
fn main() {
use teksilo::core::accesskit::Action;

let widget = my_widget
    .access_action(Action::ShowContextMenu, |ctx| {
        ctx.send_intent(AppIntent::OpenMenu);
    })
    .access_action(Action::Increment, |ctx| {
        ctx.send_intent(AppIntent::StepUp);
    });
}

Both calls advertise the action on the AT node AND register the callback. Multiple access_action calls register separate callbacks for distinct actions; the dispatcher routes each invoked action to the matching callback.

Layering with on_access_action. If the developer also calls .on_access_action(|action, ctx| …) directly, both fire for the same dispatched event — the override-registered callback first, then the user's catch-all. Builder ordering doesn't matter; the dispatcher reads node.access_overrides.actions directly.

Action suppression — access_remove_action

A widget like Button emits Action::Click and Action::Focus unconditionally. To neutralize one (e.g. a Button used purely as a layout shim that shouldn't appear clickable to AT):

#![allow(unused)]
fn main() {
my_button.access_remove_action(Action::Click);
}

Applied after the widget's accessibility() runs but before override-advertised actions are added — so a subsequent .access_action(Action::Click, …) call re-advertises Click with the override's callback.

Custom-named actions — access_custom_action

SwiftUI's accessibilityAction(named:) parity. The label is exposed verbatim by AT software (e.g. VoiceOver's Actions rotor reads "Reply to message").

#![allow(unused)]
fn main() {
my_message
    .access_custom_action(tr!(reply_now()), |ctx| {
        ctx.send_intent(AppIntent::Reply);
    })
    .access_custom_action(tr!(delete()), |ctx| {
        ctx.send_intent(AppIntent::Delete);
    });
}

Each entry is assigned a stable i32 id in declaration order. AT triggers a custom action via WidgetEvent::AccessAction { action: Action::CustomAction, data: Some(ActionData::CustomAction(idx)), .. } and the dispatcher routes by idx into access_overrides.custom_actions.

Shortcuts

Two variants for announcing a chord on the AT node — pick by where the binding lives.

.access_shortcut_id("app.save") — the production path

Bind to a Shortcut registered in ShortcutRegistry. The walker resolves the current effective primary keystroke at AT-build time and writes it via KeyStroke::Display ("Ctrl+S"). On a user rebind via ShortcutSettings, the registry's version() signal bumps and sync_accessibility dirties the AT cache automatically — the announcement updates without any explicit signaling from the settings UI.

#![allow(unused)]
fn main() {
// Somewhere in your root widget's build(), register the Shortcut.
ctx.register_shortcut_global(
    Shortcut::new("app.save").name("Save")
        .primary(KeyStroke::ctrl(Key::S))
        .build(),
);
ctx.register_action(Action::new("app.save").on_invoke(|_, ctx| save(ctx)));

// On the Save button, bind the AT announcement to the same id.
Button::new(tr!(save()))
    .on_activate_fn(|ctx| ctx.send_intent(AppIntent::Save))
    .access_shortcut_id("app.save");
}

If the registry has no entry for id yet (registration hasn't happened, or the app spelled the id wrong), the announcement is silently omitted — same fallback as MenuItem::for_shortcut(...) and TooltipContent::for_shortcut(...).

.access_shortcut_literal("Ctrl+S") — the explicit-string path

Frozen pre-formatted string. Use for chords NOT going through the Shortcut system: platform-native keys (Tab, Esc), app-internal hotkeys not exposed to user rebinding, or stand-alone demos.

#![allow(unused)]
fn main() {
my_button.access_shortcut_literal("Ctrl+Shift+P");
}

Does NOT track rebinds — that's the literal variant's tradeoff. For chords routed through Shortcut, prefer access_shortcut_id or the announcement and the actual binding will drift.

See shortcut-intent-action.md for the full Shortcut/Intent/Action pipeline.

Internationalization

User-visible string methods (access_label, access_description, access_hint, access_value, access_custom_action) accept impl Into<Prop<String>>. With the i18n feature enabled, teksilo_i18n::LocalizedString (the type produced by tr!(...)) implements From<LocalizedString> for Prop<String>, so:

#![allow(unused)]
fn main() {
button
    .access_label(tr!(save()))                       // Fluent-translated
    .access_description(tr!(save_explanation()))
    .access_custom_action(tr!(publish_now()), |ctx| ctx.send_intent(AppIntent::Publish));
}

flows through unchanged. The user-visible string overrides (access_label, access_description, access_hint, access_value, access_custom_action) take impl Into<Prop<String>> and store a Prop<String>, so tr!(...) stays locale-reactive: the accessibility tree re-walks on a locale change and re-resolves the announced value — no composite rebuild required. (AccessibilityOverrides lives in teksilo-core, which can't name LocalizedString; the bridge is From<LocalizedString> for Prop<String>.)

For explicitly-untranslated AT strings, wrap with lit!(...) — access_label(lit!("Debug")). A bare &str no longer compiles (it doesn't convert to Prop<String>), so the marker is mandatory. The #[doc(hidden)] _literal twins (access_label_literal, etc.) remain only as the literal path reachable from inside teksilo-core itself (where lit! isn't available); application code uses lit!.

State clearing

AccessNodeBuilder::set_hidden() and set_disabled() flip flags on. Some widgets call those setters unconditionally (e.g. Panel calls set_hidden() when a11y_presentational). To un-set widget-emitted state, the override system exposes:

• .access_hidden(false) — clears even widget-emitted set_hidden(). Full clear (no framework re-application of hidden).
• .access_disabled(false) — clears widget-emitted disabled AND arena-driven disabled. The framework's gate at accessibility_impl.rs respects the override, so even a .disabled(true) set on the widget's enabled-state can be overridden for AT purposes.

Real use cases:

1. App author wraps a Panel configured as decorative but a screen reader user does need to know about it ("Settings panel — collapsed").
2. App author force-disables a Button visually pending a save, but wants AT to keep announcing it as enabled because the disabled state is transient.
3. Test scaffolding asserts a widget is exposed regardless of internal a11y_presentational plumbing.

Synthetic children — access_customize

Widgets like RichTextEditor emit synthetic AT children (paragraphs, text-runs) via push_paragraph_child / push_text_run_child — these live inside the parent's emitted Node, not as separate WidgetNodes in the arena. The override system can't reach them through .access_* modifiers (which target whole widgets, not sub-nodes).

The supported path is access_customize, which runs last in the apply pipeline with full &mut AccessNodeBuilder access:

#![allow(unused)]
fn main() {
my_widget.access_customize(|builder| {
    // builder.inner_mut() exposes the underlying accesskit::Node — any
    // AccessKit field the typed surface doesn't cover is reachable.
    builder.inner_mut().set_class_name("custom-widget");
    builder.inner_mut().set_role_description("special panel");
});
}

Same escape-hatch model AccessKit itself uses internally. The closure runs every time the AT tree is built, so it has consistent re-render semantics with the rest of the override layer.

Apply order — the full pipeline

For each widget the AT walker visits, the sequence is:

1. node.widget.accessibility(&mut builder) — inner widget emits role, name, value, actions, hidden/disabled, etc.
2. overrides.apply(&mut builder) in this order:
   1. Scalars: label, description, value, role (replace if Some).
   2. State flags: hidden/disabled set or clear based on Some(true)/Some(false).
   3. Identity: identifier → set_author_id.
   4. Relationships: controls, described_by, labelled_by (append).
   5. Live region / aria_current / keyboard_shortcut literal / has_popup / orientation.
   6. Numeric: numeric_value, min, max, step.
   7. Action suppression: removed_actions (call remove_action).
   8. Action advertisement: actions (call add_action).
   9. Custom actions: write Vec<accesskit::CustomAction> with sequential ids.
   10. customize closure runs last with full inner_mut() access.
3. Walker post-processing:
   1. Resolve access_shortcut_id against ShortcutRegistry (this needs tree access, so it lives outside apply()).
   2. Subtree dispatch — for Merge, walk descendants and absorb into the current builder; for Exclude, prune.
4. Framework finalization:
   1. Push child NodeIds (skipped for Exclude / Merge).
   2. Inject layout bounds.
   3. Re-apply set_disabled() from the arena's enabled-flag UNLESS the override has disabled: Some(false).
   4. Tooltip → push_described_by.
   5. builder.build(id) → produces (NodeId, accesskit::Node, synthetic_children).