blockworx_kernel/

session.rs

//! Everything the editor is, apart from the surface it is shown on.
//!
//! [`Session`] holds the document and the state derived beside it — where the
//! editor is standing, what is selected, what one undo would take back, what
//! the last step lit up. Every method here is a write path a front end can
//! reach without naming a toolkit: the gesture bracket, the history walk, the
//! command registry, and the document-scoped half of [`Action`](blockworx_tools::tool::Action) dispatch.

use core::time::Duration;
use std::{
    cell::RefCell,
    collections::{BTreeMap, BTreeSet},
    rc::Rc,
};

use blockworx_doc::{
    block_model::Asset,
    document::{DocIndex, Document},
    hash::AssetHash,
    id::BlockId,
    repo::Repo,
    rev::Rev,
};
use blockworx_editor::{
    edit::{describe::Label, naming::InterfaceLock},
    gesture::Gesture,
    import,
    path::{BlockPath, Scope},
    presentation::Presentation,
    shape::ShapeId,
    widget::{drawing::Drawing, spatial::CachedIndex},
};
use blockworx_geom::{
    Pos2, Rect,
    grid::{GRID_SIZE, px_rect},
    vec2,
};
use blockworx_paint::{
    Base, Easing, EditId, EditText, Interaction, Palette, Saturation, TextEvent, TextOutcome, Tick,
    Vantage,
    theme::{FontSizes, Role, Theme},
};
use blockworx_store::{
    Refusal,
    doc::{Doc, Viewing, Writability},
    record::Identity,
};
use blockworx_tools::{
    SelectTool,
    commands::{CommandContext, CommandSet, Effect},
    history::{self, Direction},
    multi_pin_select::MultiPinSelect,
    multi_select::MultiSelect,
    spotlight::{self, Spotlight, Spotlighter},
    tool::{Deletable, Tool, ToolTrait},
};

use crate::{
    camera::{Camera, CameraWork, Glide, Refit},
    export::Sheet,
    handoff::Handoff,
};

/// How big an imported image lands, measured in grid cells along its longer
/// side.
const IMPORTED_IMAGE_CELLS: f32 = 8.0;

/// Where the editor is standing, owned: the scope's ids and the names they
/// are spelled as. Resolving the names borrows the document index that a
/// row's other fields are read out of, so a call site takes this first and
/// lends it to the attribution afterwards.
struct Standing {
    path: blockworx_store::record::ScopePath,
    names: Vec<String>,
}

impl Standing {
    fn borrowed(&self) -> blockworx_store::record::Standing<'_> {
        blockworx_store::record::Standing::new(&self.path, &self.names)
    }
}

/// A past rev on the canvas: the rev, and the log prefix folded to it.
///
/// The fold lives in here rather than beside a flag, so it is minted exactly
/// when the selection moves and can never be the wrong rev's. A fresh fold
/// mints a fresh `DocStamp`, so every derived cache beside the document — the
/// index, the presentation, the spatial tree — rebuilds against it without
/// being told which document it is looking at.
pub struct TimeMachine {
    at: Rev,
    folded: Box<Repo>,
}

impl TimeMachine {
    pub(crate) fn repo(&self) -> &Repo {
        &self.folded
    }
}

/// What the two history buttons stand over this frame: which entry each would
/// take, and what taking it costs the log. `None` is an empty stack, which
/// draws the button dead rather than hiding it.
#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Consequences {
    pub undo: Option<history::Consequence>,
    pub redo: Option<history::Consequence>,
}

impl Consequences {
    pub fn history(&self) -> blockworx_tools::commands::History {
        blockworx_tools::commands::History {
            undo: self.undo.as_ref().map(|of| of.kind),
            redo: self.redo.as_ref().map(|of| of.kind),
        }
    }
}

/// Whether a navigator pick replaces the selection or joins it.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum NavPick {
    Replace,
    Extend,
}

impl From<bool> for NavPick {
    fn from(extend: bool) -> Self {
        if extend { Self::Extend } else { Self::Replace }
    }
}

/// What the frame draws over the diagram for the author's own benefit, toggled
/// from the palette and `Off` by default — this is dev tooling with no place
/// in a diagram somebody is reading.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum Diagnostic {
    #[default]
    Off,
    /// The regional router as it sees the selection: what the selection raises
    /// into the foreground, the bound a gesture on it heals in, and the lattice
    /// the router builds inside that bound.
    RegionalRouter,
}

impl Diagnostic {
    #[must_use]
    pub fn toggled(self) -> Self {
        match self {
            Self::Off => Self::RegionalRouter,
            Self::RegionalRouter => Self::Off,
        }
    }
}

/// Whether the front end shows its frame-rate readout. The kernel keeps the
/// switch, since the palette's commands are its own; the numbers are the host's,
/// which is the side of the call with a clock.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default, serde::Serialize, serde::Deserialize)]
pub enum FrameRate {
    #[default]
    Hidden,
    Shown,
}

impl FrameRate {
    #[must_use]
    pub fn toggled(self) -> Self {
        match self {
            Self::Hidden => Self::Shown,
            Self::Shown => Self::Hidden,
        }
    }
}

/// What the record at `rev` is called — how the undo and redo buttons name
/// the step they stand over.
pub fn step_label(doc: &Doc, rev: Option<Rev>) -> Option<&str> {
    doc.label_at(rev?)
}

