Struct FrameHarness 

pub struct FrameHarness { /* private fields */ }

Implementations

impl FrameHarness

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

Resolve an exact action against the retained layout, without draining wakes, laying out, scrolling, focusing, or executing an action. Hosts must associate this metadata with the presentation that owns the layout; it is not a portable semantic node identity or a capture receipt.

pub fn semantic_locus(&self, interaction: &SemanticInteraction) -> Option<Rect>

The exact retained control locus for a semantic action, if uniquely available. Missing/ambiguous/domain-specific targets return no geometry.

pub fn published_action_locus( &self, instance: u64, app: &str, record: &str, address: &ActionAddress, ) -> Option<Rect>

Resolve only a currently mounted publication owner, exact app instance and record. The alias is never decoded without its host/lifetime registry. Reads the retained frame without input, wake draining or document edits.

pub fn controls(&self) -> Vec<Control>

Every operable control the exported accessibility tree carries now, in tree order.

pub fn control(&self, id: &str) -> Option<Control>

The control id names, if the current frame has it.

pub fn operate_control( &mut self, id: &str, input: &ControlInput, ) -> Result<(), String>

Operate the control id as a person would.

A control bound to an app action runs it through the same door as a click, so an action that needs confirmation is refused here, not run.

Errors

Returns why: no such control in this frame, disabled, it does not take this input, or the action it triggered was refused or failed.

impl FrameHarness

pub fn present_history_in_header(&mut self)

Present the window’s History in the app’s own header rather than a fallback bar of its own, as a native App window does.

pub fn invoke_local_history_action( &mut self, address: &ActionAddress, argument: Option<&str>, ) -> Result<(), String>

Invoke only this host’s local History door. This is not a collaborator transport entry point and never searches app destinations.

Errors

Refuses a window without History and invalid arguments.

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

Open History as the History shortcut does.

Errors

Refuses a window whose app registers no History.

impl FrameHarness

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

Replace the caller’s currently authenticated action projection. Resource addresses must include immutable host/route/catalogue identity. Whether the command chord opens the caller palette. A root that answers the chord with its own search (the web desktop) turns it off.

pub fn set_caller_actions(&mut self, resources: Vec<ResourceSpec>)

pub fn open_caller_search(&mut self, query: &str) -> Result<(), String>

Transfer one UI intent. The host owns durable invocation admission and recovery; this frame never acknowledges an effect or mutates its document. Browser-owned command search opens the same authoritative palette.

pub fn caller_palette_rows(&self) -> Vec<(String, Option<String>)>

The caller palette’s rows as a person reads them, label and the line under it, in display order; empty while it is closed.

pub fn take_caller_operation(&mut self) -> Option<PendingOperation>

impl FrameHarness

pub fn render_png(&self, out: &Path)

Rasterise the most recently laid-out frame to a PNG over the window ground (surfaces.content), exactly as a live window clears before drawing. --shots writes this.

new, input delivery, and set_theme all finish with relayout, so this never runs a separate screenshot-only widget pipeline. A browser page cannot read a frame back synchronously: there nothing is written.

pub fn render_rgba(&self) -> Vec<u8>

Rasterise the most recently laid-out frame over the window ground, as tightly packed RGBA8 rows viewport.0 pixels wide. Empty in a browser page, which cannot read a frame back synchronously.

pub fn render_rgba_transparent(&self) -> Vec<u8>

FrameHarness::render_rgba over a transparent background.

pub fn render_window_png(&mut self, out: &Path)

Rasterise the most recently laid-out frame under the desktop’s window bar (Self::present_in_window_bar) to a PNG as tall as the window: the bar, then the app’s frame under it.

impl FrameHarness

pub fn render_rgba_with( &self, renderer: &mut OffscreenRenderer, background: AlphaColor<Srgb>, ) -> Vec<u8>

Rasterise the recorded frame and its captured backdrop with a caller-owned renderer. Pixel oracles can reuse a renderer with stable preprocessing without changing process-wide settings or the widget draw pipeline.

Panics

Panics if the renderer dimensions differ from the capture’s device size, or the GPU cannot produce the bounded consecutive valid submissions.

impl FrameHarness

pub fn retain_invocation_results(&mut self)

Retain outcomes from subsequent explicit scenario invocations. Inputs and confirmation phrases are excluded; returned data is retained only on request.

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

Serialize retained actual Completed/Accepted/Refused outcomes in invocation order. Accepted means only admission, never successful completion of a background job.

impl FrameHarness

pub fn nav_gesture(&mut self, dir: NavDirection) -> bool

The system’s back (or forward) gesture, as the host delivers it to the whole tree once recognised; whether something took it. The frame after it is laid out.

impl FrameHarness

pub fn begin_profiling(&mut self)

Install a capture profiler so Self::relayout / Self::send time each pass and commit a per-frame sample. Called by crate::profiling::run_scenario.

pub const fn drawn_commands(&self) -> u64

The draw commands the frames drawn since construction encoded: a frame that draws only what changed adds few, one that draws the whole tree adds all of it, every frame.

pub fn end_profiling(&mut self)

Stop per-pass timing; subsequent frames pay nothing again.

pub fn profile_frame(&mut self)

Render one frame with no input and record it. A frame here is one relayout, which runs the sync → build → apply → draw passes.

pub fn clear_profile_samples(&mut self)

Discard captured frames (e.g. warmup) without stopping capture.

pub fn take_profile_samples(&mut self) -> Vec<FrameTiming>

Take every captured frame so far, draining the buffer.

impl FrameHarness

pub fn set_full_relayout(&mut self, forced: Option<bool>)

Force (Some(true)) or forbid (Some(false)) the full-rebuild path for every following frame, overriding TILO_UI_FULL_RELAYOUT; None returns to the environment’s choice. Benchmarks use this to compare both paths inside one process.

pub fn text_cache_stats(&self) -> (u64, u64)

Cumulative text measurement-cache hits and misses for this host’s renderer. Compare around input to distinguish retained scrolling from remeasuring a whole page; a cold frame must first warm the counters.

pub fn take_text_shape_stats(&mut self) -> (u64, u64, u128)

Drain this host renderer’s actual shape-cache hits, misses and time spent shaping. Like TextRenderer::take_shape_stats, this isolates input work after a measured warmup without a wall-clock threshold.

pub fn last_relayout(&self) -> RelayoutStats

What the most recent completed relayout did with its layout tree.

pub fn relayout_frames(&self) -> u64

Completed relayout frames since construction; unchanged across a skipped (inert pointer) send.

