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 enable_document_history_chrome(&mut self)

Enable the same standalone chrome used by a native App window. Widget and embedded-component harnesses retain their original content viewport.

As in the App, a root whose framework owner already supplies its own shared History surface (a hosted component, a registered framework app) keeps that one: wrapping it in the standalone adapter as well would stack two History toolbars and squeeze the app’s layout.

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

Observe a frame with an explicit error if its document authority changed. No cached private History rows escape an invalid frame.

Errors

Returns an error if the captured document authority or frame topology changed.

pub fn presentation_inspection(&self) -> InspectionSnapshot

Inspect the visible app-plus-host tree; operational root inspection is deliberately retained separately by inspection().

Panics

Panics if authority changed since layout. Use try_presentation_inspection when the caller can recover from a revoked frame without rebuilding it.

pub fn local_history_resources(&mut self) -> Result<Vec<Resource>, String>

Local host actions are intentionally separate from resources(), the application’s publishable catalogue. No remote actor is granted this door.

Errors

Returns an error if the captured document is no longer readable.

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

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

Errors

Refuses disabled chrome, stale sessions, denied reads and invalid arguments.

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

Open History as the History shortcut does: the app’s registered History where it has one, else the document History chrome.

Errors

Returns an error when the app has no History to open.

pub fn set_history_preview_root( &mut self, factory: impl Fn() -> Result<Box<dyn Widget>, String> + 'static, )

Let History preview a selected version with a fresh read-only instance of the app’s root, as the native App does.

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<Resource>)

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 take_caller_operation(&mut self) -> Option<PendingOperation>

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.

Errors

Fails when recording was not enabled or serialization fails.

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.

Errors

Returns an error while another dialog or command holds the window.

impl FrameHarness

pub fn replace_global_search_data(&mut self, data: GlobalSearchSourceData)

Replace the coherent admitted host snapshot. Revocation updates open results immediately and invalidates undrained selections from older data.

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

pub fn global_search_scope(&self) -> Option<SearchScope>

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

pub fn take_global_search_intent(&mut self) -> Option<GlobalSearchIntent>

pub fn handoff_caller_action( &mut self, address: &ActionAddress, ) -> Result<(), String>

Re-resolve an inert selected address through the existing argument, confirmation and caller/local-View admission path.

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, retaining 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. The callback captures a host task identifier/proxy, never a GPU, widget tree, or owning host reference. Browser hosts can dispatch that identifier to their local animation-frame queue.

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

The record the mounted component shows.

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

Force the mounted component’s real record writer to acknowledge all pending edits, then project the resulting durability state.

Capture scenarios use this at an explicit save boundary instead of depending on a wall-clock debounce or mutating a status widget.

Errors

Returns the record writer’s durable storage failure.

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

Attach the queue shared by this host’s actual mounted components.

Errors

A host cannot replace registration identity after attachment.

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

Service one snapshot through current checked owner and canonical admission.

Errors

Refusal retains 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 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.

Responsive structure discovered from the viewport is settled before this returns, so tests can address compact/wide controls immediately without an app-specific warm-up frame.

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 is asking about, and the text that confirms it, while it asks: a destructive verb or a removal a control, a menu or an immediate application submitted.

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

Confirm what the host is asking, as the person does: type the confirming text into its dialog and press Enter. Answers the action confirmed; None, changing nothing, when nothing is asked.

pub fn cancel_pending_history_control( &mut self, token: &ContinuationToken, ) -> bool

Cancel one exact retained control without dispatching it.

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 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_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) -> &mut W

where W: Widget + 'static,

Mutable access to the root mounted by Self::for_root. Anything may change through it, so the next frame recomposes from scratch.

Panics

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

pub fn root_and_state_mut<W>(&mut self) -> (&mut W, &mut State)

where W: Widget + 'static,

The root mounted by Self::for_root together with the live document, for calls that take both. Invalidates as Self::root_mut.

Panics

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

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

Run one frame at viewport, even when neither the size nor the composition changed since the last one.

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, and report whether the root marked it handled. Nothing is laid out until the next frame, which rebuilds only if the root reports a structural change.

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 handle_collaboration_event(&mut self, event: &CollabEvent)

Deliver an authenticated transport answer through the native widget tree.

pub fn state(&self) -> &State

The live document, read-only.

pub fn theme(&self) -> &Theme

Theme the next frame is drawn with.

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 drawable frame. Uses the same bounded prepaint lifecycle as the live App host. Equal sizes are a no-op; paint and scroll-only frames do not trigger viewport refreshes.

Errors

Returns a layout error if measurement or bounded composition settlement fails. The failed frame is not painted; callers may retry the resize.

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

Register replayable document action decoders for a driven app. Mirrors crate::App::action_registry_mut. Install an authenticated peer’s action transport before dispatching actions. Existing authority/owner/admission checks still run in the bound dispatcher.

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

pub fn perform_undo(&mut self) -> bool

Undo the last action, the way the live host does — through State::undo_as with this driver’s author. Returns whether anything was undone.

The driver’s one undo door: Ctrl+Z and an UndoButton both arrive here, so a scenario cannot pass against a path the user never takes.

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 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. No callbacks run synchronously. Requests coalesce and survive failed composition or postponed host presentation until the original pipeline completes. A caller must still retire maps before replacing widgets; this scheduling request does not establish topology validity.

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 widget names from its root to the deepest widget whose demand none of its children explains. A diagnostic for idle redraws; it walks only the demanding branches.

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>, ) -> Result<bool, FontCatalogError>

Install one verified optional font, invalidate text caches, then rebuild layout before the browser is allowed to request a redraw.

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.

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 currently 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 yet. Includes protected components and secret fields reported by the production paint, including cached trees.

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 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.

Errors

Returns the app’s refusal, or an unavailable error without a mounted app.

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. Returns whether a record set handled it — false means the caller should persist the document 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 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.

Errors

Returns an error instead of capturing an unfinished placeholder when the work does not complete within timeout.

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.

Errors

Returns a timeout error naming the missing target.

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 input_ownership_sequence(&self) -> u64

Mount-local token for asynchronous input. Includes changes that do not pass through explicit activation (pointer, semantics, modal, removal).

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

The taffy node holding keyboard focus, if any.

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.

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 targets(&self) -> HashMap<String, Rect>

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.

Errors

Returns an error for a missing target or an action that neither the widget nor the app-level generic fallback supports.

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.

Errors

Returns an error for a missing owner or unsupported child action.

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.

Errors

Returns an error if serializing the pure-data snapshot fails.

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<Resource>

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 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 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 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<Resource>, 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<Resource>, 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<Resource>, 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 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(&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.

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 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.

Errors

Returns an error when name is absent or its widget has no tappable layout rectangle.

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.

Errors

Returns an error if the widget is not found or has a zero-sized rect.

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

Press and release one key.

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 physical-to-logical input scale; layout and capture remain logical pixels.

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 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 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 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 end_profiling(&mut self)

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

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 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_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.

Errors

Describes the first node (in traversal order) whose child count, location or size differs, or the layout error of the rebuild.

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).

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.

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

Set the held modifier set. Names: ctrl, shift, alt, logo.

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 deliver_external(&mut self, payload: &str)

Deliver an out-of-band payload the way the live host delivers a crate::app::UserEvent::External — a worker’s progress line, or a wake-up for requests the app queued itself — then run the host tick.

pub fn dump_json(&mut self) -> String

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

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.

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.