Trait ResourceSurface 

pub trait ResourceSurface<R: Resource, E: Effect = NoEffect>: Widget {
    // Required method
    fn present(&mut self, state: &Rc<R::State>);

    // Provided methods
    fn supports_device_shell(&self) -> bool { ... }
    fn device_shell_operation(
        &mut self,
        _operation: &DeviceShellOperation,
    ) -> Result<Value, String> { ... }
    fn request_device_shell(&mut self) -> bool { ... }
    fn search_query(&mut self, query: &SearchQuery) { ... }
    fn take_save_retry(&mut self) -> bool { ... }
    fn take_host_intent(&mut self) -> Option<AppHostIntent> { ... }
    fn attach(&mut self, cx: SurfaceCx<R>) { ... }
    fn landed(&mut self, participant: &ParticipantId, place: &Place) { ... }
    fn read_only_changed(&mut self, read_only: bool) { ... }
    fn stage(&mut self, scenario: Option<&str>) { ... }
    fn effect(&mut self, effect: E, cx: &mut EffectCx<R, Self>) -> EffectAnswer
       where Self: Sized { ... }
    fn effects(&self) -> Vec<EffectStatus> { ... }
    fn availability(&self) -> Vec<EffectStatus> { ... }
    fn bound_declarations(&self) -> Vec<ActionDecl<R>> { ... }
    fn live_rows(&self) -> Vec<LiveRow> { ... }
    fn live_row(&self, id: &str) -> Option<LiveRow> { ... }
    fn row_declarations(&self, row: &str) -> Vec<ActionDecl<R>> { ... }
    fn search_entries(&self) -> Vec<SearchEntry> { ... }
}

A custom widget or renderer — a timeline, a canvas, a GPU viewport, a page layout engine — taking part in a resource.

Pixels, layout and input stay the toolkit’s Widget contract, unchanged. This trait adds only what the framework cannot infer:

• Read — present receives the resource state whenever it changes: a local edit, a collaborator’s, an undo. In History mode the framework builds the surface again from a read-only ViewCx and presents a past version, so time travel needs no extra code as long as the surface draws from what it was presented. A surface over a large resource reads through SurfaceCx::live instead of copying, and demands the parts it shows (Live::demand) from the document its sync receives — the live one, or the past version in History mode.
• Write — edits go through the Dispatcher handed to attach: a named action, or any typed action value via Dispatcher::apply. The host checks permissions, applies, records one undo step per action, attributes it in history and replicates it. A surface never writes the document.
• Undo granularity — one action is one undo step. Preview a gesture locally (a drag, a scrub) and dispatch one action when it ends; a gesture that is several edits goes in one Dispatcher::group (or holds a Dispatcher::begin_group guard for the input event), so one Ctrl+Z takes all of it back.
• Permissions — RecordEnv::read_only says the participant may only view; present accordingly. It follows role changes while the app runs, and read_only_changed announces each one. Refused actions change nothing.
• Confirmation — a typed value whose risk is destructive (deleting a clip) waits for the user’s confirmation, like a declared destructive action. When an edit is refused or held for confirmation, the surface is presented the stored state again, undoing any optimistic preview; a confirmed edit then arrives as an ordinary change.
• Presence — report where the user is as a ResourceSelection from the toolkit’s Widget::presence_payload (one line: selection.presence::<R>(app_id)), and draw collaborators from the PresenceCtx every draw receives, under the same keys.
• Effects — work with no document delta (back up now, connect, run a query) is the surface’s effect vocabulary E, a #[derive(Effect)] enum: implement ResourceSurface<R, E> and answer each effect in effect with &mut self, starting a job through the EffectCx when it takes time. Every caller — a button (Dispatcher::effect), the palette, an agent — reaches it the same way; effects says which are unavailable right now.
• Run mode — start work that reaches outside the process (a decoder service, a socket, a probe) only when RecordEnv::mode is live. A capture reads RecordEnv::fixture instead; a past version starts nothing. Work still in flight that the frame shows (a page render, a decode) is reported by the toolkit’s Widget::has_pending_visual_work; a capture waits for it.
• One published tree — what the surface offers the palette, agents and scripts joins the resource’s own publication: bound_declarations for edits bound to where the user is (delete the selected clip, bookmark the current folder), and live_rows for the live external entities it shows (processes, containers), which carry only view and effect operations. A document action the surface’s own PublishesResources offers is dropped, so nothing reaches the document beside the resource’s actions.

Required Methods

fn present(&mut self, state: &Rc<R::State>)

The resource state to show.

Provided Methods