pub fn rebuilt_frames(&self) -> u64

Completed frames that recomposed the layout tree. One input may produce several frames (press and release, a commit tick), so callers asserting on a structural change compare this across the input.

pub fn layout_nodes_built(&self) -> u64

Layout nodes built since construction: every node of each tree a frame rebuilt, and each node a change carried out in place mounted. What a change cost the layout, whichever way it went.

pub fn layout_node_ids(&self) -> Vec<u64>

Every taffy node of the current composition, sorted. Equal across two frames exactly when the tree was retained rather than rebuilt.

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

Compare the retained composition’s geometry against a fresh rebuild of the same state. Runs one forced full relayout, so it is a test and diagnostics hook, not something a live host calls per frame.

pub fn set_retained_geometry_check(&mut self, every: u32)

Debug builds only: after every everyth retained frame, verify the retained geometry against a fresh rebuild and panic on a mismatch. 0 disables the check (the default).

impl FrameHarness

pub fn for_root<W>( state: State, root: W, viewport: (u32, u32), theme: Theme, ) -> FrameHarness

where W: Widget + 'static,

Mount one concrete widget as the root so a test can read and adjust it through Self::root and Self::root_mut between frames.

pub fn for_app<W>( state: State, root: W, viewport: (u32, u32), theme: Theme, ) -> FrameHarness

where W: AppWidget + 'static,

Self::for_root for an app: its window’s bar (Self::present_in_window_bar) wears the app’s icon and title, as a desktop window’s tab does.

pub fn for_root_with<W>( state: State, root: W, viewport: (u32, u32), options: FrameOptions, ) -> FrameHarness

where W: Widget + 'static,

Self::for_root with every construction option spelled out.

pub fn root<W>(&self) -> &W

where W: Widget + 'static,

The root mounted by Self::for_root.

Panics

When the root was not mounted through Self::for_root as a W.

pub fn root_mut<W>(&mut self) -> RootMut<'_, W>

where W: Widget + 'static,

Mutable access to the root mounted by Self::for_root. When it is let go of, the harness takes what the widgets report changed, as the live host does after each event: a change they carry out in place is remounted by the next frame, any other change (or a widget that replaced children without saying so) lets go of the layout tree, and the next frame rebuilds it. A change the widgets do not report keeps the tree, as it would live.

Panics

When the root was not mounted through Self::for_root as a W.

pub fn root_and_state_mut<W>(&mut self) -> RootAndStateMut<'_, W>

where W: Widget + 'static,

The root mounted by Self::for_root together with the live document, for calls that take both (RootAndStateMut::split). Letting go of them is as for Self::root_mut.

Panics

When the root was not mounted through Self::for_root as a W.

impl FrameHarness

pub fn settle_owed(&mut self)

Run the frame an action asks for, then frames as an idle live window does until every reply the root is owed (crate::wake::WakeHandle::owe) has landed and a frame took it up: what the action caused off the UI thread (a worker’s answer the app asked for in reply to it) is applied before the action answers, so its effects are the action’s and not the next one’s. Waits for wakes, never polls.

impl FrameHarness

pub fn open_search(&mut self, request: &SearchRequest) -> Result<(), String>

Open search the way request asks: this app or one part of it, with the query already typed.

impl FrameHarness

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

Click the sidebar button where the window’s bar, as the desktop draws it across the window, puts it, and hand the app what the press runs (Self::press_window_slot).

Errors

When the bar shows no sidebar button, or the click runs nothing.

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

Where the window’s sidebar stands now: what the bar’s button shows, what the window’s shell holds and what its frame lays out.

Errors

While the bar has no sidebar button or no shell with a sidebar is laid out.

pub fn press_window_sidebar_button( &mut self, presses: usize, ) -> Result<Vec<SidebarShown>, String>

Click the window bar’s sidebar button presses times, each followed by the frames the window draws until its motion has landed, and return where the sidebar stood before and after each.

Errors

When a click fails (Self::click_window_sidebar_button) or the window has no sidebar to read back.

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

Click the window bar’s sidebar button three times and check that each click flipped the sidebar, with the bar, the window’s shell and its frame agreeing every time, whatever opened it. Returns whether the sidebar was shown before the first click.

Errors

What the clicks did instead, as a sentence naming each state.

impl FrameHarness

pub fn host_window_slots(&mut self)

Host the app’s window-bar slots in a row across the top of the frame, as a window of its own outside a Tilo session does (a browser page that mounts one app): the app is told its slots, search and History are hosted, its frame is laid out under the row, and the row is painted, routed and inspected with it. A frame standing in for the desktop’s bar (Self::present_in_window_bar) already hosts them.

pub fn hosts_window_slots(&self) -> bool

Whether the frame hosts the app’s window-bar slots in a row of its own (Self::host_window_slots).

pub fn host_window_controls(&mut self)

The frame is a window of its own on a desktop that leaves the frame to the app (Self::host_window_slots): its row carries the window’s minimize, maximize and close in their pill at its trailing end, as the native runner’s row does, and a press on the row’s empty ground moves the window. A browser page’s row carries none: the browser has the window’s own chrome.

pub fn hosts_window_controls(&self) -> bool

Whether the frame’s row carries the window’s controls (Self::host_window_controls).

impl FrameHarness

pub fn cursor_at(&self, point: Point) -> Option<CursorIcon>

The pointer shape the laid-out surface asks for at logical point, by the rule every host shares (crate::widget::cursor): its laid-out nodes, and the shown tree walked as well, since a container that places its own children (a desktop’s strip of windows) keeps them out of the node map.

pub fn pointer_cursor(&self) -> CursorIcon

The pointer shape to show where the pointer last was: the default arrow off the surface and where nothing asks for another.

impl FrameHarness

pub fn present_in_window_bar(&mut self)

Show the app as a desktop window shows it: its slots, search and History in the window’s bar, its frame under the bar. The window keeps the size it had; the app gets the part under the bar, and a capture (super::write_capture) names the whole window.

pub fn presents_window_bar(&self) -> bool

Whether the harness draws the desktop’s window bar over the app.

pub fn window_history_control(&self) -> Option<HistoryControl>

The History control the window lists beside the app’s slots, as the desktop’s bar (or, outside a session, the runner’s slot row) shows it: none while the app has no History to open.

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

Press the window’s History control as the bar hands the press over: it runs on the app’s History door, as the History shortcut does, and never reaches the app.

pub fn search_in_window( &mut self, opening: SearchOpening, query: &str, ) -> Option<(usize, usize)>

