Struct App 

pub struct App {
    pub theme: Theme,
    pub debug_mode: bool,
    pub focused_node: Option<NodeId>,
    pub focusable_order: Vec<NodeId>,
    pub autofocus_first: bool,
    pub autofocus_on_structure_change: bool,
    pub appearance_reconcile: bool,
    pub presence_ctx: PresenceCtx,
    pub permission_ctx: PermissionContext,
    /* private fields */
}

Fields

theme: Theme

debug_mode: bool

focused_node: Option<NodeId>

focusable_order: Vec<NodeId>

autofocus_first: bool

Opt-in: focuses the first focusable widget after initial layout, so the app is keyboard-usable without a click.

autofocus_on_structure_change: bool

Opt-in: re-establishes keyboard focus on every structural rebuild. crate::widget::Widget::take_focus_reset jumps to the first focusable (wizard advancing a step); otherwise focus is preserved by ordinal position so an unrelated rebuild doesn’t drop the caret.

appearance_reconcile: bool

Opt-in, off by default so host-themed apps pay nothing: polls the tree each tick for crate::widget::Widget::appearance_intent and re-themes live.

presence_ctx: PresenceCtx

permission_ctx: PermissionContext

Implementations

impl App

pub fn request_close(&mut self) -> bool

Refusal keeps every live owner and wake scope available for editing.

impl App

pub fn without_native_document_chrome(self) -> App

Omit the automatically added History and Search controls at native startup. System surfaces such as a login screen have no document to browse. Their own semantic actions and accessibility remain available. Ordinary applications retain native document chrome by default.

pub fn enable_document_history_chrome(&mut self)

Enable shared standalone services presentation without wrapping the app root. Native windows enable this automatically; embedding remains opt-in.

pub fn open_document_history(&mut self) -> Result<(), String>

Capture the focused document before moving focus into shared chrome.

pub fn document_history_snapshot( &mut self, ) -> Result<Option<DocumentHistorySnapshot>, String>

pub fn select_document_history( &mut self, entries: &[HistoryEntryId], ) -> Result<(), String>

pub fn close_document_history(&mut self)

impl App

This impl block contains no public items.

The Edit door: the one undo, reached by keyboard, menu and automation.

impl App

pub fn pump_hosted_model(&mut self)

A worker has no redraw loop. Advance one bounded model pass using the same phases as the window runner, without adding caller attribution.

impl App

pub fn join_participant(&mut self, participant: &ParticipantId) -> bool

A participant joined the record this app serves. Multi-participant widgets create its own view (Writer: caret at the document end). Idempotent. Returns whether a view was newly created.

pub fn leave_participant(&mut self, participant: &ParticipantId)

Drop a participant’s view (its task ended). Idempotent.

pub fn set_participant_host(&mut self, host: bool)

This app serves only remote participants and has no local person: multi-participant widgets publish their participant-independent catalogue schema instead of their own caret’s snapshot.

pub fn set_participant_label( &mut self, participant: &ParticipantId, label: &str, )

Name shown beside a participant’s caret.

pub fn participant_presence(&self) -> Vec<ParticipantPresence>

Current presence of every remote participant this app holds a view for.

impl App

pub fn set_capture_protected(&mut self, protected: bool)

Withhold this app’s windows from screenshots, recordings, screen sharing and remote viewers — for windows that show secrets, such as a password manager’s. The local display is unaffected; captures show a themed placeholder instead. Outside a Tilo session this is a no-op.

pub fn capture_protected(&self) -> bool

Whether Self::set_capture_protected asked for protection.

impl App

pub fn action_registry_mut(&mut self) -> &mut ActionRegistry

Lets the hosted app register its action types, e.g. app.action_registry_mut().register::<TubeAction>("tube.action").

pub fn set_action_transport(&mut self, transport: Box<dyn ActionTransport>)

pub fn collect_resources(&self) -> Vec<Resource>

The complete machine-driveable surface: domain resources declared by the app plus ordinary controls projected from its retained semantic tree. Ctrl+K, scripts, and agents therefore consume one catalogue.

pub fn control_action_coverage(&self) -> Vec<ControlBindingCoverage>

Audit every retained control binding against the fresh resource tree. This is public so development tooling can turn remaining explicit legacy controls and stale/duplicate action addresses into a coverage report without inspecting widget implementation details.

pub fn action_ui_routes( &mut self, address: &ActionAddress, ) -> Vec<ActionUiRoute>

