Crate tilo_app

Expand description

The Tilo application SDK.

The golden path is framework: declare a resource type and its actions with [tilo_resource], write views against a framework::ViewCx, and framework::run provides storage, sync, collaboration, history, undo, permissions, the action palette, the agent and script door, and search. The CRDT engine is not part of that surface.

The rendering toolkit is re-exported unchanged for widgets, custom surfaces and the imperative escape hatches.

Application manifests normally rename this package to ui:

ui = { package = "tilo-app", path = "../../crates/sdk/tilo-app" }

That one line is the whole manifest an app needs. Every OS affordance is on by default — history, undo, permissions, collaboration and device sync, the host file chooser, media controls, notifications and GPU video — so an app never picks features to get them. A headless tool that wants only the toolkit sets default-features = false.

Shell and framework internals may depend on the lower tilo-ui package directly; ordinary applications should use this facade.

Re-exports§

pub use tilo_resource;
pub use tilo_workspace_agent;
pub use tilo_workspace_emoji;
pub use tilo_reference;
pub use registry_types as registry;
pub use serde_json;
pub use tilo_feedback as feedback;
pub use tilo_files as files;

Modules§

a11y: Accessibility semantic model: the data layer. Defines the toolkit-ergonomic semantic types — Role, AccessNode, AccessState, and Action — that every Widget describes itself with via Widget::accessibility.
a11y_tree: The retained accessibility tree: a stable, frame-to-frame semantic model of the running UI.
accesskit
accesskit_bridge: AccessKit bridge: turns the toolkit’s per-widget semantic model (crate::a11y::AccessNode, from Widget::accessibility) into an accesskit::TreeUpdate, published over AT-SPI2.
action_palette: ActionPalette — the one Ctrl+K surface for a tilo_ui::App.
advanced: What a hand-written Widget draws and lays out with: the renderer’s scene and transforms, the layout tree and the windowing events. Views built from framework::ViewCx never name them.
agent_identity: A single, non-human identity silhouette for agents across Tilo.
animation: What is left of the toolkit’s early animation primitives besides the motion library (crate::motion, where every motion lives): IdleFade for chrome that shows on activity and fades once quiet, the looping indicators’ cadence, and Lerp for blending values that are not motion.
app
application: Checked application construction shared by hosts, independent of any runner.
application_view: Versioned, device/workspace-local presentation. Never contains document bytes.
arriving: Data that is not here yet: the one model for every read whose answer arrives later.
attention: What wants a person: the waiting stack, and the ledger an outcome goes to when it does not. Replaces the transient notice as a category. Attention, and the ledger: the two places a thing the system says can go.
auth_backdrop: Quiet current: the shared authentication artwork for the lock and greeter.
author: The one way every app draws who did something, so no app can forget to say that a bot is a bot. A person gets their round avatar; an agent its identity mark; a bot a rounded-square tile and a chip that is never elided: Bot, or for a person a bridge speaks for the mark of the service they write from (Discord’s), saying where when hovered. A bot may show another name (an appearance): it is shown, the chip stays, and a name that looks like a workspace member’s carries its service.
autocorrect: The word-boundary corrections every text field applies, for an input method that commits whole words itself (the on-screen keyboard).
automerge: Automerge
backdrop: The blurred material floating chrome is made of.
background: Background work and timers, provided by the host: tilo_rt::background under the toolkit’s module path.
bound_dispatch: Lifetime and canonical-record routing shared by retained and raw widget dispatch.
call_pictures: A call’s pictures, decoded for the tiles that show them.
capability_door: The capability door: privilege is granted, never inferred.
caps_lock: Heuristic Caps-Lock detection.
capture: Screen capture, as the host provides it.
chart_palette: Theme-aware reusable colour palettes for charts and data visualisation.
charts: Charts and plots
chrome: Reusable chrome — the framed UI around content. Two layers, not the same thing: application chrome (page, status_bar and the crate::widget::Toolbar) is the frame an app draws around its own content (the app owns button specs and click handling, the toolkit owns the look); shell chrome (shell) is the vocabulary the OS paints in around and between apps — top bar, window decorations, workspace disc, quick settings, collaborator surfaces (see crates/sdk/ui-core/HIG.md §9).
clipboard: Clipboard backends — how a ui process accesses the selection: tilo_clipboard under the toolkit’s module path.
clock: The clock as a person reads it: local date and time.
close_admission: Shared, device-local close admission. Saving an external document still goes through its declared action; host chrome owns only the close decision.
collaboration: Toolkit-side collab client. The broker client (routes, transport, committed reads, signing, invocation updates, presence transport) is the collaboration crate, which a process that commits to a workspace links without the toolkit; it keeps its path here. What stays is the widget side: who is in the workspace as the toolkit shows them, and the content a view reads.
collection_transition: The rows of a virtualized collection on their way after a structural change. Owners note only their shown rows: survivors move from where they stood, arrivals fade in, and (for an owner that paints them) the rows the change took away fade out where they stood. Once the change has run its course every row stands where it is laid out.
color: Colour conversions shared by the toolkit and apps: #hex parsing and formatting, HSV and HSL, and WCAG relative luminance and contrast.
color_compat: Compatibility helpers for the byte-channel accessors and f64 constructors that peniko::Color does not provide.
component: Components: the toolkit’s widgets as described, composable data.
component_lifecycle: How a widget takes part in closing its window and components: unsaved work, persistence checkpoints, component close reports and deferred window close.
content: Content by address: the store a host lends an app (ViewCx::content), and in a native process the device store the launcher handed it, so an app or a headless agent reaches content through the toolkit rather than through the store’s own crates.
content_layout: Responsive content-width policies for app surfaces.
content_zoom: Content zoom: one mechanism for every app window.
control_custody: Emission-time local control custody. Emission-time custody for registered local controls.
control_hints: Control hints: a small lit card that teaches one control at the moment it is useful, beside where it is done, and goes the moment it is done.
control_notice: Why something the person just did did not run, said where they did it.
damage: Damage in device pixels: the pixels a list of rectangles covers, how a long list merges into a few, and where a relayout moved widgets.
date: Proleptic-Gregorian day counts for apps that label dates, on chrono.
deferred: Code a program fetches the first time it is used rather than before its first frame (the browser desktop’s lazily loaded modules).
desk_widgets: The desk widgets and the screen edges things kept at the screen’s edges wait at, as the settings document keeps them: what every desktop host places them by, the native shell and a browser page alike.
desktop: The actions the host publishes itself, named for apps to call through ui. The desktop’s own actions, which an app asks of the desktop it runs in through Call::host: named here so an app reaches them through ui rather than depending on the host’s own crate. The session’s broker answers them.
device_local_door: A hosted surface’s device-local door, shared with whoever lists and invokes its actions while its host owns the surface.
diag: Diagnostic output that cannot take the application down with it.
dmabuf_import: Zero-copy DMA-BUF → wgpu texture import via Vulkan external memory. Shared by the WebView’s page buffers and the video decoder’s hardware frames. DMA-BUF → wgpu texture import via Vulkan external memory.
dnd
doc: CRDT helpers: writes that keep Automerge documents from churning, and typed reads.
doc_source: Read sources for controls backed by the app document. User edits are submitted by the control owner as resource actions.
edge_autoscroll: Edge autoscroll: a drag resting in the band along a viewport’s edge scrolls the viewport that way, from nothing at the band’s inner side to full speed at the edge and beyond it. Window strips, reorderable lists and trees, block drags and text selections all scroll by this one model.
element_pictures: Pictures a renderer copies on the GPU from where the page shows them.
emoji_catalogue: The Unicode emoji the toolkit offers: the shared picker’s and reaction strip’s catalogue, the names and keywords a text field resolves :shortcode: with, and the person’s recently used emoji.
env: The toolkit’s debug, capture and benchmark knobs: TILO_UI_* variables.
evdev: Linux input-event codes (linux/input-event-codes.h), the key codes the peer protocol carries on every host.
fact: A value that carries its measure, its provenance and its as-of.
feedback_composer: Shared private feedback presentation. Desktop hosts lend the system-owned controller into a private component; no draft is a workspace record.
floating_layer: Where the floating layer’s cards stand, as plain arithmetic.
floating_surface: Shared placement contract for app-bound overlays and shell-owned PiP.
focus_visible: Focus-visible: the focus ring shows for keyboard focus only (docs/design-language.md, “Colour roles”).
font_catalog
format: The one way Tilo shows dates, times, numbers, sizes and durations.
framework: The app framework: a workspace’s records, their views, and the chains kept beside them, read and written by every app that opens them. The app framework: a resource, its actions, and views bound to it.
fullscreen: Shared fullscreen / presentation mechanism.
gesture: Pointer-driven selection gestures — the press → move → release state machine behind click-to-place-caret, drag-to-select, double-click-word, triple-click-line, and shift-extend. App-agnostic: it tracks the gesture and reports intents (extend? what granularity?); the app maps points to its own caret/selection model. Lives in ui so every app gets consistent selection behaviour instead of re-deriving the timing/anchor rules.
gpu: wgpu state, asked for in a size this machine can give.
gpu_video: Painting decoded video on the GPU: uploading a hardware decoder’s planar output and converting YUV to RGB in a shader. Plain wgpu, so every target (WebGPU included) has it; gpu-video adds the zero-copy dmabuf import, which media::availability(Feature::ZeroCopyVideo) reports. Painting a decoded video frame on the GPU.
graph_editor: Reusable graph model for node/graph editors.
headless: Driving a ui app without a display.
held_images: Pictures an app already holds as data: a contact’s photo, artwork a media file embeds. They load like any other image (decoded off the UI thread by an ImageStore, cached, a placeholder painted until then), but nothing is fetched: the store’s fetcher reads the bytes the app registered with HeldImages::hold, and an address no one holds fails.
history_mode: Window-independent projection of a managed record’s historical states.
history_source: Turning a live CRDT document into the rows the history widgets render.
host: Host services — the capabilities a ui process borrows from whatever is hosting it.
host_data: Named data a host supplies on request, for builds that ship large application data (fonts, archives) beside the program instead of inside it. An application asks for a name each time it needs the bytes; a host that can fetch drains the requests, fetches each, installs the bytes or a failure, and relayouts its surfaces so the application asks again. Builds that embed their data never ask, and a host that never drains leaves every request pending.
host_notifications: Native notification scheduling where this build has none.
host_worker: Ordinary application workers shared by durable native and hosted owners. The host supplies current authority and committed bytes; this module owns only the real application runner and its original recovery custody.
hosted_window: The window around an app its host shows in its own process.
i18n
icons: Lucide-icon glyphs, stroked to match the concept’s 1.5 px aesthetic.
image_decoders: The toolkit’s image decoders (the image crate: PNG, JPEG, WebP), for a web page’s images (webview::paint) and the pictures an crate::ImageStore loads.
image_store: Async image loading, decode and cache — keyed by URL. Displaying remote thumbnails on the UI thread would jank every frame, so loads run off the UI thread — fetched through a caller-supplied Fetcher and decoded as crate::background::Background jobs, or fetched by the host through a HostImageLoader — and the decoded peniko::ImageData is cached and handed back on a later frame; until then the caller paints a placeholder.
ime: Focused widget IME intent shared by native windows and browser input bridges.
input: Device-neutral action bindings and the legends shown beside controls.
input_frame: Where a key’s time goes inside the app, stage by stage.
input_generation: How much input and model change the tree has been handed since a frame drew it.
interaction: Host-owned input capabilities shared by the retained widget tree.
invocation_scope: Host-local invocation custody. No wire caller can manufacture these checks.
jobs: What is running: one cancellable job with a body, which the whole system can see and which outlives the window that started it. Jobs: the long work the whole system can see.
jpeg: JPEG encoding of 8-bit frames and decoded images.
keycaps: The words and symbols printed on the keys of the active keyboard layout.
keys: One spelling for a key: the token a shortcut declares (Ctrl+Enter), the token a live press answers to (enter), and the key a test drives (Enter).
latin_chord: Shortcuts on non-Latin keyboard sources.
launch: The toolkit’s launch vocabulary, with run resolved to the runner this build targets: the native event loop on Linux and macOS, registration with the page runtime in the browser.
lazy_code: A surface whose code loads on first use.
linked_accounts: Accounts elsewhere a person links to who they are in a workspace: their Discord account in a workspace bridged to a Discord server, say.
live_activity: What an app keeps going outside its own window: a running timer, a call, a route, a song, a picture in a picture.
live_collaboration: Workspace-level collaboration experience shared by every application.
local_document_action: Bounded, speculative local action observations. These are not authorizations.
local_identity: Who sits at this device, as far as undo attribution and history authors are concerned: the collab client’s identity seam (collaboration::local_identity), and the person’s photo ready to paint.
local_state: Small, typed process-local state for retained application views.
location: Device location, as the host provides it: tilo_location under the toolkit’s module path.
lock: Locking that outlives a panicking holder.
math: Shared structured mathematical typesetting.
mentions: Mentions as a workspace fact: who a record’s rich text names, read from the record itself, and the one notice each mentioned reader gets.
models: Asynchronous model access explicitly supplied by an authenticated host.
motion: Tilo’s standard motions: the one library every animation in the toolkit, the shell and the apps is composed from. A call site says what moves, never how:
mpris: MPRIS — org.mpris.MediaPlayer2 desktop media control, in the toolkit.
native: The native desktop side of the toolkit, behind the default-on native feature.
native_media: Closed local call controls. Identity and capture authority never come from this wire.
native_scenario: Opt-in native input timelines. These schedule delivery, not display completion.
nav_stack: A reusable, app-agnostic navigation stack with a back action and an edge-swipe back-gesture hook.
notify: User notifications: tilo_notify under the toolkit’s module path.
num: Explicit numeric conversions used at UI/model boundaries.
offscreen: Headless offscreen render harness: renders a Vello Scene into a GPU texture with no window, reads the bytes back and optionally writes a PNG.
outside_paint: Whether a drawing read state outside the widgets that made it.
overlay: The window’s top layer: what modal and anchored surfaces share.
own_paint: What a widget paints itself, kept from one frame to the next, so the frame damages the widget’s box only when it painted differently: a hover in a window’s sidebar leaves a file list, a calendar’s month or a path bar beside it as they were, and repaints none of them.
owner_wake: Optional exact-component wake intake. This module does not schedule, service, freeze, or skip any component. A wake reason is not proof of model purity.
paint: Scene-painting shorthands for apps that draw their own surfaces.
paragraph: Paragraph-wide line composition.
part_paint: Part painters: the host side of the theme SDK (tilo_theme_sdk, docs/architecture/theming.md, “Part painters”).
passcode_keyboard: A keyboard drawn on the screen for entering a passcode by touch.
pen: The stylus behind the pointer event a widget is handling.
people_photos: The pictures people chose for themselves, as this process learnt them.
permissions: The toolkit’s permission gate.
person_card: Asking for someone’s card: a click on a person anywhere (an author in Chat, a member in its list) opens the one card the desktop shows for them, with who they are, what they are doing, their id, Message and Follow.
personal_dictionary: Current authenticated host’s shared local vocabulary. No filesystem or app-local fallback; missing/revoked channels clear personal hints.
pick: Picking parts of a window from its retained tree: what a person means when they point at “this” to report a problem with it.
pick_wire: Picking parts of a window drawn by another process: what the desktop asks the app that draws a window while a person points at what is wrong (crate::floating_surface::FloatingSurfaceHostMessage::Pick), and what the app answers from its own retained tree with answer (crate::floating_surface::FloatingSurfaceClientMessage::PickAnswered).
pictures: The pictures a window’s components show: each [Picture] as the toolkit’s decoded image.
pipeline_seed: The session’s read-only vello pipeline cache every app starts from. A pipeline cache every app starts from, written by the session.
platform: Semantic platform conventions for app-authored controls and shortcuts.
png: Lossless PNG encoding and decoding of tightly packed 8-bit RGBA frames.
pointer_replay: A still pointer over a rebuilt tree.
portal: The file-chooser and URI-opening vocabulary: requests, outcomes and the URI → path rule every backend shares.
prelude: The usual imports for application code.
presence
profiling: Frame profiler and headless performance-testing harness for ui apps.
published: A published resource tree whose unchanged subtrees are shared between versions.
query_text: Shared visual/IME state for transient search and command queries.
raster: Images built from raw RGBA8 pixels.
reader_hud: Shared reading-surface chrome for the document readers (ebook, pdf_viewer), so both present the same selection affordances with the same spacing, hover, and selected-state treatment:
realtime_continuity: Transport-neutral application contract for active realtime-session handoff. The contract is defined in [collab_types::realtime], where the session’s services read it without the toolkit.
record: Records — the unit of state, collaboration and storage: a type, a stable identity and a home workspace. A file’s identity is its file record, which a rename or move keeps, and its path is only where it sits; records reference other records rather than nesting, so “share the book without my notes” is expressible. One document per record is forced, not chosen: an Automerge change graph names its dependencies by hash, so a filtered stream leaves orphaned changes.
remote_actions: An application’s own client for the session’s action door.
render_bump_recovery: Repaint after a presented frame overflowed Vello’s bump buffers.
render_thread: UI render worker thread.
reorder: Shared drag/reorder state for virtualized collection widgets.
resources: Resources a widget publishes: the tree of open tilo_actions::ResourceSpecs with the actions each exports to the palette, agents and scripts, and the bounded pages the broker’s pull directory reads.
retained_present: Drawing for a presenter that keeps the desktop between frames.
retained_raster: Rasterizing frames into one retained target: only a frame’s damage (or all of it), its scroll copies made first and its backdrops blurred. Every host that keeps the pixels it presented draws through RetainedRaster: the native app’s render worker, the workspace’s render service and the browser desktop, so they produce the same pixels from the same frame.
richtext: RichTextLayout — attributed, word-wrapped, hit-testable text layout. The toolkit’s rich-text primitive (cosmic-text under the hood): per-run bold/italic, underlines, wrapping to a width, caret geometry, selection rectangles, and point↔offset hit-testing. Render it with crate::text_render::TextRenderer::draw_rich.
rt: The one async runtime model for Tilo processes.
save_status: A document’s save status, said in the window’s bar (crate::window_toolbar::notify).
scale: Display-scale plumbing shared by the render loop.
scene_parts: Keyed parts of a shell scene section, so a small change inside a section damages that change’s bounds instead of the whole display.
screen_reader: Built-in screen reader.
screen_reader_chord: The chord that turns the screen reader on and off on every screen: Ctrl + Super + Enter, and on a device without a keyboard both volume keys held for three seconds (docs/security/sign-in.md §3.4).
screen_reader_touch: Explore by touch: what a finger means while the built-in screen reader is on, as TalkBack and VoiceOver read it.
scroll_copy: Scrolling by copying the pixels that stay on screen.
search: Search as a platform service: apps never draw a search field or a result list, they declare what they can find and the platform presents it.
secret_paint: Whether a paint put a secret on screen.
secrets: App-scoped secrets: tilo_secrets under the toolkit’s module path.
selection: Shared collection selection models: SelectionModel, the compact index-based form for immutable local lists, and KeySelection, which keeps selection attached to stable model keys and represents select-all as a complement, for mutable, virtualized and partially resident collections.
semantic_document_read: App reader registration and the SDK’s committed-read admission.
session_door: Opening another app, the one way every host does it.
shared_selection: What the person has selected in a window, for sending it somewhere.
shell_choosers: Choosers the session shell draws itself, for sessions whose apps reach no desktop portal (a provider’s headless guest).
shell_tabs: Tabs belong to the desktop, never to an application.
shortcut_table: The desktop’s keyboard shortcut table (actions, their chords and the defaults) as the settings document keeps it: what every desktop host resolves a key press through, the native shell and a browser page alike.
snap: Snapping: what is dragged lands on the edges and centres of other boxes, and a guide shows what it lined up with.
state
storage: Where an app keeps what is not a document: one seam for app files, preferences and secrets, the same on Linux, macOS and the web.
strip_layers: A frame drawn as retained layers, and strip pans composited from them.
surface: Shared surface-drawing primitives — how a card/panel casts a shadow.
surface_peer: The actions socket a session hands a surface app is a descriptor of a native process: a browser page is no surface, and no session places its window. A surface app’s actions on the session that places its window.
surface_services: The session’s services as a surface app reaches them.
synthetic_input: Deterministic window input shared by native scenarios, headless driving, test control and tests: what they deliver in place of a device.
sysdirs: Localized XDG user directories.
table_model: The editable table’s model: the document layout a Table shows, and the operations its owner applies inside its own action (apply with the widget’s TableEdits). The widget itself only reads the document.
taffy: Taffy
text_assistance: Process-local view of the shared spelling preferences: the per-user text_assistance section every app’s text fields follow.
text_break: Unicode line-break opportunities shared by shaping-adjacent layout code.
text_detect: Identifiers inside free text: links, email addresses, mentions and workspace aliases found in a run of prose.
text_edit: EditCore — the shared headless text-editing model.
text_input: Private completion receipts shared by native and browser text editors. These types grant no access to an embedded browser or its engine.
text_metrics: Shared text-metric arithmetic for widgets that paint a line of text themselves.
text_position: Path-free text presentation for native continuation, anchored in the CRDT. This contains view state only. Resource contents retain their existing sync route, and restoring a view neither changes focus nor grants input authority.
text_render
text_selection: Shared text-selection primitives for TextInput, NotesApp, and any future text editor (terminal scrollback selector, code editor, …).
theme
theme_bundle: A theme bundle: a theme document and the painter modules it names (docs/architecture/theming.md, “Theme bundles”).
tilo_actions: Tilo ACTION model
time: The toolkit’s clock: tilo-clock, under the toolkit’s module path.
tokens
type_ahead: Type-ahead in a list: typing the first letters of a name moves to it.
ui_graph: Versioned, serializable UI object graphs compiled into ordinary widgets.
undo: Seeing and driving undo from inside a widget.
uri: Percent-decoding for URIs, with the + question answered once.
vello: Vello is a 2d graphics rendering engine written in Rust, using wgpu. It efficiently draws large 2d scenes with interactive or near-interactive performance.
view: The View: an app’s presentation layer, distinct from its state.
virtual_viewport: Shared one-dimensional virtualization geometry for lists, trees, and tables.
wake: Instance-scoped background wake routing: tilo_rt::wake under the toolkit’s module path.
webview: Engine-agnostic embedded web view plumbing.
widget
window_door: Every window of an app in a workspace, served by one process.
window_icon: Resolves the raster icon named by the launcher’s TILO_APP_ICON, falling back to a generated Tilo icon when it is missing or invalid.
window_name: What a window is called to the person: the app it shows, and the title the window carries beside it (“Groceries — Notes”).
window_pictures: Live pictures of this device’s own windows, drawn by their apps.
window_share: Sharing a window live: one app shows another app’s view of a resource, and the desktop says which windows there are to share.
window_slots: What a desktop keeps of the slots its apps put in their windows’ bars (crate::window_toolbar), and how it shows them: every desktop, the session’s shell and the browser’s alike, holds one WindowSlots.
window_targets: The controls of a window’s own content, as the app that draws them describes them to the desktop: what a session finds and presses by name (crate::floating_surface::FloatingSurfaceClientMessage::WindowTargets), and what the desktop presses on the app (crate::floating_surface::FloatingSurfaceHostMessage::PressTarget), which answers through the same path an assistive technology’s activation takes.
window_toolbar: An app’s toolbar is slots in the window’s bar, never a row it draws.
winit: Winit is a cross-platform window creation and event loop management library.
workspace_emoji: A workspace’s own emoji, as every view of a window draws them.
workspace_sync: Whether the workspace an app’s window is in has synced with its host, as the shell tells the app (crate::floating_surface::FloatingSurfaceHostMessage::Appearance).