Type query into the window bar’s search, opened with Find or Replace as the desktop opens it, and carry it to the app’s widgets, which find it in place. Returns the current match and the count, as the bar shows them.

pub fn step_window_search(&mut self, forward: bool) -> Option<(usize, usize)>

Step the window bar’s search to the next (or previous) match.

pub fn replace_in_window(&mut self, with: &str, all: bool) -> bool

Type with into the open search’s replacement and press Replace (or Replace all); the frame after writes what the app made of it. Returns whether the search offered Replace on what the window shows.

pub fn window_search_position(&self) -> Option<(usize, usize)>

The window bar’s search’s current match and count, as the bar shows them; None with nothing found.

pub fn window_search_query(&self) -> &str

The query the window bar’s search field shows.

pub fn window_search_count(&self) -> Option<FilterCount>

What the window bar’s search counts: the rows a list or a query view kept of all of them, the current match of all matches in a document; None before anything is typed.

pub fn window_search_replaces(&self) -> bool

Whether the window bar’s search offers Replace on what the window shows.

pub fn press_window_slot(&mut self, event: ToolbarEvent)

Press one of the app’s own slots in the window’s bar (a mode, an action, the sidebar toggle), as the desktop hands the press to the app. The press is a press on the app: it hands the app the keyboard (Self::hand_keyboard_to_app), as in the native window. What the app asked of the host when its sync took the press (the Undo beside a notice asks for an undo) is done and shown, as the live window’s idle service does after that sync.

pub fn press_window_action(&mut self, name: &str) -> Result<(), String>

Press the action named name the app declares in its window’s bar, among its leading actions, its actions and their menu items, as the person finds it by what it says.

Errors

Says what the bar offers when no action is named name.

pub fn window_bar_notice(&mut self, width: f64) -> Option<WindowBarNotice>

How the window’s bar, as the desktop draws it across a window width wide, shows the notice up (none: no notice is up).

pub fn click_window_notice_action( &mut self, width: f64, index: usize, ) -> Result<(), String>

Click the notice’s button index where the window’s bar, as the desktop draws it across a window width wide, puts it (in the location’s place, or in a compact window’s strip), and hand the app what the press runs, as Self::press_window_slot does.

Errors

When no notice with that button is up, or the press runs nothing.

pub fn invoke_window_notice_action( &mut self, width: f64, index: usize, ) -> Result<(), String>

Run the notice’s button index through its semantic action, as assistive technology and automation do, on the window’s bar as the desktop draws it across a window width wide, and hand the app what it runs, as Self::press_window_slot does.

Errors

When the bar lists no such button, or its action runs nothing.

impl FrameHarness

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

Mount a prepared component without a native window, GPU or service discovery. # Errors Refuses exhausted mount generations or remounts, keeping the original recovery.

pub fn from_component_with_wake_notifier( component: AppComponent, viewport: (u32, u32), inputs: ComponentRunnerInputs, notify: impl Fn() + Send + Sync + 'static, ) -> Result<FrameHarness, LaunchError>

Mount with a lightweight scheduling signal: a host task identifier or proxy, never a GPU, widget tree or owning host, which a browser host dispatches to its animation-frame queue.

pub fn component_record_content_lane(&self) -> Option<Arc<ContentLane>>

The lane the mounted component’s record content travels on: the lane its window keeps, read as the window reads it, so a test asking what the window asked for looks here.

pub fn component_record(&self) -> Option<&RecordCheckout>

The record the mounted component shows.

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

Force the record writer to acknowledge every pending edit, then project the resulting durability state: an explicit save boundary for captures instead of a debounce.

pub fn attach_owner_wake_queue( &mut self, queue: OwnerWakeQueue, ) -> Result<(), BoundDispatchError>

Attach the queue shared by this host’s mounted components. # Errors Registration identity cannot be replaced after attachment.

pub fn service_pending_owner_models( &mut self, ) -> Result<usize, BoundDispatchError>

Service one snapshot through the checked owner and canonical admission. # Errors A refusal keeps the current and unvisited requests for retry.

pub fn service_pending_owner_models_report(&mut self) -> OwnerModelServiceReport

Scheduling progress from the actual taken snapshot, including a returned partial failure. This receipt grants no owner/map authority.

pub fn park_until(&self, deadline: Instant) -> bool

Park as an idle window does until a component is woken from another thread or deadline passes; returns at once when no component queues wakes.

pub fn has_pending_owner_models(&self) -> bool

Queue presence is scheduling metadata, never a service/authority proof.

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, viewport: (u32, u32), ) -> Result<FrameHarness, HistoryRegistrationError>

Stand the app up and resolve its first observable layout with responsive structure settled.

Errors Refuses invalid scope metadata or unavailable mounted document custody.

pub fn control_coverage(&self) -> ControlCoverage

Install the runner’s current authority, including revocations.

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

Replace permissions for the legacy host document. Bound components keep their own independently scoped permission contexts.

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

Errors

Refuses missing, stale or mismatched managed owner registrations.

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

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

pub fn pending_history_control_token( &mut self, id: PendingControlId, ) -> Option<ContinuationToken>

Mint a one-use token for the current presentation of one retained item.

pub fn continue_pending_history_control( &mut self, token: &ContinuationToken, ) -> Option<PendingControlStatus>

Continue one exact retained control under current authority.

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

Continue after the caller explicitly confirmed this exact current item: the action the host’s confirmation asks about, and the question it asks while it asks.

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

Why the host asks, when the workspace’s grants ask rather than the action itself, as the person reads it in the confirmation.

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

Answer the question the host asked, as the person does: activate the dialog’s button named for the verb (a destructive question starts on Cancel).

pub fn new( state: State, root: Box<dyn Widget>, viewport: (u32, u32), ) -> FrameHarness

pub fn new_with_theme( state: State, root: Box<dyn Widget>, viewport: (u32, u32), theme: Theme, ) -> FrameHarness

Stand the app up under an explicit theme and resolve the first observable layout, including viewport-dependent structure.

pub fn relayout_at( &mut self, viewport: (u32, u32), ) -> Result<(), WidgetLayoutError>

Run one frame at viewport even when neither size nor composition changed. # Errors As Self::resize.

pub fn recompose(&mut self) -> Result<(), WidgetLayoutError>

Run one frame that rebuilds the whole layout tree, as a structural change does, even when no widget reported one. # Errors As Self::resize.

pub fn relayout_themed( &mut self, viewport: (u32, u32), theme: Theme, ) -> Result<(), WidgetLayoutError>

Self::relayout_at under theme, which later frames keep. # Errors As Self::resize.