fn supports_device_shell(&self) -> bool

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

Answer a private owner operation from the authenticated hosting shell.

Errors

Refuses unsupported or unavailable device-shell operations.

fn request_device_shell(&mut self) -> bool

A trusted hosting shell owner selected the device-shell target. No grant is implied.

fn search_query(&mut self, query: &SearchQuery)

The latest bounded query from the platform’s canonical search source. Runs on the UI thread before sync, coalescing queries between frames. A surface may refresh remote results through its attached jobs; expose their entries through search_entries, rather than another provider. Never called for a History view and lends no document.

fn take_save_retry(&mut self) -> bool

Consume a request to retry this window’s failed record save, once. The framework’s record owner performs the retry after releasing its document loan; the surface never writes or flushes storage itself. History surfaces cannot request a retry.

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

A pending device-local request for the hosting shell, consumed once. The host answers it through its permission flow; this callback lends no document.

fn attach(&mut self, cx: SurfaceCx<R>)

The channel edits go through, and whether they will be accepted. Called once, before the first present.

fn landed(&mut self, participant: &ParticipantId, place: &Place)

A participant’s action — an agent’s verb, a collaborator’s edit taken through the door — left them at place, as the resource says it lands (Resource::lands). Called after present showed the state holding it. Presence draws them there already; a surface that acts at a participant’s place (typing at an agent’s caret) reads it here, or any time through Live::place_of, instead of keeping its own copy.

fn read_only_changed(&mut self, read_only: bool)

The participant’s permission to edit changed while the app runs: a role granted or taken away. Present accordingly. The dispatcher already refuses or accepts edits under the new permissions.

fn stage(&mut self, scenario: Option<&str>)

Stage view state for a screenshot scenario (None for a plain --shots): a selection, an open menu, a drag in flight. Called at the start of the sync after the scenario’s actions applied and were laid out, so the surface has been presented their result, knows its geometry, and its own sync follows with the document. Edits it dispatches here are submitted like any other and applied before the frame is captured. Must be deterministic: the same scenario stages the same scene on every run. Never called in a live window.

fn effect(&mut self, effect: E, cx: &mut EffectCx<R, Self>) -> EffectAnswer

where Self: Sized,

Answer effect, invoked by a control, the palette, an agent or a script: finish now (Effected::done), or start a job with EffectCx::thread, EffectCx::spawn or EffectCx::reply and answer Effected::Pending (only for an effect declared job). A job’s completion runs on the UI thread with &mut self again, and changes the document through the context’s dispatcher. Never called in History mode.

Errors

Returns why the effect failed, which its caller is told.

fn effects(&self) -> Vec<EffectStatus>

The effects that differ from their declaration right now, as the surface’s state says: unavailable while the engine is offline, relabelled while recording. Read after every sync, so the published actions follow the surface.

fn availability(&self) -> Vec<EffectStatus>

The resource’s own actions that differ from their declaration right now, as the surface’s live state says (Camera::SET_MODE unavailable while recording, with why). Read whenever the resource is published, so the palette, agents and the door follow the surface: an action unavailable here is refused with its reason.

fn bound_declarations(&self) -> Vec<ActionDecl<R>>

Edits bound to the surface’s view state — the selection, the caret, the playhead, the folder or page shown — as typed builders of the resource’s action, published on the resource beside its declared actions. Invoking one dispatches the action it builds through the same permission check, confirmation and undo as any other. An id the resource already publishes keeps the resource’s action, unless the bound one refines it (tilo_resource::bind_declaration): same parameters, permission and risk, adding only where it was invoked from, such as the caret an append leaves its writer at.

fn live_rows(&self) -> Vec<LiveRow>

The live external entities the surface shows, published as children of the resource and merged by id with its document children. Keep it to what fits a published tree (the rows on screen, a bounded page) and resolve the rest in live_row.

fn live_row(&self, id: &str) -> Option<LiveRow>

The live row id, when live_rows leaves it out, so an action addressed to any entity the surface knows still reaches it.

fn row_declarations(&self, row: &str) -> Vec<ActionDecl<R>>

Edits of the resource bound to the live row row (rename this file): typed builders of the resource’s action, published on that row and applied through the same permission check, confirmation and undo as the resource’s own declarations. A row itself carries only view and effect operations; this is how it offers a document change.

fn search_entries(&self) -> Vec<SearchEntry>

Search entries for what the surface shows that the resource does not hold — a page’s text, a book’s outline, the processes running — indexed with the resource’s own (Resource::search) as the app’s one search source. Read whenever someone searches, so keep it to what the surface already has at hand.

Implementors