Struct LiveSession 

pub struct LiveSession { /* private fields */ }

Opaque, backend-backed live render session: a persistent compiler that serves reads (render, paint seams, regions) from its current compile and takes edits via apply. Reads between edits see a stable document — apply is transactional, swapping the compile only on success — so immutability is an invariant between commits, not a type.

Geometry reads (regions, position_at, locate) resolve against the current compile. Anchoring a caret or selection across edits is the editor’s job (its own transaction mapping) — the session holds no change log and maps no positions forward; a consumer re-reads geometry after each committed apply.

Implementations

impl LiveSession

pub fn page_count(&self) -> usize

pub fn supports_canvas(&self) -> bool

Whether this session can paint pages to a canvas — the authoritative, session-level capability. Derived directly from the canvas seam (a painter exposes page_size_pt for its pages), so there is no separate capability flag to keep in sync: a canvas backend pairs render_rgba with page_size_pt, so this reflects what paint will do. A canvas-capable backend with zero pages reports false (nothing to paint).

For a pre-session estimate (no open session yet), see formats_support_canvas.

pub fn page_size_pt(&self, page: usize) -> Option<(f32, f32)>

Page dimensions in points, or None if page is out of range or the backend has no canvas painter. Generalized canvas-preview seam — see [SessionHandle::page_size_pt].

pub fn render_rgba( &self, page: usize, scale: f32, ) -> Option<(u32, u32, Vec<u8>)>

Rasterize page to non-premultiplied RGBA8 at scale× 72 ppi, or None if page is out of range or the backend has no canvas painter. A Some result is a complete raster of the page — all content visible, no caller-side compositing — per the per-backend contract on [SessionHandle::render_rgba].

pub fn regions(&self) -> Vec<RenderedRegion>

Schema-field geometry for the compiled session — each content field’s first placement (one RenderedRegion per page it touches), plus one region per field:-bound widget and per direct scalar reference site, keyed on the quill schema field path. A session-level query computed without rendering bytes; an interactive preview reads it to scroll to / highlight the focused field over a paint-ed canvas. Empty for backends that place no schema fields.

field is still not unique in the result: a placement breaking across pages surfaces one fragment per page (a highlight covers continuation pages), a scalar referenced at several plate sites surfaces each site, and a field arising from both tracked content and a bound widget surfaces both (overlapping rects that route to the same field). Group by field; every entry routes to that field in the editor. Later placements of one content value are not enumerated — for point-driven lookup over any placement, use field_at.

Reflects the current compile; re-read after each committed apply to pair a highlight box with the edit it shows.

pub fn field_boxes(&self, field: &str) -> Vec<RenderedRegion>

The whole-field highlight boxes for field — one union rect per page, over the field’s span-bearing content segments (the “highlight the focused field” quantity). The convenience that owns the union regions leaves derived: it keeps regions() as the low-level disjoint truth (#829) and folds the span-filter + per-page union here so no consumer reimplements it. Content only — a field placed solely as a scalar reference or a bound widget carries no span and yields nothing here; its box is a single regions rect. Reflects the current compile, like regions. See crate::field_boxes.

pub fn field_at(&self, page: usize, x: f32, y: f32) -> Option<String>

The schema field whose content is under a point on page — the forward (click → field) direction: hit-test a click against the compiled document and get back the field address to focus in the editor. x/y are PDF points with a bottom-left origin, the same convention as RenderedRegion::rect (a canvas consumer applies the inverse of the overlay transform it already uses for regions). Every placement answers, not just the first surfaced by regions. None off any field’s ink, out of range, or for backends that place no schema fields.

pub fn position_at(&self, page: usize, x: f32, y: f32) -> Option<ContentHit>

A point → content position — the fine-grained click direction: hit-test a point and get back the field and a USV offset into its Content, for placing a caret or mapping a selection into the content model. x/y are PDF points, bottom-left origin, the same convention as field_at. The offset is cluster-exact and degrades to the containing segment’s start on origin-less ink (list markers, a code fence’s interior). None off all content ink, on a scalar/widget, or for backends with no content map. See ContentHit.

Resolves against the current compile; the editor owns the caret it places and anchors it across later edits itself.

pub fn locate(&self, field: &str, pos: usize) -> Option<RenderedRegion>

A content position → caret rect — the reverse of position_at: given a field and a USV offset into its Content, return the box (page-indexed) to draw a caret at. None when the field places no tracked content or the offset maps to no drawn glyph. Resolves against the current compile.

pub fn warnings(&self) -> &[Diagnostic]

Non-fatal diagnostics of the session’s current compile — set at Backend::open and refreshed by each committed apply; a failed apply keeps the last-good compile and its warnings. Also appended to RenderResult::warnings on each render call. Exposed for consumers (e.g. canvas previews) that never call render().

pub fn render(&self, opts: &RenderOptions) -> Result<RenderResult, RenderError>

pub fn apply(&mut self, json_data: &Value) -> Result<ChangeSet, RenderError>

Recompile the session against new document data — the edit verb of a live preview. Transactional: on Err the previous compile stays live, so every read keeps serving the last-good document and its warnings; on Ok the session serves the new compile — warnings included — and the ChangeSet reports what changed. Pass data compiled by the same schema pipeline as Backend::open’s json_data (Quill::compile_data) — and from the same quill: the $quill reference check lives at the layer that still holds a Document (Quillmark::open, the WASM apply); compiled data does not carry the reference, so this seam cannot re-check it.