pub fn dispatch_to_root(&mut self, event: &WindowEvent) -> bool

Hand event straight to the root’s handle_event against the last frame’s layout, bypassing host focus routing; nothing is laid out until the next frame.

pub fn dispatch_to_root_with( &mut self, event: &WindowEvent, modifiers: &Modifiers, ) -> bool

Self::dispatch_to_root with an explicit modifier state for this one event.

pub fn dispatch_to_root_outcome( &mut self, event: &WindowEvent, modifiers: &Modifiers, ) -> RootDispatch

Self::dispatch_to_root_with, also reporting the node the root asked to focus.

pub fn root_widget(&self) -> &dyn Widget

The root widget, whatever it was mounted as.

pub fn root_widget_mut(&mut self) -> &mut dyn Widget

The root widget, mutably, for a test that pokes what it mounted between the events it sends.

pub fn handle_collaboration_event(&mut self, event: &CollabEvent<SdkCustody>)

Deliver an authenticated transport answer through the native widget tree.

pub fn take_collaboration_requests(&mut self) -> Vec<CollabRequest>

What the widget tree asked of the transport since the last call, as a live window’s host takes it: the other half of Self::handle_collaboration_event.

pub fn state(&self) -> &State

The live document, read-only.

pub fn theme(&self) -> &Theme

Theme the next frame is drawn with.

pub fn backdrops(&self) -> &BackdropFrame

The backdrops the last frame’s floating surfaces were drawn over, in frame pixels: what a host blurs outside the renderer and hands back.

pub fn resize(&mut self, viewport: (u32, u32)) -> Result<(), WidgetLayoutError>

Resize in logical pixels and settle geometry-dependent composition before exposing targets, accessibility or a frame; equal sizes do nothing. # Errors Returns a layout error when measurement or bounded composition fails, leaving the frame unpainted.

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

Register replayable document action decoders, as crate::App::action_registry_mut does; authority, owner and admission checks still run.

pub fn set_session_door( &mut self, client: RemoteActions, workspace: Option<String>, )

Serve this window the session client stands for, in workspace: where opening another app goes. A host that serves its windows in process, such as a page, installs its session here.

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

pub fn perform_undo(&mut self) -> bool

Undo the last action as the live host does, through State::undo_as with this driver’s author, and say whether anything was undone.

pub fn perform_redo(&mut self) -> bool

Redo the last undone action. The mirror of Self::perform_undo.

pub fn undo_status(&mut self) -> UndoStatus

History selected by the focused component, or the outer history when unbound. Widget publication remains specific to each widget’s own component binding.

pub fn quiet_frames(&self) -> u64

Frames that found nothing new to sync or publish (FrameWitness) since construction.

pub fn settled_history_frames(&self) -> u64

Quiet frames that did not ask the History surfaces again, because nothing moved: whether each hosted app keeps the owners its History registered, and whether a frontier moved.

pub fn replayed_window_draws(&self) -> u64

Windows a frame that only moved laid-out content showed by replaying their last drawing where they are now (crate::retained_present::PanReplay), since construction.

pub const fn replayed_draws(&self) -> bool

Whether the last frame replayed a window at rest instead of drawing it (Self::settle_replayed_draws).

pub fn settle_replayed_draws(&mut self)

Draw the last frame again if it replayed windows at rest, so what their widgets note while drawing describes where they are now; input does this before reaching a widget.

pub fn take_skip_report(&mut self) -> Option<String>

The report of the last frame the harness skipped on its own, when one was due: a host whose log is not tracing’s prints it.

pub fn skip_frame(&mut self, error: &WidgetLayoutError) -> Option<String>

Skip a frame whose layout failed with error, as every host does: the next frame lays out again and what was presented last stays on screen, so input keeps landing. Returns the line to log when one is due (crate::widget::SkippedFrames).

pub fn set_pan_replay(&mut self, allowed: bool)

Let following frames replay windows at rest when they only move laid-out content (the default), or draw every window; a host about to read a frame’s semantics forbids it for that frame, which then needs no Self::settle_replayed_draws.

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

Use a different palette for subsequent frames.

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

Set the input capabilities for the next frame without synthesising an OS event. Controls receive the same propagation as in the live host.

pub fn interaction_environment(&self) -> InteractionEnvironment

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

Switch platform HIG behavior without cross-compiling the test.

pub fn platform_conventions(&self) -> PlatformConventions

pub fn request_layout(&mut self)

Request deferred full composition without changing the viewport; callbacks run asynchronously and requests coalesce until the pipeline completes. A caller must still retire maps before replacing widgets: this does not establish topology validity.

pub fn queued_work_sources(&self) -> Vec<&'static str>

What makes FrameSchedule::queued_work true, by name: what an idle window would wake for. Diagnostics for a test holding a window idle; not part of scheduling.

pub fn frame_schedule(&self) -> FrameSchedule

Read wake demand without materializing document text or semantic nodes.

pub fn frame_requesters(&self) -> Vec<(String, FrameDemand)>

The widgets behind Self::frame_schedule’s animation demand and due wake deadline, each as the path of names from its root to the deepest widget whose demand none of its children explains. A diagnostic for idle redraws.

pub fn layout_measure_requesters(&self) -> Vec<String>

The widgets that make a retained frame re-solve sizes rather than only re-apply positions: each widget reporting layout_needs_measure that none of its children explains, as its path from the root with a test id in brackets. Empty when the next retained frame would solve no size.

pub fn browser_font_demands_pending(&self) -> bool

Whether Self::take_browser_font_demands has anything to hand over.

pub fn take_browser_font_demands(&mut self) -> Vec<String>

Drain optional canonical font assets demanded by the most recent authoritative shaping pass.

pub fn install_browser_font( &mut self, name: &str, bytes: Vec<u8>, sha256: &str, ) -> Result<bool, FontCatalogError>

Install one verified optional font and invalidate text caches, so the next frame rebuilds the layout once for every font installed before it. # Errors Propagates canonical font integrity and face-validation failures.

pub fn browser_font_failed(&mut self)

Rearm shaping demand after a host fetch failed, without producing a frame or mutating focus/document state on asynchronous completion.

pub fn redraw_sources(&self) -> Vec<String>

Diagnostic paths of dirty subtrees, without inspecting document content. Queried outside a measured frame; not part of normal scheduling. It reads the tree as Self::frame_schedule does — presence lent, no widget entered — so a path it names is one the schedule counted.

pub fn track_scene_parts(&mut self, track: bool)

