Struct Session 

pub struct Session {

    pub doc: Doc,
    pub identity: Identity,
    pub path: BlockPath,
    pub doc_index: DocIndex,
    pub gesture: Gesture,
    pub undo_stack: UndoStack,
    pub recorded_through: Rev,
    pub recording: Recording,
    naming: Naming,
    pub moved: Moved,
    pub spotlight: Spotlighter,
    pub(crate) theme: Theme,
    pub presentation: Presentation,
    pub spatial: CachedIndex,
    pub tool: Tool,
    pub time_machine: Option<TimeMachine>,
    pub easing: Rc<RefCell<Easing>>,
    pub diagnostic: Diagnostic,
    pub frame_rate: FrameRate,
    pub(crate) camera: Camera,
    pointer_at: Option<Pos2>,
    refit: Refit,
    tick: Tick,
    repaint: Option<Duration>,
    handoffs: Vec<Handoff>,
    sent_assets: BTreeSet<AssetHash>,
    pub sheet: Sheet,
    last_hover_world: Option<Pos2>,
    last_click_world: Option<Pos2>,
    pub failures: Notices,
    pointer: Resolver,
    editor: Option<EditId>,
    text_outcome: Option<TextOutcome>,
}

The editor, minus its surface.

Fields

doc: Doc

The document, always: an in-process session or an attached .bwx container. Every read goes through it and every write through Self::submit, so which of the two homes is open is not a question the editor asks.

identity: Identity

Who this session’s commits are attributed to. The shell restores it from the preferences; what it is used for is entirely here.

path: BlockPath

Where the editor is looking. The scope being edited is the path’s last segment (Scope::Root at the document root).

doc_index: DocIndex

The index over the repo’s document, kept across frames and rebuilt only when a commit lands (DocIndex::view).

gesture: Gesture

The gesture in progress: its ops and the prediction they imply.

undo_stack: UndoStack

One step back, for the user: document edits and the view steps between them, interleaved.

recorded_through: Rev

The rev Self::undo_stack has already accounted for. Everything the repo has assigned above it is the frame’s to record — read off the repo rather than tallied beside it, so the two cannot drift.

recording: Recording

Suspended for the rest of a frame that ran an undo or a redo, whose restore must not be recorded as a fresh step.

naming: Naming

The container name Self::undo_stack has accounted for — read off the document at the start of a frame, as Self::recorded_through is read off the repo at the end of one.

moved: Moved

How the editor arrived where it stands — what one undo would take back, in the words its tooltip names.

spotlight: Spotlighter

The ring over what the last document step changed, while one is up.

theme: Theme

The roles and fonts are the engine’s own; the palette is the one the front end last told it (Action::SetPalette).

presentation: Presentation

The document’s derived state — solver geometry, measurement caches, propagated accents.

spatial: CachedIndex

Spatial index over the current level’s hittables, shared by viewport culling and hit-testing.

tool: Tool

time_machine: Option<TimeMachine>

The past rev on the canvas, folded — the time machine. None at head, which is where an ordinary session stays.

easing: Rc<RefCell<Easing>>

The session’s keyed easings: the table outlives any one frame’s canvas, so an affordance that started growing on one frame is read back on the next.

diagnostic: Diagnostic

frame_rate: FrameRate

camera: Camera

Where the diagram is shown from: the session’s own, moved by the host’s pointer through Self::moves and framed by what the document does.

pointer_at: Option<Pos2>

Where the pointer is over the canvas, in screen space, as the last Self::resolve left it.

refit: Refit

tick: Tick

repaint: Option<Duration>

handoffs: Vec<Handoff>

What the editor has to hand back, until the host takes it.

sent_assets: BTreeSet<AssetHash>

The artwork whose bytes have already crossed to the host: a hash in here is one the host can draw without being told again.

sheet: Sheet

What an export of this session says about itself beyond the document — stated by the host, the way the camera and the clock are.

last_hover_world: Option<Pos2>

Last world-space pointer hover over the canvas, used as the preferred paste target so a pasted group lands under the cursor.

last_click_world: Option<Pos2>

Last world-space click over the canvas, used as the paste target when no hover position is available.

failures: Notices

The failures this session has owned up to, and the user has not yet acknowledged.

pointer: Resolver