Locate every on-screen affordance for one canonical action and rank usable, visible, short paths first. Agents still invoke address directly; the chosen route makes the resulting interaction project into the same UI a person sees without fragile coordinate clicking.

pub fn preferred_action_ui_route( &mut self, address: &ActionAddress, ) -> Option<ActionUiRoute>

pub fn invoke_local_resource_action( &mut self, address: &ActionAddress, arguments: &Map<String, Value>, ) -> Result<ResourceOperationStart, DoorError>

Invoke a registered action as this application’s current local person. This uses the same current record, policy and broker checks as the palette.

Errors

Refuses unavailable, denied, stale or ambiguous actions and invalid arguments.

pub fn pending_history_controls(&self) -> Vec<PendingControlReview>

Review pre-entry controls retained by the native managed History surface.

pub fn open_action_palette(&mut self)

pub fn open_search(&mut self, request: SearchRequest)

Open search the way request asks: this app, or one part of it, with the query already typed. A standalone window shows its own palette; inside the Tilo shell the component hands the request to the shell.

pub fn close_action_palette(&mut self)

pub fn with_component_root<U>( &mut self, f: impl FnOnce(&mut dyn Widget) -> U, ) -> Option<U>

Run f on the root of the app component this window shows, inside that component’s own frame: for a test, or a host, reaching into the mounted app between frames. None without a mounted component.

pub fn action_palette(&self) -> Option<&ActionPalette>

pub fn asking(&self) -> Option<(ActionAddress, String)>

The action the host’s confirmation is asking about, and the text that confirms it, while it asks.

pub fn confirm_asked(&mut self) -> Option<ActionAddress>

Confirm what the host asks through its own dialog, as the person does: the confirming text, then Enter; what it confirmed is applied. Answers the action confirmed; None, changing nothing, when nothing is asked.

impl App

pub fn apply_accessibility_request(&mut self) -> bool

The screen-reader flag tracks Self::screen_reader_enabled. Apply a preference change a control asked for (see Widget::take_accessibility_request). Returns whether one was pending.

pub fn text_scale(&self) -> f32

pub fn set_text_scale(&mut self, factor: f32)

Layout grows to fit so text never clips; the value is clamped to a sane range by the theme.

pub fn ui_scale(&self) -> f32

pub fn set_ui_scale(&mut self, factor: f32)

pub fn set_interaction_environment( &mut self, environment: InteractionEnvironment, )

Override the host-detected input environment. Useful for platform shells and deterministic tests; normal apps do not need to call it.

pub fn interaction_environment(&self) -> InteractionEnvironment

pub fn set_platform_conventions(&mut self, conventions: PlatformConventions)

Override platform HIG conventions for a native shell or deterministic cross-platform test. Ordinary apps use the host default.

pub fn platform_conventions(&self) -> PlatformConventions

pub fn high_contrast(&self) -> bool

pub fn set_high_contrast(&mut self, on: bool)

Off restores the captured base theme, not a hard-coded default.

pub fn toggle_high_contrast(&mut self) -> bool

pub fn reduce_motion(&self) -> bool

pub fn set_reduce_motion(&mut self, on: bool)

pub fn set_theme(&mut self, theme: Theme)

Low-vision preferences are re-applied on top, so changing the base theme doesn’t discard them.

pub fn set_screen_reader_enabled(&mut self, enabled: bool)

Disabling stops in-flight speech and returns every narration call site to a no-op.

pub fn screen_reader_enabled(&self) -> bool

pub fn build_a11y_tree_update(&mut self, scale: f64) -> TreeUpdate

scale is the window scale factor so bounds land in physical pixels (what AT-SPI expects).

pub fn dispatch_a11y_action( &mut self, target: NodeId, action: &Action, ) -> Option<(f64, f64)>

Resolves both retained AccessKit nodes and synthetic semantic children (virtual rows/cells) to their owning widget. The widget gets first refusal; synthetic children additionally carry an opaque stable target produced by that widget. If a retained widget declines, Action::Focus moves keyboard focus and activation returns click coordinates.

pub fn refresh_semantic_tree(&mut self) -> TreeDelta

Node identity is preserved for everything that recurred, so a consumer reacts to just the diff.

pub fn semantic_tree(&self) -> &SemanticTree

pub fn invoke_semantic_action( &mut self, id: &SemanticId, name: &str, arg: Option<&str>, ) -> Result<bool, String>