Record the damage parts of every scene the draw pass produces from now on (crate::scene_parts), for a host that compares each frame with the one it presented before.

pub fn scene_parts(&self) -> Option<&SectionParts>

The damage parts of the last scene drawn, when they were recorded (Self::track_scene_parts) and well nested.

pub fn frame_render_input(&self) -> FrameRenderInput<'_>

Borrow the completed scene. Use frame_output when semantics are needed.

pub fn frame_output(&self) -> FrameOutput<'_>

Inspect a completed frame without creating a GPU, worker, or window.

pub fn ime_window(&self) -> Option<ImeWindowState>

The IME window of the current keyboard owner: the ime of Self::frame_output without building the whole inspection tree.

pub fn poll_frame(&mut self) -> Result<bool, WidgetLayoutError>

Pump component wakes and animate using the production update/layout/draw passes. Returns whether a new scene was produced. The host schedules this on its frame clock.

pub const fn capture_protected(&self) -> bool

Whether the prepared scene must be withheld from external capture; a host binds this to its actual presentation, never an update that has not reached the surface. Includes protected components and secret fields of the production paint, cached trees included.

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

Drive a record-aware app: the live document is a record’s, and the widget names which one. Mirrors crate::App::with_records.

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

The records this driver has open, if the app under test uses them.

pub fn device_shell_operation( &mut self, operation: &DeviceShellOperation, ) -> Result<Value, String>

Deliver a trusted shell operation through the mounted app adapter.

pub fn request_device_shell(&mut self) -> bool

Deliver the existing trusted host selection through the mounted canonical adapter.

pub fn take_host_intent(&mut self) -> Option<AppHostIntent>

Consume one device-local shell request through the mounted app’s canonical adapter. This exposes no mutable document or direct surface callback.

pub fn persist_tick(&mut self) -> bool

Offer the live document to its record’s writer; false means the caller should persist it itself, as an app without records does.

pub fn persist_flush(&mut self)

Write out every open record and wait for it to land.

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

Flush records while retaining storage failures for the command’s exit status.

Errors

Reports unavailable or failed record writers.

pub fn relayout(&mut self)

Re-run the app’s frame: sync from the CRDT, rebuild Taffy, apply layout, and draw. Called after every action so the next one sees where things actually moved.

The draw pass isn’t decoration: many widgets record their hit-test rects while drawing, so skipping it would leave every click silently missing — exactly the false-pass this harness must avoid. Nothing is rasterised; the Scene is encoded on the CPU and discarded.

pub fn idle(&mut self)

What the live window does once input stops: the frame the input asked for if it has not run yet, control invocations dispatched, edits offered to the record’s writer, and the frame that asks for. Unlike Self::wait_until it forces nothing: a frame runs only when something asks for one, and syncs and publishes only when something it reads moved, as in the live window.

pub fn wait_until( &mut self, timeout: Duration, condition: impl FnMut(&FrameHarness) -> bool, ) -> bool

Drive production-equivalent frames until condition becomes true or timeout expires.

This is the deterministic test seam for worker completions and asynchronous model notifications. Each attempt runs update, sync, layout, and draw. Between attempts the thread parks on the current crate::background::Background: a pumped executor runs its queue and advances its virtual clock instead of waiting in real time.

pub fn settle_for_capture(&mut self, bound: Duration) -> bool

Run production frames until the window has settled, as a person sees it a moment after it opened: no animation running (a tab’s entrance, a panel sliding in) and no image load the frame asked for still in flight. Waits at most bound and returns whether it settled. A capture calls this before it writes, so shots match the live window.

Animations run on the toolkit’s clock (crate::time::now), so the bound is measured on it too: an executor with a virtual clock (a pumped test) cannot run the bound out before an entrance has ended.

pub fn wait_for_visuals(&mut self, timeout: Duration) -> Result<(), String>

Run the normal frame pipeline until requested visual work completes.

pub fn wait_for_named( &mut self, name: &str, timeout: Duration, ) -> Result<(), String>

Wait until a retained widget with name is present in the live layout.

pub fn focus_order(&self) -> Vec<NodeId>

The keyboard-focusable widgets in tree order — the same DFS crate::app::App::update_focusable_order walks, so a Tab that reaches a widget here reaches it in the live app too. The deepest modal focus trap confines this order using the same policy as the native host.

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

Reject external activation while a modal owns input. Search acceptance calls this only after its overlay has closed and its intent was taken.

pub fn remember_app_focus(&mut self)

Remember a stable component/control identity, never a layout NodeId.

pub fn prepare_app_activation(&mut self, instance: u64)

Resolve focus only in the selected, live app instance. A missing control is an authoritative no-owner result; layout cannot revive another app.

pub fn activate_app_focus(&mut self, instance: u64)

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

The taffy node holding keyboard focus, if any.

pub fn clear_focus(&mut self)

Give the keyboard up: no widget of the tree holds it, as a window whose field had the focus has none once another window comes forward. What a host that drew a field asks for when the person went elsewhere, so the field stops taking what is typed.

pub fn tab(&mut self, back: bool) -> Option<NodeId>

Advance keyboard focus like Tab (or Shift+Tab when back), cycling the focus order. Returns the newly-focused node.

pub fn focus_access_nodes(&self) -> Vec<AccessNode>

The accessibility node of every keyboard-focusable control, in focus order — one entry per Tab stop. Non-mutating (it does not move focus), so a test can assert the expected controls exist with the right roles, names, and states in a single pass.

pub fn focused_access_node(&self) -> Option<AccessNode>

The local accessibility node of the currently-focused widget, if any — what a screen reader would announce when Tab lands here.

pub fn a11y_nodes(&self) -> Vec<(NodeId, Node)>

The full accessibility tree the AccessKit bridge exports for the current frame — the exact (NodeId, Node) list that reaches AT-SPI2 / Orca and the built-in screen reader, with the driver’s focus marked. The accessibility nodes with their bounds in the tree’s logical pixels (scale 1.0): a widget lays itself out in logical pixels, so its node stands there too, whatever device scale the frame is drawn at. A host that draws at a device scale converts them to the screen with the rest of its layout, and never divides them by that scale again.

pub fn a11y_node_named(&self, name: &str) -> Option<NodeId>

The id of the exported accessibility node whose accessible name is name — the handle a headless test uses to address an element that has no widget of its own (a table row, a clip on a timeline track).

Returns None when nothing carries that name this frame, which is a meaningful failure: an element a test cannot name is one a screen-reader user cannot find either.

pub fn a11y_focus(&self) -> Option<(NodeId, Node)>