Macros§

android_main: Export the Android entry point for this binary’s main.
built_in_definition: The definition of the framework::ResourceApp $app for a host that runs it in its own process (the shell’s built-in apps, the web desktop, an agent’s participant host), naming the app crate’s committed surface.toml as its surface: such a host runs no package whose payload names one. An app’s library defines its definition() with it; the app’s own binary uses framework::definition, so it does not carry the file.
column: Build a retained Column from concrete child widgets without repeating push(Box::new(...)).
described: Say that a described widget is its own type, inside its Widget impl: described!();.
dev_reload_entry: Export the entry points every platform’s host enters the app library by.
diag: eprintln! that cannot kill the process. See the module docs for why that difference is load-bearing.
embedded_catalog: Define the calling crate’s EmbeddedCatalog: locales/en-US.ftl in the crate embedded as the source, the crate’s other locales/<locale>.ftl read from the language packs (LanguagePack, named by the crate’s package name), the user’s locale when no host chose one, and source copy pinned in the crate’s own tests.
engine_main: The entry an app’s engine library exports for the app’s binary: run the app, after init, as main! would. Invoke it once at the root of the engine library (a runtime engine that carries the app’s library), and name the library in the app’s ui::main!(App, init = .., engine = ".."). The app’s package then holds only that call, and its code ships in the runtime bundle beside the runtime it is built against.
forward_to_child: The Widget methods a wrapper that keeps one child Element in self.$child — laid out as the only child of its own node, whose box it stores in self.$rect — forwards to it unchanged: placement, painting, events, child walks and its box.
forward_to_composed: The Widget methods a view owning a Composed in self.$field forwards to it unchanged: layout placement, painting, events, child walks, its box and whether it must be rebuilt.
i18n
lazy_code: Declare the code of a surface that loads on first use where feature (a feature of the declaring crate) is on, and is linked otherwise:
main: The binary entry point of an app, identical on every target.
optional_emitter_controls: The custody, drain and availability ActionControls methods of a widget whose only producer is its optional self.action emitter. Pass custody to leave availability to a widget that refreshes it itself.
provides: Declare the capabilities a widget provides, inside its impl Widget: provides!(dyn FullscreenProvider, dyn Continuable);
reach_tests: Declare the test that a drive of every scenario of an app reaches every action it publishes (framework::testing::check_scenarios_reach_every_action, built with test-support): none is advertised yet handled only by a click. The scenarios stage fixtures; the app someone opens acts on this machine (its files, its processes), so it is not walked.
rect_geometry: Implements Widget::apply_layout and Widget::get_rect for a widget that keeps the box layout gives it in self.rect.
redraw_flag: Implements Widget::needs_redraw and Widget::mark_drawn for a widget that tracks whether it needs repainting in self.dirty.
row: Build a retained Row from concrete child widgets.
settings_codec: SettingsSchema::from_settings_value and SettingsSchema::to_settings_value compiled where the impl is, never in the crates that read the setting: for a large settings type whose crate is in the shared runtime or an engine, every app or pane reading it otherwise carries its own copy of serde’s decoder. Use it inside the impl SettingsSchema.
stack: Build a retained Stack from overlapping concrete child widgets.