The pointer between frames: the press being held, the click a second one could double.

editor: Option<EditId>

The in-place editor the last frame asked for, which is the one the front end’s field can be reporting on.

text_outcome: Option<TextOutcome>

How that editor ended since the last frame, landing on the next frame’s interaction.

Implementations

impl Session

pub fn vantage(&self) -> Vantage

pub fn viewport(&self) -> Rect

pub fn set_viewport(&mut self, viewport: Rect)

The screen rect the canvas is laid out in — told whenever it changes.

pub fn set_safe_region(&mut self, safe: Rect)

The part of the viewport the floating chrome leaves clear, measured by whoever draws the chrome. Every framing centres in this rather than in the raw viewport, so nothing lands under a pill.

pub fn visible_world(&self) -> Rect

The world rect the viewport currently shows.

pub fn screen_to_world(&self, screen: Pos2) -> Pos2

A screen position under the camera — where a tool carried off the cluster was dropped.

pub fn moves(&mut self, moves: &[Move])

What the host’s pointer did to the camera this frame, applied in the order it happened.

pub fn stand_at(&mut self, vantage: Vantage)

Put the camera exactly here — what a history step restores.

pub fn fit_to_rect(&mut self, content: Rect)

Frame this world rect, snapping — an authored camera rect.

pub fn fit_content(&mut self, content: Rect)

Frame the level’s contents, the way the owed fit is taken once the diagram has been measured.

pub(crate) fn focus_on(&mut self, content: Rect, glide: Glide)

pub(crate) fn bring_into_view(&mut self, content: Rect, glide: Glide)

pub(crate) fn zoom_step(&mut self, step: ZoomStep, anchor: Option<Pos2>)

impl Session

pub fn top_bar(&mut self) -> TopBar

The top bar’s words, read off the session once so the breadcrumb, the lens and the dot cannot disagree with the document.

pub fn ground(&self) -> Ground

The colours under the diagram: the canvas ground and the grid over it, resolved through the same palette the diagram is — so the read-only drain cannot reach one and miss the other.

pub fn landed(&self, stood: Rev) -> Option<String>

What a frame wrote, where the log moved from stood: the confirmation the status line shows. Read off the log rather than off what did it, so the confirmation and the history row word one edit the same way, and a frame that turned out to write nothing says nothing.

pub fn history_rows(&self) -> Vec<Row>

The document’s history as its readers see it, oldest first.

pub fn displayed_tool(&self) -> ToolName

The tool the rail shows armed.

pub fn reading(&mut self) -> Reading

Everything the status line could say this frame.

fn selection_path(&mut self) -> Option<String>

What is selected, as a path — the ephemeral half of the status line, which is why it cannot live in the bar’s own breadcrumb.

One shape is named where the document names it; several are counted, since a list of names is not a path and would not fit on a line.

fn title_block(&self) -> TitleBlock

The status line’s title block: who this session attributes its work to, the rev on the canvas, and when that rev was written. Under the lens that is the rev being looked at, because a title block describes the drawing in front of the reader.

pub fn written_at(&self, rev: Rev) -> Option<WallTime>

When rev was written, where this session keeps rows. A scratch session keeps none, and answers None rather than the wall clock — which would make two readings of one rev differ.

pub fn nav_tree(&mut self) -> NavTree

The navigator’s tree over the document on the canvas.

pub fn overlay( &mut self, bounds: Option<Rect>, commands: &CommandSet, ) -> Option<Overlay>

The selection bar’s contents, for the selection whose on-screen bounds the canvas pass measured — None while nothing is selected. commands is the frame’s registry: the swatch and the I/O toggle read the targets of the commands it offers.

pub fn notices(&self) -> Vec<Notice>

What this session has to tell the user: its failures first, since a failure is news, then the standing facts about its files.

fn file_notices(&self) -> Vec<String>

The standing facts about the files under this document. A session with no container has none, so it has nothing to say.

impl Session

pub fn dispatch( &mut self, transition: impl Into<Transition>, layout: &dyn TextLayout, )

Apply one action, or a tool’s hand-off — all of it, since that is what the core executes and nothing else reaches here.

layout is the host’s text engine: an export lays its diagram out through the engine the canvas paints with, so it breaks its lines where the screen did.