The accessibility node the exported tree currently marks focused — what a screen reader would be sitting on. For a canvas widget this is the element inside it, not the widget, so a test can assert where the user actually is.

pub fn perform_a11y_action( &mut self, target: NodeId, action: &Action, ) -> Result<(), String>

Perform an accessibility Action on an exported node, exactly as an assistive technology would.

This is the headless counterpart of App::dispatch_a11y_action and deliberately takes the same route: resolve the id against the live tree, then hand the owning widget the action plus the key path naming the element, so a synthetic node is operated rather than the widget that painted it. Without this a canvas app could be described in a headless test but not driven by one, which caps how well it can be verified at all.

Errors

Returns an error when the id names nothing in the current frame — a stale reference is reported, never quietly retargeted at whatever now occupies the slot — or when it addresses the inoperable window root.

pub fn tab_through(&mut self) -> Vec<(Role, Option<String>)>

Tab through the entire focus order from the top, returning the accessible (role, name) a screen reader would announce at each stop. One assertion proves both that every control is reachable by keyboard and that each announces a sensible role + label.

pub fn drawn_tooltip(&self) -> Option<(&str, Rect)>

The text and chip (logical) of the tooltip the last frame painted.

pub fn targets(&self) -> HashMap<String, Rect>

pub fn embedded_targets(&mut self) -> HashMap<String, Rect>

The rects the widgets inside the [EmbeddedApp] root answer to, by name, in the frame’s own pixels.

targets stops at the app: an embedded app keeps its widget tree to itself, so a caller that drives the app alone (a recording of it) reads them from here instead.

Panics

When the root was not mounted as an [EmbeddedApp].

pub fn perform_named( &mut self, name: &str, action: &Action, ) -> Result<(), String>

Perform one semantic action against a stable widget id or fallback path, through the same routing contract as live assistive technology. A control a widget paints itself and publishes as a semantic child (a custom surface’s button) is named by its action_target, as in inspection output, without naming the widget that owns it. A node with no target is reached by its accessible name through a11y_node_named and perform_a11y_action.

pub fn perform_semantic_named( &mut self, name: &str, semantic_target: Option<&str>, action: &Action, ) -> Result<(), String>

Perform an action against a synthetic semantic child owned by a named retained widget. The child target is the stable opaque value exposed as action_target in inspection output.

pub fn expect(&mut self, expected: &SemanticExpectation) -> Result<(), String>

Assert the live accessibility contract of a retained widget or one of its synthetic model-addressed descendants.

Errors

Returns every mismatched field in one diagnostic, or a precise missing target/semantics error. An expectation built with SemanticExpectation::within drives live-equivalent frames until it matches or the explicit bound expires.

pub fn semantic_owner_instance(&self, name: &str) -> Option<u64>

App instance bound to a live semantic owner path or stable widget id.

pub fn inspection(&self) -> InspectionSnapshot

Capture widget identity, geometry, hierarchy, and accessibility from the same laid-out frame.

pub fn inspection_json(&self) -> Result<String, Error>

Pretty JSON form used by the standard --headless-drive inspector.

pub fn accessibility_audit(&self) -> AccessibilityAudit

Audit the exact retained and synthetic semantic tree exported in the current laid-out frame.

pub fn native_app_audit(&self) -> NativeAppAudit

Certify the laid-out application against the action-native contract.

Unlike a source-pattern check this resolves bindings against the live resource tree, so conditional resources and custom widgets are covered. A custom-painted control participates by exposing accessibility semantics and an crate::widget::ActionEmitter inventory entry.

pub fn resources(&self) -> Vec<ResourceSpec>

Snapshot the exact resource tree the native host currently publishes. Tests can assert search/agent visibility without reaching into widget internals or rebuilding a parallel catalogue.

pub fn component_contract_violations(&mut self) -> Vec<ContractViolation>

Every action contract violation that would make the live host refuse to publish a mounted component’s surface. The host withdraws a whole component when one of its actions breaks its contract, so a test asserts this is empty rather than finding the surface gone at runtime.

pub fn state_mut(&mut self) -> &mut State

The live document. Used to dump state and to hand to a saver.

pub fn send_host_event(&mut self, event: &WindowEvent)

Deliver platform input including host keyboard policy. Browser/native adapters forward real events here; synthetic helpers use the same path.

pub fn send(&mut self, event: &WindowEvent)

Deliver one event through the production dispatch path.

pub fn set_coalesce_input_frames(&mut self, coalesce: bool)

Leave the frame a wheel, pinch, key, composed text or pointer move asks for to the host’s next Self::poll_frame instead of composing, laying out and drawing it inside Self::send_host_event. For a host that presents on its own frame clock, as a browser page does on animation frames: a trackpad sends wheel events, a typist keys and a drag moves faster than frames, so every frame but the last would be replaced unseen, and the host’s frame lays out once more anyway. The event is still dispatched at once, against the last frame’s layout, as a native window dispatches it.

pub fn last_send_skipped_relayout(&self) -> bool

Whether the most recent Self::send_host_event skipped its relayout because it was inert pointer motion.

pub fn published(&self) -> u64

How many resources the components here have published since this frame started: a host that could not reach a destination yet asks again when it moves, rather than on every frame.

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

Invoke one explicit component destination using its current captured owner.

Errors

Refuses unavailable, denied, stale or ambiguous destinations and action failures.

pub fn invoke_bound_action_within( &mut self, address: &BoundActionAddress, arguments: &Map<String, Value>, ambient: &ActionContext, ) -> Result<ResourceOperationStart, DoorError>

Self::invoke_bound_action within ambient, the context a caller’s connection gives every invocation it makes (an agent’s run).

Errors

As Self::invoke_bound_action.

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

Invoke an action after the host caller explicitly confirmed this exact request. Permission, live owner and action availability are still checked.

Errors

Refuses unavailable, denied, stale or ambiguous destinations and action failures.

pub fn call_on( &mut self, resource: &str, action: &str, arguments: Value, ) -> Result<ResourceOperationStart, DoorError>

Invoke the action action that the hosted component publishes on its resource resource (its own, an item, a child or a live row, by the id it publishes), with JSON arguments, the way an agent’s call reaches it, then lay out again.

Errors

Refuses when no component is hosted or arguments is no object, and as Self::invoke_bound_action.

pub fn call_on_confirmed( &mut self, resource: &str, action: &str, arguments: Value, ) -> Result<ResourceOperationStart, DoorError>

Self::call_on after the caller confirmed this invocation, as the host’s confirmation prompt does for a destructive action.

Errors