A Verb routes through the same dispatch_a11y_action path an AccessKit ActionRequest takes; an App affordance dispatches through tilo_actions::dispatch, the same audited path the Ctrl+K palette uses. Call refresh_semantic_tree first so the ids are current.

Errors

Returns Err when the underlying app action fails to decode or dispatch (see Self::dispatch_encoded_semantic).

impl App

pub fn from_prepared_component_with_collaboration( collaboration: CollaborationManager, prepare_host: impl FnOnce() -> Result<PreparedComponentInputs, LaunchError>, instantiate: impl FnOnce(HostContext, LaunchTarget, RestoreInput) -> Result<AppComponent, LaunchError>, ) -> Result<App, LaunchError>

Prepare and mount an application on its already admitted collaboration manager. Host preparation runs inside the existing native read custody. The original record binding is checked before the component factory runs, and the same manager and wake scope transfer into the mounted application exactly once. Construct the host and its record owners inside prepare_host, where they retain this construction’s native read bridge. Only an existing record target is accepted; absence cannot become a default new document.

Errors

Returns preparation, current-read, binding, factory or mount failures. Binding failures preserve the original record store for recovery.

pub fn set_frame_tick<F>(&mut self, tick: F)

where F: FnMut(&mut PresenceCtx) -> bool + Send + Sync + 'static,

Called once per event-loop wakeup, so it must be cheap and non-blocking.

pub fn set_presence_broadcast_sink<F>(&mut self, sink: F)

where F: Fn(&PresenceKey, &PresencePayload) + Send + Sync + 'static,

pub fn clear_presence_broadcast_sink(&mut self)

pub fn set_pointer_space(&mut self, space: PointerSpace)

pub fn set_presence_broadcast_scope(&mut self, key: Option<PresenceKey>)

Decides whether to publish and under what scope, not what space the pointer is in — see Self::set_pointer_space.

pub fn presence_broadcast_scope(&self) -> Option<&PresenceKey>

pub fn presence_ctx(&self) -> &PresenceCtx

pub fn presence_ctx_mut(&mut self) -> &mut PresenceCtx

pub fn set_followed_peer(&mut self, user_id: Option<String>)

pub fn followed_peer(&self) -> Option<&str>

pub fn followed_peer_target(&self) -> Option<[f32; 2]>

pub fn try_follow_click(&mut self, viewport: Rect, point: Point) -> bool

A miss leaves the current follow target untouched.

pub fn permission_ctx(&self) -> &PermissionContext

pub fn set_permission_ctx(&mut self, ctx: PermissionContext)

pub fn broadcast_presence(&mut self, key: PresenceKey, payload: PresencePayload)

The server attributes the broadcast to this user’s id automatically, so callers only specify what changed.

pub fn broadcast_status( &mut self, workspace: PresenceKey, status: Option<&LiveStatus>, ) -> bool

Publish the collaboration rail’s current status through the real room presence path. None is an explicit clear. Only workspace keys are accepted, preventing an intention from being accidentally scoped to a single widget and disappearing as the participant navigates.

pub fn follow(&mut self, peer_id: impl Into<String>)

Following a peer who hasn’t published a View yet latches the intent without moving anything; the viewport snaps to them once their first View arrives.

pub fn unfollow(&mut self)

pub fn pump_collab_presence(&mut self) -> bool

Shared by the per-frame tick and the headless test path. Returns true iff presentation changed (not merely that a packet arrived).

pub fn collaboration_state(&self) -> CollaborationState

Where the app’s collaboration connection stands. Managers connect in the background, so an app opens CollaborationState::Connecting and later becomes ready or offline; a frame is scheduled at each change.

pub fn channel_access(&self) -> Option<ChannelAccessState>

What this device can do with the document’s end-to-end encrypted channel: while it is waiting for access (a new device before its welcome arrives) or was removed, nothing is read or written and the app says so instead of showing stale or undecryptable content. None until the route reports.

pub fn local_author(&self) -> &UserId

impl App

pub fn with_autosave(self, autosave: DocWriter) -> App

Pair with crate::persist::open, which hands back the document the previous session left plus its writer:

let (state, autosave) = ui::persist::open("so.tilo.my-app");
ui::App::from_factory(state, my_app::app_root)
    .with_autosave(autosave)
    .run();

Panics

Fails closed if the host storage lifetime counter is exhausted.

pub fn with_records(self, records: RecordSet, room_index: AutoCommit) -> App

