Skip to main content

DocumentSession

Trait DocumentSession 

Source
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§

Source

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.

Source

fn scroll_by(&mut self, dx: f32, dy: f32) -> bool

Scroll the viewport; true if the offset changed.

Source

fn scroll_for_key(&mut self, key: SessionScrollKey) -> bool

Source

fn click_at(&mut self, x: f32, y: f32) -> SessionClick

The link hit-table off the retained layout (no live-DOM query per click) — the mechanism all three lanes already share.

Source

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.

Source

fn as_any(&mut self) -> &mut dyn Any

Provided Methods§

Source

fn take_encoded_form_submission( &mut self, ) -> Option<SessionEncodedFormSubmission>

Consume the encoded request paired with the latest input’s Submit.

Source

fn current_address(&self) -> Option<String>

Visible top-document identity, distinct from an effective resource base.

Source

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.

Source

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.

Source

fn external_texture_draws(&self) -> &[SessionExternalTextureDraw]

Producer draws associated with the most recent Self::frame.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

fn effect_for_click(&mut self, click: SessionClick) -> SessionEffect

Source

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.

Source

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.

Source

fn text_input(&mut self, _text: &str) -> bool

Insert independent text, including paste or accessibility edits.

Source

fn ime_input(&mut self, ime: SessionIme) -> bool

Source

fn focus_input(&mut self, _focused: bool)

Source

fn focus_move(&mut self, _direction: SessionFocusDirection) -> bool

Source

fn cancel_input(&mut self) -> bool

Source

fn editable_focus(&self) -> bool

Source

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.

Source

fn cursor_at(&self, _x: f32, _y: f32) -> SessionCursor

Source

fn form_submission(&mut self, action: &str) -> SessionFormSubmission

Source

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.

Source

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.

Source

fn document_find_step( &mut self, _direction: DocumentFindDirection, ) -> Result<DocumentFindState, SessionError>

Step the current retained model, wrapping at either end.

Source

fn clear_document_find(&mut self) -> Result<(), SessionError>

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

fn pump(&mut self, _now_ms: f64)

Drive timers / pending script work (scripted lanes). No-op default.

Source

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.

Source

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.

Source

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.

Source

fn set_hidden(&mut self, _hidden: bool)

Visibility hint (a hidden tile may skip raster-adjacent work).

Source

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.

Source

fn freeze(&mut self)

Suspend all document task delivery after its lifecycle event. Sessions without this capability leave the request unchanged.

Source

fn resume(&mut self)

Restore task delivery and dispatch the document’s resume event.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Implementors§