As Self::call_on, except that no confirmation is required.

pub fn call_on_instance( &mut self, instance: u64, resource: &str, action: &str, arguments: Value, ) -> Result<ResourceOperationStart, DoorError>

Self::call_on on the hosted component instance instance, such as one window of several.

Errors

As Self::call_on.

pub fn call_on_instance_confirmed( &mut self, instance: u64, resource: &str, action: &str, arguments: Value, ) -> Result<ResourceOperationStart, DoorError>

Self::call_on_instance after the caller confirmed this invocation.

Errors

As Self::call_on, except that no confirmation is required.

pub fn invoke_published( &mut self, resource: &str, action: &str, arguments: &Map<String, Value>, ) -> Result<ResourceOperationStart, DoorError>

Invoke one published action of the tree the app publishes now (see Self::invoke_action) by its resource id and action id, unconfirmed.

Errors

As Self::invoke_action.

pub fn start_bound_job( &mut self, address: &BoundActionAddress, arguments: &Map<String, Value>, confirmed: bool, ) -> Result<(InvocationId, ResourceOperationStart), DoorError>

Self::invoke_bound_action (confirmed when confirmed) for an operation that may run as a job: answers with the invocation whose progress and result Self::job_updates then report, as the frames poll it.

Errors

As Self::invoke_bound_action.

pub fn start_bound_job_for( &mut self, invoker: Option<ActionInvoker>, address: &BoundActionAddress, arguments: &Map<String, Value>, confirmed: bool, ) -> Result<(InvocationId, ResourceOperationStart), DoorError>

Self::start_bound_job for invoker rather than the person at this device, as the host runs an invocation an agent or a collaborator was admitted for: the operation and every edit it submits are theirs, and an edit needing more than the operation they were admitted for is refused, failing the operation.

Errors

As Self::invoke_bound_action; the operation’s failure when it answered at once.

pub fn start_bound_job_within( &mut self, invoker: Option<ActionInvoker>, ambient: Option<&ActionContext>, address: &BoundActionAddress, arguments: &Map<String, Value>, confirmed: bool, ) -> Result<(InvocationId, ResourceOperationStart), DoorError>

Self::start_bound_job_for within ambient: the task the invoker is carrying out (an agent’s run, its purpose), recorded with every edit the operation makes.

Errors

As Self::start_bound_job_for.

pub fn control_failures(&self) -> &[String]

Every update the job invocation reported so far, oldest first. Why the operations driven through this harness that ended refused, failed or cancelled after they started did, oldest first.

pub fn job_updates(&self, invocation: InvocationId) -> &[InvocationUpdate]

pub fn cancel_job( &mut self, invocation: InvocationId, ) -> Option<InvocationUpdate>

Cancel the running job invocation, as its caller does from the host: the operation is asked to stop and answers with what it ended as, recorded in Self::job_updates like any other update. None when no job of this harness runs under invocation or it has not answered yet.

pub fn bound_resources( &self, id: Option<&str>, ) -> Result<Vec<ResourceSpec>, DoorError>

The resources the hosted component publishes, as its permissions let its bound actions be invoked. With id, only that resource: an app may resolve it lazily (a search hit, an open document), so it can be absent from the root listing and still be addressable.

Errors

Refuses a closed or unavailable component.

pub fn bound_resources_of( &self, instance: Option<u64>, id: Option<&str>, ) -> Result<Vec<ResourceSpec>, DoorError>

Self::bound_resources of one hosted component instance, such as one window of a desktop; None for every hosted component.

Errors

Refuses a closed or unavailable component.

pub fn published_bound_resources_of( &self, instance: Option<u64>, ) -> Result<Vec<ResourceSpec>, DoorError>

Component-owned transport aliases through the same publication namespace used by the native host. This does not execute actions or drain wakes.

Errors

Refuses unavailable components or invalid publication identities.