pub fn records(&self) -> Option<&RecordSet>

pub fn room_index(&self) -> Option<&AutoCommit>

pub fn swap_requested_component(&mut self) -> bool

Show the record the window’s component asked to open in its place (AppComponent::take_replacement): close the component, keeping its recovery, mount the one it built, and move the window’s collaboration to the new record’s route. Whether the window now shows another record.

pub fn record_tick(&mut self) -> bool

pub fn autosave(&self) -> Option<&DocWriter>

Lets a caller check crate::persist::DocWriter::last_error rather than assuming the disk accepted the writes.

impl App

pub fn run(self)

Run this application on the platform event loop.

pub fn run_with_setup<F>(self, setup: F)

where F: FnOnce(EventLoopProxy<UserEvent>),

Like App::run but exposes the winit EventLoopProxy before the loop starts, so callers can spawn threads that inject UserEvents.

Panics

Panics if the platform windowing system can’t create the event loop. Once running, a Wayland compositor disconnect is a normal application shutdown boundary (session logout, compositor restart), so an ExitFailure is logged and returned rather than converted into a panic.

impl App

pub fn surface_input( &mut self, window: &dyn AppSurface, event: WindowEvent, synthesized_touch: bool, ) -> bool

Handle event from the surface the app is shown on. Pointer positions are in the surface’s physical pixels, relative to the app’s own origin. synthesized_touch marks pointer events the host made from a touch, which keep touch modality. Returns whether anything handled the event.

pub fn set_tab_order_continues_in_host(&mut self, continues: bool)

Whether the host the app is shown in continues its focus order past the app, so Tab at either end of the app’s order leaves the app.

pub fn focus_order_edge(&mut self, last: bool) -> bool

Focus the first control of the app’s order, or the last with last: where keyboard focus lands when it enters the app from its host. Returns whether the app has a control to focus.

pub fn focused_control(&self) -> Option<NodeId>

The control with keyboard focus, to restore when focus comes back.

pub fn restore_focused_control(&mut self, control: Option<NodeId>) -> bool

Give keyboard focus back to control if it is still in the app’s focus order, or take it from every control with None.

pub fn unsettled(&self) -> bool

Whether the last frame left a sync or a layout to settle.

pub fn set_surface_modifiers(&mut self, modifiers: Modifiers)

The modifier keys held, as the surface reports them.

pub fn surface_frame( &mut self, surface: &dyn AppSurface, scene: &mut Scene, ) -> bool

Run one frame of the app on surface and paint it into scene, in the surface’s logical pixels from the app’s own origin: its model pumped (collaboration, invocations, publication), synchronized, laid out and drawn, as a window of its own runs it. Returns whether the app wants another frame.

pub fn surface_frame_with_damage( &mut self, surface: &dyn AppSurface, scene: &mut Scene, damage: &mut SurfaceDamage, ) -> bool

Self::surface_frame, adding to damage where this frame’s pixels differ from the last frame’s, as a window of its own submits them.

impl App