/// What a lens does to the palette: the past is drained of colour, so a rev on
/// the canvas cannot be mistaken for the writable present.
pub fn saturation(viewing: Viewing) -> Saturation {
    match viewing {
        Viewing::Head => Saturation::Full,
        Viewing::Past(_) => Saturation::Drained,
    }
}

/// The repo the canvas reads: the document's own, or the prefix fold the time
/// machine is holding. A free function over the two fields rather than a
/// method, so the passes that also need `&mut` on the index, the presentation,
/// or the gesture can still split the borrow.
pub fn viewed<'a>(doc: &'a Doc, time_machine: Option<&'a TimeMachine>) -> &'a Repo {
    match time_machine {
        None => doc.repo(),
        Some(past) => &past.folded,
    }
}

/// The tool a set of freshly-landed shapes is left selected in.
fn select_shapes(shapes: Vec<ShapeId>) -> Tool {
    if shapes.is_empty() {
        Tool::Select(SelectTool)
    } else {
        Tool::MultiSelect(MultiSelect::Selected { shapes })
    }
}

/// The editor, minus its surface.
pub struct Session {
    /// 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.
    pub doc: Doc,
    /// Who this session's commits are attributed to. The shell restores it
    /// from the preferences; what it is used for is entirely here.
    pub identity: Identity,
    /// Where the editor is looking. The scope being edited is the path's last
    /// segment (`Scope::Root` at the document root).
    pub path: BlockPath,
    /// The index over the repo's document, kept across frames and rebuilt
    /// only when a commit lands (`DocIndex::view`).
    pub doc_index: DocIndex,
    /// The gesture in progress: its ops and the prediction they imply.
    pub gesture: Gesture,
    /// One step back, for the user: document edits and the view steps between
    /// them, interleaved.
    pub undo_stack: history::UndoStack,
    /// 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.
    pub recorded_through: Rev,
    /// Suspended for the rest of a frame that ran an undo or a redo, whose
    /// restore must not be recorded as a fresh step.
    pub recording: history::Recording,
    /// 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.
    naming: history::Naming,
    /// How the editor arrived where it stands — what one undo would take
    /// back, in the words its tooltip names.
    pub moved: history::Moved,
    /// The ring over what the last document step changed, while one is up.
    pub spotlight: Spotlighter,
    /// The roles and fonts are the engine's own; the palette is the one the
    /// front end last told it
    /// ([`Action::SetPalette`](blockworx_tools::tool::Action::SetPalette)).
    pub(crate) theme: Theme,
    /// The document's derived state — solver geometry, measurement caches,
    /// propagated accents.
    pub presentation: Presentation,
    /// Spatial index over the current level's hittables, shared by viewport
    /// culling and hit-testing.
    pub spatial: CachedIndex,
    pub tool: Tool,
    /// The past rev on the canvas, folded — the time machine. `None` at head,
    /// which is where an ordinary session stays.
    pub time_machine: Option<TimeMachine>,
    /// 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.
    pub easing: Rc<RefCell<Easing>>,
    pub diagnostic: Diagnostic,
    pub frame_rate: FrameRate,
    /// 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.
    pub(crate) camera: Camera,
    /// Where the pointer is over the canvas, in screen space, as the last
    /// [`Self::resolve`] left it.
    pointer_at: Option<Pos2>,
    refit: Refit,
    tick: Tick,
    repaint: Option<Duration>,
    /// What the editor has to hand back, until the host takes it.
    handoffs: Vec<Handoff>,
    /// The artwork whose bytes have already crossed to the host: a hash in
    /// here is one the host can draw without being told again.
    sent_assets: BTreeSet<AssetHash>,
    /// What an export of this session says about itself beyond the document —
    /// stated by the host, the way the camera and the clock are.
    pub sheet: Sheet,
    /// Last world-space pointer hover over the canvas, used as the preferred
    /// paste target so a pasted group lands under the cursor.
    last_hover_world: Option<Pos2>,
    /// Last world-space click over the canvas, used as the paste target when
    /// no hover position is available.
    last_click_world: Option<Pos2>,
    /// The failures this session has owned up to, and the user has not yet
    /// acknowledged.
    pub failures: crate::chrome::Notices,
    /// The pointer between frames: the press being held, the click a second
    /// one could double.
    pointer: crate::pointer::Resolver,
    /// The in-place editor the last frame asked for, which is the one the
    /// front end's field can be reporting on.
    editor: Option<EditId>,
    /// How that editor ended since the last frame, landing on the next
    /// frame's interaction.
    text_outcome: Option<TextOutcome>,
}