Structs§

A11ySettings: Stored in the per-user settings CRDT and mirrored into spawned sandboxes via TILO_A11Y_* env vars. Defaults are all-off so existing single-user setups are unaffected until a user opts in.
AccessBounds: Serializable absolute logical-pixel geometry for a synthetic AccessNode. This mirrors Rect without requiring widget authors to depend on its serialization feature.
AccessNode: The per-widget local accessibility semantics returned by Widget::accessibility; name/description must already be FTL-resolved strings (via i18n!), not translation keys, since AccessKit/AT-SPI consume final text.
AccessState: Tri-state fields use Option<bool> where None means “the state does not apply” (e.g. a Role::Button is never checked) — matching ARIA’s aria-checked="false" vs. absent distinction.
AccessibleTextSelection: Editable-text selection in the widget’s native UTF-8 document space.
ActionBindings
ActionPalette: The unified Ctrl+K palette: a SearchField over a SearchResultsView, fed by the focused app’s resource/action tree plus any folded-in SearchProviders.
ActionUiRoute: One visible expression of a domain action in the retained UI. The action address remains the execution identity; this route is presentation metadata for focus, presence, animation, and “show me where” behavior.
ActivityBrief
ActivityBriefAction
ActivityDigest
ActivityTimeline: Scrolling, filterable, groupable activity pane. See module-level docs.
Actor: The thing asking to reach a sandboxed resource: every Principal it can prove it is, and its signing key if it has one.
AgentRun: One instruction that spanned one or more applications.
App
AppCommand: A command palette entry contributed by an app. Invoked with a mutable CRDT handle and the app’s root ObjId so the command can mutate state directly (matching quick-ui’s direct-mutation event model).
AppearanceIntent: Polled by crate::app::App once per frame and reconciled against the live theme. Level-triggered like fullscreen_intent: a steady value is correct, since the App only re-themes when a field differs from what’s applied, so a settings pane can return the same intent every open frame.
ArgumentSpec: What one step of an argument asks: a heading, a field and what it holds.
ArrivalClock: The timing of one read, from the moment it was asked: the one place the placeholder steps are decided, for crate::widget::ArrivingView and for immediate-mode painters alike.
ArrivalCompletion: The single-use capability of one restart of a read (Arriving::begin). Only the newest restart may publish.
ArrivalWriter: Publishes a read’s answers without restarting it. See Arriving::writer.
Arriving: A read whose answer arrives later. Clones share one read.
AuthorDirectory: Maps automerge actor ids to the people the chrome should name.
BandUndoRequest: What [Undo] on a band asks for: the range, not a single id like [Restore] sends. Restore means “put the document back to this moment, discarding everything after”; undo means “take this band out, leave the rest alone” — a host cannot tell the two apart from one id.
BindingConflict
BindingSet: Rebindable, app-owned actions. This intentionally stores stable action ids instead of callbacks so apps can persist the map in their ordinary state.
CallPresence: The voice channel a person is in, as their presence carries it beside how available they are: the channel’s id (what joining it names) and its name (what the people here read, “In voice”). It rides in presence’s one call text as the id, a line break, then the name; a text without the break is an id alone, its name not said.
CapOverride: One sandbox capability.
CapsLockEstimate: A running estimate of whether Caps Lock is engaged, inferred from typed letters. Cheap to copy and to keep alive; update it by feeding each typed character (and the Shift state that produced it) through observe / observe_text.
Card: A retained card. See the module docs.
CardGrid: Reflows its cards into equal, aligned columns by width. Each row is as tall as its tallest card; cards share the row’s height so their footers line up, and a row of short cards stays short.
CaretWord: Debounces the word under the caret: it is settled once the same word (same text at the same place) has been under a collapsed caret for SUGGESTION_SETTLE. Typing into the word or moving to another one restarts the wait; moving the caret within the word does not.
ChangeRun: A contiguous run of changes, addressed by its first and last change.
CharSplice: An Edit in Automerge’s char offsets: delete removed chars at char at, then insert inserted chars there.
CommandEntry: One row a host feeds the palette: what it reads as, and what choosing it needs.
CommandOutcome: The result of pressing Enter on a row: its id plus the free-text argument (only Some for rows that asked for one). Drained via ActionPalette::take_outcome.
ComposedLine: One chosen line, indexing a half-open range of the input boxes.
ContentSurface: Tokens a content surface paints with when ContentSurface::forced is set. When it is clear, a document keeps its own page palette.
ControlCoverage: This is an inventory, never an assertion that arbitrary private storage was observed.
ControlDomain
ControlOutbox: A retained producer does not keep its owner, registry or widget alive.
ControllerBinding
CopyWatch: Watches the copy behind a confirmation the app already showed, so a copy whose outcome settles later can still say it failed.
DocumentFrontier: An explicit outbound synchronization frontier for one document route.
DragScrollFinish: Result of releasing a pointer tracked by DragScroller.
DragScrollUpdate: Result of moving a pointer tracked by DragScroller.
DragScroller: Thresholded, single-axis pointer panning shared by virtual collections. A press remains a click until it moves four logical pixels; once active, offset and release velocity are derived from the same pointer samples.
DragSelect: Tracks a text-selection drag gesture across press → move → release, including multi-click (word/line) and shift-extend.
DropCandidate
DropTarget
EdgeSwipeBack: Arms when a press starts within edge_width of the left edge, fires NavAction::Back once the pointer travels trigger_distance px right in a mostly-horizontal drag. No velocity/animation, but a complete pointer-event contract a richer recognizer can later drop into.
Edit: A splice to apply to the buffer, in byte offsets over the pre-edit text: at..at+removed is replaced by inserted. Edit::apply applies it to a String mirror; Edit::splice_automerge to a char-addressed Automerge Text.
EditCore: The caret + selection model, the IME composition in progress, and the field’s admission filter. Selection offsets are bytes into the bound text (matching text_selection and cosmic-text’s byte-indexed layout).
EditableLabel
EmbeddedCatalog: An application’s Fluent catalogues, embedded with include_str! and loaded on first use on each thread.
FileFilter: One entry in the chooser’s file-type dropdown.
FnProvider: A SearchProvider built from a closure plus its kind label — the convenient way to register a source without declaring a struct. Created via SearchRegistry::register_fn.
FocusView: The focused widget’s ephemeral presentation state, captured through the same mechanism the undo path uses to restore a caret across a rebuild. ordinal is stable exactly when the tree shape is — the condition under which restoring a caret is meaningful; ephemeral is the opaque string from crate::undo::UndoPoints::get_state/set_state.
FocusedContentLane: A centered, horizontally constrained lane that remains fluid on compact viewports. Vertical bounds always match the supplied viewport.
Followed: A live result RemoteActions::follow follows. Dropping it stops following: the invocation is cancelled.
FontVariation: One design-space coordinate for a variable font.
Fragmentation: Lines a split text block keeps on either side of a page break.
FrameProfiler: The crate::app::App holds one of these behind an Option; the headless crate::headless::FrameHarness holds another for the perf harness. Both feed it the same way: record a pass duration, then commit_frame once per frame.
FrameTiming: This is the atom every surface shares: the HUD graphs it, the dump serialises it, and PerfReport aggregates it.
FrozenApp: The versioned freeze envelope: an app’s serialized state bytes alongside its captured View. Collaboration and freeze/thaw serialize the same state; this pairs it with the presentation so a restore lands the user back where they were, not merely on the same data.
GlyphOutline: One shaped glyph as geometry: see TextRenderer::glyph_outlines.
GroundedNarrative
GroupNameRequest: What a host must write when a user names, renames, or un-names a run of changes. Both history surfaces emit this rather than writing to the document directly — neither widget has one, only the host does.
GroupingConfig
HangingPunctuation: Optical punctuation protrusion at paragraph edges.
HistoryAttribution: An author that acted for someone: an agent’s change is the agent’s, on behalf of its person, in every history (an app’s, the Files history, and what the history actions return).
HistoryAuthor: Not crypto material — just enough metadata to render a per-author colour dot, display name, and a short identity hash for disambiguation when two authors share a name.
HistoryComparison
HistoryController
HistoryEntry
HistoryEntryId: One entry of a history as people read it. Opaque: only ever compared for equality (revert/restore callbacks pass it back to the caller). The caller picks the byte layout — UUID-v4 today, a content hash later.
HistoryFacetIndex
HistoryFilter: Empty fields are “match everything” so a freshly-constructed filter behaves like no filter at all. The chrome owns the filter (not the widget) so the host can persist it across remounts, e.g. a workspace switch, without poking at widget internals.
HistoryGroup: One collapsible band in a history surface.
HistoryResource: Full authority namespace for one historical resource.
HistoryResourceTarget
HistorySelectionDetail
HistorySnapshot: Immutable Automerge bytes at one exact causal frontier.
HistorySource: Construct one, hand it an AuthorDirectory so actor ids resolve to people, and call HistorySource::entries whenever the document changes.
HostImageLoader: The loading half of a host-driven ImageStore.
HudControls: Which controls a SelectionHud offers besides the always-present Copy: the highlight swatch row, and the Note and Delete controls when enabled.
HudPlacement: Where a SelectionHud floats: anchor is the horizontal centre and top-y of the selection’s first band, bounds the area the bar must stay inside, both in the drawing transform’s space.
HudSwatch: One highlight colour offered in the HUD’s swatch row.
I18nManager
ImageStore: A cheap-to-clone handle to a shared image cache whose loads run off the UI thread — on the toolkit’s Background for ImageStore::new, or in the host for ImageStore::host_driven.
InputAvailability: A compact set of the input devices discovered for this session.
Intents: The queue a view’s controls write what they ask for to, and its app applies in one ordered place after the event: a click, a key and an accessibility action all become the same intent. Clones share the queue.
InteractionEnvironment: Runtime interaction information propagated by the host to every widget.
KeptSlot: A slot the revert declined to touch, and why.
KeySelection: Stable-key multi-selection for virtualized and mutable collections.
KeyboardBinding
KeyboardMap: Theme-aware map of an explicitly selected physical model. It observes only ordinary focused window events, never global devices or document edits.
KeyboardMapInput: Private, process-local physical press state shared across page recomposition. It contains no entered text or logical input history and never edits a document.
KeyboardMapKey: A key’s physical outline and ordered XKB levels, in model coordinates.
KeyboardMapSelection: Action-bound inspection over the shared physical map. Keyboard presses never select an inspector or publish entered text.
Keycaps: The legends of one keyboard: its layout’s language and whether it is an Apple keyboard.
KineticSampler: Release-velocity estimator for continuous (pixel) scrolling.
LatestRequest: UI-thread inbox for worker results where only the newest request may win.
LatestTask: Typed state for restartable background work where only the latest run may publish a result. Starting or cancelling a run invalidates every older TaskCompletion.
ListIndex: Ranks the rows of a list against a query, for surfaces that rebuild their rows on every query or change (commands, windows, actions).
LiveStatus
LiveUi: A retained host whose child is reconciled after a validated graph edit.
LocalState: A cloneable handle to typed, process-local application state.
LocalStateWriter: A background-safe LocalState mutation handle with event-loop wakeup.
MarkerDrag: A reader begins a drag when a press lands on a marker it owns, tracks the pointer while held, and reads back the marker origin on release to persist the new anchor. Agnostic of the coordinate space (page points vs. screen-y) — the caller decides how to interpret the returned origin.
ModelView: A retained subtree selected by a value projected from application state.
NameField: A one-line name field. Hosts own the placement and the lifetime; this owns the text and the keys.
NamedRange: A user’s name over a run of history, as stored in the document.
NarrativeRequest
NarrativeSource
NativeView: Retained widget adapter around a NativeViewBackend.
NativeViewGeometry: Parent-relative geometry in both toolkit-logical and native physical pixels. Backends should use physical_* for child-window APIs.
NativeViewHost: Live parent-window context supplied before a native view is shown.
NativeViewInput: Event coordinates and modifiers already normalized by the toolkit host.
NavItem: One destination. Every part but the label is optional.
NavList: The navigation list. See the module docs.
NavSection: A group of destinations under a sentence-case title.
NavShell: The one window shell. See the module docs.
NavStack: A generic navigation history. T names a view (an app’s route/screen descriptor). Back and forward keep browser-style history; pushing after a Back clears the abandoned forward branch.
OpenTypeFeature: One explicit OpenType substitution/positioning setting.
OpenTypeTag: A four-byte OpenType feature or variation tag (kern, dlig, opsz, …).
PaintedActionMarker: One marker exported only by the action-presence painter, in surface-local logical coordinates. It grants no authority to its actor.
ParagraphBox: One shaped box in logical order. A box is usually a word or an unbreakable inline fragment; callers retain the actual glyph/style data separately.
ParagraphOptions: Tunable paragraph-composition policy. Defaults are deliberately close to TeX’s ordinary prose behavior while remaining expressed in font-relative space capacities supplied by the caller.
ParticipantPresence: One remote participant’s live presence (caret/selection), published by a multi-participant widget under that participant’s identity. Same key and payload shape as the local window’s own presence (Writer: wp_block key, byte offsets into the caret block).
PerfReport: Per-pass and total statistics over every frame a PerfScenario produced, plus how many blew the frame budget.
PerfScenario: Reusable across any app: build a crate::headless::FrameHarness over the app’s real root + state, then call run_scenario.
PermissionContext: The authority and sandbox a frame’s permission checks are decided against. Held by App, consulted by app::dispatch_gated_event before a gated widget ever sees an event.
PickRequest: A portal file-chooser request, built up and then send on a worker thread.
Pictures: What a component showing a picture reads: the store its bytes load through (which caches a decoded picture by its address), and what a window’s pictures are.
PlatformConventions: Host-selected conventions. Copyable so it can be propagated through a retained tree and overridden by deterministic tests or a native shell.
PolygonTextLayout: Built-in layout engine that fits text into and clips it against a polygon.
PresenceCtx
QueryComposition: Retained shaping and IME state for an inline query editor. Editing goes through the shared EditCore: the owner’s Selection is loaded into it for every event and written back afterwards, so a query keeps the same grapheme, word, clipboard and composition rules as every other field.
QueryInk: The colours a QueryComposition paints with.
QueryView: The query a QueryComposition paints: the committed text and its selection, the placeholder shown while it is empty, and whether the caret is visible.
RecordCheckout: A record named together with its type — what a widget declares it is working on, and what a workspace index holds.
RecordId: The stable identity of a record. Encoded by prefix: file-record:<uuid> (a file, by the durable id its filesystem record carries — see RecordId::identify_file), file:<absolute path> (a file known only by where it is: a not-yet-written Save As target, or a filesystem that can’t hold the durable id), uuid:<uuid> (minted, for a record with no natural name), tab:<tab id> (a window’s scratch document until a file names it, see RecordId::for_tab) and derived:<role>@<id> (see RecordId::derived).
RecordKind: What kind of thing a record is — document, annotation-set, book, playlist. App-owned rather than system-registered, so an app can add a kind without coordinating; the cost is no cross-app library view yet (needs a system-owned type registry, not built here).
RecordRef: One record’s reference to another: annotations → the document they mark up, a duplicate → the record it was copied from.
RecordRefusal: An action whose change the workspace refused: the record withdrew it, and the app holding the record is told, as it is of an action refused on this device.
RecordSet: The records one app process has open, and which is live. Owns per-record persistence and parking, not collaboration: routing a record’s deltas is the toolkit’s business, since a channel belongs to the connection.
RecordStore: A RecordSet several widgets share via a handle, so two tabs on the same file stay one document; single-threaded on purpose, since a Mutex here would guard against nothing.
RedactionDisplay: Optional on HistoryEntry — when present, the widget renders the row with the struck-through summary, suppresses the [Revert] chip, and exposes the redactor + reason on hover.
RemoteActions: An application’s client for the session’s action door. Clones share one client.
RemoteActionsGuard: Keeps a RemoteActions::enter host current on this thread.
ReorderController: Gesture controller shared by list and tree widgets. Widgets retain model mutation authority and supply their own hit-tested, validated candidates.
ReorderDrop
ReorderMotion
RequestCompletion: Single-use worker capability returned by LatestRequest::begin.
ResponsiveControlBar: Shared one-row/two-row policy for dense command and find bars. Callers declare the width their inline composition genuinely needs; the same value then drives reserved layout height and paint-time row placement, preventing controls from being clipped by a one-off app breakpoint.
RestoreReview: Opaque proof that a particular selected state was reviewed against a particular live frontier. Validation grants no authority and writes nothing; the host must separately recheck permissions before restoring.
RevertOutcome: What a revert did, and what it deliberately did not do.
RichSpan: A styled inline run. size/family override the block defaults per run.
RichTextLayout: A laid-out block of attributed text.
RouteHandle: A cloneable controller for one router’s process-local route stack.
Router: A retained single-screen host driven by an explicit RouteHandle.
RowFace: One person in a row’s face stack (CommandRow::faces).
RowMotion: A row on its way after a change the person made (motion::ListChange): moving from where it stood to its new place, or fading in where it arrived. Rows the change did not move have none.
RowMotions: The rows of a virtualized list or table on their way after a change the person just made (motion::ListChange): the owner notes where its shown rows stand before the change (Self::capture), and the next frame moves the survivors from there to where they are laid out now and fades arrivals in (Self::start). Only rows shown after the change move; nothing outside the viewport animates. A change nobody just asked for (a sync), a shortcut’s result and reduced motion land at once.
RunStep: One application’s share of a run.
RunUndoReport: What a whole-run undo did, across every application it touched.
SaveNotice: What to tell a person who cannot see a document whose save gave up: post it as a notification whose action is “Try again”, and route that action to SaveStatusSurface::retry_from_notice. See SaveStatusSurface::take_notice.
SaveStatusSurface: A document’s save status, in the window’s bar (see the module).
ScreenReader
ScrollGlide: The glide of a scroll view that pans both ways (a document, a canvas, a wide table): one ScrollMomentum per axis, so it decays as every list glides (glide_step) and steps in whole device pixels, which a host that copies what a scroll keeps on screen copies.
ScrollMomentum: Deterministic single-axis momentum used by virtualized collection widgets. Wheel input moves immediately; line-wheel impulses additionally feed this decay curve so detented wheels can traverse long collections without requiring one event per row.
SearchGroup: A ranked bucket of results that share a SearchResult::kind. The results overlay renders one section per group, headed by kind.
SearchRegistry: The set of providers a search surface draws from. One registry can back a single app (its own providers) or, in the shell, every app’s providers at once for a global Ctrl+K.
SearchResult: One typed hit produced by a SearchProvider.
Section: An intrinsic-height group of content with an optional header. See the module docs.
Selection: Anchor + cursor pair. anchor == cursor means “no live selection”.
SelectionHud: A drawn SelectionHud: its bounding rect plus the hit rects of its controls. Built fresh each frame by SelectionHud::draw; the caller either hit-tests it directly via SelectionHud::hit or folds its buttons into its own hit list via SelectionHud::buttons.
SelectionModel: Index-based multi-selection state. Indices are opaque usizes the owning widget assigns to its items (typically the row/cell order).
SelectionRange
SemanticAction: One thing an assistive client can do to a SemanticNode, addressable by a stable name.
SemanticId: Stable identity of a semantic node, preserved across refresh as long as the backing widget or resource recurs.
SemanticNode: One node of the retained semantic tree.
SemanticTree: The retained accessibility tree. Persists node identity across frames and diffs each refresh against the previous.
Shortcut: A semantic shortcut whose display and matching use platform conventions.
ShownPicture: One picture a widget shows, by its address: loaded through the window’s pictures the first frame it is here, and kept while the address stays. A widget holds one and reads it from sync and draw.
SparseAnchor: Stable scroll anchor captured from a model-resolved sparse viewport.
SparseVirtualViewport: Virtual geometry for collections whose logical item count is much larger than the set of resident keys.
StatSummary: For one column of measurements (a single pass, or the total), in microseconds.
State: The unified state object that holds our CRDT document.
StepOutcome: One application’s outcome within a run undo.
SurfaceShape: The surface a window’s content is drawn on, as the scene being drawn sees it: its bounds and the radius of each of its corners, 0 where a corner is square. A host that knows the shape it shows a window in puts it on the window’s theme (Theme::surface); what runs along the window’s edges (a scroll bar) keeps its ends out of a rounded corner.
TaskCompletion: A single-use capability returned by LatestTask::begin.
TextEdit: The splice splice_text_diffed applied, in characters — Automerge Text is char-addressed, not byte-addressed. A no-op reports {pos:0, del:0, ins:0}.
TextFlowRegion: Non-rectangular local-coordinate region used for both line fitting and exact scene clipping. Concave polygons may produce several independent spans on one baseline, allowing text to flow around an inset or cutout.
TextLayoutConstraints: Width/height offered to a pluggable text layout engine.
TextPosition: A document byte offset plus the visual side of an ambiguous boundary.
TextRenderer
TextStyle: The complete typographic style for a plain text run.
Theme
TouchPointerEmulator: Converts direct touch into the toolkit’s ordinary pointer contract.
TreeDelta: What changed between two refreshes. Ids that appear in neither list are present and byte-identical in both frames — their identity and content survived unchanged.
TypingRun: A burst of typing: every edit touches the run, and a programmatic replacement of the text closes it.
UiBuildContext: Process-local services available while compiling a serialized graph.
UiComponentRequest: Inputs passed to one app-owned serialized-graph component factory.
UiDocument
UiGraphEditor: A native, accessible object-graph editor with a live production-widget preview. It is also the root component used by the standalone UI builder.
UiGraphHandle
UiValues: A graph’s text and checked values, by each control’s value_path, and which buttons were clicked, by each button’s on_click_path.
UndoAccess: The undo half of a widget, as one embeddable field: the last UndoStatus the host published, plus at most one pending UndoRequest.
UndoEntry: One step of the history as a window shows it: the changes it brackets, where the caret was, and who made it.
UndoLog: A document’s undo, as one window drives it. See the module docs.
UndoStatus: What the live undo history can do right now, as a widget sees it.
UserId: A person’s stable id, as apps and presence spell it.
View: A participant’s View: everything about where they are looking that is never merged into anyone else’s. Every field derives Serialize/Deserialize so a future presence layer can broadcast any subset. View::default is “top of the document, nothing focused, no resource” — the correct starting point for a freshly-launched app.
ViewContribution: The typed presentation fields a widget contributes to (and has restored from) the View — its scroll offset(s) and its current view mode. Kept structured rather than folded into FocusView::ephemeral because a presence layer wants to broadcast scroll/view-mode on their own — “this peer is scrolled here, in grid mode” — independent of whether the scrolling container is the focused widget.
ViewRect: A rectangle in physical pixels — the app’s viewport at capture time.
VirtualViewport: Variable-height virtual collection geometry, keyed by model identity.
WakeEvent: A weak identity for a queued wake; it never owns an app or its scope.
WakeHandle: Captures one scope, or remains detached forever. Unlike a closed scope, detached execution may publish local/headless state without waking a host.
WakeScope: The non-clone owner of one mount incarnation. Drop closes it.
WakeScopeGuard: A thread-affine construction/dispatch guard, independent of an App borrow.
WindowAppearance: What the host showing a window knows about where, and for whom, it is shown: the temperature of the workspace the window is in and the colour of the person sitting at it. The shell resolves both and hands them to its own chrome and, over the shell-ui channel, to every app window (crate::floating_surface::FloatingSurfaceHostMessage::Appearance). A window nobody told stays neutral and wears the default colour.

