pub trait DocumentSession<F>: Any {
Show 54 methods
// Required methods
fn frame(&mut self, width: u32, height: u32) -> F;
fn scroll_by(&mut self, dx: f32, dy: f32) -> bool;
fn scroll_for_key(&mut self, key: SessionScrollKey) -> bool;
fn click_at(&mut self, x: f32, y: f32) -> SessionClick;
fn links(&self) -> Vec<SessionLink>;
fn as_any_ref(&self) -> &dyn Any;
fn as_any(&mut self) -> &mut dyn Any;
// Provided methods
fn take_encoded_form_submission(
&mut self,
) -> Option<SessionEncodedFormSubmission> { ... }
fn current_address(&self) -> Option<String> { ... }
fn document_capabilities(&self) -> DocumentCapabilities { ... }
fn try_frame(&mut self, width: u32, height: u32) -> Result<F, String> { ... }
fn external_texture_draws(&self) -> &[SessionExternalTextureDraw] { ... }
fn scroll_at(&mut self, _x: f32, _y: f32, dx: f32, dy: f32) -> bool { ... }
fn scroll_to(&mut self, _y: f32) { ... }
fn pointer_down(&mut self, x: f32, y: f32) -> SessionClick { ... }
fn pointer_move(&mut self, _x: f32, _y: f32) -> bool { ... }
fn pointer_up(&mut self, _x: f32, _y: f32) -> SessionClick { ... }
fn input(&mut self, input: SessionInput) -> SessionInputResult { ... }
fn effect_for_click(&mut self, click: SessionClick) -> SessionEffect { ... }
fn key_input(
&mut self,
_key: SessionKey,
_state: SessionButtonState,
_modifiers: SessionModifiers,
_repeat: bool,
) -> SessionEffect { ... }
fn keyboard_text_input(&mut self, text: &str) -> bool { ... }
fn text_input(&mut self, _text: &str) -> bool { ... }
fn ime_input(&mut self, ime: SessionIme) -> bool { ... }
fn focus_input(&mut self, _focused: bool) { ... }
fn focus_move(&mut self, _direction: SessionFocusDirection) -> bool { ... }
fn cancel_input(&mut self) -> bool { ... }
fn editable_focus(&self) -> bool { ... }
fn text_input_state(&self) -> Option<SessionTextInputState> { ... }
fn cursor_at(&self, _x: f32, _y: f32) -> SessionCursor { ... }
fn form_submission(&mut self, action: &str) -> SessionFormSubmission { ... }
fn text_target(&self, _text: &str) -> Option<SessionTextTarget> { ... }
fn document_find(
&mut self,
_query: &DocumentFindQuery,
) -> Result<DocumentFindState, SessionError> { ... }
fn document_find_step(
&mut self,
_direction: DocumentFindDirection,
) -> Result<DocumentFindState, SessionError> { ... }
fn clear_document_find(&mut self) -> Result<(), SessionError> { ... }
fn set_page_zoom(
&mut self,
_factor: f32,
) -> Result<DocumentZoomState, SessionError> { ... }
fn capture_page(
&mut self,
_request: PageCaptureRequest,
) -> Result<PageCaptureOutput, SessionError> { ... }
fn content_height(&mut self, _width: u32, height: u32) -> u32 { ... }
fn subresources(&self) -> Vec<String> { ... }
fn provide_subresource(&mut self, _url: &str, _bytes: &[u8]) -> bool { ... }
fn apply_host_mutations(
&mut self,
_mutations: &[HostMutation],
) -> Result<HostMutationReport, SessionError> { ... }
fn element_ids_with_prefix(&self, _prefix: &str) -> Vec<String> { ... }
fn pump(&mut self, _now_ms: f64) { ... }
fn collection_stats(&self) -> (usize, usize) { ... }
fn pending_work(&mut self) -> SessionPendingWork { ... }
fn settled(&mut self) -> bool { ... }
fn set_hidden(&mut self, _hidden: bool) { ... }
fn supports_freeze_resume(&self) -> bool { ... }
fn freeze(&mut self) { ... }
fn resume(&mut self) { ... }
fn inspect(&self) -> Option<ContentReport> { ... }
fn clip(&self) -> Option<DocumentClip> { ... }
fn accessibility_projection(&self) -> Option<DocumentA11yProjection> { ... }
fn accessibility_click_target(
&self,
_target: DocumentA11yNodeId,
) -> Option<DocumentA11yClickTarget> { ... }
fn dispatch_accessibility_action(
&mut self,
_request: &DocumentA11yActionRequest,
) -> bool { ... }
}Expand description
A live document: a retained layout session producing paint frames.
All methods take &mut self; the session is single-owner, driven from the
host’s content thread — exactly how the lane types are driven today. Not
Send by default (scripted lanes hold JS engine state).
Required Methods§
Sourcefn frame(&mut self, width: u32, height: u32) -> F
fn frame(&mut self, width: u32, height: u32) -> F
Lay out (if needed) and paint at the given viewport. Resize is implicit: a size change re-lays-out, same as the lanes today.
Sourcefn scroll_by(&mut self, dx: f32, dy: f32) -> bool
fn scroll_by(&mut self, dx: f32, dy: f32) -> bool
Scroll the viewport; true if the offset changed.
fn scroll_for_key(&mut self, key: SessionScrollKey) -> bool
fn click_at(&mut self, x: f32, y: f32) -> SessionClick
Sourcefn links(&self) -> Vec<SessionLink>
fn links(&self) -> Vec<SessionLink>
The link hit-table off the retained layout (no live-DOM query per click) — the mechanism all three lanes already share.
Sourcefn as_any_ref(&self) -> &dyn Any
fn as_any_ref(&self) -> &dyn Any
Lane-specific extras (a scripted lane’s DOM stats, a static lane’s content report) stay on the concrete type; hosts that need them downcast through here rather than the trait growing every lane’s diagnostics.
fn as_any(&mut self) -> &mut dyn Any
Provided Methods§
Sourcefn take_encoded_form_submission(
&mut self,
) -> Option<SessionEncodedFormSubmission>
fn take_encoded_form_submission( &mut self, ) -> Option<SessionEncodedFormSubmission>
Consume the encoded request paired with the latest input’s Submit.
Sourcefn current_address(&self) -> Option<String>
fn current_address(&self) -> Option<String>
Visible top-document identity, distinct from an effective resource base.
Sourcefn document_capabilities(&self) -> DocumentCapabilities
fn document_capabilities(&self) -> DocumentCapabilities
Document-facing controls this retained session can presently serve.
A session can expose find while leaving page zoom and raster capture to its host. Retained navigation is commonly partial because the host owns lineage, policy, and refetch.
Sourcefn try_frame(&mut self, width: u32, height: u32) -> Result<F, String>
fn try_frame(&mut self, width: u32, height: u32) -> Result<F, String>
Paint a frame while preserving an engine’s refusal reason. Existing infallible sessions inherit the ordinary frame path.
Sourcefn external_texture_draws(&self) -> &[SessionExternalTextureDraw]
fn external_texture_draws(&self) -> &[SessionExternalTextureDraw]
Producer draws associated with the most recent Self::frame.
Sourcefn scroll_at(&mut self, _x: f32, _y: f32, dx: f32, dy: f32) -> bool
fn scroll_at(&mut self, _x: f32, _y: f32, dx: f32, dy: f32) -> bool
Scroll the scrollable under (x, y) (nested scrollers); true if an
offset changed. Defaults to viewport scroll for single-scroller lanes.
Sourcefn scroll_to(&mut self, _y: f32)
fn scroll_to(&mut self, _y: f32)
Jump to an absolute vertical offset (anchor / fragment navigation). Defaulted no-op for lanes without absolute addressing; lanes that track their offset override.
Sourcefn pointer_down(&mut self, x: f32, y: f32) -> SessionClick
fn pointer_down(&mut self, x: f32, y: f32) -> SessionClick
Begin a primary-pointer gesture in lane-local coordinates.
The default preserves the original click-on-press contract for lanes that have not adopted gesture state. Text-selecting lanes override this to retain an anchor and defer link activation until pointer-up.
Sourcefn pointer_move(&mut self, _x: f32, _y: f32) -> bool
fn pointer_move(&mut self, _x: f32, _y: f32) -> bool
Extend the captured primary-pointer gesture. true means visible
session state changed and the host should redraw.
Sourcefn pointer_up(&mut self, _x: f32, _y: f32) -> SessionClick
fn pointer_up(&mut self, _x: f32, _y: f32) -> SessionClick
Finish the captured primary-pointer gesture.
Lanes retaining text selection return SessionClick::Handled for a
non-collapsed selection, or the ordinary click result when the gesture
collapsed.
Sourcefn input(&mut self, input: SessionInput) -> SessionInputResult
fn input(&mut self, input: SessionInput) -> SessionInputResult
Dispatch host-neutral input through the lane’s retained interaction hooks. Existing click/pointer implementations remain the compatibility floor; richer lanes override the focused keyboard, text, IME, cursor, and form hooks below.
fn effect_for_click(&mut self, click: SessionClick) -> SessionEffect
Sourcefn key_input(
&mut self,
_key: SessionKey,
_state: SessionButtonState,
_modifiers: SessionModifiers,
_repeat: bool,
) -> SessionEffect
fn key_input( &mut self, _key: SessionKey, _state: SessionButtonState, _modifiers: SessionModifiers, _repeat: bool, ) -> SessionEffect
Dispatch a keyboard event and non-text default. Printable text arrives
separately through keyboard_text_input for the same press.
Sourcefn keyboard_text_input(&mut self, text: &str) -> bool
fn keyboard_text_input(&mut self, text: &str) -> bool
Insert text paired with the preceding physical key. Override to honor
cancellation while keeping independent text_input available.
Sourcefn text_input(&mut self, _text: &str) -> bool
fn text_input(&mut self, _text: &str) -> bool
Insert independent text, including paste or accessibility edits.
fn ime_input(&mut self, ime: SessionIme) -> bool
fn focus_input(&mut self, _focused: bool)
fn focus_move(&mut self, _direction: SessionFocusDirection) -> bool
fn cancel_input(&mut self) -> bool
fn editable_focus(&self) -> bool
Sourcefn text_input_state(&self) -> Option<SessionTextInputState>
fn text_input_state(&self) -> Option<SessionTextInputState>
Observe the focused writable text control against a current completed
layout. None means there is no usable text-control observation (or
this session does not implement it). This read must not trigger layout.
Hosts publish refreshed geometry after preparing the next frame.
fn cursor_at(&self, _x: f32, _y: f32) -> SessionCursor
fn form_submission(&mut self, action: &str) -> SessionFormSubmission
Sourcefn text_target(&self, _text: &str) -> Option<SessionTextTarget>
fn text_target(&self, _text: &str) -> Option<SessionTextTarget>
Resolve the first laid-out occurrence of text to pointer endpoints.
This remains read-only: callers must drive the normal pointer lifecycle
to create selection state.
Sourcefn document_find(
&mut self,
_query: &DocumentFindQuery,
) -> Result<DocumentFindState, SessionError>
fn document_find( &mut self, _query: &DocumentFindQuery, ) -> Result<DocumentFindState, SessionError>
Replace the retained find model for this session and reveal its first match. Engines own their document internals; the host receives only the portable model.
Sourcefn document_find_step(
&mut self,
_direction: DocumentFindDirection,
) -> Result<DocumentFindState, SessionError>
fn document_find_step( &mut self, _direction: DocumentFindDirection, ) -> Result<DocumentFindState, SessionError>
Step the current retained model, wrapping at either end.
fn clear_document_find(&mut self) -> Result<(), SessionError>
Sourcefn set_page_zoom(
&mut self,
_factor: f32,
) -> Result<DocumentZoomState, SessionError>
fn set_page_zoom( &mut self, _factor: f32, ) -> Result<DocumentZoomState, SessionError>
Present this document at an absolute page-zoom factor (1.0 = 100 %).
This is user-agent document zoom, not CSS zoom: the CSS viewport
shrinks as the factor grows, media queries re-evaluate against it, and
the engine scales its rendered output back up. Host chrome is never
scaled. The caller owns its own ladder and persistence — reset is
factor 1.0 — while the engine owns only bounds and quantization, which
it reports in the returned DocumentZoomState.
Sourcefn capture_page(
&mut self,
_request: PageCaptureRequest,
) -> Result<PageCaptureOutput, SessionError>
fn capture_page( &mut self, _request: PageCaptureRequest, ) -> Result<PageCaptureOutput, SessionError>
Capture immediately from this retained session. Retained sessions have no event queue solely for capture symmetry; a future implementation can return the same output vocabulary directly.
Sourcefn content_height(&mut self, _width: u32, height: u32) -> u32
fn content_height(&mut self, _width: u32, height: u32) -> u32
Full laid-out content height at this viewport, for hosts that band scenes. Sessions that scroll internally return the viewport height.
Sourcefn subresources(&self) -> Vec<String>
fn subresources(&self) -> Vec<String>
Absolute subresource URLs this retained session wants the host to fetch. The host owns transport, trust, credentials, and scheduling; sessions only name resources needed for their current presentation.
Sourcefn provide_subresource(&mut self, _url: &str, _bytes: &[u8]) -> bool
fn provide_subresource(&mut self, _url: &str, _bytes: &[u8]) -> bool
Deliver one host-fetched subresource. true means visible session
state changed and the host should redraw.
Sourcefn apply_host_mutations(
&mut self,
_mutations: &[HostMutation],
) -> Result<HostMutationReport, SessionError>
fn apply_host_mutations( &mut self, _mutations: &[HostMutation], ) -> Result<HostMutationReport, SessionError>
Apply one batch of host-driven DOM changes before the next
Self::frame, and report what the batch did.
The batch is applied as one turn — resolve, mutate, drain, restyle — so a host pays one invalidation for the whole set rather than one per mutation. Sessions whose DOM is immutable leave this unsupported; the host reports the absence rather than quietly rendering an unchanged document.
Sourcefn element_ids_with_prefix(&self, _prefix: &str) -> Vec<String>
fn element_ids_with_prefix(&self, _prefix: &str) -> Vec<String>
Element id attributes beginning with prefix, in document order.
The companion read to Self::apply_host_mutations: a host driving a
deterministic mutation pattern over “the controls” needs to name them
without having counted the document by hand. Empty for sessions with no
element-id plane.
Sourcefn pump(&mut self, _now_ms: f64)
fn pump(&mut self, _now_ms: f64)
Drive timers / pending script work (scripted lanes). No-op default.
Sourcefn collection_stats(&self) -> (usize, usize)
fn collection_stats(&self) -> (usize, usize)
Cumulative garbage-collection tally since this session was spawned:
(reflectors_unpinned, nodes_collected). This is the engine-owned
inspection seam a host correlates with its captured frame to confirm
collection (G5’s Lifetime contract), not a live API surface for
script. Static and non-scripted lanes have nothing to report.
Sourcefn pending_work(&mut self) -> SessionPendingWork
fn pending_work(&mut self) -> SessionPendingWork
Report the work that should wake this session after the current turn.
Static sessions remain idle. Scripted sessions report their earliest
timer and set external while host-owned fetch or Worker work remains.
Sourcefn settled(&mut self) -> bool
fn settled(&mut self) -> bool
Whether script-visible completion has settled: no pending microtasks or host-owned external work. Future timers do not block completion. This handshake does not track layout dirtiness or establish rendered quiescence. Static lanes are always settled by default.
Visibility hint (a hidden tile may skip raster-adjacent work).
Sourcefn supports_freeze_resume(&self) -> bool
fn supports_freeze_resume(&self) -> bool
Whether the host can suspend and resume this session’s task delivery. A hidden presentation still runs throttled work and is distinct from this lifecycle control.
Sourcefn freeze(&mut self)
fn freeze(&mut self)
Suspend all document task delivery after its lifecycle event. Sessions without this capability leave the request unchanged.
Sourcefn inspect(&self) -> Option<ContentReport>
fn inspect(&self) -> Option<ContentReport>
A structural ContentReport of the addressed content, for hosts that
cannot downcast to the concrete session type (it may be private to its
engine crate — turnstone’s one registered lane is exactly that case, which
is why this is a trait method and not an as_any detour). None for
lanes without a structural read; the host reports the absence honestly
rather than synthesizing one.
Sourcefn clip(&self) -> Option<DocumentClip>
fn clip(&self) -> Option<DocumentClip>
Capture the current semantic clip. None means this document lane
cannot supply clip content; hosts must not synthesize authority or
recover source bytes by downcasting.
Sourcefn accessibility_projection(&self) -> Option<DocumentA11yProjection>
fn accessibility_projection(&self) -> Option<DocumentA11yProjection>
Current renderer-neutral semantic snapshot of this retained document.
The projection, when present, is the live truth about semantic completeness and limitations. It replaces host-side guesses based on concrete session type. Local IDs remain stable for the same semantic object across revisions and must be namespaced by a host before entering a global accessibility tree.
Sourcefn accessibility_click_target(
&self,
_target: DocumentA11yNodeId,
) -> Option<DocumentA11yClickTarget>
fn accessibility_click_target( &self, _target: DocumentA11yNodeId, ) -> Option<DocumentA11yClickTarget>
Revalidate an advertised clickable node and return its current pointer
target. Hosts use the returned point with their ordinary click_at
path, keeping link routing and host navigation custody unchanged.
A None result means the node is stale, no longer clickable, or its
geometry is unavailable. The returned revision must match the current
projection before the host acts on it.
Sourcefn dispatch_accessibility_action(
&mut self,
_request: &DocumentA11yActionRequest,
) -> bool
fn dispatch_accessibility_action( &mut self, _request: &DocumentA11yActionRequest, ) -> bool
Revalidate and dispatch a non-pointer accessibility action.
Engines return true only after accepting a request whose revision and
target are current and whose action is advertised by that target.
Click intentionally returns false: it travels through
Self::accessibility_click_target and the ordinary pointer path.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".