impl Session {
    /// A session over `doc`, opened inside the document's designated top
    /// block, with the undo depth the container was closed with.
    pub fn opening(doc: Doc, identity: Identity) -> Self {
        let path = BlockPath::opening(doc.document());
        let vantage = Vantage::resting();
        let undo_stack = history::UndoStack::reconstructed(
            doc.trail(),
            &history::State {
                camera: vantage,
                scope: path.clone(),
                stood: history::Stood::of(doc.trail()),
                named: doc.container_name(),
                moved: history::Moved::default(),
                selection: None,
            },
        );
        Self {
            recorded_through: doc.repo().rev(),
            naming: history::Naming::Settled(doc.container_name()),
            doc,
            identity,
            path,
            doc_index: DocIndex::default(),
            gesture: Gesture::idle(),
            undo_stack,
            recording: history::Recording::default(),
            moved: history::Moved::default(),
            spotlight: Spotlighter::default(),
            theme: Theme::from_embedded(),
            presentation: Presentation::default(),
            spatial: CachedIndex::default(),
            tool: Tool::Select(SelectTool),
            time_machine: None,
            easing: Rc::new(RefCell::new(Easing::default())),
            diagnostic: Diagnostic::default(),
            frame_rate: FrameRate::default(),
            camera: Camera::resting(),
            pointer_at: None,
            refit: Refit::Idle,
            tick: Tick::at(Duration::ZERO),
            repaint: None,
            handoffs: Vec::new(),
            sent_assets: BTreeSet::new(),
            sheet: Sheet::default(),
            last_hover_world: None,
            last_click_world: None,
            failures: crate::chrome::Notices::default(),
            pointer: crate::pointer::Resolver::default(),
            editor: None,
            text_outcome: None,
        }
    }