Enums§

Access: How far a sandbox capability reaches into its resource.
ActionKind: What an action is able to do, derived by the framework from the action’s code and never declared by an app.
AppKind
ArgValue: An owned value to interpolate into a localized message. Owned (rather than a borrowed FluentValue) so callers — most importantly the retained-mode Text widget — can stash arguments alongside a translation key and re-format every frame without keeping the original references alive.
ArgumentKind: What an argument step collects.
Arrival: Where one read stands.
AuthorRelation: Who an author is to the person reading the history. Rows draw the reader’s own changes, a collaborator’s and an agent’s differently.
Availability: How available a person says they are, beside their face. Emoji-free presets; idle and away also come on their own (no input for IDLE_AFTER, a locked screen).
BaselineShift: Per-run baseline shift, for superscript / subscript runs.
CapDecision: The outcome of a sandbox check.
CapScope: What a sandbox capability ranges over.
CompareError
ContentKind: What the shell’s content is, so it knows the narrowest the content still works at; below that the window shows one column at a time. Apps say what their content is, never how wide it is.
ControlProducerDiscipline
ControllerButton
ControllerFamily: Controller legend/layout used when rendering face buttons.
DialogActionOrder: Visual order of a primary confirmation and its secondary/cancel action.
DropPlacement
EditOutcome
EntryKind: What a history entry did, as the history and activity views mark, filter and group it. Read from the change itself (its entry and what it wrote), not from the transport that carried it.
FontChoice: A font family to shape with. The three generic classes resolve to the system’s default face for that class; Named targets a specific installed family by name.
FontFamily: A generic font family the toolkit can resolve from system fonts.
Granularity: Selection granularity, from the click count.
HistoryClassification
HistoryError
HostShortcut: A host service every app answers by shortcut, whichever chrome shows it.
HudAction: The swatch index in HudAction::Highlight indexes into the swatches slice passed to SelectionHud::draw; the caller maps it back to its own colour model.
HudSide: Which side of the selection a SelectionHud prefers.
Hyphenation
I18nError
IconDescriptor: A lightweight icon descriptor usable before the full asset pipeline lands. Glyph is a Nerd Font / unicode codepoint (existing approach in both the iced file-explorer and quick-terminal). Named is a symbolic name for future theme-driven icon resolution.
InputBinding
InputDevice: Devices known to be available in this session. This is deliberately separate from InputModality: moving a mouse must not make a connected touchscreen or controller disappear from shortcut help.
InputModality: The kind of interaction most recently used.
KeyLegend
KeyboardFamily: Physical legends printed on the connected keyboard. Tilo may run on Linux with an Apple keyboard attached, so this cannot be inferred from the OS.
KeyboardModifier
KeycapLanguage: The legend language of a keyboard layout: which words are printed on its modifier and navigation keys. Layouts whose keyboards carry English legends (Dutch, Portuguese, Nordic, Swiss, Japanese) differ from US English only in naming the right Alt key Alt Gr.
LineBreakKind: Whether a UAX #14 opportunity permits or requires a break.
Motion: A caret motion. Vertical motion across wrapped lines is the host’s job because it needs laid-out line geometry; Motion::LineUp and Motion::LineDown move across \n-delimited lines only.
NameFieldOutcome: What a key did to the field.
NativeViewAccessibility: Whether AccessKit or the native child owns this view’s semantic subtree.
NavAction: Navigation history intents shared by gestures, keys, and buttons.
NavMode: What the sidebar becomes when the window is too narrow to dock it.
NavPane: A screen of the narrow push stack.
NumericStyle: Numeric glyph style requested from an OpenType face.
OpFamily: Grouping never mixes two families, so a filter chip can never empty a group while leaving its header claiming rows that are no longer shown.
OpticalSizing: Whether a variable font’s opsz axis follows the rendered font size.
ParagraphAlign: Paragraph alignment, including inter-word justification.
Pass: Attributes a measured duration to the right column of the current frame’s FrameTiming.
PathSegment
PerfStep: Each step drives the headless driver and produces one or more measured frames.
PermissionScope: What a widget or a launch asks permission for.
Platform: Platform family relevant to human-interface conventions.
PointerPrecision: Accuracy of the active pointing device.
PortalOutcome: The result of a single-file portal interaction (open, or a Save destination), delivered back to the UI thread over a channel.
PresenceKey
PresencePayload
PresenceVisibility: What the people in a workspace see of this person, chosen per workspace.
PreviewSide: Which exact frontier of a selected change or group is being previewed.
PseudoLocale: Layout-stress translation mode used by screenshots and acceptance tests. It deliberately preserves digits and punctuation while expanding letters, making clipped labels and fixed-width controls visible before translators have completed a catalog.
QueryEventChange: Result of routing an event through the shared single-line query editor.
QueryImeChange: Whether an IME event changed only the display composition or committed a new query value. Owners should re-run filtering only for Committed.
ReadingFace: A reading face the system ships, chosen by name in a theme’s type role or by a reader in an app that sets long-form text (Books). Each is set through the Reading role’s family, so its optical sizes, features and script fallbacks work like the default’s.
ReconcileError: A key appeared more than once in a reconciliation input.
ResourceRef: A sandboxed resource an app might reach.
RevertError: Why a run could not be addressed at all — distinct from “addressed it and chose to keep some of it”, which is RevertOutcome::kept.
Role: A role preset. A member of a workspace holds one; the workspace keeps the grants each role carries (see crate::roles).
RouteError
SaveAction: What a person did about a save.
SaveState: What a document’s save state is, as the save status surface says it.
ScrollAlignment: Where an item should land when explicitly scrolled into view.
SemanticActionKind: How a SemanticAction is carried out when invoked.
Slot: A place in the document a change wrote to, at the granularity where two writers collide.
StatusOrigin
StatusSharing
StepState: What happened to one application’s share of a run.
Subject: Who a capability is about: one signing identity or a named Principal.
TextAffinity: Which shaped run owns a caret at a shared logical byte boundary.
TextAlign: Horizontal alignment of a block.
TextFlowRegionError
TextGround: The ground text is set on, as far as the face is concerned. Light ink on a dark ground loses fine hairlines first, so a family drawn in separate optical cuts keeps its sturdier text cut to larger sizes there (OpticalSizing::Auto). A theme’s roles carry its content ground; a surface that paints its own ground (a book’s page) says which it is.
TextKind: What a run of text is, so the toolkit can pick its OpenType features.
TextRole: What a piece of text is. Pick the role; never a pixel size.
TextScaling: What a TextStyle’s size (and pixel letter spacing) is measured in.
TextWeight: Named weight tiers mapping 1:1 to cosmic_text::fontdb::Weight’s numeric constants (Tailwind’s font-medium/semibold/bold), so call sites read declaratively instead of passing raw u16s.
TextWrapMode: Line selection policy for a constrained paragraph.
ThawError: Why a FreezeThaw::thaw failed. Thaw never panics — truncated or garbage bytes, an unknown version, or an unloadable state payload all surface here.
TouchClaim: What a contact means to the widget where it begins.
TouchGesture
TouchPointerEvent: Pointer events synthesised from direct touch, so ordinary widgets work on a touchscreen without interpreting contact streams themselves.
UiButtonRole
UiFace: A UI face the system ships, chosen by name in a theme’s type role or by the accessibility layer. Reading (ReadingFace) and code keep their own faces.
UiGraphEdit: One validated edit to a serialized UI object graph.
UiGraphError
UiNavigation: Process-local navigation requested by a button.
UiNode
UiTextRole
UiTextSource
UndoRequest: A widget’s request that the host drive the history. The host performs it through the one undo implementation; a widget never touches the stacks.
WakeBindError: Why a platform destination could not be installed.
WheelStep: What a vertical collection should do with one wheel event, decided by ScrollMomentum::wheel.