pub fn serve_provider( &mut self, provider: impl Into<String>, serve: Box<dyn FnMut(&ProvidedInvocation<'_>) -> Result<ActionOutput, DoorError>>, )

Answer provider’s actions with serve, as the workspace broker would deliver them to it: what the app’s controls bound to another provider’s actions (tilo_actions::ActionSpec::run_by) invoke.

pub fn control_notice(&self) -> Option<&ControlNotice>

What stands at the control the person last used: why what they did did not run, until their next press or key.

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

Why an invocation the person made did not run, wherever it is said: at their control, else in the window’s bar.

pub fn palette_shown(&self) -> bool

Whether the window’s own search is showing. A confirmation standing at a control is not search (Self::asking_at).

pub fn palette_rows(&self) -> Vec<SearchResult>

The rows the window’s own search shows, as its list paints them: what each says, the line under it, its picture and its shortcut’s keys (for tests and diagnostics).

pub fn asking_at(&self) -> Option<Rect>

The control the open confirmation stands beside, as a popover, while it asks about what the person pressed there.

pub fn touch_hold_at(&mut self, x: f64, y: f64)

Hold one finger still at logical (x, y) past the long-press delay, then lift it: the touchscreen’s secondary click. The hold is resolved at its deadline instead of waiting for it in real time.

pub fn touch_down_and_hold_at(&mut self, x: f64, y: f64)

Put one finger down at logical (x, y) and hold it still past the long-press delay, leaving it down: what a hold does, before the lift or drag that follows it (Self::touch with the id 0). The hold is resolved at its deadline instead of waiting for it in real time.

pub fn touch(&mut self, id: u64, phase: TouchPhase, x: f64, y: f64)

Deliver one finger’s contact update at logical (x, y); id distinguishes simultaneous fingers.

pub fn click_at(&mut self, x: f64, y: f64)

Move the pointer to (x, y) and press+release the left button — the three events a click produces, in order. Each is judged once dispatched, as Self::send judges it: a move that changed nothing a frame reads leaves its frame quiet, as hover does in the live App.

pub fn double_click_at(&mut self, x: f64, y: f64)

Two left clicks at (x, y) that count as one double-click however long the frames between the presses take: the multi-click window is widened for exactly these two presses, so a slow host cannot split them into two single clicks.

pub fn triple_click_at(&mut self, x: f64, y: f64)

Three left clicks at logical (x, y) that count as one triple-click however slow the frames between them.

pub fn double_tap_at(&mut self, x: f64, y: f64)

Two finger taps at logical (x, y) that count as one double tap however slow the frames between them.

pub fn drag_at(&mut self, from: (f64, f64), to: (f64, f64))

Press the left button at from, move through intermediate points to to and release there: a pointer drag in logical coordinates, as a drawing or a handle drag sees it.

pub fn tap_at(&mut self, x: f64, y: f64)

Direct-touch activation at logical coordinates.

pub fn swipe_at(&mut self, start: (f64, f64), end: (f64, f64))

Move one direct touch through enough intermediate points for widgets to receive smooth pixel scroll deltas rather than one synthetic jump.

pub fn tap_named(&mut self, name: &str) -> Result<(), String>

Touch the centre of a named widget.

pub fn click_named(&mut self, name: &str) -> Result<(), String>

Click the centre of the named widget. Err names the target when it is not in the tree, so a stale scenario fails loudly instead of quietly doing nothing.

pub fn key(&mut self, spec: &str)

Press and release one key, holding the modifiers a + chord names (Ctrl+Z, Shift+F10) for as long as the press lasts.

Tab drives host focus traversal unless the focused widget explicitly owns it (for example, a code editor’s indentation). This mirrors crate::app::App’s live routing; every delivered key then follows the normal root-widget event path.

pub fn type_text(&mut self, text: &str)

Type a string one character at a time.

pub fn commit_text(&mut self, text: &str)

Commit text through the production input-method path in one event.

Use this for scenarios whose subject is the resulting document rather than physical-key handling. It models a completed input-method composition without manufacturing a rendered frame for every character.

pub fn set_input_scale(&mut self, scale: f64) -> Result<(), String>

Set the display’s scale: device pixels per logical pixel, by which input is scaled. Layout and capture remain in logical pixels, with every edge on a device pixel: the next frame solves the layout again on the new grid.

Errors

Rejects a non-finite or non-positive scale.

pub fn focus_presence(&self) -> Option<(PresenceKey, PresencePayload)>

What the focused widget publishes as presence (its caret or selection), for a live host to send to peers.

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

The collaborator state the draw pass renders (remote carets, selections, names), for a live host applying peers’ presence. Takes effect in the next relayout.

pub fn set_presence_context(&mut self, presence: PresenceCtx)

Replace the host-projected collaborator state used by the real draw pass. Capture and integration hosts use this to exercise the same presence rendering that a live broker frame supplies, without a broker process.

pub fn update_presence( &mut self, update: impl FnOnce(&mut PresenceCtx) -> bool, ) -> bool

Mutate the collaborator presence read by the draw pass. When update reports a change the next scheduled frame redraws; unlike Self::set_presence_context this never runs a synchronous relayout, so live remote carets cost one ordinary frame at display cadence.

pub fn set_placed_pointers(&mut self, pointers: Vec<PeerCursor>) -> bool

Show other people’s pointers where its host placed them, in the surface’s logical pixels: each with its arrow and a name tag laid out to stay on screen, over windows, popovers and the bar alike. Replaces the last set; the next scheduled frame draws it. A pointer outside the surface is left out. Whether anything shown changed.

pub fn placed_pointers(&self) -> &[PeerCursor]

The pointers Self::set_placed_pointers last kept.

pub fn drawn_placed_pointers(&mut self) -> Vec<PeerCursor>

The placed pointers as the last frame drew them: without the name of one whose tag would meet the caret tag of the same person.

pub fn presence(&self) -> &PresenceCtx

Read-only view of the collaborator presence drawn by this harness.

pub fn focus_presence_payload(&self) -> Option<(PresenceKey, PresencePayload)>

Outbound caret/selection presence of the widget holding keyboard focus (the same poll crate::app::App broadcasts to peers).

pub fn scroll(&mut self, dx: f64, dy: f64)

Send wheel line-deltas at the last pointer position. Move the pointer inside the intended content viewport first, as a live user would.

pub fn native_input_snapshot(&self) -> Option<Value>

The root’s native input diagnostic, as the native runner samples it (see crate::widget::Widget::native_input_snapshot).

pub fn set_modifiers(&mut self, names: &[String])

Set the held modifier set. Names: ctrl, shift, alt, logo, and command: the platform’s command modifier, which a crate::platform::Shortcut::command chord is pressed with (Cmd on macOS, Ctrl elsewhere).

pub fn perform(&mut self, action: &Action) -> Result<(), String>

Run one action.

Errors

Returns an error if the action cannot be performed.

pub fn invoke_action( &mut self, address: &ActionAddress, arguments: &Map<String, Value>, confirm: bool, confirmation_phrase: Option<&str>, ) -> Result<ResourceOperationStart, DoorError>

Invoke one published action by address, the way an agent, a script or a screen reader does: resolve it against the tree the app publishes now, refuse it when unavailable, require the confirmation its contract names (confirm for Confirm, the exact phrase for Phrase), bind the arguments strictly, and run it through the host’s own executor. Then run the same host tick a real input event gets.

Errors

Returns the door’s refusal: unknown or hidden address, unavailable action, missing confirmation, invalid arguments, or a failed run.

pub fn component_instance_id(&self) -> Option<u64>

The instance id of the hosted application component, the instance_id its bound actions are addressed by. None when the root is not a component.

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

Admit an agent task participant into the hosted component under label, its display name, as a host worker does before the task’s first invocation (HostWorker::join_participant). A host whose own author is that participant makes the component act as the agent. Idempotent.

pub fn complete_content(&mut self) -> Option<(Size, Scene)>

What a whole-window capture draws of the root, as the desktop’s “full app” capture does: the size the root shows beyond its window and its scene at that size. None when it shows nothing more than the window. The next frame lays the root out again as it lives.

pub fn scene(&self) -> &Scene

The scene the last laid-out frame encoded: what Self::render_rgba rasterises. Its encoding is exact where pixels are not, so a capture’s determinism is asserted on it.

pub fn with_widget_mut<T, O>( &mut self, visit: impl FnOnce(&mut T) -> O, ) -> Option<O>

where T: 'static,

Reach the first retained widget of type T — found through Widget::as_any_mut, depth first along children_mut, into hosted components — run visit on it, then run one input-free frame (the host tick and a relayout) so whatever it queued is handled as after an event. None when no widget of that type opts in to as_any_mut.

This is how a screenshot scenario stages view state (a selection, an open dialog) in the widget that owns it, instead of reaching around it.

pub fn widget_mut<T>(&mut self) -> Option<&mut T>

where T: 'static,

The first retained widget of type T, found as with_widget_mut finds it, without running a frame: for a test reading or poking a widget between the events it sends. None when no widget of that type opts in to as_any_mut.

pub fn dump_json(&mut self) -> String

The document rendered as JSON, for a harness to diff across a restart.

Trait Implementations

impl Drop for FrameHarness

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.