    /// 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 resolve(&mut self, input: &blockworx_paint::Input) -> Interaction {
        let mut interaction =
            self.pointer
                .resolve(input, self.now(), self.vantage(), self.viewport().min);
        interaction.text = self.text_outcome.take();
        self.pointer_at = self.pointer.latest();
        interaction
    }

    // ── The in-place editor ────────────────────────────────────────────────

    /// 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 text(&mut self, event: &TextEvent) {
        if self.editor == Some(event.id()) {
            self.text_outcome = Some(event.clone().outcome());
        }
    }

    /// The editor the frame's canvas pass asked for, if any.
    pub fn asked_editor(&mut self, asked: Option<&EditText>) {
        self.editor = asked.map(|edit| edit.id);
    }

    /// 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 take_handoffs(&mut self) -> Vec<Handoff> {
        std::mem::take(&mut self.handoffs)
    }

    /// Where the pointer last hovered over the canvas, in world space.
    pub fn hovered_world(&self) -> Option<Pos2> {
        self.last_hover_world
    }

    /// Where the pointer last clicked on the canvas, in world space.
    pub fn clicked_world(&self) -> Option<Pos2> {
        self.last_click_world
    }

    /// Where the pointer is over the canvas, in screen space.
    pub fn pointer_screen(&self) -> Option<Pos2> {
        self.pointer_at
    }

    /// The same pointer, in world space — where the hover affordances light
    /// up.
    pub fn pointer_world(&self) -> Option<Pos2> {
        self.pointer_at.map(|p| self.screen_to_world(p))
    }

    /// Leave a result for the host to take.
    pub(crate) fn hands_back(&mut self, handoff: Handoff) {
        self.handoffs.push(handoff);
    }

    /// Hand out the bytes of every asset a frame drew that the host has not
    /// been given yet.
    pub(crate) fn hand_out_assets(&mut self, drawn: BTreeMap<AssetHash, Asset>) {
        for (hash, asset) in drawn {
            if self.sent_assets.insert(hash) {
                self.hands_back(Handoff::Asset { hash, asset });
            }
        }
    }

    /// 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 fit_view(&mut self) {
        self.refit = Refit::Owed;
        self.moved = history::Moved::Fit;
    }

    /// Whether a fit is owed, taking it: the caller measures what the frame
    /// paints and frames the camera on it.
    pub fn take_refit(&mut self) -> Refit {
        std::mem::replace(&mut self.refit, Refit::Idle)
    }

    /// Where the pointer last rested over the canvas, in world space.
    pub fn note_pointer(&mut self, event: Option<blockworx_paint::Event>) {
        match event {
            Some(blockworx_paint::Event::HoverAt(p)) => self.last_hover_world = Some(p),
            Some(blockworx_paint::Event::Clicked { pos }) => self.last_click_world = Some(pos),
            _ => {}
        }
    }

    // ── What the session is looking at ─────────────────────────────────────

    /// 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 scope_path(&self) -> blockworx_store::record::ScopePath {
        self.path.segments().iter().copied().collect()
    }

    /// 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.
    fn standing(&mut self) -> Standing {
        Standing {
            path: self.scope_path(),
            names: self.scope_names(),
        }
    }

    /// The scope path, as the content path spells it.
    pub fn scope_names(&mut self) -> Vec<String> {
        let doc = viewed(&self.doc, self.time_machine.as_ref()).document();
        blockworx_tools::content_path::segments(&self.doc_index.view(doc), &self.path)
    }

    /// The scope an edit lands in, as a label reads it — the content path's
    /// own spelling, empty at the document root.
    pub fn scope_name(&mut self) -> String {
        let doc = viewed(&self.doc, self.time_machine.as_ref()).document();
        blockworx_tools::content_path::to_string(&self.doc_index.view(doc), &self.path)
    }

    /// 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.
    fn camera(&self) -> blockworx_store::record::Camera {
        crate::recorded_camera(self.vantage(), self.viewport().size())
    }

    /// Which document the canvas is showing.
    pub fn viewing(&self) -> Viewing {
        match &self.time_machine {
            None => Viewing::Head,
            Some(past) => Viewing::Past(past.at),
        }
    }

    /// 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_repo(&self) -> &Repo {
        viewed(&self.doc, self.time_machine.as_ref())
    }

    pub fn viewed_document(&self) -> &Document {
        self.viewed_repo().document()
    }

    /// 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 may_write(&self) -> Writability {
        match (self.doc.writability(), self.viewing().writability()) {
            (Writability::Writable, Writability::Writable) => Writability::Writable,
            _ => Writability::ReadOnly,
        }
    }

    /// What the drawing is painted in: the roles and fonts, and the palette
    /// the front end last told.
    pub fn theme(&self) -> &Theme {
        &self.theme
    }

    /// 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(crate) fn paint_in(&mut self, palette: Palette) {
        self.theme.set_palette(palette);
        self.repaint_after(Duration::ZERO);
    }

    /// 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 retune(
        &mut self,
        bases: impl IntoIterator<Item = (Role, Option<Base>)>,
        sizes: FontSizes,
    ) {
        for (role, base) in bases {
            self.theme.set_base(role, base);
        }
        self.theme.set_font_sizes(sizes);
    }

    /// The palette this frame paints through, drained under a lens.
    pub fn palette(&self) -> Palette {
        self.theme.palette().toned(saturation(self.viewing()))
    }

    /// 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 chrome_color(&self, role: Role) -> blockworx_paint::Color {
        self.palette().resolve(self.theme.swatch(role))
    }

    /// The document as it stood at `rev`. `None` — having said why — for a
    /// rev this session cannot show.
    pub fn document_at(&self, rev: Rev) -> Option<Document> {
        let _span = tracing::info_span!("read_rev", rev = rev.get()).entered();
        self.doc
            .document_at(rev)
            .inspect_err(|why| tracing::error!("{why}"))
            .ok()
    }

    // ── The write door ─────────────────────────────────────────────────────

    /// 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 drawing(&mut self) -> Drawing<'_> {
        blockworx_editor::gesture::drawing(
            viewed(&self.doc, self.time_machine.as_ref()),
            &mut self.doc_index,
            &self.path,
            &mut self.presentation,
            &mut self.gesture,
        )
    }

    /// 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 begin_gesture(&mut self, label: Label) {
        debug_assert!(
            self.gesture.ops().is_empty(),
            "a gesture was left open — every begin_gesture is matched by an end_gesture",
        );
        self.gesture = Gesture::open(label, self.may_write());
    }

    #[tracing::instrument(level = "info", skip_all)]
    pub fn end_gesture(&mut self) {
        let sealed = blockworx_editor::gesture::seal(
            viewed(&self.doc, self.time_machine.as_ref()).document(),
            &mut self.doc_index,
            &self.path,
            &self.presentation,
            &mut self.gesture,
        );
        if let Some(sealed) = sealed {
            self.submit(sealed.commit);
            // The gesture knows what it disturbed, so the wires outside that
            // rectangle are drawn from geometry nothing moved near. Bringing
            // the rest up to date here leaves the next borrow's stamp gate
            // with nothing to do; a gesture that could not say what it reached
            // leaves the gate to re-derive the document, as it always has.
            if let Some(disturbed) = sealed.disturbed {
                let indexed = {
                    let _s = tracing::info_span!("doc_index").entered();
                    self.doc_index
                        .view(viewed(&self.doc, self.time_machine.as_ref()).document())
                };
                self.presentation
                    .reconstruct_within(&indexed, &self.path, disturbed);
            }
        }
    }

    /// 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.
    #[tracing::instrument(level = "info", skip_all)]
    pub fn submit(&mut self, commit: blockworx_doc::commit::Commit) {
        // The canvas keeps dragging in a read-only session — the registry
        // withholds the commands, not the pointer — so a gesture can still
        // seal here. While the time machine is open it would be worse than
        // refused: the ops were built against a past rev, and the head they
        // would land on is not what the user is looking at.
        if self.may_write() == Writability::ReadOnly {
            tracing::debug!("a read-only session sealed a gesture; it is not recorded");
            return;
        }
        let standing = self.standing();
        let camera = self.camera();
        let by = blockworx_store::record::Attribution {
            author: &self.identity,
            standing: standing.borrowed(),
            camera,
        };
        match self.doc.submit(commit, by) {
            Ok(_) => {}
            Err(Refusal::Fold(refusal)) => {
                // Unreachable by construction: the emitters read the same
                // document the fold will judge the commit against. Mirrored
                // rather than asserted — dying over a broken invariant would
                // cost the user the drawing.
                tracing::error!("the document refused a gesture built on its own head: {refusal}");
            }
            Err(refusal) => tracing::warn!("the edit was not recorded: {refusal}"),
        }
    }

    /// Edit the current level under `label` and seal the result — the shape
    /// every document mutation outside the canvas pass takes.
    pub fn commit_gesture<R>(
        &mut self,
        label: Label,
        edit: impl FnOnce(&mut Drawing<'_>) -> R,
    ) -> R {
        self.begin_gesture(label);
        let edited = edit(&mut self.drawing());
        self.end_gesture();
        edited
    }

    // ── History ────────────────────────────────────────────────────────────

    /// 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 consequences(&self) -> Consequences {
        let now = self.state();
        let of = |direction| {
            let target = self.undo_stack.peek(direction, &now)?;
            let kind = history::Kind::of_step(&now, &target);
            // A step is named by the move that reaches its later state, which
            // going back is the state being left.
            let (earlier, later) = match direction {
                Direction::Back => (&target, &now),
                Direction::Forward => (&now, &target),
            };
            let named = match kind {
                history::Kind::View => later.moved.label().to_owned(),
                history::Kind::Rename => earlier.rename_to(later)?.label(),
                history::Kind::Doc => {
                    let trail = self.doc.trail();
                    let commit = match direction {
                        Direction::Back => trail.next_undo(),
                        Direction::Forward => trail.next_redo(),
                    };
                    step_label(&self.doc, commit).unwrap_or_default().to_owned()
                }
            };
            Some(history::Consequence {
                target: named,
                kind,
            })
        };
        Consequences {
            undo: of(Direction::Back),
            redo: of(Direction::Forward),
        }
    }

    /// Take one step of history: restore the state the stack lands on, and
    /// walk the trail only as far as that state's [`Stood`](history::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 step_history(&mut self, direction: Direction) {
        let now = self.state();
        let Some(target) = self.undo_stack.peek(direction, &now) else {
            return;
        };
        // Under the lens, and on a container this session may not write, undo
        // still serves view entries — a camera move costs the log nothing.
        // Checked here as well as in the registry, so a step asked for
        // outright rather than through it cannot slip past.
        if history::Kind::of_step(&now, &target).writes()
            && self.may_write() == Writability::ReadOnly
        {
            return;
        }
        let Some(target) = self.undo_stack.step(direction, &now) else {
            return;
        };
        self.recording = history::Recording::Suspended;
        if let Some(rename) = now.rename_to(&target) {
            self.naming = history::Naming::Asked(rename.to.clone());
        }
        let changed = self.walk_document(target.stood);
        self.restore_view(&target, &now);
        if let Some(spotlight) = changed {
            self.show_what_changed(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.
    pub fn walk_document(&mut self, target: history::Stood) -> Option<Spotlight> {
        let standing = self.standing();
        let camera = self.camera();
        let mut changed = None;
        while history::Stood::of(self.doc.trail()) != target {
            let here = history::Stood::of(self.doc.trail());
            let by = blockworx_store::record::Attribution {
                author: &self.identity,
                standing: standing.borrowed(),
                camera,
            };
            // The inverse is written against the document as it stands now,
            // which is what the spotlight reads its footprints off — so it is
            // taken before the step, not after.
            let against = self.doc.document().clone();
            let stepped = if here > target {
                self.doc
                    .trail()
                    .next_undo()
                    .map(|commit| self.doc.undo(commit, by))
            } else {
                self.doc
                    .trail()
                    .next_redo()
                    .map(|commit| self.doc.redo(commit, by))
            };
            match stepped {
                Some(Ok(at)) if history::Stood::of(self.doc.trail()) != here => {
                    changed = changed.or_else(|| self.where_a_step_worked(&against, at));
                }
                Some(Ok(_)) => {
                    tracing::error!("a history step left the document where it was");
                    return changed;
                }
                Some(Err(refusal)) => {
                    tracing::debug!("the trail would not take the step: {refusal}");
                    return changed;
                }
                None => {
                    tracing::debug!("the trail no longer holds the step the stack asked for");
                    return changed;
                }
            }
        }
        changed
    }

    /// 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 where_a_step_worked(&self, against: &Document, at: Rev) -> Option<Spotlight> {
        let worked = self.doc.worked_at(at)?;
        spotlight::worked(
            spotlight::Step {
                before: against,
                after: self.doc.document(),
            },
            &self.presentation.routes,
            &worked,
        )
    }

    /// 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.
    fn show_what_changed(&mut self, spotlight: Spotlight) {
        let Some(path) = BlockPath::showing(self.viewed_document(), spotlight.scope) else {
            return;
        };
        self.spotlight.light(self.now(), spotlight);
        self.request_repaint();
        let region = px_rect(spotlight.region);
        if self.path == path {
            self.bring_into_view(region, Glide::Snap);
        } else {
            self.path = path;
            self.after_navigate();
            // The arrival owes the level a fit; this framing *is* the
            // arrival, and letting the fit land would show the level rather
            // than the change.
            self.refit = Refit::Idle;
            self.focus_on(region, Glide::Snap);
        }
        self.moved = history::Moved::Focus;
    }

    /// 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 fn record_history(&mut self, before: &history::State, at: Duration) {
        let submitted = self.doc.repo().revs_after(self.recorded_through);
        self.recorded_through = self.doc.repo().rev();
        if self.recording == history::Recording::Suspended {
            self.recording = history::Recording::On;
            let now = self.state();
            self.undo_stack.landed(&now);
            debug_assert_eq!(
                now.stood,
                history::Stood::of(self.doc.trail()),
                "the state fed back does not stand where the trail does",
            );
            return;
        }
        if self.camera.worked == CameraWork::Worked {
            self.moved = history::Moved::Camera;
            self.camera.worked = CameraWork::Idle;
        }
        if !submitted.is_empty() {
            self.moved = history::Moved::Edit;
        }
        let now = self.state();
        if submitted.is_empty() {
            self.undo_stack.feed(at, &now);
        } else {
            self.undo_stack.edited(at, before, &now);
        }
    }

    /// 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 account_for_rename(&mut self) {
        let called = self.doc.container_name();
        let accounted =
            std::mem::replace(&mut self.naming, history::Naming::Settled(called.clone()));
        match accounted {
            history::Naming::Asked(asked) => {
                if called.as_ref() != Some(&asked) {
                    let now = self.state();
                    self.undo_stack.landed(&now);
                }
            }
            history::Naming::Settled(was) => {
                let before = history::State {
                    named: was,
                    ..self.state()
                };
                let now = history::State {
                    moved: history::Moved::Rename,
                    ..self.state()
                };
                if before.rename_to(&now).is_some() {
                    self.moved = now.moved;
                    let at = self.now();
                    self.undo_stack.edited(at, &before, &now);
                }
            }
        }
    }

    /// The rename a history step asked for, while the container is not yet
    /// called that — the front end's to perform.
    pub(crate) fn owed_rename(&self) -> Option<Effect> {
        match &self.naming {
            history::Naming::Asked(to) if self.doc.container_name().as_ref() != Some(to) => {
                Some(Effect::RenameDocument(to.as_str().to_owned()))
            }
            history::Naming::Asked(_) | history::Naming::Settled(_) => None,
        }
    }

    /// Whether the stack has a step this way, of either kind.
    pub fn has_step(&self, direction: Direction) -> bool {
        self.undo_stack.peek(direction, &self.state()).is_some()
    }

    /// The editor's state as it stands now, for the stack to remember or
    /// compare against.
    pub fn state(&self) -> history::State {
        history::State {
            camera: self.vantage(),
            scope: self.path.clone(),
            stood: history::Stood::of(self.doc.trail()),
            named: self.naming.stands_under().cloned(),
            moved: self.moved,
            selection: self.tool.selection().map(|what| history::Selection {
                what,
                anchor: self.tool.overlay_anchor(),
            }),
        }
    }

    /// 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.
    fn restore_view(&mut self, to: &history::State, leaving: &history::State) {
        if self.path != to.scope {
            self.path = to.scope.clone();
            self.after_navigate();
        }
        self.stand_at(to.camera);
        // `after_navigate` owes the drawing a fit; the camera this step
        // restores *is* the framing, and letting the fit land would walk the
        // camera off the state the stack believes it reached.
        self.refit = Refit::Idle;
        let candidates: Vec<&history::Selection> = leaving
            .selection
            .iter()
            .chain(to.selection.iter())
            .collect();
        let tool = {
            let drawing = self.drawing();
            history::tool_for(&drawing, &candidates)
        };
        self.tool = tool;
        self.moved = to.moved;
    }

    // ── Navigation ─────────────────────────────────────────────────────────

    /// 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 after_navigate(&mut self) {
        self.tool = Tool::Select(SelectTool);
        self.fit_view();
        // The fit is part of arriving, not a move of its own, so the entry
        // this leaves is named for the arrival.
        self.moved = history::Moved::Scope;
    }

    /// 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 nav_select(&mut self, block: BlockId, pick: NavPick) {
        let path_to = BlockPath::to_parent_of(self.viewed_document(), block);
        let same_level = path_to.as_ref() == Some(&self.path);
        if let Some(path) = path_to
            && !same_level
        {
            self.path = path;
        }
        let shape = ShapeId::Rect(block);
        let base = match (pick, same_level) {
            (NavPick::Extend, true) => self
                .tool
                .selection()
                .and_then(|d| d.shapes())
                .unwrap_or_default(),
            _ => Vec::new(),
        };
        self.tool = blockworx_tools::select_tool::extend_with_shape(&base, shape);
        let world = self.drawing().shape(shape).map(|s| s.gui_rect());
        if let Some(world) = world {
            self.focus_on(world, Glide::Eased);
            self.moved = history::Moved::Focus;
        }
    }

    /// 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.
    pub fn view_rev(&mut self, rev: Rev) {
        if self.viewing() == Viewing::Past(rev) {
            return;
        }
        let worked = self.doc.worked_at(rev);
        // Two documents: the rev being viewed, and the one before it. The
        // spotlight needs both ends — a delete's subject stands only in the
        // departure.
        let (Some(previous), Some(after)) = (rev.prev(), self.document_at(rev)) else {
            return;
        };
        let Some(before) = self.document_at(previous) else {
            return;
        };
        let spotlight = worked.and_then(|worked| {
            spotlight::worked(
                spotlight::Step {
                    before: &before,
                    after: &after,
                },
                &self.presentation.routes,
                &worked,
            )
        });
        self.time_machine = Some(TimeMachine {
            at: rev,
            folded: Box::new(Repo::at(after)),
        });
        self.settle_on_viewed();
        if let Some(spotlight) = spotlight {
            match self.doc.camera_at(rev) {
                Some(camera) => self.stand_where_it_was_made(spotlight, camera),
                None => self.show_what_changed(spotlight),
            }
        }
    }

    /// 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.
    fn stand_where_it_was_made(
        &mut self,
        spotlight: Spotlight,
        camera: blockworx_store::record::Camera,
    ) {
        let Some(path) = BlockPath::showing(self.viewed_document(), spotlight.scope) else {
            return;
        };
        self.spotlight.light(self.now(), spotlight);
        self.request_repaint();
        if self.path != path {
            self.path = path;
            self.after_navigate();
        }
        // The arrival owes the level a fit; the recorded camera *is* the
        // arrival, and letting the fit land would show the level rather than
        // where its author stood.
        self.refit = Refit::Idle;
        let stood = crate::vantage_of(camera, self.viewport().size());
        self.stand_at(stood);
        self.moved = history::Moved::Focus;
    }

    /// 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 view_head(&mut self) {
        if self.time_machine.take().is_some() {
            self.settle_on_viewed();
        }
    }

    /// 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 settle_on_viewed(&mut self) {
        self.tool = Tool::Select(SelectTool);
        if !self.path.is_held_by(self.viewed_document()) {
            self.path = BlockPath::opening(self.viewed_document());
            self.fit_view();
        }
    }

    /// 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 adopt(&mut self, doc: Doc) -> Doc {
        self.recorded_through = doc.repo().rev();
        self.naming = history::Naming::Settled(doc.container_name());
        // A rev of the outgoing document's log names nothing in the incoming
        // one.
        self.time_machine = None;
        std::mem::replace(&mut self.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 opens(&mut self, doc: Doc) -> Doc {
        let was = self.adopt(doc);
        self.path = BlockPath::opening(self.doc.document());
        self.presentation = Presentation::default();
        self.gesture = Gesture::idle();
        // The steps on the old stack name revs of a trail this document does
        // not have; the new one's trail is what it stands ready to invert,
        // which for a reopened container is everything it was closed with.
        self.undo_stack = history::UndoStack::reconstructed(self.doc.trail(), &self.state());
        self.tool = Tool::Select(SelectTool);
        // The failures were about the document that just left.
        self.failures.forget();
        self.fit_view();
        was
    }

    /// 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 tag_rev(&mut self, at: Rev, name: &str, how: blockworx_store::tags::Tagging) {
        let standing = self.standing();
        let camera = self.camera();
        let by = blockworx_store::record::Attribution {
            author: &self.identity,
            standing: standing.borrowed(),
            camera,
        };
        if let Err(refusal) = self.doc.tag(at, name, how, by) {
            tracing::warn!("rev {} was not tagged: {refusal}", at.get());
        }
    }

    // ── Editing ────────────────────────────────────────────────────────────

    /// 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.
    #[tracing::instrument(level = "info", skip_all)]
    pub fn nudge_selection(&mut self, dx: i32, dy: i32) {
        let Some(sel) = self.tool.selection() else {
            return;
        };
        let delta = vec2(dx as f32 * GRID_SIZE, dy as f32 * GRID_SIZE);
        match sel {
            Deletable::Shape(id) => {
                self.commit_gesture(Label::verb("Nudge"), |d| d.move_shape(id, delta));
            }
            Deletable::Shapes(ids) => {
                self.commit_gesture(Label::verb("Nudge"), |d| d.move_shapes(&ids, delta));
            }
            Deletable::Pins(anchors) if dy != 0 => {
                self.commit_gesture(Label::verb("Nudge"), |d| d.nudge_pins(&anchors, dy));
            }
            Deletable::Pins(_) | Deletable::Route(_) => {}
        }
    }

    /// 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.
    pub fn paste_target(&self) -> Pos2 {
        self.last_hover_world
            .or(self.last_click_world)
            .unwrap_or_else(|| {
                let viewport = self.viewport();
                if viewport.is_positive() {
                    self.vantage()
                        .screen_to_world(viewport.min, viewport.center())
                } else {
                    (-self.vantage().translation / self.vantage().zoom.get()).to_pos2()
                }
            })
    }

    /// 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).
    fn show_landed(&mut self, landed: &[ShapeId]) {
        let Some(bounds) = landed
            .iter()
            .filter_map(|&id| Some(self.drawing().shape(id)?.gui_rect()))
            .reduce(Rect::union)
        else {
            return;
        };
        self.bring_into_view(bounds, Glide::Eased);
    }

    /// 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 paste(&mut self, text: &str) {
        let Some(clip) = blockworx_editor::edit::clipboard::Clipboard::from_json(text) else {
            return;
        };
        let into = self.doc.session();
        if !clip.is_pin_paste() {
            let target = Some(self.paste_target());
            // Pasted images carry their own payload; the painter registers
            // sources lazily on first draw, so nothing to pre-register here.
            let shapes = self.commit_gesture(Label::verb("Paste"), |d| {
                d.paste_snapshot(&clip, into, target)
            });
            self.show_landed(&shapes);
            self.tool = select_shapes(shapes);
            return;
        }
        let target_block = match self.tool.selection().and_then(|d| d.shapes()) {
            Some(shapes) if shapes.len() == 1 => shapes[0].block(),
            _ => None,
        };
        let owner = target_block.map_or_else(|| self.path.scope(), Scope::Block);
        let pins = self.commit_gesture(Label::verb("Paste"), |d| {
            d.paste_pins(clip.snapshot(), owner)
        });
        self.tool = if pins.is_empty() {
            Tool::Select(SelectTool)
        } else if target_block.is_some() {
            Tool::MultiPinSelect(MultiPinSelect::Selected { pins })
        } else {
            select_shapes(pins.into_iter().map(ShapeId::Port).collect())
        };
    }

    /// 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_imported(&mut self, name: &str, bytes: Vec<u8>) {
        let target = self.paste_target();
        let Some(asset) = import::interpret(name, bytes) else {
            tracing::warn!("Unsupported or unreadable import: {name}");
            return;
        };
        let Ok(intrinsic) = blockworx_paint::image::image_intrinsic_size(&asset) else {
            tracing::error!("Failed to import image: not a valid image");
            return;
        };
        if !blockworx_editor::edit::lower::asset_within_limit(&asset, name) {
            return;
        }
        let scale = GRID_SIZE * IMPORTED_IMAGE_CELLS / intrinsic.x.max(intrinsic.y).max(1.0);
        let rect = Rect::from_center_size(target, intrinsic * scale);
        let shape = self.commit_gesture(Label::verb("Import"), |d| {
            d.add_image(blockworx_editor::edit::assets::Placement::Box(rect), &asset)
        });
        self.tool = blockworx_tools::resize_block::ResizeBlock::Selected { shape }.into();
    }

    /// 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 handle_embedded(&mut self, name: &str, bytes: &[u8]) {
        let target = self.paste_target();
        let source = match blockworx_store::transfer::document_in(bytes) {
            Ok(source) => source,
            Err(why) => {
                tracing::warn!("Unreadable diagram: {name}: {why}");
                return;
            }
        };
        let title = embedded_title(name);
        let block = self.commit_gesture(Label::verb("Embed"), |d| d.embed(&source, &title, target));
        let landed = ShapeId::Rect(block);
        self.show_landed(&[landed]);
        self.tool = select_shapes(vec![landed]);
    }

    // ── What the user can invoke ───────────────────────────────────────────

    /// 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 available_commands(&mut self, current_lock: InterfaceLock) -> CommandSet {
        let history = self.consequences().history();
        let writability = self.doc.writability();
        let saving = self.doc.saving();
        let viewing = self.viewing();
        let indexed = self
            .doc_index
            .view(viewed(&self.doc, self.time_machine.as_ref()).document());
        let drawing = Drawing::new(
            indexed,
            &self.path,
            &mut self.presentation,
            &mut self.gesture,
        );
        CommandSet::available(&CommandContext {
            tool: &self.tool,
            data: &drawing,
            history,
            current_lock,
            writability,
            saving,
            viewing,
        })
    }

    /// The lock the interface stands under right now — what the registry
    /// gates the editing commands on.
    pub fn current_lock(&mut self) -> InterfaceLock {
        self.drawing().current_locked().into()
    }

    /// 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 window_title(&self, opened: Option<&str>) -> String {
        if let Some(name) = self.doc.container_name() {
            return match self.doc.read_only_reason() {
                Some(_) => format!("{name} - BlockWorx [read-only]"),
                None => format!("{name} - BlockWorx"),
            };
        }
        let opened = match opened {
            Some(name) => format!("{name} - BlockWorx"),
            None => "BlockWorx".to_string(),
        };
        format!("{opened} [nothing persisted]")
    }

    /// 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 document_name(&self, opened: Option<&str>) -> String {
        if let Some(name) = self.doc.container_name() {
            return import::file_stem(name.as_str());
        }
        match opened {
            Some(opened) => import::file_stem(opened),
            None => import::UNTITLED.to_owned(),
        }
    }

    /// 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 ticks(&mut self, tick: Tick) {
        let elapsed = tick.now().saturating_sub(self.tick.now());
        self.tick = tick.after(self.tick);
        // A framing in flight moves by what the frame took, and asks for the
        // next frame while it has further to go.
        if self.camera.ease(elapsed) {
            self.request_repaint();
        }
    }

    /// The frame clock: monotonic since the host started.
    pub fn now(&self) -> Duration {
        self.tick.now()
    }

    pub fn tick(&self) -> Tick {
        self.tick
    }

    /// Ask for another frame as soon as the host can give one.
    pub fn request_repaint(&mut self) {
        self.repaint_after(Duration::ZERO);
    }

    fn repaint_after(&mut self, after: Duration) {
        self.repaint = Some(self.repaint.map_or(after, |soonest| soonest.min(after)));
    }

    /// The soonest another frame was asked for since this was last drained.
    pub fn take_repaint(&mut self) -> Option<Duration> {
        self.repaint.take()
    }

    /// Fold in what one canvas frame asked for.
    pub(crate) fn asked_repaint(&mut self, after: Option<Duration>) {
        if let Some(after) = after {
            self.repaint_after(after);
        }
    }
}

/// What an embedded document's block is called: the file's name without the
/// suffixes it travelled under. `engine.bwx.zip` is the diagram "engine" —
/// both extensions come off, since a container's own name carries neither.
pub(crate) fn embedded_title(name: &str) -> String {
    let stem = std::path::Path::new(name)
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or(name);
    let stem = stem.strip_suffix(".zip").unwrap_or(stem);
    let stem = stem.strip_suffix(".bwx").unwrap_or(stem);
    let stem = stem.strip_suffix(".json").unwrap_or(stem);
    if stem.is_empty() {
        name.to_owned()
    } else {
        stem.to_owned()
    }
}