Constants§

BLOB_SCHEME: How an app names a picture by its content address.
FRAME_BUDGET_US: Rounded 60 Hz CPU-work budget. Exceeding it is a CPU diagnostic, not evidence of an actual dropped display frame.
FROZEN_VERSION: Envelope format version. Bump when the wire shape of FrozenApp changes in a way older readers cannot decode; FreezeThaw::thaw refuses a version it does not understand rather than mis-reading it.
IDLE_AFTER: No input for this long and a person shows as idle.
INFERRED_STATUS_TTL: Automatic summaries go stale quickly. A stale intention is worse than no status because it makes collaborators coordinate around work that stopped.
LIVE_GRAPH_DIR_ENV: Directory of live *.json screen graphs. When set, graph apps load and hot-reload screens from disk instead of the embed baked by include_str!.
LIVE_GRAPH_OPERATION: Operation type for live graph mutations published by LiveUi.
MAX_GROUP_DEPTH: Two levels is what a reader can hold; three is a tree of edit history nobody asked for.
MAX_STATUS_CHARS: Manual statuses are explicit communication and therefore remain until the author clears them.
SAVE_GIVE_UP: How long a save may stay unconfirmed before the surface stops waiting and asks the person to try again: the first submission’s SAVE_STALL, then as long again for the retry it asked for, so the retry gets the same chance before the person is asked.
SAVE_RETRY_ACTION: The bar action id of the save notice’s “Try again”.
SAVE_STALL: How long a save may wait for the store to confirm before the surface says so in plain words and asks the host to submit the changes again. Until then it says nothing: a document whose every change is a CRDT operation saves continuously, and a save that is merely slow is a performance bug to fix where it happens, never news for the person.
SUGGESTION_SETTLE: How long the word under the caret must stay the same before a field offers a spelling suggestion for it: a short pause at the end of a word, or the caret coming to rest in a word typed earlier.
UI_GRAPH_VERSION
UI_HYPERLEGIBLE_FAMILY: The built-in “Hyperlegible” UI face a theme or the accessibility layer can choose instead of UI_SANS_FAMILY.
UI_MONOSPACE_FAMILY
UI_SANS_FAMILY: Product-wide primary font families. Tilo ships these exact faces, and the renderer also assigns them to the CSS-like generic families below. Keeping the names here makes plain text, rich text, and theme tokens agree instead of depending on each machine’s fontconfig defaults.
UI_SERIF_FAMILY: The default reading face, New Computer Modern. Set in this family, text takes the cut its size calls for: the 8 pt design for footnotes, Book for body text and Regular for titles (crate::tokens::ReadingFace).