pub fn set_native_input_probe(&mut self, probe: impl Fn() -> Value + 'static)

Install a read-only workload observer for scheduled native inputs. Snapshots verify fixture state changes; they do not prove pixel presentation. Keep this callback inexpensive: it executes on the UI thread.

pub fn from_component( component: AppComponent, inputs: ComponentRunnerInputs, ) -> Result<App, LaunchError>

Mount an already prepared component with explicit presentation and local services.

Errors

Returns the original component recovery owners when mounting is refused.

pub fn from_component_with_collaboration( component: AppComponent, inputs: ComponentRunnerInputs, collaboration: CollaborationManager, ) -> Result<App, LaunchError>

Mount a checked component on an explicitly admitted collaboration manager. The manager retains the certified SDK route; no ambient identity or service lookup is added. Component authority and record custody remain unchanged.

pub fn from_component_with_native_services( component: AppComponent, inputs: ComponentRunnerInputs, ) -> Result<App, LaunchError>

Mount a standalone native component with the process’s existing system services, including record-scoped collaboration and accessibility. Presentation, identity, storage and authority still belong to the host.

Errors

Preserves the component’s recovery owners on mount or route mismatch.

pub fn collaboration_is_connected(&self) -> bool

Current SDK transport health, including fail-closed publication errors.

pub fn close_components(&mut self)

Capture/close embedded components while the host still owns their trees. Recovery reports stay owned by this host until explicitly transferred.

pub fn component_close_reports(&self) -> &[ComponentCloseReport]

pub fn take_component_close_reports(&mut self) -> Vec<ComponentCloseReport>

Transfer pending recovery to another owner; ordinary tile destruction cannot lose it.

pub fn from_managed_root( state: State, root: ManagedRoot, ) -> Result<App, HistoryRegistrationError>

Detached convenience for explicitly supplied managed roots. Production launchers construct under their installed wake scope, then install History.

Errors

Refuses invalid or mismatched managed owner registrations.

pub fn control_coverage(&self) -> ControlCoverage

Registered producer inventory; legacy private custody remains unqualified.

pub fn new(state: State, root_widget: Box<dyn Widget>) -> App

Construct an explicitly detached app for headless or test execution. This masks any ambient host while setup runs; native launchers use Self::from_factory, Self::try_from_factory or Self::from_scoped_parts.

pub fn with_collaboration_manager( state: State, root_widget: Box<dyn Widget>, collab_manager: CollaborationManager, ) -> App

Construct an explicitly detached app with a connected collaboration manager for headless or test execution.

The detached context applies during App setup only. It does not adopt handles captured earlier by state, root_widget, or the manager.

pub fn from_factory( state: State, factory: impl FnOnce() -> Box<dyn Widget>, ) -> App

Construct a live app whose root factory captures a fresh owner.

pub fn try_from_factory<E>( state: State, factory: impl FnOnce() -> Result<Box<dyn Widget>, E>, ) -> Result<App, E>

Fallible form of Self::from_factory. A failed factory closes all capabilities it created before returning the error.

Errors

Returns the error produced by factory.

pub fn from_scoped_parts( wake_scope: WakeScope, state: State, root_widget: Box<dyn Widget>, ) -> App

Transfer an existing owner into a live app.

The caller must enter this exact scope before constructing all state, models, and widgets passed here. The owner is bound once at native startup; detached or foreign captures cannot be adopted retroactively.

pub fn from_scoped_parts_local( wake_scope: WakeScope, state: State, root_widget: Box<dyn Widget>, ) -> App

Construct a live app without discovering workspace services or identity.

Local effects and wake ownership remain available. The caller still owns storage policy; private windows must supply memory-only state/autosave.

pub fn enter_wake_scope(&self) -> WakeScopeGuard

impl App

pub fn set_window_appearance(&mut self, appearance: WindowAppearance) -> bool

Where and for whom this window is shown, as the shell said it over the shell-ui channel: the workspace’s temperature and the person’s colour. A window the shell never told stays neutral and keeps the colour it started with. Returns whether the theme changed.

pub fn window_appearance(&self) -> WindowAppearance

What the host said about where and for whom this window is shown.

impl App

pub fn with_window_title(self, title: impl Into<String>) -> App

Takes effect when the window is created, so set before App::run.

pub fn with_window_app_id(self, app_id: impl Into<String>) -> App

Set the stable Wayland application id announced by this window.

pub fn window_app_id(&self) -> Option<&str>

The Wayland application id the window announces when it is not the process’s own package id: an input surface’s, or one set with Self::with_window_app_id.

impl App

pub fn validate_history_registration( &self, ) -> Result<(), HistoryRegistrationError>

Errors

Refuses missing, stale, foreign or unsupported installed owner registrations.

impl App

pub fn document_sync_status(&self) -> Option<&str>

Local queue state, not an acknowledgement of remote delivery/durability.

Trait Implementations

impl Drop for App

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl FreezeThaw for App

fn serialize_state(&self) -> Vec<u8>

AutoCommit::save takes &mut self to flush its open transaction; freeze is &self on a cold path, so save a clone rather than widen the signature.

fn restore_state(&mut self, bytes: &[u8]) -> Result<(), ThawError>

Also resets the undo history — the old stacks name changes this document has never seen.

fn restore_view(&mut self, view: &View)

open_resource is carried for presence/reboot to reopen the record; record-navigation itself is the host’s and is not driven here.

fn capture_view(&self) -> View

Capture this app’s presentation into a View. Default: an empty View, so an implementor with no toolkit-managed presentation still round-trips.

fn freeze(&self) -> Vec<u8>

Serialize state and view into one versioned envelope. Not an override point — overriding serialize_state is enough to change what this produces.

fn thaw(&mut self, bytes: &[u8]) -> Result<(), ThawError>

Restore state and view from bytes produced by freeze.