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 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 live_rows(&self) -> Vec<LiveRow> { ... }
    fn live_row(&self, id: &str) -> Option<LiveRow> { ... }
}

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: live_rows for the live external entities it shows (processes, containers), which carry only view and effect operations. Edits bound to where the user is are the view’s (ViewCx::bind_declarations), and so are search entries for what it shows (Publishes::search_entries). 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.

Keeping state past this call is allowed but not free: while it is held, the next change brings a copy up to date. A copy shares what the change did not touch — every Collection item, untouched Keyed/Ordered fields, the untouched chunks of a Map, Set or Grid — but plain fields (a Vec, a BTreeMap) are copied whole on every change, so a large one belongs in one of those, and a surface keeps the parts it needs rather than the Rc when the state has large plain ones.

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.

fn request_device_shell(&mut self) -> bool

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

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

Implementors