Traits§

ActivityNarrator
AppWidget: Trait every in-process app implements so the shell can host it inside a TileContent::App. AppWidget: Widget means the shell always falls through to the widget contract for layout, draw, and events.
ColorCompat
FreezeThaw: Freeze/thaw for a Tilo app, extendable at exactly one seam.
Lerp: Interpolation from self to other at t (0..=1).
NativeViewBackend: App/platform implementation of one native child view.
SearchProvider: A source of search results — implemented by an app for each searchable type it exposes (its contacts, its open files, its commands, …).
TextLayoutEngine: Replaceable measurement/painting boundary used by crate::widget::Text. Implementations keep localization, accessibility, Taffy integration, scene caching, and inspection supplied by the standard widget. style is always renderer-relative: implementations which delegate to TextRenderer pass it through unchanged. For theme-resolved or fixed-size widgets, Text compensates the font size for the renderer’s current multiplier before this boundary; renderer-relative letter spacing keeps its established behavior.
UiDocumentExt: Compile a validated serialized graph into ordinary Tilo widgets.
Widget

Functions§

builtin_hyphenation: TeX/Liang hyphenation by the patterns hypher embeds.
card_column_width: The width of each of cols columns that, with gap between them, fill avail_w exactly. Never negative.
card_columns: How many columns of at least min_card_w fit in avail_w with gap between them. Always at least 1.
clipboard_copy: Push text onto the system clipboard — the Ctrl+C buffer.
clipboard_copy_image: Push an RGBA8 image (width * height * 4 bytes, row-major, no padding) onto the system clipboard as image data, so it can be pasted into an image editor or chat. Returns false when the buffer size is wrong or no backend can carry an image. Used by the PDF reader to copy a selected page region. Like try_clipboard_copy, it never waits, and its outcome may settle later.
clipboard_copy_primary: Push text onto the primary selection — the mouse-driven “select then middle-click paste” buffer, distinct from the Ctrl+C clipboard. Terminals and editors set this whenever a range is selected so a middle-click paste in any app receives it. Goes through the same clipboard as clipboard_copy.
clipboard_copy_rich_accepted: Copy formatted text: html for the apps that read formatting, plain for every other. Reports whether the host’s clipboard took it, as clipboard_copy_accepted does, so Cut never deletes words a refused copy did not keep.
clipboard_paste: Pull the current clipboard contents as a UTF-8 string. Returns None when the clipboard is empty / unavailable / non-text.
clipboard_paste_image: The image on the clipboard, when another app copied one (a screenshot, an image from a viewer or a browser). None when it holds no image.
clipboard_paste_primary: Read the primary selection as a UTF-8 string — what a middle-click paste should insert. None when empty or unavailable.
clipboard_paste_rich: The formatted text on the clipboard, when what was copied has formatting: its HTML with its plain-text words. None when it holds plain text only, or nothing; read clipboard_paste then.
compare_entries: Compare the dependency frontier immediately before the selected changes to the frontier after every selected change. Concurrent changes outside the selection are excluded. Pending edits are neither committed nor included.
compose_paragraph: Compose a paragraph globally. If the requested tolerance has no feasible solution, progressively looser emergency passes are tried; the final fallback preserves every box and always makes forward progress.
configured_font_system
delete_last_grapheme: Backspace for text typed only at its end (a type-ahead query, a digit entry): remove the last character as a person sees it, never half of a combining sequence or an emoji. Returns whether anything was removed.
describe: Compose the spoken phrase for an accessible node — the pure, heavily unit-tested core of the screen reader.
deterministic_narrative: Privacy-preserving fallback used when no model is configured or when a generated result fails grounding validation.
discretionary_hyphen_breaks: UTF-8 byte offsets at which TeX/Liang patterns permit a discretionary hyphen for language. The source text is never modified; callers decide whether a chosen line break should paint the hyphen glyph.
extend_span_drag: Word/line-granularity drag extension — the shared rule behind double-click-then-drag in TextInput and the reader.
flatten_reading_order: The accessibility walk ([crate::a11y_tree::walk]) the AccessKit bridge and the retained tree take, flattened. A widget’s synthetic children (a table’s rows, a keyboard’s keys) follow its widget children, each placed where the widget draws it ([crate::a11y::with_synthetic_bounds]) and followed by the widgets it hosts.
forget_run: Remove a run record. The changes it referenced stay untouched in their own documents; only the grouping goes.
format_relative_time: Used by both widgets so the wording stays uniform with every other “time ago” label (crate::format::relative). Re-renders every frame, so the label freshens naturally as now advances — no clock plumbing needed.
grapheme_boundary_at_or_before: The nearest extended-grapheme boundary at or before byte_idx.
group_entries: Group entries (oldest first, in the producer’s causal order).
heads_for_entry: The other half of HistorySource::entries: a restore needs a document state for the HistoryEntryId a widget hands back. None when the id names no change in this document — mixed ids from two artifacts.
hue_to_rgb: HSV(h, 0.65, 0.95) → RGB. Saturation and value held constant so generated author colours stay visually coherent (no neon outliers, no muddy ones).
human_label: label when a person could read it as a name; None when it is empty, repeats the machine id, or carries an identifier such as a hash or uuid. Producers fall back to ids when a record has no title yet, and those must not reach anyone reading the activity feed.
hyphenation_generation: How many times the patterns arrived: never, as they were always there.
latest_run_by: The contiguous run of changes authored by actor_hex, ending at the document’s newest change by that actor.
line_boundaries: Byte range (start, end) of the line containing byte_idx, where lines are linefeed-delimited (\n). The end is the index of the trailing \n, or text.len() for the final line. Triple-click line selection uses this.
line_break_opportunities: Iterate byte offsets where a line may or must end according to Unicode Standard Annex #14. Every offset is a UTF-8 boundary and the final text boundary is always returned as mandatory.
local_surface_id: Public because it is half of a protocol: what a pointer published in this surface’s content coordinates is scoped to (crate::presence::PointerSpace::Surface) — both ends must spell the surface the same way by calling this same function.
next_char_boundary: Step one user-perceived character to the right of byte_idx. See prev_char_boundary for the compatibility note.
next_word_boundary: Mirror of prev_word_boundary for forward movement: the next UAX #29 word start, or the end of the string.
next_word_boundary_chars: Char index of the next word boundary at or after char_idx — the char-indexed mirror of next_word_boundary. Used to extend a reader selection rightward by a whole word (Shift+Ctrl+Right).
parse_ui_graph_edits: Parse a non-empty JSON array of tagged graph edits.
participant_display_label: Turn a durable collaboration principal into copy suitable for people-facing history and audit UI.
plan_revert: Work out what undoing run would do, without touching the document.
prev_char_boundary: Step one user-perceived character to the left of byte_idx. Extended grapheme clusters keep combining marks, emoji modifiers, flags, and ZWJ sequences together. The legacy function name is retained for API compatibility.
prev_word_boundary: Walk back to the previous UAX #29 word start. If the cursor is inside a word this returns that word’s start; at its start it returns the preceding word’s start. The result is always a UTF-8 boundary.
prev_word_boundary_chars: Char index of the previous word boundary at or before char_idx — the char-indexed mirror of prev_word_boundary. Used to extend a reader selection leftward by a whole word (Shift+Ctrl+Left).
put_text_diffed: Creates the Text object on first use (inserting the whole value); subsequent calls splice only the diff.
read_runs: Read every recorded run out of doc, oldest key first. A record that does not parse is skipped rather than guessed at: an undo affordance pointing at the wrong changes is worse than no affordance.
record_run: Record a run. Returns the document key, which is also AgentRun::id. The transaction is left open — the caller commits, so the record lands stamped and attributed like any other edit. A run with no steps is not recorded: nothing changed, so there is nothing to offer undo on.
record_run_with_details: Record a run with the task evidence needed for a later review.
refuse_run: Build the report for a run that was refused whole. Nothing was written.
reserve_clipboard_copy: Claim the Ctrl+C clipboard for text that is not known yet, such as a link the person’s click asks a host for, and copy it once it is handed over (ReservedCopy::fill), as try_clipboard_copy would. Call it inside the click: a browser copies only there, and lets a copy claimed there be filled later. Elsewhere the text is copied when it arrives. Dropping the reservation copies nothing.
resolve_theme_layers: Resolve the stack. Order, lowest first:
revert_run: Undo a run of changes by writing its inverse forward into doc.
run_scenario: The driver runs the app’s real five passes with no GPU or display, so timings are of the production code path, not a mock.
run_scenario_on: The one-call entry point for an app author or a test: no driver bookkeeping.
run_starting_at: The run whose first step starts at start, if one is recorded.
spell_shortcut: A row of a shortcut reference, as this platform spells it: {cmd:K} is the command key with K (Ctrl+K, or the Command key on a Mac), {cmd+shift:Enter} adds Shift, {alt:Up} is Alt with Up and {F2} is a key on its own, each in the active keyboard’s legends. Everything else is shown as written.
splice_text_diffed: Prefer put_text_diffed when you have a parent object + key and want the Text created on first use.
try_clipboard_copy: Copy text only if a system clipboard backend accepts it, without waiting for it to.
try_clipboard_copy_secret: Copy a secret — a password, a one-time code, a recovery key, an enrolment token — so it pastes anywhere as plain text while clipboard histories and device sync are told not to keep it (ClipboardBackend::set_secret_text).
undo_run: Undo every step of a run, given the documents the caller could open.
undo_step: Undo one application’s share of a run against the document that app owns.
unreachable_steps: Steps whose documents this process cannot reach.
validate_narrative
version_index_for_entry
word_at_caret: The word the caret is in or just after, as a byte range: letters plus in-word apostrophes, so don't is one word. None between words.
word_boundaries: Byte range (start, end) of the UAX #29 word containing byte_idx, or the word immediately on the left when the index lands in following punctuation or whitespace. Used by double-click word selection.
word_boundaries_chars: Char range (start, end) of the word containing char_idx — the char-indexed mirror of word_boundaries. Drives double-click word selection in a reflowable reader.
workspace_hue: The neutral temperature a workspace takes from its wallpaper (RGBA8 pixels): the image’s dominant hue, or None for a wallpaper with none (a grey photograph, a missing file), which leaves the material neutral. Only the hue is taken — the material never gains chroma from a wallpaper.

Type Aliases§

CancellationCall: A request to cancel a running invocation: Ready(()) is the host’s acknowledgement. Acknowledgement is not a terminal invocation outcome; callers must keep observing the original InvocationCall until it reports Cancelled or another terminal state.
CatalogueCall: A catalogue read: every page of one query, gathered.
CharFilter: A per-character admission rule (for example a spreadsheet cell-reference box that only takes [A-Za-z0-9$:]). Applied to every insertion path: typing, paste, IME preedit and commit, programmatic insertion.
Element
Fetcher: Fetches the raw encoded bytes for a URL, or None on failure. Invoked as background work, so it may block on I/O.
Hyphenate: Calls out with the byte offset in word after each of its syllables but the last, by lang’s patterns.
InvocationCall: An invocation: its latest lifecycle update, or the host’s refusal (then nothing ran).
MakeHyphenation: Hands over the patterns’ Hyphenate, for install_hyphenation.
PortalChannel: A pending single-file request: the receiver the UI thread drains each frame. Some(rx) means a picker is in flight; None means idle.

Crate tilo_app

Crate tilo_app Copy item path

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate tilo_app