fn set_icon(&mut self, block: BlockId, asset: &Asset, label: &'static str)

Wear the artwork as the block’s icon, left selected for repositioning. Artwork the document will not carry writes nothing, and the block itself is what stays selected.

fn place_picked_image(&mut self, asset: &Asset, label: &'static str)

Draw the artwork, left selected so the next gesture resizes it. Artwork the document will not carry — over the limit, or not an image at all — writes nothing and leaves the selection empty.

fn place_image(&mut self, asset: &Asset, label: &'static str) -> Option<ShapeId>

The drawn image itself, or None for a file that is not one. The picker knows nothing about the canvas, so where the artwork goes is decided here: centred where a paste would land, at the size the file’s own aspect gives it.

fn zoom(&mut self, step: ZoomStep)

One keyboard zoom step, about the pointer where there is one over the canvas.

fn copied(&mut self, clip: Option<Clipboard>)

Leave whatever a copy or a cut yielded on the clipboard.

impl Session

pub(crate) fn export_content( &mut self, layout: &dyn TextLayout, format: ExportFormat, selection: Option<Vec<ShapeId>>, ) -> ExportContent

What an export writes, apart from the file it is written to — so the bytes a user gets are the bytes a test can read.

fn export_source(&self, at: Rev) -> Source

What an export this session writes says about where it came from, for the fold at at.

fn export_pdf(&self, layout: &dyn TextLayout) -> ExportContent

The whole viewed document as a PDF. A failed export writes an empty file rather than taking the session down with it, and says so where the developer already is.

fn selection_repo(&mut self, shapes: &[ShapeId]) -> Option<Repo>

A standalone one-commit repo holding just the selection: copy the shapes, then paste them into a fresh empty document, whose root the block path then views. Reuses the paste pipeline (id remapping, route re-reconstruction). A repo rather than a bare document because the projection’s names come from the log. None when nothing copyable is selected.

impl Session

pub fn content_bounds<R: Renderer>(&mut self, renderer: &mut R) -> Option<Rect>

What a fit-to-content framing would frame: the extent of everything this level’s draw passes cover, measured through the backend that would draw them.

pub fn canvas_frame<C: Canvas>( &mut self, interaction: &Interaction, canvas: &mut C, ) -> Framed

One canvas frame: the gesture bracket, the ring over what the last step changed, the tool, and the escape that drops back to selection.

The pass is the tool’s gesture: everything written before the seal at the end is one commit, labelled for the tool that made it. A pass that only previewed writes nothing and seals to no commit.

impl Session

pub fn opening(doc: Doc, identity: Identity) -> Self

A session over doc, opened inside the document’s designated top block, with the undo depth the container was closed with.

pub fn resolve(&mut self, input: &Input) -> Interaction

What this frame’s pointer and keys come to for the tools, resolved against the camera the session was last shown and dated by its clock. Where the pointer is over the canvas is read off the same pass, so the two cannot disagree.

pub fn text(&mut self, event: &TextEvent)

How the front end’s editor ended, landing on the next frame’s interaction for the tool that opened it. A report on an editor the last frame did not ask for is one that has already closed.

pub fn asked_editor(&mut self, asked: Option<&EditText>)

The editor the frame’s canvas pass asked for, if any.

pub fn take_handoffs(&mut self) -> Vec<Handoff>

What the editor has to hand back — drained by the host each frame. See Handoff: the host never asks the editor for a result, so a result that took a thread to compute arrives here without the poll changing.

pub fn hovered_world(&self) -> Option<Pos2>

Where the pointer last hovered over the canvas, in world space.

pub fn clicked_world(&self) -> Option<Pos2>

Where the pointer last clicked on the canvas, in world space.

pub fn pointer_screen(&self) -> Option<Pos2>

Where the pointer is over the canvas, in screen space.

pub fn pointer_world(&self) -> Option<Pos2>

The same pointer, in world space — where the hover affordances light up.

pub(crate) fn hands_back(&mut self, handoff: Handoff)

Leave a result for the host to take.

pub(crate) fn hand_out_assets(&mut self, drawn: BTreeMap<AssetHash, Asset>)

Hand out the bytes of every asset a frame drew that the host has not been given yet.

pub fn fit_view(&mut self)

Ask for the current drawing’s contents to fill the view. Called whenever the block path changes so each navigation lands on a normalized, fully-visible view. The framing itself is taken in the next canvas pass, where the diagram can be measured; it snaps instantly, since the path changed underneath and animating across the now-different content is jarring.

pub fn take_refit(&mut self) -> Refit

Whether a fit is owed, taking it: the caller measures what the frame paints and frames the camera on it.

pub fn note_pointer(&mut self, event: Option<Event>)

Where the pointer last rested over the canvas, in world space.

fn scope_path(&self) -> ScopePath

Where this session is standing, as a row carries it: advisory, so a rev whose scope no longer exists still says where it was made.

fn standing(&mut self) -> Standing

Where this session is standing, in both spellings a row records: the ids the spotlight filters by and the names a history row’s scope line reads.

pub fn scope_names(&mut self) -> Vec<String>

The scope path, as the content path spells it.

pub fn scope_name(&mut self) -> String

The scope an edit lands in, as a label reads it — the content path’s own spelling, empty at the document root.

fn camera(&self) -> Camera

What this session is looking at, as a row carries it: the author’s own framing at the moment of the edit, which is evidence of what they were working on where a region computed from the change is only a guess.

pub fn viewing(&self) -> Viewing

Which document the canvas is showing.

pub fn viewed_repo(&self) -> &Repo

The repo the canvas draws, hit-tests, exports, and copies out of. Writes never come through here — they go to Self::doc, which is always the head.

pub fn viewed_document(&self) -> &Document

pub fn may_write(&self) -> Writability

Whether this frame may write the document at all: both the container’s answer and the time machine’s, since either alone is enough to make the canvas read-only.

pub fn theme(&self) -> &Theme

What the drawing is painted in: the roles and fonts, and the palette the front end last told.

pub(crate) fn paint_in(&mut self, palette: Palette)

Paint in palette from here on. The call that told it has already painted by the time its actions run, so the next frame is owed.

pub fn retune( &mut self, bases: impl IntoIterator<Item = (Role, Option<Base>)>, sizes: FontSizes, )

Re-point the roles and re-size the canvas fonts — what the dev editors (--theme-editor, --font-editor) author live over the tables the engine embeds. The palette is not among them.

pub fn palette(&self) -> Palette

The palette this frame paints through, drained under a lens.

pub fn chrome_color(&self, role: Role) -> Color

One of the theme’s colours, resolved through that palette — what the host paints its own chrome (the canvas ground, the grid) with, so the read-only drain cannot reach the diagram and miss the background.

pub fn document_at(&self, rev: Rev) -> Option<Document>

The document as it stood at rev. None — having said why — for a rev this session cannot show.

pub fn drawing(&mut self) -> Drawing<'_>

The current level’s drawing. Borrows all of self, so passes that also need the tool or the theme build their Drawing from the fields directly instead.

pub fn begin_gesture(&mut self, label: Label)

Open a gesture: everything written until Self::end_gesture lands in one commit under label.

The frame’s writability rides on the sink, which is how it reaches the tools: they read it back off the Drawing to decide what to offer, and the sink itself declines whatever slips past them.

pub fn end_gesture(&mut self)

pub fn submit(&mut self, commit: Commit)

The editor’s write door: whatever a gesture sealed goes to whichever home this document has, attributed to this session’s identity.

A refusal is reported and dropped rather than asserted. Two of them are reachable: a container that turned read-only under us (the canvas still drags, even though the registry withholds the editing commands), and a failed append, which has already cost the container its lock.

pub fn commit_gesture<R>( &mut self, label: Label, edit: impl FnOnce(&mut Drawing<'_>) -> R, ) -> R

Edit the current level under label and seal the result — the shape every document mutation outside the canvas pass takes.

pub fn consequences(&self) -> Consequences

What one press of undo and one of redo would do this frame — what the registry gates on and what the cluster’s tooltip says, answered once so the two cannot disagree.

pub fn step_history(&mut self, direction: Direction)

Take one step of history: restore the state the stack lands on, and walk the trail only as far as that state’s Stood asks. A step that crosses no trail position touches no log at all.

Recording stops for the rest of the frame; the restore below is the step, and reading the inverse commits it authored as fresh edits would push the step straight back onto the stack.

A step across a rename cannot rename the container itself — that is the front end’s door — so it asks for one through the call’s effects, and the stack stands under the asked-for name from here on.

pub fn walk_document(&mut self, target: Stood) -> Option<Spotlight>

Walk the trail until the document stands where target says, and say where the first step it took did its work.

Each step submits an inverse as an ordinary commit, so the log records the walk rather than erasing what it crossed. A step the trail will not take ends the walk rather than spinning: the stack has already moved, and the state fed at the end of the frame is what puts the two back in step.

The plan comes back from the first step because that is the one the press names — a walk of several is the history panel jumping, and what the hand asked to see is the near end of it.

fn where_a_step_worked(&self, against: &Document, at: Rev) -> Option<Spotlight>

The scope and world region the step at at moved: the names its row carries, measured across the step it made — against is the document it was written against, and the head is where it left things.

fn show_what_changed(&mut self, spotlight: Spotlight)

A step that moved the document lands with what it moved in sight.

The restored vantage wins wherever it is honest — it is where the hand actually stood, and a step that changed something already on screen must not jump the camera. This only aims when the region is out of sight, or in a scope the restored one is not looking at.

The scope is not optional. A change is depicted on the level it happened on, so a viewer looking at another level is being shown a drawing the step did not touch.

pub fn record_history(&mut self, before: &State, at: Duration)

Close the frame: offer the stack the state the frame ended in.

Whether that becomes an entry is the stack’s own call — its coalescing window — except for a frame that edited, which punctuates the stack either side of itself so two quick edits are still two presses.

The commits are read off the repo rather than tallied here: a frame can submit through more than one door — a gesture, a dispatched action, both — and a second tally kept by hand is the thing that drifts.

A suspended frame only feeds: the step it ran already moved the stack, and the inverse commits it authored are that step, not a new edit.

pub(crate) fn account_for_rename(&mut self)

Account for a rename the front end performed since the last frame, before the frame takes the state it starts from.

A rename the user asked for lands as an entry of its own, punctuated like an edit. One a step asked for is that step, so it lands nothing — and a door that did not rename re-pins the stack on the name the container kept, rather than reading as a rename back.

pub(crate) fn owed_rename(&self) -> Option<Effect>

The rename a history step asked for, while the container is not yet called that — the front end’s to perform.

pub fn has_step(&self, direction: Direction) -> bool

Whether the stack has a step this way, of either kind.

pub fn state(&self) -> State

The editor’s state as it stands now, for the stack to remember or compare against.

fn restore_view(&mut self, to: &State, leaving: &State)

Put the editor back where a step says it was: the scope, the camera, then the best selection the document still holds — resolved through the one selection-to-tool map, against the document as it stands after the walk, so a selection the undo just removed gives way to the next candidate rather than leaving a tool pointed at nothing.

Both ends of the step offer a selection, best first. Undoing a move puts the block back and the block is still there, so what the state being left holds is the thing that changed and showing it selected is how the undo shows its work — and mid-drag tools report no selection at all, so the state the drag started in has none. Undoing a delete restores what the delete removed, which is what the state being landed on holds.

pub fn after_navigate(&mut self)

Settle onto the level the block path now names: the selection belonged to the level we left, and the new one gets a fresh framing.

pub fn nav_select(&mut self, block: BlockId, pick: NavPick)

Select a block picked in the navigator. The tree spans the whole document, so the block may live below another level: jump the canvas to its parent diagram first (an extend can’t carry across levels, so it falls back to a plain replace there), then frame the block.

pub fn view_rev(&mut self, rev: Rev)

Put rev on the canvas. The document is cached in TimeMachine and re-read only when the selection moves.

The camera stays put where it honestly can: the point of the time machine is to watch one place in the diagram change. What it may not do is leave the viewer on a level the picked rev did not touch.

fn stand_where_it_was_made(&mut self, spotlight: Spotlight, camera: Camera)

A rev pick lands on the author’s own view: the level they were standing on, and the camera they had set when they made the change.

The view a row carries is evidence of what its author was working on, where a region computed from the change is only a guess at what mattered — so a rev made while zoomed far out replays zoomed far out.

pub fn view_head(&mut self)

Back to the writable present — which is also what clears the history panel’s selection, since the panel reads Self::viewing rather than keeping one of its own.

pub fn settle_on_viewed(&mut self)

What every change of viewed document has to settle: the selection named entities the other document may not hold, a popup hangs off that selection, and the block path may name a block that had not been drawn yet at the rev now on the canvas.

pub fn adopt(&mut self, doc: Doc) -> Doc

Take doc as the session’s document and hand back the one it displaces. The undo stack’s watermarks move with it: the incoming document’s existing commits are its past, not steps this editor took, and the name it arrives under is not a rename.

pub fn opens(&mut self, doc: Doc) -> Doc

Take doc as the session’s document and stand the editor back up around it: the scope, the derived state, the gesture, the tool, the step stack and the notices all named shapes the last document had.

A document that only moved house comes through Self::adopt instead — the view and the selection are still about it, which is the whole point of saving from inside the lens.

pub fn tag_rev(&mut self, at: Rev, name: &str, how: Tagging)

Put one of a rev’s names on at, or take one off.

Not routed through the gesture bracket: a tag is about history, not part of it, so nothing folds and the undo stack does not move.

pub fn nudge_selection(&mut self, dx: i32, dy: i32)

Arrow-key move of the current selection. Shapes shift by whole grid cells; a pin selection shifts vertically by whole slots (horizontal arrows are ignored for pins). The tool’s selection ids are unchanged, so the selection persists across repeated nudges.

pub fn paste_target(&self) -> Pos2

Where something pasted, imported or inserted lands: under the pointer where there has been one, then the last click, then the middle of the view. One answer, so the three doors cannot drop things in three different places.

fn show_landed(&mut self, landed: &[ShapeId])

Point the camera at what a paste just dropped. A paste lands at the pointer, and a group wider than the gap between the pointer and the viewport edge lands partly outside it — which is indistinguishable, from the viewer’s chair, from not having landed (G6).

pub fn paste(&mut self, text: &str)

Paste a clipboard payload, selecting what landed. A payload a pin copy made pastes by the current selection — onto a single selected child block, else onto this scope’s own boundary. Anything else pastes at the paste target.

pub fn handle_imported(&mut self, name: &str, bytes: Vec<u8>)

Add a picked PNG or SVG to the current view at the paste target, as its own gesture, so an import is one commit and undoes like any edit.

pub fn handle_embedded(&mut self, name: &str, bytes: &[u8])

Embed a document as a block of this one, at the paste target, as its own gesture — so an embed is one commit and undoes like any edit.

A copy: nothing records where the block came from, and editing the source afterwards does not touch it. The block is named after the file, the arriving drawing carrying no name of its own.

pub fn available_commands(&mut self, current_lock: InterfaceLock) -> CommandSet

What the user can invoke this frame. One place, so the chrome, the chords, and the palette cannot disagree — and so a test can ask the registry the same question the toolbar does.

pub fn current_lock(&mut self) -> InterfaceLock

The lock the interface stands under right now — what the registry gates the editing commands on.

pub fn window_title(&self, opened: Option<&str>) -> String

The window title: what was opened, and where the edits are going. An attached container names itself and says when it cannot be written; a scratch session keeps its “nothing persisted” marker, which is the literal truth about it. opened is the file a scratch document came from — the one fact about the title that belongs to the platform rather than the document.

No dirty marker, deliberately: the log is written before an edit returns, and the projection keeps itself fresh — a staleness indicator would read as “unsaved changes”, of which there are none.

pub fn document_name(&self, opened: Option<&str>) -> String

What the document is called, for the workspace key and an export’s file name. opened is the scratch document’s source file, if any.

pub fn ticks(&mut self, tick: Tick)

Tell the session what time it is — where crate::Event::Tick lands, read before anything polls an easing.

A tick that states no prediction of the next frame’s length is given the interval since the last one, so a front end that knows only what time it is animates the way a host reading its own frame history does.

pub fn now(&self) -> Duration

The frame clock: monotonic since the host started.

pub fn tick(&self) -> Tick

pub fn request_repaint(&mut self)

Ask for another frame as soon as the host can give one.

fn repaint_after(&mut self, after: Duration)

pub fn take_repaint(&mut self) -> Option<Duration>

The soonest another frame was asked for since this was last drained.

pub(crate) fn asked_repaint(&mut self, after: Option<Duration>)

Fold in what one canvas frame asked for.