blockworx/

app.rs

use blockworx_geom::{Pos2, Rect, vec2};
use blockworx_paint::{Cursor, FontChoice, Scheme};

use crate::canvas::convert::{IntoEgui as _, IntoGeom};
// The browser has no files: every path in this module is on a native-only
// flow (the container, the documents directory, the recent list).
#[cfg(not(target_arch = "wasm32"))]
use std::path::{Path, PathBuf};

use blockworx_store::doc::Doc;
use blockworx_store::record::Identity;

use crate::io_pin_picker::{self, PinTypePick};
use crate::kernel::session::{Consequences, viewed};
use crate::kernel::{CameraWork, Framing, Glide, Refit, Session, Sighting};
use crate::{
    canvas::{CanvasChrome, View},
    edit::naming::InterfaceLock,
    grid::GridCell,
    panels::{
        overlay::{OpenPicker, RightClick, Selection, selection_overlay},
        palette::{Palette, PaletteOutcome},
    },
    path::BlockPath,
    preferences::Preferences,
    role_picker::{self, RolePick},
    shape::{ShapeId, ShapeRef},
    theme::Role,
    tools::{
        commands::CommandSet,
        tool::{Action, Deletable, ExportTo, ImageTarget, RoleTarget, ToolTrait},
    },
    widget::drawing::Drawing,
};
// The tool a document swap settles onto; a browser session has no container
// to swap.
#[cfg(not(target_arch = "wasm32"))]
use crate::tools::{SelectTool, tool::Tool};
use blockworx_doc::id::{BlockId, PinId};
use blockworx_doc::repo::Repo;

/// The frame clock, as the undo stack and the spotlight read it: seconds since
/// the app started, and never before that.
fn now(ctx: &egui::Context) -> core::time::Duration {
    core::time::Duration::try_from_secs_f64(ctx.input(|i| i.time)).unwrap_or_default()
}

/// What the session opens on (D20).
#[cfg(not(target_arch = "wasm32"))]
#[derive(Default)]
pub enum Opening {
    /// The path a command line named: a `.bwx` container, which attaches, or
    /// a document file, which opens as a scratch session.
    Path(PathBuf),
    /// Nothing was named, so a document is born: a container under a name of
    /// three words in the documents directory, attached from its first edit.
    Born,
    /// Neither — a session with no file behind it. The browser has only this,
    /// and so does a test driving the editor without a filesystem.
    #[default]
    Detached,
}

// On the web every field but the two editor flags is compiled out, leaving a
// config that is nothing but flags — and a by-value parameter clippy wants
// copied rather than moved.
#[cfg_attr(target_arch = "wasm32", derive(Clone, Copy))]
#[derive(Default)]
pub struct AppConfig {
    #[cfg(not(target_arch = "wasm32"))]
    pub opening: Opening,
    /// Where a new document's container is created — at startup and at
    /// File ▸ New (D20). Injected rather than read off the environment down
    /// in the flow, so a test can point it at a directory of its own.
    #[cfg(not(target_arch = "wasm32"))]
    pub documents: blockworx_store::naming::Documents,
    /// Open the live theme editor in a second window and persist its result to
    /// `theme.json` on exit.
    pub theme_editor: bool,
    /// Open the live font-size editor in a second window and persist its result
    /// to `font_sizes.json` on exit.
    pub font_editor: bool,
}

/// The eframe storage key the workspace panel's per-document state lives
/// under, beside the preferences blob and the recent-files list.
const WORKSPACES: &str = "workspaces";

/// What separates the levels of a selection path in the status line — the
/// mockup's own `join(" / ")`.
const SELECTION_SEPARATOR: &str = "/";

pub struct App {
    /// The editor itself: the document, where this session is standing, what
    /// it has selected, what one undo would take back. Every document read
    /// and every write goes through it, and the canvas pass below is its
    /// [`Session::canvas_frame`] over an egui `Painter`.
    session: Session,
    /// The file a *scratch* document was opened from, for the window title.
    /// `None` on the web (no filesystem) and when nothing was there to open.
    /// An attached container names itself.
    #[cfg(not(target_arch = "wasm32"))]
    opened: Option<String>,
    /// Where the document this session opened came from, when it was opened
    /// from an export that carried D19's provenance. Advisory and
    /// session-only: the title block says it, nothing writes it, and saving
    /// into a container does not carry it past this session.
    #[cfg(not(target_arch = "wasm32"))]
    opened_from: Option<blockworx_store::projection::Provenance>,
    /// What this session has owned up to and the user has not yet
    /// acknowledged: an error nobody can dismiss makes the editor unusable
    /// (docs/ui-issues.md). Dropped with the document it was about.
    failures: Vec<String>,
    /// The containers the File menu offers to reopen, persisted through the
    /// eframe storage DB.
    #[cfg(not(target_arch = "wasm32"))]
    recent: crate::file::RecentFiles,
    /// Where File ▸ New puts the container it creates (D20).
    #[cfg(not(target_arch = "wasm32"))]
    documents: blockworx_store::naming::Documents,
    /// The containers *this session* created that nobody has claimed: born
    /// under a generated name, never committed to and never renamed. They
    /// are removed on a clean exit, so launching and quitting leaves the
    /// documents directory as it was, and they stay off the recent list
    /// until they are claimed, so it does not fill with dead names.
    #[cfg(not(target_arch = "wasm32"))]
    unclaimed: Vec<PathBuf>,
    /// The File menu's rename box, which has to survive the frames it is
    /// open across.
    #[cfg(not(target_arch = "wasm32"))]
    rename_draft: String,
    /// The channel an in-flight File-menu dialog delivers its pick on.
    /// Polled each frame; `None` when no dialog is open.
    #[cfg(not(target_arch = "wasm32"))]
    pending_file: Option<crate::file::PickReceiver>,
    /// User appearance preferences (theme, mode, font), persisted in the
    /// eframe storage DB and applied live via [`Self::apply_preferences`].
    pub preferences: Preferences,
    /// The (theme, resolved-dark, font) last pushed to the egui context, so
    /// appearance is only re-applied (a relayout) when the effective look changes.
    applied_appearance: Option<(Scheme, bool, FontChoice)>,
    /// The title last pushed to the viewport, so it is only re-sent when it
    /// changes.
    #[cfg(not(target_arch = "wasm32"))]
    applied_title: String,
    /// The head [`Self::refresh_projection`] is waiting out, and since when.
    #[cfg(not(target_arch = "wasm32"))]
    head_moved: Option<(blockworx_doc::rev::Rev, std::time::Instant)>,
    canvas: View,
    /// Whether the `--theme-editor` window is shown. Cleared when that window is
    /// closed; gates whether `theme.json` is written on exit.
    theme_editor: bool,
    /// Whether the `--font-editor` window is shown. Cleared when that window is
    /// closed; gates whether `font_sizes.json` is written on exit.
    font_editor: bool,
    /// Whether the app's toolbar icons have been registered with the canvas yet.
    /// Done once, on the first frame (registration needs `egui::Context`).
    images_loaded: bool,
    /// The open selection popup, if any. Set by an [`Action`] and read one frame
    /// later so the click that opened it isn't mistaken for a click-outside
    /// dismiss. The popup anchors itself above the selection overlay via
    /// [`Self::overlay_top_right`].
    popup: Option<Popup>,
    /// The selection overlay's top-right corner from the latest frame it was
    /// drawn, used to anchor the accent popup directly above it. `None` when
    /// nothing is selected.
    overlay_top_right: Option<Pos2>,
    /// The selected object's on-screen bounding box from this frame, in screen
    /// pixels. Computed inside the canvas closure (where the painter transform and
    /// the canvas's world→screen remap are available) and consumed by
    /// `selection_overlay` after
    /// the closure to place the overlay. `None` when nothing is selected.
    selection_screen_bounds: Option<Rect>,
    /// The command palette while open (Ctrl+K toggles it).
    palette: Option<Palette>,
    /// The channel an in-flight import dialog delivers its picked file on.
    /// Polled each frame; `None` when no import is pending.
    pending_import: Option<ImportReceiver>,
    /// The channel an in-flight image dialog delivers its pick on, and what
    /// the session asked for it. Polled each frame; `None` when no image is
    /// pending.
    pending_image: Option<(ImageTarget, ImageReceiver)>,
    /// Which view the navigator is showing, whether it is showing at all, and how
    /// wide it was left — for the document that is open (spec §8).
    workspace: crate::shell::workspace::Workspace,
    /// What the floating chrome left the canvas last frame (spec §2.1). Read
    /// by the framing that has to land inside it, and by the overlay that has
    /// to clamp into it.
    safe: crate::shell::SafeArea,
    /// The same, for every document this session has opened. Persisted
    /// through the eframe storage DB beside the recent-files list, so a
    /// document reopens with the panel it was left with.
    workspaces: std::collections::BTreeMap<String, crate::shell::workspace::Workspace>,
    /// The history panel's search box (§8.1). Kept here rather than in
    /// egui's transient store because a query the user typed must survive
    /// the panel being collapsed and reopened.
    history_search: String,
}

/// A selection popup and the selection it acts on. At most one is open at a
/// time, so opening either closes the other.
enum Popup {
    /// The accent-color picker, for one block, port, route, area, or text box.
    Role(RoleTarget),
    /// The pin-type (I/O style) picker, for the pins it retypes (a single pin, a
    /// pin group, or a port's pin).
    PinType(Vec<PinId>),
}

impl Popup {
    fn picker(&self) -> OpenPicker {
        match self {
            Popup::Role(_) => OpenPicker::Role,
            Popup::PinType(_) => OpenPicker::PinType,
        }
    }
}

/// What an import file dialog delivers: the picked file's name and bytes, or
/// `None` if the user cancelled.
type ImportReceiver = std::sync::mpsc::Receiver<Option<(String, Vec<u8>)>>;

/// What an image dialog delivers: the picked artwork, or `None` if the user
/// cancelled or the file could not be read.
type ImageReceiver = std::sync::mpsc::Receiver<Option<blockworx_doc::block_model::Asset>>;

/// How the view spells the session's [`Glide`].
fn glided(glide: Glide) -> crate::canvas::Framing {
    match glide {
        Glide::Eased => crate::canvas::Framing::Animated,
        Glide::Snap => crate::canvas::Framing::Immediate,
    }
}

/// The cursor to actually publish for the active tool: the tool's requested
/// cursor while the pointer is over the canvas, and none otherwise so the tool
/// cursor never overrides an overlay's own cursor.
fn effective_cursor(tool_cursor: Option<Cursor>, pointer: PointerOver) -> Option<Cursor> {
    match pointer {
        PointerOver::Canvas => tool_cursor,
        PointerOver::Elsewhere => None,
    }
}

/// Where the pointer sits: over the canvas, or over an overlay (which owns its
/// own cursor).
#[derive(Clone, Copy, PartialEq, Eq)]
enum PointerOver {
    Canvas,
    Elsewhere,
}

/// The accent role `target` carries now, or `None` when it has none.
fn current_role(drawing: &Drawing<'_>, target: RoleTarget) -> Option<u8> {
    use crate::edit::lower::accent_from_role;
    match target {
        RoleTarget::Block(rid) => drawing.block(rid).and_then(|b| accent_from_role(b.role)),
        RoleTarget::Port(pid) => match drawing.shape(ShapeId::Port(pid)) {
            Some(ShapeRef::Port(port)) => accent_from_role(port.pin.port_accent),
            _ => None,
        },
        RoleTarget::Route(rid) => drawing
            .auto_route(rid)
            .and_then(|wire| accent_from_role(wire.route.role)),
        RoleTarget::Area(cid) => match drawing.shape(ShapeId::Area(cid)) {
            Some(ShapeRef::Area(area)) => accent_from_role(area.role),
            _ => None,
        },
        RoleTarget::Text(tid) => match drawing.shape(ShapeId::Text(tid)) {
            Some(ShapeRef::Text(text)) => accent_from_role(text.text.role),
            _ => None,
        },
    }
}

/// The most recent paste event's text this frame, if any.
fn latest_paste(ctx: &egui::Context) -> Option<String> {
    ctx.input(|i| {
        i.events.iter().rev().find_map(|e| match e {
            egui::Event::Paste(s) => Some(s.clone()),
            _ => None,
        })
    })
}

/// The arrow key pressed this frame, as a one-cell nudge of the selection.
fn arrow_nudge(ctx: &egui::Context) -> Option<Action> {
    use egui::{Key, Modifiers};
    let (dx, dy) = ctx.input_mut(|i| {
        if i.consume_key(Modifiers::NONE, Key::ArrowLeft) {
            Some((-1, 0))
        } else if i.consume_key(Modifiers::NONE, Key::ArrowRight) {
            Some((1, 0))
        } else if i.consume_key(Modifiers::NONE, Key::ArrowUp) {
            Some((0, -1))
        } else if i.consume_key(Modifiers::NONE, Key::ArrowDown) {
            Some((0, 1))
        } else {
            None
        }
    })?;
    Some(Action::Nudge { dx, dy })
}

/// The role the picker's "no accent" swatch shows for `target`: its own
/// un-accented stroke.
fn unaccented_role(target: RoleTarget) -> Role {
    match target {
        RoleTarget::Area(_) => Role::AreaStroke,
        RoleTarget::Text(_) => Role::TextBoxStroke,
        _ => Role::AccentDefault,
    }
}

#[cfg(not(target_arch = "wasm32"))]
/// A repo whose one commit creates everything `doc` holds, under the ids
/// the file gave them. The one door a document takes into the editor now:
/// F5's courtesy file open comes through here, and a document the fold
/// refuses opens empty rather than taking the editor down.
fn seeded_repo(doc: &blockworx_doc::document::Document, label: &str) -> Repo {
    let commits: Vec<_> = doc.creating_commit(label).into_iter().collect();
    Repo::folding(&commits).unwrap_or_else(|e| {
        tracing::error!("{label} will not seed a repo: {e}");
        Repo::default()
    })
}

/// What opening a plain document file came back with.
#[cfg(not(target_arch = "wasm32"))]
enum Loaded {
    /// The file opened: this is what it held, under this name, and — for an
    /// export — where it says it came from (D19). Boxed, so the enum is the
    /// size of the sentence it carries rather than of a document.
    Document {
        repo: Box<Repo>,
        name: String,
        from: Option<blockworx_store::projection::Provenance>,
    },
    /// Nothing was there to open, which is not a complaint.
    Nothing,
    /// It was there, would not open, and this says why.
    Failed(String),
}

/// Whether `path` names a document in a format this build no longer reads.
/// The reader is gone, so the honest answer is a refusal naming the format —
/// not a JSON parse failure over a file that was never JSON.
#[cfg(not(target_arch = "wasm32"))]
fn names_a_retired_format(path: &std::path::Path) -> bool {
    path.extension()
        .is_some_and(|ext| ext.eq_ignore_ascii_case("kdl"))
}

#[cfg(not(target_arch = "wasm32"))]
fn retired_format_notice(name: &str) -> String {
    format!("{name} is in the retired KDL document format, which this build no longer reads")
}

/// A plain document file — an export, or a hand-written one — read into a
/// fresh repo and named for the window title. Nothing there opens blank
/// without complaint (F9 — a boot invents no content the user never
/// authored); a read or parse failure comes back as [`Loaded::Failed`] and
/// the session opens blank around it, since refusing to start helps nobody.
#[cfg(not(target_arch = "wasm32"))]
fn open_document_file(path: &std::path::Path) -> Loaded {
    if !path.is_file() {
        return Loaded::Nothing;
    }
    let name = path
        .file_name()
        .map_or_else(String::new, |n| n.to_string_lossy().into_owned());
    if names_a_retired_format(path) {
        return Loaded::Failed(retired_format_notice(&name));
    }
    let src = match std::fs::read_to_string(path) {
        Ok(src) => src,
        Err(e) => return Loaded::Failed(format!("Failed to open {}: {e}", path.display())),
    };
    match blockworx_store::document_file::parse(&src, &name) {
        Ok(doc) => Loaded::Document {
            repo: Box::new(seeded_repo(&doc, &format!("Opened {name}"))),
            from: blockworx_store::projection::exported_stamp_in(&src).and_then(|s| s.provenance),
            name,
        },
        Err(e) => {
            // The console gets the spans and the offending source; the canvas
            // gets the sentence, since a rendered diagnostic is a wall of text
            // in a notice.
            tracing::error!("Failed to open {}:\n{e:?}", path.display());
            Loaded::Failed(format!("Failed to open {}: {e}", path.display()))
        }
    }
}

/// What the session starts on: the document, the name the window title says
/// was opened, the container this startup created if it made one, and
/// whatever would not open on the way — which the canvas says out loud
/// rather than only the console.
#[cfg(not(target_arch = "wasm32"))]
struct Startup {
    doc: Doc,
    opened: Option<String>,
    from: Option<blockworx_store::projection::Provenance>,
    born: Option<PathBuf>,
    failure: Option<String>,
}

#[cfg(not(target_arch = "wasm32"))]
impl Startup {
    /// A session with nothing behind it — the blank canvas D20 starts on
    /// when there is nowhere to be born.
    fn detached() -> Self {
        Startup {
            doc: Doc::default(),
            opened: None,
            from: None,
            born: None,
            failure: None,
        }
    }
}

/// Open whatever the session was pointed at. A document born here is the
/// no-argument case (D20).
#[cfg(not(target_arch = "wasm32"))]
fn open_startup(opening: Opening, documents: &blockworx_store::naming::Documents) -> Startup {
    match opening {
        Opening::Path(path) => open_startup_path(&path),
        Opening::Born => born_attached(documents),
        Opening::Detached => Startup::detached(),
    }
}

/// What the toast says a Save-as did. Two sentences, because two things
/// happened: at the head the document has a new home, and under the lens a
/// *rev* of it does — and which one it was is the thing the user needs to
/// read back (R37, R38).
#[cfg(not(target_arch = "wasm32"))]
fn saved_as(root: &Path, scope: crate::file::SaveScope) -> String {
    let named = crate::file::document_name(root);
    match scope {
        crate::file::SaveScope::Whole => format!("Saved as {named}"),
        crate::file::SaveScope::Through(at) => {
            format!("Saved through rev {} as {named}", at.get())
        }
    }
}

/// D20's born-attached start: a container of its own, so append-on-commit
/// holds from the first edit. A container that cannot be created is a
/// notice and a scratch session, never a refusal to start.
#[cfg(not(target_arch = "wasm32"))]
fn born_attached(documents: &blockworx_store::naming::Documents) -> Startup {
    match documents.create(blockworx_store::naming::entropy) {
        Ok(store) => Startup {
            born: Some(store.root().to_path_buf()),
            doc: Doc::attached(store),
            opened: None,
            from: None,
            failure: None,
        },
        Err(failure) => Startup {
            failure: Some(failure.notice()),
            ..Startup::detached()
        },
    }
}

/// What a named path opens: a container attached, or — for a plain document
/// file, and for anything that will not open — a scratch session, which
/// persists nothing.
///
/// The plain-file half is the command line's alone (R53). Nothing in the
/// chrome offers to open a `document.json`: it is the projection beside a
/// log, carrying neither that log nor the assets, so opening one would hand
/// the user half a diagram wearing its name. A developer naming one on the
/// command line has asked for exactly that, and is told what they got by the
/// title bar's "[nothing persisted]".
#[cfg(not(target_arch = "wasm32"))]
fn open_startup_path(path: &std::path::Path) -> Startup {
    let mut failure = None;
    if crate::file::names_a_container(path) {
        match crate::file::open_container(path) {
            Ok(store) => {
                if let Some(reason) = store.read_only_reason() {
                    tracing::warn!("{} opened read-only: {reason}", path.display());
                }
                return Startup {
                    doc: Doc::attached(store),
                    ..Startup::detached()
                };
            }
            Err(e) => {
                failure = Some(format!("Failed to open {}: {e}", path.display()));
            }
        }
    }
    let (repo, opened, from, load_failure) = match open_document_file(path) {
        Loaded::Document { repo, name, from } => (*repo, Some(name), from, None),
        Loaded::Nothing => (Repo::default(), None, None, None),
        Loaded::Failed(why) => (Repo::default(), None, None, Some(why)),
    };
    Startup {
        doc: Doc::scratch(repo),
        opened,
        from,
        born: None,
        failure: failure.or(load_failure),
    }
}

impl App {
    pub fn new(config: AppConfig) -> Self {
        let AppConfig {
            #[cfg(not(target_arch = "wasm32"))]
            opening,
            #[cfg(not(target_arch = "wasm32"))]
            documents,
            theme_editor,
            font_editor,
        } = config;
        #[cfg(not(target_arch = "wasm32"))]
        let Startup {
            doc,
            opened,
            from,
            born,
            failure,
        } = open_startup(opening, &documents);
        // The browser has no filesystem; open on an empty document.
        #[cfg(target_arch = "wasm32")]
        let doc = Doc::default();

        let app = Self {
            session: Session::opening(doc, Identity::from_environment()),
            #[cfg(not(target_arch = "wasm32"))]
            opened,
            #[cfg(not(target_arch = "wasm32"))]
            opened_from: from,
            #[cfg(not(target_arch = "wasm32"))]
            failures: failure.into_iter().collect(),
            #[cfg(target_arch = "wasm32")]
            failures: Vec::new(),
            #[cfg(not(target_arch = "wasm32"))]
            recent: crate::file::RecentFiles::default(),
            #[cfg(not(target_arch = "wasm32"))]
            documents,
            #[cfg(not(target_arch = "wasm32"))]
            unclaimed: born.into_iter().collect(),
            #[cfg(not(target_arch = "wasm32"))]
            rename_draft: String::new(),
            #[cfg(not(target_arch = "wasm32"))]
            pending_file: None,
            preferences: Preferences::default(),
            applied_appearance: None,
            // Seeded below, once the fields it quotes are in place.
            #[cfg(not(target_arch = "wasm32"))]
            applied_title: String::new(),
            #[cfg(not(target_arch = "wasm32"))]
            head_moved: None,
            canvas: View::default(),
            selection_screen_bounds: None,
            palette: None,
            theme_editor,
            font_editor,
            images_loaded: false,
            popup: None,
            overlay_top_right: None,
            pending_import: None,
            pending_image: None,
            workspace: crate::shell::workspace::Workspace::default(),
            safe: crate::shell::SafeArea::default(),
            workspaces: std::collections::BTreeMap::new(),
            history_search: String::new(),
        };
        // `main` opens the window with `window_title()`, so seeding from the
        // same call is what leaves the first frame nothing to re-send.
        #[cfg(not(target_arch = "wasm32"))]
        let app = {
            let mut app = app;
            app.applied_title = app.window_title();
            app
        };
        app
    }

    /// What a scratch document's source file is called — the one fact about
    /// the window title and the document's name that belongs to the platform
    /// rather than to the document.
    // The browser has no file to have opened one from, so the answer there is
    // a constant `None` — and the shape of the question is still the shell's.
    #[cfg_attr(target_arch = "wasm32", expect(clippy::unused_self))]
    fn opened_name(&self) -> Option<&str> {
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.opened.as_deref()
        }
        #[cfg(target_arch = "wasm32")]
        {
            None
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub fn window_title(&self) -> String {
        self.session.window_title(self.opened_name())
    }

    fn document_name(&self) -> String {
        self.session.document_name(self.opened_name())
    }

    /// Re-normalize everything that referenced the previous document after the
    /// whole editor state is swapped out: the tool and popups may point at
    /// absent shapes and the nav history at absent paths.
    #[cfg(not(target_arch = "wasm32"))]
    fn after_document_swap(&mut self, was: &str) {
        self.session.tool = Tool::Select(SelectTool);
        self.popup = None;
        self.settle_workspace(was);
        // The failures were about the document that just left.
        self.failures.clear();
        self.session.fit_view();
    }

    /// Export `format` for `block` — or the current view when `None`. The
    /// image formats render the framed level (PNG rasterizes the SVG source
    /// off-thread when it is written); JSON projects the document itself, so
    /// the file holds exactly what is on screen.
    ///
    /// A block export makes that block the top of a standalone diagram carrying
    /// only its subtree.
    fn export(
        &mut self,
        ctx: &egui::Context,
        format: crate::export::ExportFormat,
        selection: Option<Vec<crate::shape::ShapeId>>,
    ) {
        let name = self.document_name();
        let content = self.export_content(format, selection);
        crate::export::spawn_export(ctx, crate::export::ExportPayload { name, content });
    }

    /// D19's rev export: the ordinary flattened-document export, run over
    /// the rev copy at `at` instead of over the head, and delivered to the
    /// clipboard or through the save dialog. It writes nothing, so a
    /// read-only session — and a session looking at another rev entirely —
    /// takes it.
    fn export_rev(&self, ctx: &egui::Context, at: blockworx_doc::rev::Rev, to: ExportTo) {
        let source = self.export_source(at);
        let stamp = self.session.doc.stamp_at(at);
        let content = if at == self.session.doc.repo().rev() {
            blockworx_store::projection::export_text(self.session.doc.document(), stamp, source)
        } else {
            let Some(document) = self.session.document_at(at) else {
                return;
            };
            blockworx_store::projection::export_text(&document, stamp, source)
        };
        match to {
            ExportTo::Clipboard => ctx.copy_text(content),
            ExportTo::File => crate::export::spawn_export(
                ctx,
                crate::export::ExportPayload {
                    name: format!("{}-r{}", self.document_name(), at.get()),
                    content: crate::export::ExportContent::Json(content),
                },
            ),
        }
    }

    /// What an export this session writes says about where it came from
    /// (D19), for the fold at `at`.
    fn export_source(&self, at: blockworx_doc::rev::Rev) -> blockworx_store::projection::Source {
        blockworx_store::projection::Source {
            document: self.document_name(),
            author: self.session.identity.name.clone(),
            tags: self.session.doc.tags().of(at).to_vec(),
        }
    }

    /// What an export writes, apart from the dialog that delivers a path —
    /// so the bytes a user gets are the bytes a test can read.
    fn export_content(
        &mut self,
        format: crate::export::ExportFormat,
        selection: Option<Vec<crate::shape::ShapeId>>,
    ) -> crate::export::ExportContent {
        use crate::export::{ExportContent, ExportFormat};

        // A selection export writes a private standalone document (the
        // selection pasted into a fresh empty one); the current-view export
        // writes the live one in place.
        let selection_repo = selection.and_then(|shapes| self.selection_repo(&shapes));
        match format {
            // The whole-document export is the artifact D19 stamps; a selection
            // export is an excerpt of shapes rather than the document at a rev,
            // so it carries no rev to be provenance for.
            ExportFormat::Json => ExportContent::Json(if let Some(repo) = selection_repo {
                blockworx_store::document_file::to_json(repo.document())
            } else {
                let at = self.session.viewed_repo().rev();
                let source = self.export_source(at);
                let stamp = self.session.doc.stamp_at(at);
                blockworx_store::projection::export_text(
                    viewed(&self.session.doc, self.session.time_machine.as_ref()).document(),
                    stamp,
                    source,
                )
            }),
            // A selection has no scope hierarchy to navigate, so
            // [`crate::export::ExportScope::Selection`] does not offer PDF and
            // there is no selection arm to write.
            ExportFormat::Pdf => self.export_pdf(),
            ExportFormat::Svg | ExportFormat::Png => {
                let svg = if let Some(repo) = selection_repo {
                    let mut index = blockworx_doc::document::DocIndex::default();
                    let mut presentation = crate::presentation::Presentation::default();
                    crate::export::level::render_svg(
                        &self.session.theme,
                        &self.text_layout(),
                        index.view(repo.document()),
                        &BlockPath::empty(),
                        &mut presentation,
                    )
                } else {
                    let doc =
                        viewed(&self.session.doc, self.session.time_machine.as_ref()).document();
                    crate::export::level::render_svg(
                        &self.session.theme,
                        &self.text_layout(),
                        self.session.doc_index.view(doc),
                        &self.session.path,
                        &mut self.session.presentation,
                    )
                };
                if format == ExportFormat::Png {
                    ExportContent::Png(svg)
                } else {
                    ExportContent::Svg(svg)
                }
            }
        }
    }

    /// The text engine an export lays its diagram out through: the session's
    /// own typeface, through the backend the canvas draws with, so an export
    /// breaks its lines exactly where the screen did (D2).
    fn text_layout(&self) -> crate::canvas::EpaintLayout {
        crate::canvas::EpaintLayout::new(self.preferences.font)
    }

    /// The whole viewed document as a PDF (D21). A failed export writes an
    /// empty file rather than taking the session down with it, and says so
    /// where the developer already is.
    fn export_pdf(&mut self) -> crate::export::ExportContent {
        let repo = self.session.viewed_repo();
        let rev = repo.rev();
        let provenance = self
            .session
            .doc
            .stamp_at(rev)
            .from(self.export_source(rev))
            .provenance;
        let doc = repo.document().clone();
        let block = self.title_block();
        let mut index = blockworx_doc::document::DocIndex::default();
        let layout = self.text_layout();
        let scene = crate::export::pdf::Scene {
            document: index.view(&doc),
            theme: &self.session.theme,
            scheme: self.preferences.theme,
            layout: &layout,
            block,
            provenance,
        };
        crate::export::ExportContent::Pdf(crate::export::pdf::export(scene).unwrap_or_else(|e| {
            tracing::error!("Failed to export PDF: {e}");
            Vec::new()
        }))
    }

    /// 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-materialization). A repo rather than a bare document because the
    /// projection's names come from the log (D11). `None` when nothing
    /// copyable is selected.
    fn selection_repo(&mut self, shapes: &[crate::shape::ShapeId]) -> Option<Repo> {
        let clip = self.session.drawing().copy_selection(shapes)?;
        let doc = blockworx_doc::document::Document::default();
        let mut index = blockworx_doc::document::DocIndex::default();
        let mut presentation = crate::presentation::Presentation::default();
        // The scratch document this builds is the export's own, never the
        // session's, so a read-only session still exports its selection.
        let mut gesture = crate::gesture::Gesture::open(
            crate::edit::describe::Label::verb("Export"),
            blockworx_store::doc::Writability::Writable,
        );
        let path = BlockPath::empty();
        // A document of its own, so nothing on the clipboard can be a cut
        // coming home to it: the export always mints.
        let into = blockworx_store::doc::DocumentNonce::mint();
        Drawing::new(index.view(&doc), &path, &mut presentation, &mut gesture)
            .paste_snapshot(&clip, into, None);
        let commit = gesture.seal("Exported a selection".to_owned())?;
        Repo::folding(&[commit])
            .inspect_err(|refusal| {
                tracing::error!("the export document refused a paste: {refusal}");
            })
            .ok()
    }

    /// Push the appearance preferences — palette, egui visuals and fonts — to
    /// `ctx`, but only when they actually change, since `set_fonts`/`set_visuals`
    /// trigger a relayout. `System` mode resolves via the OS light/dark
    /// preference, so a runtime OS theme flip re-resolves the theme variant here
    /// too.
    pub fn apply_preferences(&mut self, ctx: &egui::Context) {
        // Cmd+Plus/Minus/0 belong to the canvas (zoom the diagram, fit the
        // document). egui consumes those chords at the end of every frame to
        // scale the whole UI instead, and nothing in the editor scales the UI
        // any more (R47).
        ctx.options_mut(|o| o.zoom_with_keyboard = false);
        // §2.3 asks for one motion curve across the whole shell. egui has one
        // knob for it, so this is the whole of the vocabulary — press states,
        // hovers, tooltips and the navigator all move at the same rate.
        ctx.all_styles_mut(|style| {
            style.animation_time = crate::shell::glass::MOTION.as_secs_f32();
        });
        let system_dark = ctx.system_theme().map(|t| t == egui::Theme::Dark);
        let dark = self.preferences.mode.is_dark(system_dark);
        let theme = self.preferences.theme;
        let font = self.preferences.font;
        if self.applied_appearance != Some((theme, dark, font)) {
            self.session.theme.set_palette(theme.palette(dark.into()));
            ctx.set_visuals(crate::canvas::convert::visuals(
                self.session.theme.palette(),
            ));
            ctx.set_fonts(crate::canvas::build_fonts(font));
            self.applied_appearance = Some((theme, dark, font));
        }
    }

    /// Restore persisted preferences from the eframe storage DB (written by
    /// [`eframe::App::save`]). Called once at startup, before the first frame, so
    /// the app opens with the user's saved theme/font/size. A malformed blob is
    /// ignored, leaving the defaults in place.
    pub fn restore_preferences(&mut self, storage: &dyn eframe::Storage) {
        if let Some(s) = storage.get_string("preferences")
            && let Ok(prefs) = serde_json::from_str(&s)
        {
            self.preferences = prefs;
        }
        if let Some(s) = storage.get_string(WORKSPACES)
            && let Ok(workspaces) = serde_json::from_str(&s)
        {
            self.workspaces = workspaces;
            let key = self.workspace_key();
            self.workspace = self.workspaces.get(&key).copied().unwrap_or_default();
        }
        // A stored profile name (D9) overrides what the environment says
        // this user is called, so the identity is re-read here rather than
        // only at construction.
        self.session.identity = self.preferences.identity();
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.recent = crate::file::RecentFiles::restore(storage);
            // A container opened from the command line belongs at the front
            // of the list too — the restore above would otherwise bury it.
            // One this session invented does not: it earns its place by
            // being written in or renamed (D20).
            if let Some(root) = self.attached_root()
                && !self.unclaimed.contains(&root)
            {
                self.recent.remember(&root);
            }
        }
    }

    /// The container this session is attached to, if it is.
    #[cfg(not(target_arch = "wasm32"))]
    fn attached_root(&self) -> Option<PathBuf> {
        self.session.doc.container_root().map(Path::to_path_buf)
    }

    /// Re-title the window when what it says has changed under it: eframe
    /// sets the title once at startup.
    #[cfg(not(target_arch = "wasm32"))]
    fn apply_window_title(&mut self, ctx: &egui::Context) {
        let title = self.window_title();
        if title != self.applied_title {
            ctx.send_viewport_cmd(egui::ViewportCommand::Title(title.clone()));
            self.applied_title = title;
        }
    }

    /// Write the current role → base mapping to the source-tree `theme.json` so
    /// the next build embeds it via `include_str!` (see [`Theme::from_embedded`](crate::theme::Theme::from_embedded)).
    /// Targeting `CARGO_MANIFEST_DIR` makes this independent of the working
    /// directory. Only called when the theme editor is active, so ordinary runs
    /// never touch the file.
    #[cfg_attr(target_arch = "wasm32", allow(dead_code, clippy::unused_self))]
    fn save_theme(&self) {
        // Dev-only editor feature that writes into the source tree; there is no
        // source tree (or filesystem) on the web, so it is a no-op there.
        #[cfg(not(target_arch = "wasm32"))]
        {
            let path = concat!(env!("CARGO_MANIFEST_DIR"), "/src/theme/theme.json");
            match serde_json::to_string_pretty(&self.session.theme.overrides()) {
                Ok(s) => {
                    if let Err(e) = blockworx_store::atomic::write_atomically(
                        std::path::Path::new(path),
                        s.as_bytes(),
                    ) {
                        tracing::error!("Failed to write {path}: {e}");
                    }
                }
                Err(e) => tracing::error!("Failed to serialize theme: {e}"),
            }
        }
    }

    /// Write the current canvas font sizes to the source-tree `font_sizes.json`
    /// so the next build embeds them via `include_str!` (see
    /// [`Theme::from_embedded`](crate::theme::Theme::from_embedded)). Like [`Self::save_theme`], this targets
    /// `CARGO_MANIFEST_DIR` and is only called when the font editor is active, so
    /// ordinary runs never touch the file.
    #[cfg_attr(target_arch = "wasm32", allow(dead_code, clippy::unused_self))]
    fn save_font_sizes(&self) {
        // See `save_theme`: dev-only source-tree write, a no-op on the web.
        #[cfg(not(target_arch = "wasm32"))]
        {
            let path = concat!(env!("CARGO_MANIFEST_DIR"), "/src/theme/font_sizes.json");
            match serde_json::to_string_pretty(&self.session.theme.font_sizes()) {
                Ok(s) => {
                    if let Err(e) = blockworx_store::atomic::write_atomically(
                        std::path::Path::new(path),
                        s.as_bytes(),
                    ) {
                        tracing::error!("Failed to write {path}: {e}");
                    }
                }
                Err(e) => tracing::error!("Failed to serialize font sizes: {e}"),
            }
        }
    }

    /// This frame's selection popup, driven from state set on a previous frame
    /// (so the click that opened it isn't read as a click-outside dismiss).
    /// Returns which picker was open on entry: the toolbar's Accent/I/O buttons
    /// show active from it, and it has to be captured before a dismissal here
    /// clears it, or the dismissing click reads as a request to reopen.
    /// Returns the picker that was open, for the chrome, and whatever it
    /// reported — a pick is dispatched with the frame's other actions rather
    /// than written here, so it takes the same road as the rest.
    fn show_popups(&mut self, ctx: &egui::Context) -> (Option<OpenPicker>, Option<Action>) {
        let was_open = self.popup.as_ref().map(Popup::picker);
        // A popup anchors above the selection overlay, whose corner was captured
        // last frame; with no overlay there is nowhere to put it.
        let Some(corner) = self.overlay_top_right else {
            return (was_open, None);
        };
        let at = corner - vec2(0.0, crate::grid::GRID_SIZE);
        let (still_open, picked) = match self.popup.take() {
            Some(Popup::Role(target)) => self.show_role_picker(ctx, at, target),
            Some(Popup::PinType(pins)) => self.show_pin_type_picker(ctx, at, pins),
            None => (None, None),
        };
        self.popup = still_open;
        (was_open, picked)
    }

    /// The accent-color picker for `target`. The targeted shape stays selected
    /// behind it. `None` once it is dismissed.
    fn show_role_picker(
        &mut self,
        ctx: &egui::Context,
        at: Pos2,
        target: RoleTarget,
    ) -> (Option<Popup>, Option<Action>) {
        let current = current_role(&self.session.drawing(), target);
        let picked = match role_picker::show(
            ctx,
            at.egui(),
            &self.session.theme,
            current,
            unaccented_role(target),
        ) {
            RolePick::Set(role) => Some(Action::SetRole { target, role }),
            RolePick::Dismiss => return (None, None),
            RolePick::None => None,
        };
        (Some(Popup::Role(target)), picked)
    }

    /// The pin-type (I/O style) picker for `pins`, which stay selected behind
    /// it. The current cell is the pins' shared type, or none when they
    /// disagree; a click sets every one of them. `None` once dismissed.
    fn show_pin_type_picker(
        &mut self,
        ctx: &egui::Context,
        at: Pos2,
        pins: Vec<PinId>,
    ) -> (Option<Popup>, Option<Action>) {
        let current = {
            let drawing = self.session.drawing();
            let mut kinds = pins
                .iter()
                .filter_map(|pin| drawing.pin_on_shape(*pin).map(|(_, p)| p.dir));
            kinds.next().filter(|first| kinds.all(|k| k == *first))
        };
        let picked = match io_pin_picker::show(ctx, at.egui(), current) {
            PinTypePick::Set(kind) => Some(Action::SetPinsKind {
                pins: pins.clone(),
                kind,
            }),
            PinTypePick::Dismiss => return (None, None),
            PinTypePick::None => None,
        };
        (Some(Popup::PinType(pins)), picked)
    }

    /// The dev-only editor windows (`--theme-editor`, `--font-editor`). Both
    /// mutate `self.session.theme` in place, so they run before the theme is handed to
    /// this frame's canvas; closing either writes its file.
    fn show_editor_windows(&mut self, ctx: &egui::Context) {
        if self.theme_editor && crate::theme_editor::show(ctx, &mut self.session.theme) {
            self.theme_editor = false;
            self.save_theme();
        }
        if self.font_editor && crate::font_editor::show(ctx, &mut self.session.theme) {
            self.font_editor = false;
            self.save_font_sizes();
        }
    }

    /// While an in-canvas text editor has focus, a plain-text paste should feed
    /// the `TextEdit`, but an OBJECT paste (our clipboard format) should behave
    /// like a normal deselected object paste instead of dumping JSON into the
    /// box. Consume that event here and surrender editor focus so the tool
    /// commits the box's current text this frame; the payload is returned to be
    /// pasted after the canvas pass.
    fn intercept_object_paste(&self, ctx: &egui::Context) -> Option<String> {
        if !ctx.egui_wants_keyboard_input() {
            return None;
        }
        let text = latest_paste(ctx)?;
        if !crate::widget::clipboard::is_object_clipboard(&text) {
            return None;
        }
        ctx.input_mut(|i| {
            i.events.retain(|e| !matches!(e, egui::Event::Paste(_)));
            i.raw.events.retain(|e| !matches!(e, egui::Event::Paste(_)));
        });
        let focused = ctx
            .memory(egui::Memory::focused)
            .or_else(|| self.canvas.focused_edit_id());
        if let Some(id) = focused {
            ctx.memory_mut(|m| m.surrender_focus(id));
        }
        Some(text)
    }

    /// The canvas pass: run the active tool over this frame's interaction,
    /// draw the level, and publish the tool's cursor.
    fn show_canvas(&mut self, ui: &mut egui::Ui) -> Option<Action> {
        // The canvas resolves palette colors itself; the grid/background
        // chrome is resolved here and handed in (the canvas never sees a
        // role). Both go through the *same* palette, so the read-only drain
        // (spec §3.2) cannot reach one and miss the other.
        let chrome = CanvasChrome {
            background: self.session.chrome_color(Role::CanvasBackground),
            grid: self.session.chrome_color(Role::GridLine),
        };
        // The framing a `fit_view` asked for, taken before anything is
        // painted: the extent is whatever the draw passes cover, and the
        // recorder that measures them draws nothing — so the camera it
        // yields is the one this frame paints under. Deferring it to the
        // next frame painted the new level once under the old level's
        // camera (G2's flash).
        let owed = self.session.take_refit();
        let session = &mut self.session;
        let mut canvas = self.canvas.begin(ui, session.palette(), chrome);
        if owed == Refit::Owed {
            canvas.fit_to(|painter| session.content_bounds(painter));
        }
        let framed =
            canvas.paint(|interaction, painter| session.canvas_frame(&interaction, painter));
        self.selection_screen_bounds = framed.selection_bounds;
        // Only apply a tool cursor while the pointer is over the canvas, so it
        // never leaks over the nav bar, toolbar, or selection overlay.
        let cursor = effective_cursor(
            framed.cursor,
            if self.canvas.canvas_hovered() {
                PointerOver::Canvas
            } else {
                PointerOver::Elsewhere
            },
        );
        if let Some(cursor) = cursor {
            ui.output_mut(|o| {
                o.cursor_icon = cursor.egui();
            });
        }
        framed.action
    }

    /// The chrome that still floats over the canvas: the selection overlay
    /// and its pickers, the command palette, and the notices. Everything
    /// docked went into [`crate::shell`]. Each layer's request overrides the
    /// one below it, starting from what the tool asked for on the canvas.
    fn show_canvas_chrome(
        &mut self,
        ui: &mut egui::Ui,
        commands: &mut CommandSet,
        open_picker: Option<OpenPicker>,
        canvas_action: Option<Action>,
    ) -> Option<Action> {
        let ctx_owned = ui.ctx().clone();
        let ctx = &ctx_owned;
        let mut action = canvas_action;
        let viewport = self.canvas.viewport();
        // §3.6 is a pointer-platform duplicate of the bar, so the gesture is
        // read where the canvas is: a right-click over a floating piece of
        // chrome belongs to that piece, and a right *drag* pans instead.
        let right_click = RightClick::from(
            self.canvas.canvas_hovered() && ctx.input(|i| i.pointer.secondary_clicked()),
        );
        let selection = self
            .selection_screen_bounds
            .zip(self.session.tool.selection())
            .map(|(screen, sel)| Selection {
                screen: screen.egui(),
                count: sel.count(),
            });
        let (overlay_action, overlay_corner) = {
            let indexed = self
                .session
                .doc_index
                .view(viewed(&self.session.doc, self.session.time_machine.as_ref()).document());
            let drawing = Drawing::new(
                indexed,
                &self.session.path,
                &mut self.session.presentation,
                &mut self.session.gesture,
            );
            selection_overlay(
                ui,
                crate::panels::overlay::Overlay {
                    commands,
                    data: &drawing,
                    theme: &self.session.theme,
                    open_picker,
                    selection,
                    safe: self.safe,
                    camera: self.canvas.camera(),
                    right_click,
                },
            )
        };
        if let Some(overlay_action) = overlay_action {
            action = Some(overlay_action);
        }
        self.overlay_top_right = overlay_corner.map(IntoGeom::geom);
        // A popup can't outlive the selection it targets.
        if overlay_corner.is_none() {
            self.popup = None;
        }
        // The command palette: Ctrl+K toggles it; a picked row joins the
        // action flow like any overlay button.
        let palette_toggle = egui::KeyboardShortcut::new(egui::Modifiers::COMMAND, egui::Key::K);
        if ctx.input_mut(|i| i.consume_shortcut(&palette_toggle)) {
            self.palette = match self.palette {
                None => Some(Palette::new()),
                Some(_) => None,
            };
        }
        let indexed = self
            .session
            .doc_index
            .view(viewed(&self.session.doc, self.session.time_machine.as_ref()).document());
        // Built only for an open palette: the rows are the whole
        // document's history, and nothing else in the frame needs them
        // read per frame.
        let revs = match self.palette {
            Some(_) => {
                blockworx_store::history::rows(self.session.doc.journal(), self.session.doc.tags())
            }
            None => Vec::new(),
        };
        let scope = crate::panels::palette::PaletteScope {
            document: &indexed,
            path: &self.session.path,
            revs: &revs,
        };
        let outcome = self
            .palette
            .as_mut()
            .map(|palette| palette.show(ctx, commands, scope, viewport.egui()));
        match outcome {
            None | Some(PaletteOutcome::Open) => {}
            Some(PaletteOutcome::Close) => self.palette = None,
            Some(PaletteOutcome::Dispatch(palette_action)) => {
                action = Some(*palette_action);
                self.palette = None;
            }
        }
        // Nothing docked hangs over the canvas, so the notices sit against
        // its own top edge.
        self.show_document_notices(ui, viewport, Rect::NOTHING);
        action
    }

    /// The top bar: the document menu and its name, the liveness dot, the
    /// breadcrumb, the viewing mode, and the right-hand actions (§2.0).
    fn show_top_bar(
        &mut self,
        chrome: &mut crate::shell::Chrome,
        commands: &mut CommandSet,
    ) -> Option<Action> {
        let name = self.document_name();
        let names = self.session.scope_names();
        let viewing = self.session.viewing();
        // The rev's own row, so the bar's age is the history panel's, read
        // the same way from the same rows.
        let age = match viewing {
            blockworx_store::doc::Viewing::Head => None,
            blockworx_store::doc::Viewing::Past(at) => {
                let rows = blockworx_store::history::rows(
                    self.session.doc.journal(),
                    self.session.doc.tags(),
                );
                rows.iter()
                    .find(|row| row.rev == at)
                    .map(|row| row.since(blockworx_store::history::now()))
            }
        };
        let Consequences { undo, redo } = self.session.consequences();
        #[cfg(not(target_arch = "wasm32"))]
        let renaming = self.session.doc.renaming();
        #[cfg(not(target_arch = "wasm32"))]
        let home = self.session.doc.container_root();
        let clicked = crate::shell::top_bar::top_bar(
            chrome,
            commands,
            crate::shell::top_bar::TopBar {
                name: &name,
                scope: crate::shell::top_bar::Scope {
                    path: &self.session.path,
                    names: &names,
                },
                steps: crate::shell::top_bar::UndoSteps { undo, redo },
                lens: crate::shell::top_bar::Lens {
                    viewing,
                    head: self.session.doc.repo().rev(),
                    age: age.as_deref().unwrap_or_default(),
                },
                liveness: crate::shell::top_bar::Liveness::of(
                    viewing,
                    self.session.doc.writability(),
                    self.session.doc.projection(),
                ),
                navigator: self.workspace.open().into(),
                theme: &self.session.theme,
                prefs: &mut self.preferences,
                #[cfg(not(target_arch = "wasm32"))]
                recent: self.recent.paths(),
                #[cfg(not(target_arch = "wasm32"))]
                document: crate::shell::top_bar::Document {
                    draft: &mut self.rename_draft,
                    renaming,
                    home,
                },
            },
        );
        if clicked.browse {
            self.workspace.toggle();
        }
        clicked.action
    }

    /// The status line: §2.0.1's four states, resolved by the module that
    /// owns the priority between them.
    fn show_status_line(&mut self, chrome: &mut crate::shell::Chrome) {
        let cursor = self
            .canvas
            .canvas_hovered()
            .then(|| self.session.hovered_world().map(GridCell::at))
            .flatten();
        crate::shell::status_line::status_line(
            chrome,
            crate::shell::status_line::Reading {
                tool: crate::tools::names::instruction(crate::tools::names::displayed_tool(
                    self.session.tool.name(),
                )),
                selection: self.selection_path(),
                zoom: self.canvas.zoom(),
                cursor,
                title: self.title_line(),
            },
        );
    }

    /// What is selected, as a path — the ephemeral half of §2.0.1, 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 selection_path(&mut self) -> Option<String> {
        let count = self.session.tool.selection().map_or(0, |sel| sel.count());
        if count == 0 {
            return None;
        }
        let named = (count == 1)
            .then(|| {
                let shape = self
                    .session
                    .tool
                    .selection()?
                    .shapes()?
                    .into_iter()
                    .next()?;
                let title = self
                    .session
                    .drawing()
                    .shape(shape)?
                    .title()?
                    .name
                    .to_owned();
                let mut path = self.session.scope_names();
                path.push(title);
                Some(path.join(&format!(" {SELECTION_SEPARATOR} ")))
            })
            .flatten();
        Some(named.unwrap_or_else(|| format!("{count} selected")))
    }

    /// Say what this frame did, where the document moved (§2.0.1's fourth
    /// state, R43).
    ///
    /// Asked of the whole frame rather than of the dispatch, because most
    /// edits are a tool's gesture sealing on the canvas rather than an action
    /// anybody named. And read off the log rather than off what did it: the
    /// label is the one the commit itself carries, so the confirmation and
    /// the history row word one edit the same way, and a frame that turned
    /// out to write nothing says nothing.
    fn confirm_what_landed(&mut self, ctx: &egui::Context, stood: blockworx_doc::rev::Rev) {
        let take_back = self.session.doc.trail().next_undo();
        let repo = self.session.doc.repo();
        let now = repo.rev();
        if now == stood {
            return;
        }
        let said = match crate::kernel::session::step_label(&self.session.doc, take_back) {
            Some(label) => format!("{label} \u{2014} rev {}", now.get()),
            None => format!("Rev {}", now.get()),
        };
        crate::shell::status_line::say(ctx, said);
    }

    /// Put the navigator away, because the user is going back to work (§8).
    ///
    /// More than shutting it: the Hierarchy filter is a transient search, not
    /// a persistent view, so it goes too — which supersedes §9's "survives
    /// Escape" for this panel, on spec v3's own instruction.
    fn dismiss_navigator(&mut self, ctx: &egui::Context) {
        if !self.workspace.open() {
            return;
        }
        self.workspace.close();
        crate::panels::nav_tree::clear_filter(ctx);
    }

    /// The navigator's body: whichever view its segments have open.
    fn show_navigator_body(&mut self, ui: &mut egui::Ui) -> Option<Action> {
        let view = self.workspace.view;
        match view {
            crate::shell::workspace::PanelView::History => {
                let viewing = self.session.viewing();
                let Self {
                    session,
                    history_search,
                    ..
                } = self;
                let (doc, theme) = (&session.doc, &session.theme);
                let rows = blockworx_store::history::rows(doc.journal(), doc.tags());
                crate::panels::history_panel::body(
                    ui,
                    crate::panels::history_panel::HistoryPanel {
                        scene: crate::panels::history_panel::HistoryScene {
                            rows: &rows,
                            viewing,
                            head: doc.repo().rev(),
                            now: blockworx_store::history::now(),
                            theme,
                        },
                        search: history_search,
                    },
                )
            }
            crate::shell::workspace::PanelView::Hierarchy => {
                let selected_blocks: Vec<BlockId> = self
                    .session
                    .tool
                    .selection()
                    .and_then(|d| d.shapes())
                    .unwrap_or_default()
                    .into_iter()
                    .filter_map(ShapeId::block)
                    .collect();
                let indexed = self
                    .session
                    .doc_index
                    .view(viewed(&self.session.doc, self.session.time_machine.as_ref()).document());
                crate::panels::nav_tree::body(
                    ui,
                    crate::panels::nav_tree::NavScene {
                        document: &indexed,
                        path: &self.session.path,
                        selected: &selected_blocks,
                        theme: &self.session.theme,
                    },
                )
            }
        }
    }

    /// What the drawing's title block is stamped with: what the document is
    /// called, who is drawing it, which rev is on the canvas — the current
    /// one, or the one the time machine is showing — and when that rev was
    /// written. The same statement the printed sheet's block carries, since
    /// both are drawn from it.
    fn title_block(&self) -> crate::tools::title_block::TitleBlock {
        let rev = self.session.viewed_repo().rev();
        crate::tools::title_block::TitleBlock {
            name: self.document_name(),
            author: self.session.identity.name.clone(),
            rev,
            date: self.date_of(rev),
            from: self.opened_from(),
        }
    }

    /// 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.
    // The browser has only the scratch arm, which keeps no rows.
    #[cfg_attr(target_arch = "wasm32", expect(unused_variables))]
    fn written_at(
        &self,
        rev: blockworx_doc::rev::Rev,
    ) -> Option<blockworx_store::record::WallTime> {
        match &self.session.doc {
            Doc::Scratch { .. } => None,
            #[cfg(not(target_arch = "wasm32"))]
            Doc::Attached { store, .. } => store.row(rev).map(|row| row.wall_time),
        }
    }

    /// The date `rev` was written — the title block's Date row.
    fn date_of(&self, rev: blockworx_doc::rev::Rev) -> Option<String> {
        self.written_at(rev).map(blockworx_store::history::date)
    }

    /// The status line's own title block (R51): 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.
    fn title_line(&self) -> crate::shell::status_line::TitleBlock {
        let rev = self.session.viewed_repo().rev();
        crate::shell::status_line::TitleBlock {
            author: self.session.identity.name.clone(),
            rev,
            written: self
                .written_at(rev)
                .map(blockworx_store::history::written_at)
                .unwrap_or_default(),
        }
    }

    /// Where this session's document came from, when it was opened from an
    /// export (D19). The web build opens no files, so nothing there has a
    /// provenance to carry.
    // See `document_name`: the web build opens no files.
    #[cfg_attr(target_arch = "wasm32", allow(clippy::unused_self))]
    fn opened_from(&self) -> Option<blockworx_store::projection::Provenance> {
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.opened_from.clone()
        }
        #[cfg(target_arch = "wasm32")]
        {
            None
        }
    }

    /// Why the canvas is read-only, what the next save overwrites, and the
    /// loads that did not work — hung below `above`, the chrome band along the
    /// top of the canvas, which they may never cover. Drawn only when there is
    /// something to say, so an ordinary session says nothing at all.
    ///
    /// A past rev on the canvas is *not* said here: it is stamped across
    /// the drawing itself, and every way out of it is in the history
    /// cluster. What is left is the container's own facts.
    fn show_document_notices(&mut self, ui: &mut egui::Ui, viewport: Rect, above: Rect) {
        let notices = self.notices();
        if let Some(crate::panels::notices::Acknowledged(failure)) =
            crate::panels::notices::draw(ui, viewport.egui(), above.egui(), &notices)
        {
            self.failures.remove(failure);
        }
    }

    /// What this session has to tell the user: its failures first, since a
    /// failure is news, then the standing facts about its files.
    fn notices(&self) -> Vec<crate::panels::notices::Notice> {
        use crate::panels::notices::Notice;
        self.failures
            .iter()
            .map(|failure| Notice::Failure(failure.clone()))
            .chain(self.file_notices().into_iter().map(Notice::Standing))
            .collect()
    }

    /// The standing facts about the files under this document. The browser has
    /// none, so it has nothing to say.
    #[cfg(not(target_arch = "wasm32"))]
    fn file_notices(&self) -> Vec<String> {
        use blockworx_store::projection::Freshness;
        let mut notices = Vec::new();
        if let Some(reason) = self.session.doc.read_only_reason() {
            notices.push(format!("Read-only \u{2014} {reason}"));
        }
        if self.session.doc.projection() == Some(Freshness::Unrecognized) {
            notices.push(format!(
                "{} was not written by a fold of this log \u{2014} the next save overwrites it",
                blockworx_store::container::PROJECTION,
            ));
        }
        notices
    }

    #[cfg(target_arch = "wasm32")]
    #[expect(clippy::unused_self, reason = "the native arm reads the container")]
    fn file_notices(&self) -> Vec<String> {
        Vec::new()
    }

    /// Say on the canvas — and on the console — that something did not work.
    /// It stands until the user acknowledges it, or until the document it was
    /// about is replaced.
    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
    fn report_failure(&mut self, failure: String) {
        tracing::error!("{failure}");
        self.failures.push(failure);
    }

    /// Keyboard copy/paste/undo/nudge, independent of the mouse-driven actions.
    /// Skipped while a rename `TextEdit` holds focus so Cmd+C/V edits its text
    /// instead of the canvas selection (the canvas itself runs unfocused).
    fn handle_keyboard(&self, ctx: &egui::Context) -> Option<Action> {
        use egui::{Key, KeyboardShortcut, Modifiers};
        if ctx.egui_wants_keyboard_input() {
            return None;
        }
        let redo_z = KeyboardShortcut::new(Modifiers::COMMAND | Modifiers::SHIFT, Key::Z);
        let redo_y = KeyboardShortcut::new(Modifiers::COMMAND, Key::Y);
        let undo_z = KeyboardShortcut::new(Modifiers::COMMAND, Key::Z);
        let paste_txt = latest_paste(ctx);
        // Copy is the one chord a read-only session keeps: it is how the
        // time machine pays off (copy out of the past, paste into the
        // present). The chords are consumed either way, so a withheld one
        // does nothing rather than falling through to another handler.
        let writable = self.session.may_write() == blockworx_store::doc::Writability::Writable;
        if ctx.input_mut(|i| i.consume_shortcut(&redo_z) || i.consume_shortcut(&redo_y)) {
            // Not gated on writability: the stack holds §7.1's two kinds, and
            // taking back a camera move costs the log nothing — so the chord
            // dispatches and `step_history` refuses only what would author.
            Some(Action::Redo)
        } else if ctx.input_mut(|i| i.consume_shortcut(&undo_z)) {
            Some(Action::Undo)
        } else if let Some(text) = paste_txt {
            writable.then_some(Action::Paste(text))
        } else if ctx.input(|i| i.events.iter().any(|e| matches!(e, egui::Event::Copy))) {
            match self.session.tool.selection() {
                Some(Deletable::Pins(pins)) => Some(Action::CopyPins(pins)),
                other => other.and_then(|d| d.shapes()).map(Action::Copy),
            }
        } else if writable && self.session.tool.selection().is_some() {
            arrow_nudge(ctx)
        } else {
            None
        }
    }

    /// Apply one action: the single place a frame's requests — from the tool,
    /// the chrome, or the keyboard — take effect on the document and app state.
    fn dispatch_action(&mut self, ctx: &egui::Context, action: Action) {
        // The session answers everything that is about the document or where
        // the editor is standing; what comes back is what only a surface can
        // do — a dialog, an export thread, a picker window, a camera the view
        // eases into place.
        let was = self.session.viewing();
        let unhandled = self.session.dispatch(action);
        if self.session.viewing() != was {
            // `settle_on_viewed` dropped the selection the popup hangs off.
            self.popup = None;
        }
        if let Some(json) = self.session.take_clipboard() {
            ctx.copy_text(json);
        }
        self.apply_framings(ctx);
        let Some(action) = unhandled else {
            return;
        };
        match action {
            Action::OpenRolePicker { target } => self.open_popup(ctx, Popup::Role(target)),
            Action::OpenPinTypePicker { pins } => self.open_popup(ctx, Popup::PinType(pins)),
            Action::Camera(rect) => self.canvas.fit_to_rect_instant(rect),
            Action::Export { format, selection } => self.export(ctx, format, selection),
            Action::ExportRev { at, to } => self.export_rev(ctx, at, to),
            Action::Import => {
                self.pending_import = Some(crate::import::spawn_import_dialog(ctx));
            }
            Action::PickImage(target) => {
                self.pending_image = Some((target, crate::import::spawn_image_dialog(ctx)));
            }
            #[cfg(not(target_arch = "wasm32"))]
            Action::NewDocument => self.new_document(),
            #[cfg(not(target_arch = "wasm32"))]
            Action::RenameDocument(name) => self.rename_document(&name),
            #[cfg(not(target_arch = "wasm32"))]
            Action::PickFile(request) => {
                self.pending_file = Some(crate::file::spawn_file_dialog(ctx, request));
            }
            #[cfg(not(target_arch = "wasm32"))]
            Action::OpenRecent(root) => self.open_container(&root),
            // The browser has no container to project into, and
            // `Saving::Withheld` there keeps the command out of the registry
            // — so this arm is reachable only natively.
            Action::SaveProjection => {
                #[cfg(not(target_arch = "wasm32"))]
                self.save_projection();
            }
            other => unreachable!("the session answered {}", other.label()),
        }
    }

    /// Where the session sees the camera standing, this frame: the view's own
    /// vantage, the viewport it was laid out in, the region the chrome left
    /// clear, and whether the user worked it themselves.
    fn sighting(&self, ctx: &egui::Context) -> Sighting {
        Sighting {
            vantage: self.canvas.vantage(),
            viewport: self.canvas.viewport(),
            safe: self.safe.region().geom(),
            camera: if self.canvas.worked_camera() {
                CameraWork::Worked
            } else {
                CameraWork::Idle
            },
            pointer: ctx.pointer_hover_pos().map(IntoGeom::geom),
        }
    }

    /// Push where the camera stands into the session, so what it reads back
    /// this frame is where the view actually is.
    fn sync_camera(&mut self, ctx: &egui::Context) {
        let sighting = self.sighting(ctx);
        self.session.sees(sighting);
    }

    /// Apply the moves the session asked of the camera, and tell it where
    /// that left the view.
    fn apply_framings(&mut self, ctx: &egui::Context) {
        for framing in self.session.take_framings() {
            match framing {
                Framing::StandAt(vantage) => self.canvas.stand_at(vantage),
                Framing::Fit => self.session.fit_view(),
                Framing::BringIntoView(world, glide) => {
                    self.canvas.bring_into_view(world, glided(glide));
                }
                Framing::FocusOn(world, glide) => self.canvas.focus_on(world, glided(glide)),
                Framing::Zoom(step, anchor) => self.canvas.zoom_step(step, anchor),
            }
        }
        self.sync_camera(ctx);
    }

    /// Open a selection popup, replacing whatever was open. It renders from the
    /// top of the next frame so this opening click isn't read as a
    /// click-outside dismiss; the selection stays in the tool behind it.
    fn open_popup(&mut self, ctx: &egui::Context, popup: Popup) {
        self.popup = Some(popup);
        ctx.request_repaint();
    }

    /// Take `doc` as the session's document and settle everything that
    /// pointed at the last one. The handle it displaces drops here, which is
    /// what gives a container's lock back — there is nothing to save on the
    /// way out, since every commit was durable when it was made.
    #[cfg(not(target_arch = "wasm32"))]
    fn take_document(&mut self, doc: Doc) {
        let was = self.workspace_key();
        self.session.adopt(doc);
        // The store that just dropped gave a born container its lock back,
        // so one this session made and left behind can go now rather than
        // waiting for the exit.
        self.sweep_unclaimed();
        self.session.path = BlockPath::opening(self.session.doc.document());
        self.session.presentation = crate::presentation::Presentation::default();
        self.session.gesture = crate::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 (F6).
        self.session.undo_stack = crate::history::UndoStack::reconstructed(
            self.session.doc.trail(),
            &self.session.state(),
        );
        self.after_document_swap(&was);
    }

    /// File ▸ New: a document born attached, under a name of three words
    /// (D20). A container that cannot be created leaves the session on a
    /// scratch document — the editor opens either way — and says why.
    #[cfg(not(target_arch = "wasm32"))]
    fn new_document(&mut self) {
        self.opened = None;
        self.opened_from = None;
        match self.documents.create(blockworx_store::naming::entropy) {
            Ok(store) => {
                self.unclaimed.push(store.root().to_path_buf());
                self.take_document(Doc::attached(store));
            }
            Err(failure) => {
                // After the swap: adopting a document clears the notices
                // the last one collected, this one among them.
                self.take_document(Doc::default());
                self.report_failure(failure.notice());
            }
        }
    }

    /// Call this document something else, which renames its container (D20).
    /// The session carries straight on into it: the log it is appending to
    /// is held open, so the next edit lands in the renamed container.
    #[cfg(not(target_arch = "wasm32"))]
    fn rename_document(&mut self, name: &str) {
        let Some(root) = self.attached_root() else {
            self.report_failure("This session has no diagram on disk to rename".to_owned());
            return;
        };
        let Some(to) = crate::file::renamed_beside(&root, name) else {
            self.report_failure(format!("\u{201c}{name}\u{201d} is not a diagram name"));
            return;
        };
        if let Err(refusal) = self.session.doc.rename(&to) {
            self.report_failure(format!(
                "Failed to rename {}: {refusal}",
                crate::file::document_name(&root),
            ));
            return;
        }
        self.recent.forget(&root);
        // The panel state follows the document to its new name.
        self.settle_workspace(&crate::file::document_name(&root));
        // A name of the user's own is a claim on the document, so a
        // renamed container is never swept and joins the recent list.
        self.claim(&to);
    }

    /// A container this session created stops being unclaimed the moment
    /// the user commits to it — the first edit, or a name of their own —
    /// and joins the recent list then, so the list never fills with names
    /// nobody kept.
    #[cfg(not(target_arch = "wasm32"))]
    fn claim(&mut self, root: &Path) {
        self.unclaimed.retain(|born| born != root);
        self.recent.remember(root);
    }

    /// The first record in a born container's log is what claims it. Called
    /// from the write door, so every path that can write the first one —
    /// an edit, a paste, an import, a restore — goes through here.
    #[cfg(not(target_arch = "wasm32"))]
    fn claim_if_written(&mut self) {
        if self.unclaimed.is_empty() || self.session.doc.repo().log().is_empty() {
            return;
        }
        if let Some(root) = self.attached_root()
            && self.unclaimed.contains(&root)
        {
            self.claim(&root);
        }
    }

    /// D20's pristine cleanup, narrowed to what this session made: a
    /// container the user opened is theirs however empty it is, and
    /// deleting it would not be ours to decide. The one still open is left
    /// for the sweep on the way out, which runs after its store — and its
    /// lock — have been dropped.
    #[cfg(not(target_arch = "wasm32"))]
    fn sweep_unclaimed(&mut self) {
        use blockworx_store::container::{Discarded, discard_pristine};
        let open = self.attached_root();
        let mut still_open = Vec::new();
        for root in std::mem::take(&mut self.unclaimed) {
            if Some(&root) == open.as_ref() {
                still_open.push(root);
                continue;
            }
            match discard_pristine(&root) {
                Ok(Discarded::Removed) => {
                    tracing::info!("removed {}, which held no edit", root.display());
                }
                Ok(Discarded::Kept) => {}
                Err(e) => tracing::warn!("{} could not be tidied away: {e}", root.display()),
            }
        }
        self.unclaimed = still_open;
    }

    /// Open the container at `root`, or say why not. A held lock, a broken
    /// log and a failed write are outcomes rather than failures: the
    /// container opens read-only and the chrome carries the reason. Only a
    /// path that is no container — or has become one no longer — costs it
    /// its place in the recent list.
    #[cfg(not(target_arch = "wasm32"))]
    fn open_container(&mut self, root: &Path) {
        // The folder picker takes any folder, so the choice is judged here
        // rather than by the store's own "it has no log" complaint, which
        // answers a question the user did not ask.
        if let Some(refusal) = crate::file::refused_as_a_diagram(root) {
            self.report_failure(refusal);
            self.recent.forget(root);
            return;
        }
        match crate::file::open_container(root) {
            Ok(store) => {
                if let Some(reason) = store.read_only_reason() {
                    tracing::warn!("{} opened read-only: {reason}", root.display());
                }
                self.recent.remember(root);
                self.opened = None;
                self.take_document(Doc::attached(store));
            }
            Err(refusal) => {
                self.report_failure(format!("Failed to open {}: {refusal}", root.display()));
                self.recent.forget(root);
            }
        }
    }

    /// Open the shared diagram at `bundle`, which is always unpack-then-open:
    /// the working form is a directory, because a commit is an append and an
    /// fsync and the lock is a file another process can see (R54).
    ///
    /// It unpacks beside the zip, under the name the zip travelled under —
    /// where a file that arrived by e-mail is wanted, in the directory it was
    /// opened from. Where that name is taken, the destination becomes a
    /// question rather than a casualty: a second dialog, and nothing written
    /// until it is answered. The zip itself is never touched.
    #[cfg(not(target_arch = "wasm32"))]
    fn open_bundle(&mut self, ctx: &egui::Context, bundle: &Path) {
        match crate::file::unpacks_to(bundle) {
            crate::file::Landing::Beside(root) => self.unpack_and_open(bundle, &root),
            crate::file::Landing::Occupied(_) => {
                self.pending_file = Some(crate::file::spawn_file_dialog(
                    ctx,
                    crate::file::FileRequest::UnpackBundle(bundle.to_path_buf()),
                ));
            }
        }
    }

    /// Lay `bundle` out at `root` and open what came out of it, which is an
    /// ordinary container from there on — chain, stamp and replay are checked
    /// by the open it goes through, not by the unpack.
    #[cfg(not(target_arch = "wasm32"))]
    fn unpack_and_open(&mut self, bundle: &Path, root: &Path) {
        match crate::file::unpack_bundle(bundle, root) {
            Ok(()) => self.open_container(root),
            // Item 16's failure path, with the same shape its refusals have:
            // what was picked, and what was wrong with it.
            Err(why) => self.report_failure(format!(
                "{} is not a shared diagram: {why}",
                crate::file::container_name(bundle),
            )),
        }
    }

    /// Write the open container into one file at `to` — the transfer form
    /// (R54), whole history and no lock.
    #[cfg(not(target_arch = "wasm32"))]
    fn share_bundle(&mut self, ctx: &egui::Context, to: &Path) {
        let Some(root) = self.attached_root() else {
            // Unreachable through the menu, whose entry is disabled without
            // a container, and cheaper to answer than to prove.
            return self.report_failure("this session has no diagram on disk to share".to_owned());
        };
        match crate::file::share_container(&root, to) {
            // Routine, so the status line says it and the toast stays rare
            // (R43).
            Ok(()) => crate::shell::status_line::say(
                ctx,
                format!("Shared as {}", crate::file::container_name(to)),
            ),
            Err(why) => {
                tracing::error!("Failed to share {}: {why}", to.display());
                crate::shell::toast::say(
                    ctx,
                    format!(
                        "Could not share {}: {why}",
                        crate::file::document_name(&root),
                    ),
                );
            }
        }
    }

    /// Write this session's document into a container at `root` — the one
    /// save left, since an attached document is written as it is edited.
    ///
    /// Two paths, because a session with a log and a session without one are
    /// different problems. A container's log *is* its document, so `scope`'s
    /// rev is a cut in its lines and the save copies them: everything the
    /// records carry — wall times, authors, edit/undo/redo kinds, tags —
    /// comes over because nothing is rewritten (R37). A scratch session has
    /// only its commits, so those are seeded, and a cut is a prefix of them.
    #[cfg(not(target_arch = "wasm32"))]
    fn save_as_container(
        &mut self,
        ctx: &egui::Context,
        root: &Path,
        scope: crate::file::SaveScope,
    ) {
        use crate::file::SaveScope;
        let written = if let Some(source) = self.session.doc.container_root().map(Path::to_path_buf)
        {
            let at = match scope {
                SaveScope::Through(at) => at,
                SaveScope::Whole => self.session.doc.repo().rev(),
            };
            crate::file::save_container_through(&source, at, root, &self.session.identity)
                .map_err(|refusal| refusal.to_string())
        } else {
            let log = self.session.doc.repo().log();
            let through = match scope {
                SaveScope::Through(at) => at.get() as usize,
                SaveScope::Whole => log.len(),
            };
            let Some(prefix) = log.get(..through) else {
                // Unreachable through the menu, which reads the rev off the
                // canvas — and cheaper to answer than to prove.
                return self.report_failure(format!("this session has no rev {through}"));
            };
            crate::file::create_container(root, prefix, &self.session.identity)
                .map_err(|refusal| refusal.to_string())
        };
        match written {
            Ok(store) => {
                self.recent.remember(root);
                self.opened = None;
                self.session.adopt(Doc::attached(store));
                // The document is unchanged — only its home is — so the view
                // and the selection stay put. The undo stack cannot: what
                // this session may take back is whatever the new container's
                // own trail holds, which for a seeded one is nothing (the
                // commits are its past, not steps anybody took here) and for
                // a copied log is what replaying it gave back.
                self.session.undo_stack = crate::history::UndoStack::reconstructed(
                    self.session.doc.trail(),
                    &self.session.state(),
                );
                // A container the user just named should be readable from
                // the moment it exists, not from the first explicit save.
                self.save_projection();
                // What was on the canvas is now the head of a document this
                // session may write — which is the whole point of saving
                // from inside the lens, so the lens closes on it.
                self.session.view_head();
                // A save that worked is routine, so it is said in the
                // status line rather than raised as an attention event
                // (R43); the failure below still is one.
                crate::shell::status_line::say(ctx, saved_as(root, scope));
            }
            Err(refusal) => {
                // Toasted rather than pinned as a notice: nothing about the
                // session changed, so there is no standing fact to
                // acknowledge — only news, which is what a toast is for.
                tracing::error!("Failed to write {}: {refusal}", root.display());
                crate::shell::toast::say(
                    ctx,
                    format!(
                        "Could not save as {}: {refusal}",
                        crate::file::document_name(root),
                    ),
                );
            }
        }
    }

    /// Refresh `document.json` beside the log. The commits are already
    /// durable, so this cannot lose work; what it can do is overwrite a
    /// projection nobody recognizes, which is said out loud first.
    #[cfg(not(target_arch = "wasm32"))]
    fn save_projection(&mut self) {
        use blockworx_store::projection::Freshness;
        if self.session.doc.projection() == Some(Freshness::Unrecognized) {
            tracing::warn!(
                "overwriting a {} that no fold of this log wrote — a hand-edited \
                 projection comes back in through Import, never through a save",
                blockworx_store::container::PROJECTION,
            );
        }
        if let Err(refusal) = self.session.doc.save_projection() {
            self.report_failure(format!("Failed to write the diagram file: {refusal}"));
        }
    }

    /// Keep `document.json` fresh without a dirty state: a stale projection
    /// on a writable container is rewritten once the head has sat still for
    /// [`Self::PROJECTION_SETTLE`] — which also covers a projection a crash
    /// left behind, shortly after open. An Unrecognized (hand-edited) file
    /// stays guarded behind an explicit Save.
    #[cfg(not(target_arch = "wasm32"))]
    fn refresh_projection(&mut self, ctx: &egui::Context) {
        self.refresh_projection_at(ctx, std::time::Instant::now());
    }

    #[cfg(not(target_arch = "wasm32"))]
    fn refresh_projection_at(&mut self, ctx: &egui::Context, now: std::time::Instant) {
        use blockworx_store::projection::Freshness;
        if self.session.doc.projection() != Some(Freshness::Stale)
            || self.session.doc.read_only_reason().is_some()
        {
            self.head_moved = None;
            return;
        }
        let head = self.session.doc.repo().rev();
        let since = match self.head_moved {
            Some((seen, at)) if seen == head => at,
            _ => now,
        };
        self.head_moved = Some((head, since));
        let waited = now.duration_since(since);
        match Self::PROJECTION_SETTLE.checked_sub(waited) {
            None | Some(core::time::Duration::ZERO) => {
                self.save_projection();
                self.head_moved = None;
            }
            Some(remaining) => ctx.request_repaint_after(remaining),
        }
    }

    /// How long the head sits still before the projection follows it.
    #[cfg(not(target_arch = "wasm32"))]
    const PROJECTION_SETTLE: core::time::Duration = core::time::Duration::from_secs(2);

    /// Deliver a File-menu pick once its off-thread dialog resolves.
    #[cfg(not(target_arch = "wasm32"))]
    fn poll_pending_file(&mut self, ctx: &egui::Context) {
        let Some(rx) = &self.pending_file else {
            return;
        };
        match rx.try_recv() {
            Ok(Some(pick)) => {
                self.pending_file = None;
                match pick {
                    crate::file::FilePick::Container(root) => self.open_container(&root),
                    crate::file::FilePick::Bundle(bundle) => self.open_bundle(ctx, &bundle),
                    crate::file::FilePick::UnpackedInto(bundle, root) => {
                        self.unpack_and_open(&bundle, &root);
                    }
                    crate::file::FilePick::NewContainer(root, scope) => {
                        self.save_as_container(ctx, &root, scope);
                    }
                    crate::file::FilePick::NewBundle(to) => self.share_bundle(ctx, &to),
                }
            }
            // A cancelled dialog and a dropped sender both end the pick.
            Ok(None) | Err(std::sync::mpsc::TryRecvError::Disconnected) => {
                self.pending_file = None;
            }
            // See `poll_pending_import`: a native picker can sit open for
            // minutes, so poll it gently.
            Err(std::sync::mpsc::TryRecvError::Empty) => {
                ctx.request_repaint_after(std::time::Duration::from_millis(100));
            }
        }
    }

    /// Deliver a picked import file once the off-thread dialog resolves.
    fn poll_pending_import(&mut self, ctx: &egui::Context) {
        let Some(rx) = &self.pending_import else {
            return;
        };
        match rx.try_recv() {
            Ok(Some((name, bytes))) => {
                self.pending_import = None;
                self.session.handle_imported(&name, bytes);
            }
            // A cancelled dialog and a dropped sender both end the import.
            Ok(None) | Err(std::sync::mpsc::TryRecvError::Disconnected) => {
                self.pending_import = None;
            }
            // Poll the open dialog at a gentle cadence, not per-frame —
            // a native picker can sit open for minutes.
            Err(std::sync::mpsc::TryRecvError::Empty) => {
                ctx.request_repaint_after(std::time::Duration::from_millis(100));
            }
        }
    }

    /// Deliver a picked image once the off-thread dialog resolves — to the
    /// same target the request carried, so a pick that took minutes still
    /// lands where the gesture that asked for it meant it to.
    fn poll_pending_image(&mut self, ctx: &egui::Context) {
        let Some((_, rx)) = &self.pending_image else {
            return;
        };
        match rx.try_recv() {
            Ok(asset) => {
                if let Some((target, _)) = self.pending_image.take() {
                    self.dispatch_action(ctx, Action::ImagePicked { target, asset });
                }
            }
            // A dropped sender ends the pick with nothing to place.
            Err(std::sync::mpsc::TryRecvError::Disconnected) => {
                self.pending_image = None;
            }
            // See `poll_pending_import`: a native picker can sit open for
            // minutes, so poll it gently.
            Err(std::sync::mpsc::TryRecvError::Empty) => {
                ctx.request_repaint_after(std::time::Duration::from_millis(100));
            }
        }
    }

    /// What a cell carried off the tool cluster and released comes to: a
    /// stamp at the drop point, in the canvas's own coordinates.
    ///
    /// `None` where the drop landed on the glass, on the navigator, or off the
    /// window — the gesture ends and the cell springs back, because a
    /// release the canvas never saw must not become a thing on it.
    fn dropped(
        &self,
        ctx: &egui::Context,
        carried: crate::shell::tool_cluster::DragOut,
    ) -> Option<Action> {
        let onto_the_canvas = self.canvas.viewport().contains(carried.at.geom())
            && !crate::shell::over_the_chrome(ctx, carried.at);
        onto_the_canvas.then(|| Action::StampTool {
            tool: carried.tool,
            at: self.canvas.screen_to_world_pos(carried.at.geom()),
        })
    }

    /// One frame of the whole editor: the floating chrome of
    /// `docs/cad-ui-spec.md` §2, then the canvas edge to edge underneath it.
    ///
    /// The chrome is drawn *before* the canvas so its boxes are measured by
    /// the time a framing needs them — nothing is docked, so fit-to-view has
    /// only the safe area to keep the drawing off the glass (§2.1). The z
    /// order is the layers': every piece is an [`egui::Area`], which paints
    /// and hit-tests above the canvas's background layer whatever order the
    /// code draws them in.
    ///
    /// Split out of [`eframe::App::ui`] so a test can drive a real frame
    /// without an `eframe::Frame` to hand.
    pub(crate) fn shell_frame(&mut self, ui: &mut egui::Ui) {
        let _frame_span = tracing::info_span!("frame").entered();
        // The phases below drive popups and keyboard handling through the
        // `Context`, so bind it once. The clone is a cheap `Arc` bump and keeps
        // `ctx` a `&Context` without holding a borrow on `ui`, which the canvas
        // still needs mutably.
        let ctx_owned = ui.ctx().clone();
        let ctx = &ctx_owned;
        // Apply appearance preferences (theme/mode/font/visuals/zoom) before
        // drawing, so this frame renders with the current look.
        self.apply_preferences(ctx);
        // Where the camera stands, as of this frame — and any move the session
        // asked for outside one. The session reads the vantage back for the
        // undo stack's entry and for the world the pointer is in; it asks for
        // moves through here rather than holding a camera of its own.
        self.apply_framings(ctx);
        #[cfg(not(target_arch = "wasm32"))]
        self.refresh_projection(ctx);
        #[cfg(not(target_arch = "wasm32"))]
        self.apply_window_title(ctx);
        // Popups first: they read the overlay corner the chrome captured last
        // frame, and the picker they report is what the chrome shows as active.
        let (open_picker, picked) = self.show_popups(ctx);
        self.show_editor_windows(ctx);
        if !self.images_loaded {
            self.canvas.register_icons(ctx);
            self.images_loaded = true;
        }
        // Before the canvas: the interception has to reach the Paste event
        // ahead of the focused editor, and runs outside the canvas's borrow of
        // the document.
        let object_paste = self.intercept_object_paste(ctx);
        // The undo stack's frame: everything from here to the end of dispatch
        // is one step, whether it edits the document, moves the view, or both.
        let view_before = self.session.state();
        // Where the log stood before any of it, so the status line can say what
        // landed however it landed — a dispatched action, or a tool's own
        // gesture sealing on the canvas.
        let stood = self.session.doc.repo().rev();

        // One registry for the whole frame, so no two bands can disagree about
        // what is available.
        let current_lock: InterfaceLock = self.session.drawing().current_locked().into();
        let mut commands = self.session.available_commands(current_lock);
        // Tool chords dispatch through the registry like any button; gated
        // off while a text field owns the keyboard.
        let mut chrome_action = if !ctx.egui_wants_keyboard_input()
            && let Some(id) = crate::keys::consume_binding(ctx)
        {
            commands.take(id)
        } else {
            None
        };
        let mut band = |action: Option<Action>| {
            if action.is_some() {
                chrome_action = action;
            }
        };

        // Nothing reflows the canvas, so it is the whole of what this `Ui`
        // holds and the chrome stands over it.
        //
        // Escape is claimed in the spec's own order: the navigator closes
        // before anything else reads the key (§8), and only then does the
        // lens hear it. Both are claimed before the canvas pass, so a tool
        // armed before either opened cannot answer the key first.
        if crate::shell::navigator::escape_closes(ctx, self.workspace.open().into()) {
            self.dismiss_navigator(ctx);
        } else if let blockworx_store::doc::Viewing::Past(_) = self.session.viewing() {
            band(crate::shell::top_bar::escape_exits(ctx));
        }
        let mut chrome = crate::shell::Chrome::over(ctx, ui.max_rect());
        band(self.show_top_bar(&mut chrome, &mut commands));
        {
            let frame = crate::shell::tool_cluster::tool_cluster(
                &mut chrome,
                &mut commands,
                crate::shell::tool_cluster::ToolCluster {
                    selected: crate::tools::names::displayed_tool(self.session.tool.name()),
                    viewing: self.session.viewing(),
                },
            );
            // §8: a tool pick is unambiguous intent to edit, and editing is
            // not possible while the navigator is up, so it closes.
            if frame.action.is_some() || frame.drag_out.is_some() {
                self.dismiss_navigator(ctx);
            }
            band(frame.action);
            if let Some(carried) = frame.drag_out {
                band(self.dropped(ctx, carried));
            }
        }
        {
            // Drawn every frame, not only while it is open: it slides in and
            // out, so the frames after it is put away still hold a panel.
            //
            // The navigator edits the state its segments own; the body needs
            // the rest of the app, so the two cannot borrow `self` at once.
            // The state is `Copy`, so it goes in and comes back out.
            let mut state = self.workspace;
            let drawn = crate::shell::navigator::navigator(&mut chrome, &mut state, |ui| {
                self.show_navigator_body(ui)
            });
            self.workspace = state;
            if drawn.dismissed {
                // The press is *not* spent (§8): a canvas click dismisses
                // and performs its selection in the one gesture, so it goes
                // on to the canvas underneath.
                self.dismiss_navigator(ctx);
            }
            band(drawn.action);
        }
        self.show_status_line(&mut chrome);
        // The toast is not a piece of the frame: it says what needs
        // attention, cannot be pressed, and takes no room — so it is drawn
        // beside the chrome rather than measured with it (R38, R43).
        crate::shell::toast::toast(ctx, &self.session.theme);
        // Measured, never cached: the navigator opening or closing moves this
        // in the frame it happens, and the framing below reads it fresh
        // (§2.1).
        self.safe = chrome.safe();
        self.canvas.set_safe_region(self.safe.region().geom());
        // The canvas, edge to edge under the glass.
        egui::CentralPanel::no_frame().show(ui, |ui| {
            let frame = self.show_canvas(ui);
            band(self.show_canvas_chrome(ui, &mut commands, open_picker, frame));
        });
        // The canvas pass is where the pan, the wheel and any owed fit reach
        // the camera, so the entry the stack takes below is measured from
        // where they left it.
        self.sync_camera(ctx);

        // An intercepted object paste wins over whatever the frame asked for,
        // so the object lands even when an editor was focused; the keyboard
        // only speaks when nothing else did.
        // A pick outranks the chrome and the keyboard: the popup is in front,
        // so a click that reached it was meant for it.
        let action = match object_paste {
            Some(text) => Some(Action::Paste(text)),
            None => picked
                .or(chrome_action)
                .or_else(|| self.handle_keyboard(ctx)),
        };
        if let Some(action) = action {
            self.dispatch_action(ctx, action);
        }
        // A tool's own frame can ask for one too (a paste brought into view).
        self.apply_framings(ctx);
        if let Some(after) = self.session.take_repaint() {
            ctx.request_repaint_after(after);
        }
        self.confirm_what_landed(ctx, stood);
        self.session.record_history(&view_before, now(ctx));
        self.poll_pending_import(ctx);
        self.poll_pending_image(ctx);
        #[cfg(not(target_arch = "wasm32"))]
        self.poll_pending_file(ctx);
        // The first record in a born container's log is what claims it, and
        // every door that can write it — an edit, a paste, an import, a
        // restore — has run by now.
        #[cfg(not(target_arch = "wasm32"))]
        self.claim_if_written();
    }

    /// Which document the workspace's panel state belongs to (spec §5.1).
    fn workspace_key(&self) -> String {
        self.document_name()
    }

    /// Adopt the workspace state the document now open was last left with,
    /// filing away the one the document leaving carried. Called wherever the
    /// document is replaced or renamed, so a panel never follows the wrong
    /// document. Both of those are container doors, which the browser has
    /// none of.
    #[cfg(not(target_arch = "wasm32"))]
    fn settle_workspace(&mut self, was: &str) {
        self.workspaces.insert(was.to_owned(), self.workspace);
        let key = self.workspace_key();
        self.workspace = self.workspaces.get(&key).copied().unwrap_or_default();
    }
}

impl eframe::App for App {
    /// Persist the appearance preferences to the eframe storage DB. eframe calls
    /// this periodically and on exit (the `persistence` feature is enabled); the
    /// blob is read back in `main` on the next launch.
    fn save(&mut self, storage: &mut dyn eframe::Storage) {
        match serde_json::to_string(&self.preferences) {
            Ok(s) => storage.set_string("preferences", s),
            Err(e) => tracing::error!("Failed to serialize preferences: {e}"),
        }
        self.workspaces.insert(self.workspace_key(), self.workspace);
        match serde_json::to_string(&self.workspaces) {
            Ok(s) => storage.set_string(WORKSPACES, s),
            Err(e) => tracing::error!("Failed to serialize workspaces: {e}"),
        }
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.recent.save(storage);
        }
    }

    // The dev editors write into the source tree, which the browser has no
    // access to — and eframe does not reliably call `on_exit` there anyway.
    // The document itself goes nowhere on exit: the log is the document
    // (F5), so there is nothing here to write back.
    #[cfg(not(target_arch = "wasm32"))]
    fn on_exit(&mut self) {
        // Persist theme tweaks if the editor was open when the app quit (closing
        // just the editor window already saved via `ui`).
        if self.theme_editor {
            self.save_theme();
        }
        if self.font_editor {
            self.save_font_sizes();
        }
        // A clean exit is one of the three moments the projection is
        // refreshed (D11) — the document itself needs nothing written, since
        // every commit was durable when it was made (F5).
        if self.session.doc.saving() == blockworx_store::doc::Saving::Offered {
            self.save_projection();
        }
        // A container's lock is its store's lifetime, and eframe does not
        // promise to drop the app on every platform: give it back here
        // rather than leave the next session to find a stale one.
        self.session.doc = Doc::default();
        // D20: a container this session invented and nobody wrote in goes
        // with it, so launching and quitting leaves no litter behind.
        self.sweep_unclaimed();
    }

    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        self.shell_frame(ui);
    }
}

#[cfg(test)]
mod tests {
    use super::{App, AppConfig, BlockPath, Cursor, FontChoice, PointerOver, effective_cursor};
    use crate::canvas::convert::{IntoEgui as _, IntoGeom as _};
    use crate::tools::tool::Action;
    use blockworx_geom::{Pos2, Rect, Vec2, pos2, vec2};

    /// egui's own Cmd+Plus/Minus/0 handler scales the whole UI, which would
    /// both fight the widget-size preference and swallow the canvas's zoom
    /// chords. Applying preferences turns it off.
    #[test]
    fn applying_preferences_leaves_the_zoom_chords_to_the_canvas() {
        let ctx = egui::Context::default();
        assert!(
            ctx.options(|o| o.zoom_with_keyboard),
            "egui's default changed; the override below may be moot"
        );
        let mut app = App::new(AppConfig::default());
        app.apply_preferences(&ctx);
        assert!(!ctx.options(|o| o.zoom_with_keyboard));
    }

    /// D5: the app always holds a document. With nowhere to be born — the
    /// browser, and a session driving the editor without a filesystem —
    /// that is an in-process repo, open from the first frame.
    #[test]
    fn booting_opens_an_in_process_repo() {
        let app = App::new(AppConfig::default());
        assert_eq!(
            app.session.doc.repo().rev().get(),
            0,
            "a fresh repo starts on an empty document",
        );
    }

    /// A context the whole shell can be driven in: the app's own fonts and
    /// the image loaders its icons need. A canvas pass that paints text into
    /// a context without them panics rather than laying out.
    fn shell_ctx() -> egui::Context {
        let ctx = egui::Context::default();
        ctx.set_fonts(crate::canvas::build_fonts(FontChoice::default()));
        egui_extras::install_image_loaders(&ctx);
        ctx
    }

    /// Drive `app` through real frames on a `screen`-sized viewport, so the
    /// bands measure themselves and the canvas lands where they leave it.
    fn shell_frames(app: &mut App, ctx: &egui::Context, screen: Rect, frames: usize) {
        for frame in 0..frames {
            ctx.clone()
                .run_ui(
                    egui::RawInput {
                        screen_rect: Some(screen.egui()),
                        #[expect(
                            clippy::cast_precision_loss,
                            reason = "a frame count, not a measurement"
                        )]
                        // A coarse clock, so the shell's longest motion — the
                        // navigator's slide — is over before anything is measured.
                        time: Some(frame as f64 * 0.12),
                        ..Default::default()
                    },
                    |ui| app.shell_frame(ui),
                )
                .drop_without_applying_deltas();
        }
    }

    /// The canvas runs edge to edge: nothing is docked, so the drawing
    /// surface *is* the window and the chrome floats over it (§2).
    #[test]
    fn the_canvas_runs_edge_to_edge_under_the_chrome() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        // The busy picture: the navigator open, which is the case that takes
        // the most room from the drawing.
        app.workspace.show(PanelView::History);
        let ctx = shell_ctx();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        shell_frames(&mut app, &ctx, screen, 8);

        let canvas = app.canvas.viewport();
        assert!(
            canvas.is_positive(),
            "the canvas never laid out: {canvas:?}"
        );
        assert_eq!(
            canvas.size(),
            screen.size(),
            "something is still docked: the canvas is {canvas:?} of {screen:?}",
        );
        assert_eq!(
            every_piece_laid_out(&ctx).len(),
            crate::shell::Berth::ALL.len(),
            "the frame drew fewer pieces than §2's table lists: {:?}",
            every_piece_laid_out(&ctx),
        );
    }

    /// §2.1, the load-bearing one: a fit frames the model inside the region
    /// the *measured* chrome leaves, so nothing lands under a pill
    /// (invariant 4). Proved both ways — the model clears every piece that
    /// drew, and the same model centred on the raw viewport would not.
    #[test]
    fn a_fit_lands_the_model_clear_of_the_measured_chrome() {
        use crate::shell::workspace::PanelView;
        use crate::widget::test_fixtures as fx;
        let mut app = app_on(vec![
            fx::block_in(
                1,
                crate::path::Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(120.0, 80.0)),
            ),
            fx::block_in(
                2,
                crate::path::Scope::Root,
                Rect::from_min_max(pos2(400.0, 300.0), pos2(520.0, 380.0)),
            ),
        ]);
        // The busy picture: the navigator open, which is the deepest inset
        // the frame has and the one a raw-viewport fit would land under.
        app.workspace.show(PanelView::History);
        let ctx = shell_ctx();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        shell_frames(&mut app, &ctx, screen, 4);
        app.dispatch_action(&ctx, Action::ResetView);
        shell_frames(&mut app, &ctx, screen, 4);

        let viewport = app.canvas.viewport();
        let region = app.safe.region();
        assert!(
            region.width() < viewport.width() && region.height() < viewport.height(),
            "precondition: the chrome measured something ({region:?} of {viewport:?})",
        );
        let chrome = every_piece_laid_out(&ctx);
        assert_eq!(
            chrome.len(),
            crate::shell::Berth::ALL.len(),
            "precondition: the frame drew every piece",
        );

        let model = on_screen(&app, Rect::from_min_max(pos2(0.0, 0.0), pos2(520.0, 380.0)));
        for (berth, rect) in &chrome {
            let over = rect.intersect(model);
            assert!(
                over.width() <= 0.0 || over.height() <= 0.0,
                "{berth:?} at {rect:?} covers {over:?} of the model at {model:?}",
            );
        }
        // The other way round, so the first half cannot pass by the model
        // happening to be small: the framing *consulted* the chrome, which
        // shows as the same fit landing somewhere else once the deepest
        // piece is put away.
        app.workspace.close();
        shell_frames(&mut app, &ctx, screen, 4);
        app.dispatch_action(&ctx, Action::ResetView);
        shell_frames(&mut app, &ctx, screen, 4);
        let without_the_panel =
            on_screen(&app, Rect::from_min_max(pos2(0.0, 0.0), pos2(520.0, 380.0)));
        assert!(
            app.safe.region().width() > region.width(),
            "precondition: putting the navigator away gave the canvas its width back",
        );
        assert_ne!(
            without_the_panel, model,
            "the fit ignored the chrome: the model lands at {model:?} whether \
             or not the navigator is standing",
        );
    }

    /// Where the drawing's own bounds land on screen, under the camera the
    /// last frame painted with.
    fn on_screen(app: &App, world: Rect) -> Rect {
        let origin = app.canvas.viewport().min;
        Rect::from_min_max(
            app.canvas.world_to_screen(origin, world.min),
            app.canvas.world_to_screen(origin, world.max),
        )
    }

    /// The chrome floats, so the layers have to keep the canvas reachable
    /// under it: the pointer answers to the drawing everywhere the glass is
    /// not, and to the glass where it is. Nothing else in the suite drives a
    /// pointer through the whole frame, and a piece drawn in the wrong layer
    /// would either swallow the canvas or be swallowed by it.
    #[test]
    fn the_pointer_reaches_the_canvas_everywhere_the_chrome_is_not() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        app.workspace.show(PanelView::History);
        let ctx = shell_ctx();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        shell_frames(&mut app, &ctx, screen, 8);

        let clear = app.safe.region().center();
        assert!(
            hovering(&mut app, &ctx, screen, clear.geom()),
            "the canvas does not answer the pointer at {clear:?}, which no chrome covers",
        );
        let cluster = crate::shell::berth_rect(&ctx, crate::shell::Berth::ToolCluster)
            .expect("the tool cluster never laid out")
            .center();
        assert!(
            !hovering(&mut app, &ctx, screen, cluster.geom()),
            "the canvas answered a pointer that is over the tool cluster at {cluster:?}",
        );
    }

    /// Whether the canvas reports the pointer as its own, with it resting at
    /// `at`. Hover is computed from the previous pass's widget rects, so the
    /// pointer is held there for more than one.
    fn hovering(app: &mut App, ctx: &egui::Context, screen: Rect, at: Pos2) -> bool {
        for _ in 0..3 {
            ctx.clone()
                .run_ui(
                    egui::RawInput {
                        screen_rect: Some(screen.egui()),
                        events: vec![egui::Event::PointerMoved(at.egui())],
                        ..Default::default()
                    },
                    |ui| app.shell_frame(ui),
                )
                .drop_without_applying_deltas();
        }
        app.canvas.canvas_hovered()
    }

    /// §8's one gesture: the click that dismisses the navigator **also**
    /// performs the selection it landed
    /// on. Driven through the real frame — chrome first, then the canvas
    /// pass — and read off the canvas's own record of where it was last
    /// clicked, which is what every tool downstream of it acts on.
    #[test]
    fn the_click_that_dismisses_the_navigator_also_reaches_the_canvas() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        app.workspace.show(PanelView::History);
        let ctx = shell_ctx();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        shell_frames(&mut app, &ctx, screen, 8);
        assert!(
            app.workspace.open() && app.session.clicked_world().is_none(),
            "precondition: the navigator is up and the canvas has taken no click",
        );

        let away = app.safe.region().center();
        press_at(&mut app, &ctx, screen, away.geom());
        assert!(
            !app.workspace.open(),
            "the press away did not put the navigator down",
        );
        assert!(
            app.session.clicked_world().is_some(),
            "the dismissing press was swallowed instead of passing through",
        );
    }

    /// The other half of the dismissal (§8): the filter is a transient
    /// search, so it does not survive the panel going away — which supersedes
    /// §9's "survives Escape" for this one control.
    #[test]
    fn the_hierarchy_filter_is_forgotten_when_the_navigator_is_dismissed() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        app.workspace.show(PanelView::Hierarchy);
        let ctx = shell_ctx();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        shell_frames(&mut app, &ctx, screen, 8);
        let filter = crate::panels::nav_tree::nav_filter_id();
        ctx.data_mut(|d| d.insert_temp(filter, "boss".to_owned()));
        assert_eq!(
            ctx.data(|d| d.get_temp::<String>(filter)),
            Some("boss".to_owned()),
            "precondition: something is typed in the filter",
        );

        let away = app.safe.region().center();
        press_at(&mut app, &ctx, screen, away.geom());
        assert!(
            !app.workspace.open(),
            "precondition: the panel was dismissed"
        );
        let left = ctx
            .data(|d| d.get_temp::<String>(filter))
            .unwrap_or_default();
        assert!(
            left.is_empty(),
            "the filter outlived the panel it belongs to: {left:?}",
        );
    }

    /// §8's hand-off contract, one test per segment: every pick does its
    /// work *and leaves the navigator open*, so walking several revs or
    /// parts is one open rather than several. Driven through the whole real
    /// frame and clicked on what was actually painted.
    mod hand_off {
        use super::{App, AppConfig, app_on, screen_of};
        use crate::canvas::convert::IntoEgui as _;
        use crate::panels::painted::Chrome;
        use crate::shell::workspace::PanelView;
        use crate::tools::tool::ToolTrait as _;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;
        use blockworx_geom::{Pos2, Rect, pos2};

        /// A document with a named block at the root and a named one inside
        /// it — a scope to enter, and a part to select.
        fn nested() -> App {
            use crate::path::Scope;
            let body = |x: f32| Rect::from_min_max(pos2(x, 0.0), pos2(x + 60.0, 60.0));
            let mut app = app_on(vec![
                fx::block_in(1, Scope::Root, body(0.0)),
                fx::titled(1, "Motor"),
                fx::block_in(2, Scope::Block(block_id(1)), body(8.0)),
                fx::titled(2, "Filter"),
            ]);
            app.workspace.show(PanelView::Hierarchy);
            app
        }

        /// The panel, open on `view`, drawn through real frames of the whole
        /// shell.
        fn browsing(app: &mut App, view: PanelView) -> Chrome {
            app.workspace.show(view);
            let mut chrome = Chrome::new(screen_of());
            chrome.settle(|ui| app.shell_frame(ui));
            chrome
        }

        /// Where a row *inside the panel* landed — the lowest match, since
        /// the filter box above the list draws whatever was typed into it.
        /// The canvas draws these names too, so a test that aimed at the
        /// first match anywhere would be clicking the drawing and proving the
        /// opposite of what it claims.
        fn row(chrome: &Chrome, starting: &str) -> Pos2 {
            let panel = crate::shell::berth_rect(chrome.ctx(), crate::shell::Berth::Navigator)
                .expect("the navigator never laid out");
            let painted: Vec<String> = chrome
                .texts()
                .iter()
                .filter(|said| said.starts_with(starting))
                .map(|said| (*said).to_owned())
                .collect();
            painted
                .iter()
                .flat_map(|said| chrome.rects(said))
                .filter(|rect| panel.contains_rect(rect.egui()))
                .max_by(|a, b| a.top().total_cmp(&b.top()))
                .unwrap_or_else(|| {
                    panic!(
                        "no row in the panel reads {starting:?}: {:?}",
                        chrome.texts()
                    )
                })
                .center()
        }

        /// History: a rev pick opens the lens *behind* the panel, which stays
        /// up — the row is a lens, not a jump out of browsing.
        #[test]
        fn a_rev_pick_opens_the_lens_and_keeps_the_panel_open() {
            let mut app = app_on(vec![fx::block(1, 0.0)]);
            app.session.submit(blockworx_doc::commit::Commit::new(
                "Moved to 5".into(),
                vec![blockworx_store::fixture::block_move(1, 5)],
            ));
            let mut chrome = browsing(&mut app, PanelView::History);
            assert_eq!(
                app.session.viewing(),
                blockworx_store::doc::Viewing::Head,
                "precondition: the canvas is at the present",
            );

            let at = row(&chrome, "Built a scene");
            chrome.click_at(at, |ui| app.shell_frame(ui));
            assert!(
                matches!(
                    app.session.viewing(),
                    blockworx_store::doc::Viewing::Past(_)
                ),
                "the rev pick did not open the lens",
            );
            assert!(
                app.workspace.open(),
                "the rev pick closed the panel it was picked from",
            );
        }

        /// Hierarchy: a part pick becomes a canvas selection — which is what
        /// raises the selection overlay — and the panel stays up.
        #[test]
        fn a_part_pick_selects_on_the_canvas_and_keeps_the_panel_open() {
            let mut app = nested();
            let mut chrome = browsing(&mut app, PanelView::Hierarchy);
            assert!(
                app.session.tool.selection().is_none(),
                "precondition: nothing is selected",
            );

            let at = row(&chrome, "Motor");
            chrome.click_at(at, |ui| app.shell_frame(ui));
            assert_eq!(
                app.session.tool.selection().map(|sel| sel.count()),
                Some(1),
                "the part pick did not select on the canvas",
            );
            assert!(
                app.workspace.open(),
                "the part pick closed the panel it was picked from",
            );
        }

        /// Hierarchy again: picking a block that lives inside another makes
        /// its level the edit context, and the bar's breadcrumb says so. The
        /// filter is what reaches it — §8.2's own way of crossing a level.
        #[test]
        fn a_scope_pick_changes_the_context_and_the_breadcrumb_follows() {
            let mut app = nested();
            let mut chrome = browsing(&mut app, PanelView::Hierarchy);
            assert!(
                app.session.path.segments().is_empty(),
                "precondition: the canvas is at the document root",
            );
            chrome.ctx().data_mut(|d| {
                d.insert_temp(
                    crate::panels::nav_tree::nav_filter_id(),
                    "Filter".to_owned(),
                );
            });
            chrome.settle(|ui| app.shell_frame(ui));

            let at = row(&chrome, "Filter");
            chrome.click_at(at, |ui| app.shell_frame(ui));
            assert_eq!(
                app.session.path.segments(),
                &[block_id(1)],
                "the pick did not change the edit context",
            );
            assert!(
                app.workspace.open(),
                "the scope pick closed the panel it was picked from",
            );
            chrome.settle(|ui| app.shell_frame(ui));
            assert!(
                chrome.shows("Motor"),
                "the breadcrumb does not name the level the pick entered: {:?}",
                chrome.texts(),
            );
        }

        /// §8's other dismissal: a tool pick is intent to edit, so the panel
        /// goes — the one thing outside the canvas that closes it.
        #[test]
        fn a_tool_pick_dismisses_the_panel() {
            let mut app = App::new(AppConfig::default());
            let mut chrome = browsing(&mut app, PanelView::History);
            let column = crate::shell::berth_rect(chrome.ctx(), crate::shell::Berth::ToolCluster)
                .expect("the tool rail never laid out");
            assert!(app.workspace.open(), "precondition: the panel is up");

            chrome.click_at(
                pos2(
                    column.center().x,
                    column.top() + crate::shell::glass::TOOL.y * 1.5,
                ),
                |ui| app.shell_frame(ui),
            );
            assert!(!app.workspace.open(), "a tool pick left the panel standing");
        }
    }

    /// The tool cluster's other gesture (playbook R39): a cell pressed,
    /// carried onto the canvas, and dropped there stamps the tool's default
    /// thing where it landed — *"If the user drags the tool off the toolbar,
    /// then use the current 'stamp' behavior."* Driven through the whole
    /// frame, because the drop crosses three seams (the cell's drag sense,
    /// the chrome's own boxes, the canvas transform) and none of them can be
    /// judged alone.
    mod drag_out {
        use super::{App, AppConfig, press_at, screen_of, shell_ctx};
        use crate::canvas::convert::{IntoEgui as _, IntoGeom as _};
        use crate::tools::names::{ToolName, displayed_tool};
        use crate::tools::tool::{Action, Tool, ToolTrait as _};
        use blockworx_geom::{Pos2, Rect, pos2};

        /// A session with the shell measured and Select armed.
        fn session() -> (App, egui::Context, Rect) {
            let mut app = App::new(AppConfig::default());
            let ctx = shell_ctx();
            let screen = screen_of();
            frames(&mut app, &ctx, screen, 8, &[]);
            (app, ctx, screen)
        }

        /// `count` frames carrying `events` in the first of them, on the
        /// clock the session is already keeping — a drag reads back over
        /// several frames, and a clock that restarted would be a session
        /// travelling backwards in time.
        fn frames(
            app: &mut App,
            ctx: &egui::Context,
            screen: Rect,
            count: usize,
            events: &[egui::Event],
        ) {
            for frame in 0..count {
                let now = ctx.input(|i| i.time) + 0.12;
                ctx.clone()
                    .run_ui(
                        egui::RawInput {
                            screen_rect: Some(screen.egui()),
                            time: Some(now),
                            events: if frame == 0 {
                                events.to_owned()
                            } else {
                                Vec::new()
                            },
                            ..Default::default()
                        },
                        |ui| app.shell_frame(ui),
                    )
                    .drop_without_applying_deltas();
            }
        }

        /// Where the cluster's `tool` cell landed, found by arming it: a
        /// guessed point that armed something else would make every drag
        /// below a drag from nowhere, and this fails instead.
        fn cell_of(app: &mut App, ctx: &egui::Context, screen: Rect, tool: ToolName) -> Pos2 {
            let column = crate::shell::berth_rect(ctx, crate::shell::Berth::ToolCluster)
                .expect("the tool cluster never laid out");
            let mut y = column.top();
            while y <= column.bottom() {
                let at = pos2(column.center().x, y);
                press_at(app, ctx, screen, at);
                if app.session.tool.name() == tool {
                    app.dispatch_action(ctx, Action::SwitchTool(Tool::from_name(ToolName::Select)));
                    frames(app, ctx, screen, 2, &[]);
                    return at;
                }
                y += 8.0;
            }
            panic!("no point down the cluster arms {tool:?}");
        }

        /// A press at `from` carried to `to` and released there. egui tells a
        /// drag from a click by how far the pointer travelled, so the
        /// half-way move is what makes this the other gesture.
        fn drag(app: &mut App, ctx: &egui::Context, screen: Rect, from: Pos2, to: Pos2) {
            let button = |pos, pressed| egui::Event::PointerButton {
                pos,
                button: egui::PointerButton::Primary,
                pressed,
                modifiers: egui::Modifiers::NONE,
            };
            for events in [
                vec![egui::Event::PointerMoved(from.egui())],
                vec![button(from.egui(), true)],
                vec![egui::Event::PointerMoved((from + (to - from) * 0.5).egui())],
                vec![egui::Event::PointerMoved(to.egui())],
                vec![button(to.egui(), false)],
            ] {
                frames(app, ctx, screen, 1, &events);
            }
            frames(app, ctx, screen, 2, &[]);
        }

        /// Every title the current level holds, so a stamp can be told from
        /// nothing at all.
        fn titles(app: &mut App) -> Vec<String> {
            app.session
                .drawing()
                .shapes()
                .filter_map(|(_, shape)| shape.title().map(|t| t.name.to_owned()))
                .collect()
        }

        /// The ruling's own case: a block dropped on the canvas is the block
        /// a drag would have drawn — born named (R17), on the grid under the
        /// drop, in one commit.
        #[test]
        fn a_block_dropped_on_the_canvas_lands_where_it_was_dropped() {
            let (mut app, ctx, screen) = session();
            let cell = cell_of(&mut app, &ctx, screen, ToolName::NewBlock);
            let onto = app.safe.region().center();
            let before = app.session.doc.repo().rev();
            assert!(
                titles(&mut app).is_empty(),
                "precondition: nothing is drawn"
            );

            drag(&mut app, &ctx, screen, cell, onto.geom());

            assert_eq!(
                titles(&mut app),
                vec!["Block 1".to_owned()],
                "the drop stamped no block, or stamped an unnamed one",
            );
            assert_eq!(
                app.session.doc.repo().rev().get(),
                before.get() + 1,
                "a stamp is one commit",
            );
            let world = app.canvas.screen_to_world_pos(onto.geom());
            let wanted = crate::edit::create::stamped_block(world);
            let placed = app
                .session
                .drawing()
                .shapes()
                .map(|(_, shape)| shape.gui_rect())
                .next()
                .expect("the stamped block");
            assert_eq!(
                placed.min, wanted.min,
                "the block did not land under the drop"
            );
        }

        /// The two gestures are distinct: carrying a cell off the cluster
        /// leaves the armed cell alone, so the drag-out is not a slow click.
        #[test]
        fn a_drag_out_does_not_arm_the_tool_it_carried() {
            let (mut app, ctx, screen) = session();
            let cell = cell_of(&mut app, &ctx, screen, ToolName::NewBlock);
            assert_eq!(
                displayed_tool(app.session.tool.name()),
                ToolName::Select,
                "precondition: the cluster shows Select armed before the drag",
            );

            let onto = app.safe.region().center();
            drag(&mut app, &ctx, screen, cell, onto.geom());

            assert_eq!(
                displayed_tool(app.session.tool.name()),
                ToolName::Select,
                "the drag-out armed New Block as well as stamping one",
            );
        }

        /// *"A route cannot exist without it's endpoints."* — so carrying
        /// the route cell out does nothing at all, and the cell springs
        /// back.
        #[test]
        fn a_route_dropped_on_the_canvas_creates_nothing() {
            let (mut app, ctx, screen) = session();
            let cell = cell_of(&mut app, &ctx, screen, ToolName::Route);
            let before = app.session.doc.repo().rev();

            let onto = app.safe.region().center();
            drag(&mut app, &ctx, screen, cell, onto.geom());

            assert_eq!(
                app.session.doc.repo().rev(),
                before,
                "dropping the route tool wrote to the log",
            );
        }

        /// A drop that never reached the canvas is no drop: released over
        /// the glass, the gesture ends and nothing is made.
        #[test]
        fn a_drop_on_the_chrome_stamps_nothing() {
            let (mut app, ctx, screen) = session();
            let cell = cell_of(&mut app, &ctx, screen, ToolName::NewBlock);
            let onto = crate::shell::berth_rect(&ctx, crate::shell::Berth::TopBar)
                .expect("the top bar never laid out")
                .center();
            assert!(
                crate::shell::over_the_chrome(&ctx, onto),
                "precondition: the release point is on a piece of chrome",
            );
            let before = app.session.doc.repo().rev();

            drag(&mut app, &ctx, screen, cell, onto.geom());

            assert_eq!(
                app.session.doc.repo().rev(),
                before,
                "a drop on the chrome reached the document",
            );
            assert!(titles(&mut app).is_empty());
        }
    }

    /// The viewport every shell test drives.
    fn screen_of() -> Rect {
        Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0))
    }

    /// One full primary press and release at `at`, through the real frame.
    /// The clock runs on across the presses, so egui does not read two of
    /// them as one double click.
    fn press_at(app: &mut App, ctx: &egui::Context, screen: Rect, at: Pos2) {
        let button = |pressed| egui::Event::PointerButton {
            pos: at.egui(),
            button: egui::PointerButton::Primary,
            pressed,
            modifiers: egui::Modifiers::NONE,
        };
        for events in [
            vec![egui::Event::PointerMoved(at.egui())],
            vec![button(true), button(false)],
            Vec::new(),
            Vec::new(),
        ] {
            let now = ctx.input(|i| i.time) + 0.12;
            ctx.clone()
                .run_ui(
                    egui::RawInput {
                        screen_rect: Some(screen.egui()),
                        time: Some(now),
                        events,
                        ..Default::default()
                    },
                    |ui| app.shell_frame(ui),
                )
                .drop_without_applying_deltas();
        }
    }

    /// One shell frame carrying a key press.
    fn press_key(app: &mut App, ctx: &egui::Context, screen: Rect, key: egui::Key) {
        ctx.clone()
            .run_ui(
                egui::RawInput {
                    screen_rect: Some(screen.egui()),
                    time: Some(ctx.input(|i| i.time) + 0.12),
                    events: vec![egui::Event::Key {
                        key,
                        physical_key: None,
                        pressed: true,
                        repeat: false,
                        modifiers: egui::Modifiers::NONE,
                    }],
                    ..Default::default()
                },
                |ui| app.shell_frame(ui),
            )
            .drop_without_applying_deltas();
    }

    /// §2.0.1's four states, walked through the whole shell in the order the
    /// priority puts them: the idle readout, the selection path over it, the
    /// armed tool's instruction over that, and a confirmation over
    /// everything — each reached the way a user reaches it.
    #[test]
    fn the_status_line_reads_all_four_of_its_states_in_priority_order() {
        use crate::tools::names::ToolName;
        use crate::widget::test_fixtures as fx;
        let block = blockworx_doc::fixtures::block_id(1);
        let mut app = app_on(vec![fx::block(1, 0.0), fx::titled(1, "Motor")]);
        let ctx = shell_ctx();
        let screen = screen_of();
        shell_frames(&mut app, &ctx, screen, 4);
        let said = shell_text(&mut app, &ctx, screen);
        assert!(
            said.iter().any(|word| word == "100%"),
            "the idle line does not read the zoom (R46): {said:?}",
        );

        app.dispatch_action(
            &ctx,
            Action::NavSelect {
                block,
                extend: false,
            },
        );
        shell_frames(&mut app, &ctx, screen, 2);
        let said = shell_text(&mut app, &ctx, screen);
        assert!(
            said.iter().any(|word| word.contains("Motor")),
            "a selection does not put its path on the line: {said:?}",
        );

        app.dispatch_action(
            &ctx,
            Action::SwitchTool(crate::tools::tool::Tool::from_name(ToolName::NewArea)),
        );
        shell_frames(&mut app, &ctx, screen, 2);
        let said = shell_text(&mut app, &ctx, screen);
        let instruction =
            crate::tools::names::instruction(ToolName::NewArea).expect("a creator instructs");
        assert!(
            said.iter().any(|word| word == instruction),
            "an armed tool does not instruct: {said:?}",
        );

        // And an edit outranks all three, for its two seconds.
        app.dispatch_action(
            &ctx,
            Action::SwitchTool(crate::tools::tool::Tool::from_name(ToolName::Select)),
        );
        app.dispatch_action(
            &ctx,
            Action::NavSelect {
                block,
                extend: false,
            },
        );
        let stood = app.session.doc.repo().rev();
        press_key(&mut app, &ctx, screen, egui::Key::ArrowRight);
        assert_ne!(
            app.session.doc.repo().rev(),
            stood,
            "precondition: the arrow key authored an edit",
        );
        let said = shell_text(&mut app, &ctx, screen);
        let rev = format!("rev {}", app.session.doc.repo().rev().get());
        assert!(
            said.iter().any(|word| word.contains(&rev)),
            "the confirmation does not name the rev it wrote: {said:?}",
        );
    }

    /// R51: the title block names the rev *on the canvas*, so opening the
    /// lens changes what it says. The author rides with it, since it is the
    /// session's own and not the rev's.
    #[test]
    fn the_title_block_names_the_author_and_the_rev_the_canvas_is_showing() {
        use crate::widget::test_fixtures as fx;
        let mut app = App::new(AppConfig::default());
        // Two commits, so there is an earlier rev for the lens to stand on.
        let commits = [
            blockworx_doc::commit::Commit::new("Built a scene".into(), vec![fx::block(1, 0.0)]),
            blockworx_doc::commit::Commit::new("Named it".into(), vec![fx::titled(1, "Motor")]),
        ];
        app.session.adopt(blockworx_store::doc::Doc::scratch(
            blockworx_doc::repo::Repo::folding(&commits).expect("the scene folds"),
        ));
        app.session.path = BlockPath::opening(app.session.doc.document());
        app.session.identity = blockworx_store::record::Identity::new("Ada Lovelace");
        let ctx = shell_ctx();
        let screen = screen_of();
        shell_frames(&mut app, &ctx, screen, 4);
        let head = app.session.doc.repo().rev();
        assert!(head.get() > 1, "precondition: the log has revs to walk");
        let names = |app: &mut App, ctx: &egui::Context, rev: u64| {
            shell_text(app, ctx, screen)
                .iter()
                .any(|said| said.contains("Ada Lovelace") && said.contains(&format!("rev {rev}")))
        };
        assert!(
            names(&mut app, &ctx, head.get()),
            "the title block does not name the author and the head",
        );

        app.dispatch_action(&ctx, Action::ViewRev(blockworx_doc::fixtures::rev(1)));
        shell_frames(&mut app, &ctx, screen, 2);
        assert!(
            names(&mut app, &ctx, 1),
            "under the lens the title block still names the head",
        );
    }

    /// R53 at the app's own door: the folder picker takes any folder, so a
    /// choice that is not a diagram is refused where the user can read it —
    /// and the session it would have replaced is left standing.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn opening_a_folder_that_is_no_diagram_refuses_and_keeps_the_session() {
        use crate::widget::test_fixtures as fx;
        let dir = blockworx_store::temp::TempDir::new("open-refusal");
        let plain = dir.join("not-a-diagram");
        std::fs::create_dir_all(&plain).expect("the directory");
        let mut app = app_on(vec![fx::block(1, 0.0), fx::titled(1, "Motor")]);
        let stood = app.session.doc.repo().rev();

        app.open_container(&plain);

        let said: Vec<String> = app
            .notices()
            .into_iter()
            .map(|notice| match notice {
                crate::panels::notices::Notice::Failure(said)
                | crate::panels::notices::Notice::Standing(said) => said,
            })
            .collect();
        assert!(
            said.iter().any(|notice| notice.contains("not a diagram")),
            "the refusal never reached the user: {said:?}",
        );
        assert!(
            said.iter().all(|notice| !notice.contains("log.jsonl")),
            "the refusal answers a question nobody asked: {said:?}",
        );
        assert_eq!(
            app.session.doc.repo().rev(),
            stood,
            "a refused pick replaced the session anyway",
        );
    }

    /// Every piece of floating chrome the last frame laid out, by berth.
    fn every_piece_laid_out(ctx: &egui::Context) -> Vec<(crate::shell::Berth, Rect)> {
        crate::shell::Berth::ALL
            .into_iter()
            .filter_map(|berth| {
                crate::shell::berth_rect(ctx, berth).map(|rect| (berth, rect.geom()))
            })
            .collect()
    }

    /// §9, verified rather than built: the tablet is the same layout, and what
    /// makes it a tablet layout is the 44px target, which carries the claim
    /// alone (R47).
    ///
    /// Both widths §9 names, in points, since points and pixels are now the
    /// same thing: the chrome still takes its room from the canvas rather than
    /// from itself, and every cell is still a fingertip wide.
    #[test]
    fn the_tablet_widths_hold_at_the_taps_own_size() {
        use crate::shell::workspace::PanelView;
        for points in [1024.0, 834.0] {
            let mut app = App::new(AppConfig::default());
            app.workspace.show(PanelView::History);
            let ctx = shell_ctx();
            let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(points, 768.0));
            shell_frames(&mut app, &ctx, screen, 8);
            assert_eq!(
                ctx.zoom_factor(),
                1.0,
                "nothing scales the UI any more (R47), at {points}pt",
            );

            let canvas = app.canvas.viewport();
            assert!(
                canvas.is_positive(),
                "the canvas never laid out at {points}pt: {canvas:?}",
            );
            let chrome = every_piece_laid_out(&ctx);
            assert_eq!(
                chrome.len(),
                crate::shell::Berth::ALL.len(),
                "the frame lost a piece at {points}pt: {chrome:?}",
            );
            for (berth, rect) in &chrome {
                assert!(
                    canvas.contains_rect(*rect),
                    "{berth:?} at {rect:?} hangs off the window at {points}pt",
                );
            }
            assert!(
                app.safe.region().is_positive(),
                "the chrome swallowed the canvas at {points}pt",
            );
            let cluster = chrome
                .iter()
                .find_map(|(berth, rect)| {
                    (*berth == crate::shell::glass::Berth::ToolCluster).then_some(*rect)
                })
                .unwrap_or_else(|| panic!("the cluster never laid out at {points}pt"));
            let cells = crate::tools::names::BAND_TOOLS.len() as f32;
            assert!(
                cluster.height() >= cells * crate::shell::glass::TOOL.y,
                "a tool fell off the cluster at {points}pt: {} tall for {cells} cells",
                cluster.height(),
            );
            assert!(
                crate::shell::glass::TOOL.x >= crate::shell::glass::TAP
                    && cluster.width() >= crate::shell::glass::TAP,
                "the cluster is under a fingertip at {points}pt: {} wide",
                cluster.width(),
            );
        }
    }

    /// The whole idle frame must settle: stable shapes and no immediate
    /// repaint request. The chrome this replaced had exactly this guard, and
    /// a band that re-measures itself every frame redraws the editor at full
    /// rate while nothing is happening.
    #[test]
    fn the_idle_frame_settles() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        app.workspace.show(PanelView::History);
        let settle = crate::canvas::settle::probe(30, |ui| app.shell_frame(ui));
        crate::canvas::settle::assert_settles(&settle, 8);
    }

    /// The rail is the one way into either panel body, and switching between
    /// them swaps what the panel says — driven through real frames, so a
    /// body that laid out but never drew fails here.
    #[test]
    fn the_rail_opens_each_panel_body_in_turn() {
        use crate::shell::workspace::PanelView;
        let mut app = App::new(AppConfig::default());
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0));
        for (view, title) in [
            (PanelView::History, "History"),
            (PanelView::Hierarchy, "Hierarchy"),
        ] {
            let ctx = shell_ctx();
            app.workspace.show(view);
            shell_frames(&mut app, &ctx, screen, 4);
            let said = shell_text(&mut app, &ctx, screen);
            assert!(
                said.iter().any(|text| text == title),
                "the {title} panel never drew its own header: {said:?}",
            );
        }
    }

    /// Every word one shell frame actually painted — a body that laid out
    /// but drew nothing is absent from this.
    fn shell_text(app: &mut App, ctx: &egui::Context, screen: Rect) -> Vec<String> {
        let mut said = Vec::new();
        let mut out = ctx.clone().run_ui(
            egui::RawInput {
                screen_rect: Some(screen.egui()),
                ..Default::default()
            },
            |ui| app.shell_frame(ui),
        );
        out.textures_delta.clear();
        for clipped in &out.shapes {
            collect_text(&clipped.shape, &mut said);
        }
        out.drop_without_applying_deltas();
        said
    }

    /// Every text run in a frame's output, flattened.
    fn collect_text(shape: &egui::Shape, out: &mut Vec<String>) {
        match shape {
            egui::Shape::Text(text) => out.push(text.galley.text().to_owned()),
            egui::Shape::Vec(shapes) => {
                for shape in shapes {
                    collect_text(shape, out);
                }
            }
            _ => {}
        }
    }

    /// A document file named on the command line opens as a scratch
    /// session, and names the window after itself.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn the_path_argument_opens_and_names_the_window() {
        use blockworx_store::temp::TempDir;

        let dir = TempDir::new("app-opens-the-path");
        let file = dir.join("d.json");
        std::fs::write(
            &file,
            r#"{"version": 3, "top": "b1",
                "blocks": {"b1": {"rect": {"size": {"w": 8, "h": 8}}}}}"#,
        )
        .unwrap();

        let opened = App::new(AppConfig {
            opening: crate::app::Opening::Path(file),
            ..Default::default()
        });
        assert!(
            opened.window_title().starts_with("d.json - "),
            "the file opens and names the window: {}",
            opened.window_title(),
        );
        assert!(
            opened.session.doc.repo().rev().get() > 0,
            "and its commits seeded the repo",
        );
    }

    // ── The app-level action arms ────────────────────────────────────────────
    //
    // Step 13's straggler list called wrap top and the keyboard nudges
    // ordinary tool flows. They are not: both read app state a tool does not
    // hold — the block path, and the tool's own selection — so
    // `commands::apply_scripted` hands them back and `dispatch_action`
    // resolves them here. These drive that dispatch, which is the real path
    // the toolbar and the arrow keys both take.

    /// An app holding `ops` as its document, viewed from the document root.
    /// Seeded through a `Repo` for the same reason every other document
    /// reaches the editor that way: the log *is* the document (F5), so there
    /// is no other door to put one behind.
    fn app_on(ops: Vec<blockworx_doc::opcode::OpCodes>) -> App {
        let mut app = App::new(AppConfig::default());
        let commit = blockworx_doc::commit::Commit::new("Built a scene".into(), ops);
        app.session.adopt(blockworx_store::doc::Doc::scratch(
            blockworx_doc::repo::Repo::folding(&[commit]).expect("the scene folds"),
        ));
        app.session.path = BlockPath::opening(app.session.doc.document());
        app
    }

    /// The label that reaches the log is minted at the seal, from the ops
    /// the gesture turned out to author — so it names the entity and the
    /// scope. Driven through the real dispatch, because that is the only
    /// place the verb, the ops, and the block path are all in one room.
    #[test]
    fn a_dispatched_edit_lands_under_a_label_naming_what_it_touched() {
        use crate::path::Scope;
        use crate::shape::ShapeId;
        use crate::tools::tool::Deletable;
        use crate::widget::test_fixtures as fx;

        let ctx = egui::Context::default();
        let mut app = app_on(vec![
            fx::block(1, 0.0),
            fx::titled(1, "Amplifier"),
            fx::block_in(
                2,
                Scope::Block(blockworx_doc::fixtures::block_id(1)),
                Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
            ),
            fx::titled(2, "Filter"),
            fx::top(1),
        ]);
        assert_eq!(
            app.session.path.segments(),
            [blockworx_doc::fixtures::block_id(1)],
            "precondition: the editor opens inside the named top block",
        );
        let before = app.session.doc.repo().rev();

        app.dispatch_action(
            &ctx,
            Action::Delete(Deletable::Shape(ShapeId::Rect(
                blockworx_doc::fixtures::block_id(2),
            ))),
        );

        assert_ne!(
            app.session.doc.repo().rev(),
            before,
            "the delete reached the log"
        );
        assert_eq!(
            app.session
                .doc
                .repo()
                .log()
                .last()
                .expect("the commit")
                .label(),
            "Delete block \u{201c}Filter\u{201d}",
        );
    }

    /// Spec §7 through the real dispatch: two kinds of entry on one stack,
    /// the camera and the scope among them.
    mod two_kinds_one_stack {
        use super::{App, app_on};
        use crate::canvas::Vantage;
        use crate::history::{COALESCE, Direction, Moved};
        use crate::shape::ShapeId;
        use crate::tools::tool::Action;
        use blockworx_geom::{Rect, pos2, vec2};
        use blockworx_paint::Zoom;
        use core::time::Duration;

        /// A scene with something to edit inside the scope the editor opens
        /// in, so an edit and a camera move can interleave over one document.
        fn scene() -> App {
            use crate::path::Scope;
            use crate::widget::test_fixtures as fx;
            app_on(vec![
                fx::block(1, 0.0),
                fx::titled(1, "Amplifier"),
                fx::block_in(
                    2,
                    Scope::Block(blockworx_doc::fixtures::block_id(1)),
                    Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
                ),
                fx::titled(2, "Filter"),
                fx::top(1),
            ])
        }

        /// One frame of history bookkeeping, at `at` on the session's clock —
        /// the same two calls `App::show` makes around its dispatch.
        fn tick(app: &mut App, ctx: &egui::Context, at: Duration, action: Option<Action>) {
            app.sync_camera(ctx);
            let before = app.session.state();
            if let Some(action) = action {
                app.dispatch_action(ctx, action);
            }
            app.sync_camera(ctx);
            app.session.record_history(&before, at);
        }

        /// Hold still long enough for whatever just happened to become an
        /// entry of its own (§7.2's window).
        fn settle(app: &mut App, ctx: &egui::Context, at: Duration) -> Duration {
            tick(app, ctx, at, None);
            let at = at + COALESCE + COALESCE;
            tick(app, ctx, at, None);
            at
        }

        fn look_at(app: &mut App, x: f32) {
            app.canvas.stand_at(Vantage {
                zoom: Zoom::new(2.0),
                translation: vec2(x, 0.0),
            });
            app.session.moved = Moved::Camera;
        }

        fn select_the_filter(app: &mut App) {
            app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
                shape: ShapeId::Rect(blockworx_doc::fixtures::block_id(2)),
            }
            .into();
        }

        /// §7.1's `view` row: undoing one restores the camera and touches no
        /// log. Asserted on the log itself, not on a flag — nothing is
        /// appended and the head does not move.
        #[test]
        fn a_view_undo_restores_the_camera_and_writes_nothing_to_the_log() {
            let ctx = egui::Context::default();
            let mut app = scene();
            let at = settle(&mut app, &ctx, Duration::from_secs(1));
            let opened = app.canvas.vantage();
            let head = app.session.doc.repo().rev();
            let commits = app.session.doc.repo().log().len();

            look_at(&mut app, 40.0);
            let moved = app.canvas.vantage();
            let at = settle(&mut app, &ctx, at);
            assert_ne!(moved, opened, "precondition: the camera actually moved");
            assert!(
                app.session.has_step(Direction::Back),
                "precondition: the move became an entry",
            );

            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(app.canvas.vantage(), opened, "the camera did not come back");
            assert_eq!(
                app.session.doc.repo().rev(),
                head,
                "a view undo authored a rev"
            );
            assert_eq!(
                app.session.doc.repo().log().len(),
                commits,
                "a view undo appended a commit",
            );

            tick(&mut app, &ctx, at, Some(Action::Redo));
            assert_eq!(app.canvas.vantage(), moved, "redo did not mirror the undo");
            assert_eq!(
                app.session.doc.repo().rev(),
                head,
                "a view redo authored a rev"
            );
            assert_eq!(app.session.doc.repo().log().len(), commits);
        }

        /// The interleaving: an edit between two camera moves keeps its own
        /// turn, and the presses come back newest first whichever kind they
        /// are.
        #[test]
        fn doc_and_view_entries_undo_in_the_order_they_were_made() {
            let ctx = egui::Context::default();
            let mut app = scene();
            let at = settle(&mut app, &ctx, Duration::from_secs(1));
            let opened = app.canvas.vantage();

            look_at(&mut app, 40.0);
            let looked = app.canvas.vantage();
            let at = settle(&mut app, &ctx, at);

            select_the_filter(&mut app);
            let before_edit = super::block_rect_of(&mut app, blockworx_doc::fixtures::block_id(2));
            tick(&mut app, &ctx, at, Some(Action::Nudge { dx: 1, dy: 0 }));
            let nudged = super::block_rect_of(&mut app, blockworx_doc::fixtures::block_id(2));
            assert_ne!(nudged, before_edit, "precondition: the nudge moved it");
            let edited = app.session.doc.repo().rev();

            look_at(&mut app, 90.0);
            let at = settle(&mut app, &ctx, at);

            // Newest first: the second camera move, then the edit, then the
            // first camera move.
            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(app.canvas.vantage(), looked, "the camera move was skipped");
            assert_eq!(
                app.session.doc.repo().rev(),
                edited,
                "it authored on the way past"
            );

            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(
                super::block_rect_of(&mut app, blockworx_doc::fixtures::block_id(2)),
                before_edit,
                "the edit was not the next entry",
            );
            assert_ne!(
                app.session.doc.repo().rev(),
                edited,
                "the inverse is a rev of its own"
            );

            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(
                app.canvas.vantage(),
                opened,
                "the first move never came back"
            );
        }

        /// The guard the two stacks need: after a document undo the state fed
        /// back stands exactly where the trail does, so the next frame's
        /// feed adds nothing and the forward half survives.
        #[test]
        fn a_doc_undo_lands_the_stack_exactly_where_the_trail_stands() {
            let ctx = egui::Context::default();
            let mut app = scene();
            let at = settle(&mut app, &ctx, Duration::from_secs(1));
            select_the_filter(&mut app);
            tick(&mut app, &ctx, at, Some(Action::Nudge { dx: 1, dy: 0 }));

            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(
                app.session.state().stood,
                crate::history::Stood::of(app.session.doc.trail()),
                "the state fed back does not stand where the trail does",
            );
            assert!(
                app.session.has_step(Direction::Forward),
                "the undo left nothing to redo",
            );
            // Idle frames, well past the coalescing window: nothing happened,
            // so nothing may be recorded and the future must survive.
            let at = settle(&mut app, &ctx, at);
            assert!(
                app.session.has_step(Direction::Forward),
                "an idle frame after an undo abandoned the future",
            );
            let _ = at;
        }

        /// The walk is driven by [`Stood`](crate::history::Stood), which is
        /// now a rev rather than a depth — so it must still terminate, and
        /// land where it was aimed, over a trail with steps of every kind
        /// in it. Asserted against the documents rather than the count of
        /// steps taken: a walk that stops one short is the failure this
        /// guards.
        #[test]
        fn the_walk_lands_on_the_stood_it_was_aimed_at_over_a_mixed_trail() {
            use blockworx_doc::document::Document;

            let ctx = egui::Context::default();
            let mut app = scene();
            let at = settle(&mut app, &ctx, Duration::from_secs(1));
            select_the_filter(&mut app);
            for _ in 0..3 {
                tick(&mut app, &ctx, at, Some(Action::Nudge { dx: 1, dy: 0 }));
            }
            let three_nudges = crate::history::Stood::of(app.session.doc.trail());
            let after_three: Document = app.session.doc.document().clone();

            // A step each way, so the trail carries an undo record and a
            // redo record before the walk crosses them.
            tick(&mut app, &ctx, at, Some(Action::Undo));
            let after_one_back: Document = app.session.doc.document().clone();
            let one_back = crate::history::Stood::of(app.session.doc.trail());
            assert_ne!(one_back, three_nudges, "precondition: the undo moved");
            assert_ne!(after_one_back, after_three, "and moved the document");
            tick(&mut app, &ctx, at, Some(Action::Redo));
            assert_eq!(
                crate::history::Stood::of(app.session.doc.trail()),
                three_nudges,
                "precondition: a redo returns to the rev the undo left",
            );

            let walked = app.session.walk_document(one_back);
            assert!(walked.is_some(), "the walk framed nothing it moved");
            assert_eq!(crate::history::Stood::of(app.session.doc.trail()), one_back);
            assert_eq!(
                app.session.doc.document(),
                &after_one_back,
                "the walk landed on the right rev with the wrong document",
            );

            app.session.walk_document(three_nudges);
            assert_eq!(
                crate::history::Stood::of(app.session.doc.trail()),
                three_nudges
            );
            assert_eq!(
                app.session.doc.document(),
                &after_three,
                "the walk back up drifted"
            );
        }

        /// §7.2 under the lens: undo serves `view` entries, and withholds the
        /// `doc` ones — they would author against a head nobody is looking at.
        #[test]
        fn under_the_lens_a_view_entry_undoes_and_a_doc_entry_does_not() {
            let ctx = egui::Context::default();
            let mut app = scene();
            let at = settle(&mut app, &ctx, Duration::from_secs(1));
            select_the_filter(&mut app);
            tick(&mut app, &ctx, at, Some(Action::Nudge { dx: 1, dy: 0 }));
            let at = settle(&mut app, &ctx, at);
            let nudged = super::block_rect_of(&mut app, blockworx_doc::fixtures::block_id(2));

            let at_rev = app.session.doc.repo().rev();
            tick(&mut app, &ctx, at, Some(Action::ViewRev(at_rev)));
            assert!(
                matches!(
                    app.session.viewing(),
                    blockworx_store::doc::Viewing::Past(_)
                ),
                "precondition: a past rev is on the canvas",
            );
            let head = app.session.doc.repo().rev();
            let opened = app.canvas.vantage();

            look_at(&mut app, 40.0);
            let at = settle(&mut app, &ctx, at);
            assert!(
                app.session
                    .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                    .contains(crate::tools::commands::CommandId::Undo),
                "the lens withheld an undo that costs the log nothing",
            );
            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(app.canvas.vantage(), opened, "a view undo was refused");
            assert_eq!(
                app.session.doc.repo().rev(),
                head,
                "a view undo authored a rev"
            );

            // The next entry down is the edit, and it must not be served.
            assert!(
                !app.session
                    .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                    .contains(crate::tools::commands::CommandId::Undo),
                "the lens offered an undo that would author against the head",
            );
            tick(&mut app, &ctx, at, Some(Action::Undo));
            assert_eq!(
                app.session.doc.repo().rev(),
                head,
                "the chord wrote under the lens"
            );
            app.session.view_head();
            assert_eq!(
                super::block_rect_of(&mut app, blockworx_doc::fixtures::block_id(2)),
                nudged,
                "the document moved while nobody was allowed to write it",
            );
        }
    }

    /// §7's other half, and the one this suite was written for: a step that
    /// changes the document lands with the change *in sight*. Driven over a
    /// real canvas pass, because "in sight" is measured against a viewport
    /// and a headless view has none.
    mod a_step_lands_in_sight {
        use super::{App, app_on, block_rect_of};
        use crate::history::{COALESCE, Direction};
        use crate::panels::painted::Chrome;
        use crate::path::{BlockPath, Scope};
        use crate::shape::ShapeId;
        use crate::tools::tool::Action;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;
        use blockworx_geom::{Pos2, Rect, pos2, vec2};
        use core::time::Duration;

        fn rect(x0: f32, y0: f32, x1: f32, y1: f32) -> Rect {
            Rect::from_min_max(pos2(x0, y0), pos2(x1, y1))
        }

        fn chrome() -> Chrome {
            Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)))
        }

        /// A wide sheet with a small block at each end, so a view framed on
        /// one leaves the other far outside it.
        fn two_ends() -> (App, Chrome) {
            let mut app = app_on(vec![
                fx::block_in(1, Scope::Root, rect(0.0, 0.0, 2400.0, 800.0)),
                fx::top(1),
                fx::block_in(
                    2,
                    Scope::Block(block_id(1)),
                    rect(40.0, 300.0, 120.0, 380.0),
                ),
                fx::block_in(
                    3,
                    Scope::Block(block_id(1)),
                    rect(2200.0, 300.0, 2280.0, 380.0),
                ),
            ]);
            let mut chrome = chrome();
            chrome.settle(|ui| {
                app.show_canvas(ui);
            });
            (app, chrome)
        }

        /// One frame in the order `shell_frame` runs it: the state is read
        /// before anything, the canvas pass moves the camera, dispatch runs,
        /// and the frame is recorded last.
        /// One frame, and whatever the hand did in it. The action is
        /// dispatched through the *painting* context: a session has one, and
        /// a harness with two hides everything that is raised in a dispatch
        /// and read back while drawing.
        fn frame(app: &mut App, chrome: &mut Chrome, at: Duration, action: Option<Action>) {
            let ctx = chrome.ctx().clone();
            app.apply_framings(&ctx);
            let before = app.session.state();
            chrome.frame(|ui| {
                app.show_canvas(ui);
            });
            app.sync_camera(&ctx);
            if let Some(action) = action {
                app.dispatch_action(&ctx, action);
            }
            app.session.record_history(&before, at);
        }

        /// Idle frames enough for a framing to arrive and for whatever just
        /// happened to settle into an entry of its own (§7.2's window).
        fn settle(app: &mut App, chrome: &mut Chrome, at: Duration) -> Duration {
            for _ in 0..24 {
                frame(app, chrome, at, None);
            }
            let at = at + COALESCE + COALESCE;
            for _ in 0..2 {
                frame(app, chrome, at, None);
            }
            at
        }

        /// Put the camera on `block`'s neighbourhood, the way a hand would.
        fn look_at(app: &mut App, chrome: &mut Chrome, block: u32) {
            let at = block_rect_of(app, block_id(block));
            app.canvas.fit_to_rect_instant(at.expand(160.0));
            chrome.frame(|ui| {
                app.show_canvas(ui);
            });
        }

        fn select(app: &mut App, block: u32) {
            app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
                shape: ShapeId::Rect(block_id(block)),
            }
            .into();
        }

        fn in_sight(app: &mut App, block: u32) -> bool {
            let at = block_rect_of(app, block_id(block));
            app.canvas.visible_world_rect().intersects(at)
        }

        /// Probe 1: an edit at one end, a settled pan to the other, an edit
        /// there. Walking all three back must leave each taken-back edit
        /// where it can be seen.
        #[test]
        fn each_undo_that_moves_the_document_lands_looking_at_what_it_took_back() {
            let (mut app, mut chrome) = two_ends();
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, at);
            select(&mut app, 2);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let near_edit = block_rect_of(&mut app, block_id(2));
            let at = settle(&mut app, &mut chrome, at);

            look_at(&mut app, &mut chrome, 3);
            let at = settle(&mut app, &mut chrome, at);
            assert!(
                !in_sight(&mut app, 2),
                "precondition: the first edit is off screen from the second",
            );
            select(&mut app, 3);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let far_edit = block_rect_of(&mut app, block_id(3));
            let at = settle(&mut app, &mut chrome, at);

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            let at = settle(&mut app, &mut chrome, at);
            assert_ne!(
                block_rect_of(&mut app, block_id(3)),
                far_edit,
                "precondition: the first press took back the far edit",
            );
            assert!(
                in_sight(&mut app, 3),
                "the far edit came back out of sight: {:?} is not in {:?}",
                block_rect_of(&mut app, block_id(3)),
                app.canvas.visible_world_rect(),
            );

            // The pan between the two edits: a view step, which owes the log
            // nothing and simply walks the camera back.
            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            let at = settle(&mut app, &mut chrome, at);

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            settle(&mut app, &mut chrome, at);
            assert_ne!(
                block_rect_of(&mut app, block_id(2)),
                near_edit,
                "precondition: the third press took back the near edit",
            );
            assert!(
                in_sight(&mut app, 2),
                "the near edit came back out of sight: {:?} is not in {:?}",
                block_rect_of(&mut app, block_id(2)),
                app.canvas.visible_world_rect(),
            );
        }

        /// A sheet whose left block opens a scope with something to edit
        /// inside it — two scopes over one document.
        fn two_scopes() -> (App, Chrome) {
            let mut app = app_on(vec![
                fx::block_in(1, Scope::Root, rect(0.0, 0.0, 2400.0, 800.0)),
                fx::top(1),
                fx::block_in(
                    2,
                    Scope::Block(block_id(1)),
                    rect(40.0, 300.0, 400.0, 660.0),
                ),
                fx::block_in(
                    4,
                    Scope::Block(block_id(2)),
                    rect(80.0, 340.0, 200.0, 460.0),
                ),
                fx::block_in(
                    3,
                    Scope::Block(block_id(1)),
                    rect(2200.0, 300.0, 2280.0, 380.0),
                ),
            ]);
            let mut chrome = chrome();
            chrome.settle(|ui| {
                app.show_canvas(ui);
            });
            (app, chrome)
        }

        /// Probe 2: an edit inside a block's scope, then one a scope out.
        /// Taking the inner one back has to open the scope it happened in —
        /// otherwise the document moves in a drawing nobody is looking at.
        #[test]
        fn an_undo_that_crosses_a_scope_opens_the_scope_the_edit_happened_in() {
            let (mut app, mut chrome) = two_scopes();
            let inner = BlockPath::to_parent_of(app.session.doc.document(), block_id(4))
                .expect("block 4 has a path");
            let outer = app.session.path.clone();
            assert_ne!(
                inner, outer,
                "precondition: the two edits are in two scopes"
            );

            app.session.path = inner.clone();
            app.session.after_navigate();
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));
            select(&mut app, 4);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let inner_edit = block_rect_of(&mut app, block_id(4));
            let at = settle(&mut app, &mut chrome, at);

            app.session.path = outer.clone();
            app.session.after_navigate();
            let at = settle(&mut app, &mut chrome, at);
            select(&mut app, 3);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let at = settle(&mut app, &mut chrome, at);

            // Back through the outer edit, back through the scope change,
            // and then the inner edit itself.
            let mut at = at;
            for _ in 0..3 {
                frame(&mut app, &mut chrome, at, Some(Action::Undo));
                at = settle(&mut app, &mut chrome, at);
            }
            assert_eq!(
                app.session.path, inner,
                "the undo left the wrong scope open"
            );
            assert_ne!(
                block_rect_of(&mut app, block_id(4)),
                inner_edit,
                "precondition: the inner edit was the one taken back",
            );
            assert!(
                in_sight(&mut app, 4),
                "the inner edit came back out of sight",
            );
        }

        /// R57: putting a past rev on the canvas opens the level that rev
        /// worked on. A lens showing a drawing the step never touched is a
        /// confusion of its own, and the scope is already in the commit's own
        /// ops — the pick has no excuse not to use it.
        #[test]
        fn a_rev_pick_opens_the_scope_that_rev_worked_in() {
            let (mut app, mut chrome) = two_scopes();
            let inner = BlockPath::to_parent_of(app.session.doc.document(), block_id(4))
                .expect("block 4 has a path");
            let outer = app.session.path.clone();
            assert_ne!(
                inner, outer,
                "precondition: the edit's level is not the one the reader stands on",
            );

            // An edit two scopes in, made from the level it happened on, then
            // the reader comes back out to browse.
            app.session.path = inner.clone();
            app.session.after_navigate();
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));
            select(&mut app, 4);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let at = settle(&mut app, &mut chrome, at);
            let nudged = app.session.doc.repo().rev();
            app.session.path = outer.clone();
            app.session.after_navigate();
            let at = settle(&mut app, &mut chrome, at);
            assert_eq!(
                app.session.path, outer,
                "precondition: the reader is back outside"
            );

            frame(&mut app, &mut chrome, at, Some(Action::ViewRev(nudged)));
            assert_eq!(
                app.session.viewing(),
                blockworx_store::doc::Viewing::Past(nudged),
                "precondition: the lens is on the rev that was picked",
            );
            assert_eq!(
                app.session.path, inner,
                "the pick left the reader on a level that rev did not touch",
            );
            assert!(
                in_sight(&mut app, 4),
                "the pick opened the level but not onto what changed",
            );
        }

        /// Probe 3 / the coordinator's case (a): an edit dispatched at
        /// something the camera is nowhere near — the palette's door. The
        /// state the stack pins holds the camera the user was actually at,
        /// which never saw the edit, so restoring it alone is not enough.
        #[test]
        fn an_edit_made_off_screen_is_brought_into_sight_when_it_is_taken_back() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            select(&mut app, 3);
            assert!(
                !in_sight(&mut app, 3),
                "precondition: the edit is aimed off screen",
            );
            let before = block_rect_of(&mut app, block_id(3));
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let at = settle(&mut app, &mut chrome, at);
            assert_ne!(
                block_rect_of(&mut app, block_id(3)),
                before,
                "precondition: the off-screen edit landed",
            );

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            settle(&mut app, &mut chrome, at);
            assert_eq!(
                block_rect_of(&mut app, block_id(3)),
                before,
                "precondition: the press took the edit back",
            );
            assert!(
                in_sight(&mut app, 3),
                "the undo moved a block nobody could see: {:?} is not in {:?}",
                block_rect_of(&mut app, block_id(3)),
                app.canvas.visible_world_rect(),
            );
        }

        /// Probe 4: redo is the same contract, mirrored — and a step that
        /// framed what it changed must leave the future intact, or the
        /// framing has quietly cost the user their redo.
        #[test]
        fn a_redo_lands_looking_at_what_it_puts_back() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            select(&mut app, 3);
            let before = block_rect_of(&mut app, block_id(3));
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let nudged = block_rect_of(&mut app, block_id(3));
            assert_ne!(nudged, before, "precondition: the edit landed");
            let at = settle(&mut app, &mut chrome, at);

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            let at = settle(&mut app, &mut chrome, at);
            assert_eq!(
                block_rect_of(&mut app, block_id(3)),
                before,
                "precondition: the press took the edit back",
            );
            assert!(
                app.session.has_step(Direction::Forward),
                "framing what the undo changed abandoned the redo",
            );

            frame(&mut app, &mut chrome, at, Some(Action::Redo));
            settle(&mut app, &mut chrome, at);
            assert_eq!(
                block_rect_of(&mut app, block_id(3)),
                nudged,
                "the redo did not put the edit back",
            );
            assert!(
                in_sight(&mut app, 3),
                "the redo put a block back where nobody could see it",
            );
        }

        /// Probe 3: the edit pin. An edit punctuates the stack either side of
        /// itself, and the camera those two points carry has to be the one
        /// that held *at the edit* — not a snapshot from before whatever the
        /// hand did in the coalescing window since.
        #[test]
        fn the_state_an_edit_pins_carries_the_camera_the_edit_was_made_at() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            // The hand pans to the far block and edits it straight away —
            // inside §7.2's window, so the pan never settled into an entry
            // of its own.
            look_at(&mut app, &mut chrome, 3);
            let looking = app.canvas.vantage();
            select(&mut app, 3);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let pinned = app
                .session
                .undo_stack
                .peek(Direction::Back, &app.session.state())
                .expect("the edit is a step to take back");
            assert_eq!(
                pinned.camera, looking,
                "the edit pinned a camera the hand had already left",
            );
            assert_ne!(
                pinned.stood,
                app.session.state().stood,
                "precondition: the step being peeked is the edit itself",
            );
        }

        /// R55's other half: the step also *rings* what it took back, so a
        /// camera that arrived somewhere new says why it did. Proven through
        /// the real canvas pass, since a ring is a thing drawn: the run of
        /// outlines the frame paints gains one round the changed block, and
        /// a frame with no step behind it paints none.
        #[test]
        fn a_step_rings_what_it_took_back() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            let rings = |app: &mut App, chrome: &Chrome, world: Rect| -> Vec<Rect> {
                let wanted = on_screen(app, world.expand(crate::spotlight::CLEAR));
                chrome
                    .outlines()
                    .iter()
                    .filter(|drawn| near(**drawn, wanted))
                    .copied()
                    .collect()
            };
            let unmoved = block_rect_of(&mut app, block_id(3));
            assert!(
                rings(&mut app, &chrome, unmoved).is_empty(),
                "a frame with no step behind it drew a ring",
            );

            select(&mut app, 3);
            assert!(
                !in_sight(&mut app, 3),
                "precondition: the edit is aimed off screen, so the ring has work to do",
            );
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let at = settle(&mut app, &mut chrome, at);
            // The inverse is written against the document as it stands after
            // the nudge, so this — not the rect the undo restores — is what
            // the ring frames.
            let nudged = block_rect_of(&mut app, block_id(3));
            look_at(&mut app, &mut chrome, 2);

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            // The undo dispatches after the frame paints, so the ring it
            // raised lands on the next one.
            frame(&mut app, &mut chrome, at, None);
            let drawn = rings(&mut app, &chrome, nudged);
            assert_eq!(
                drawn.len(),
                1,
                "the undo drew {} rings round what it took back",
                drawn.len(),
            );
        }

        /// §12.7 of `docs/log-vs-snapshot.md`: a delete removes, so the rev
        /// that took a block away holds no footprint for it — the ring is
        /// read from the document the step departed. Proven through
        /// `view_rev`, the path a picked rev actually travels.
        #[test]
        fn viewing_a_delete_rings_where_the_block_stood() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 3);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));
            let stood = block_rect_of(&mut app, block_id(3));

            select(&mut app, 3);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Delete(crate::tools::tool::Deletable::Shape(
                    ShapeId::Rect(block_id(3)),
                ))),
            );
            let at = settle(&mut app, &mut chrome, at);
            let deleted = app.session.doc.repo().rev();
            assert!(
                app.session
                    .doc
                    .repo()
                    .document()
                    .block(&block_id(3))
                    .is_none(),
                "precondition: the delete removed the block rather than hiding it",
            );

            app.session.view_rev(deleted);
            frame(&mut app, &mut chrome, at, None);

            let wanted = on_screen(&app, stood.expand(crate::spotlight::CLEAR));
            assert!(
                chrome.outlines().iter().any(|drawn| near(*drawn, wanted)),
                "no ring was drawn where the deleted block stood",
            );
        }

        /// Where a world rect lands on screen under the camera as it stands.
        fn on_screen(app: &App, world: Rect) -> Rect {
            let origin = app.canvas.viewport().min;
            Rect::from_min_max(
                app.canvas.world_to_screen(origin, world.min),
                app.canvas.world_to_screen(origin, world.max),
            )
        }

        /// Two rects the same to within a rounding.
        fn near(a: Rect, b: Rect) -> bool {
            a.min.distance(b.min) < 0.5 && a.max.distance(b.max) < 0.5
        }

        /// The other half of the contract, and the one that keeps it from
        /// becoming a nuisance: a step whose change is already on screen
        /// moves the camera not one pixel. Layer 1 wins where it can.
        #[test]
        fn an_undo_of_something_in_plain_sight_leaves_the_camera_alone() {
            let (mut app, mut chrome) = two_ends();
            look_at(&mut app, &mut chrome, 2);
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            select(&mut app, 2);
            frame(
                &mut app,
                &mut chrome,
                at,
                Some(Action::Nudge { dx: 1, dy: 0 }),
            );
            let at = settle(&mut app, &mut chrome, at);
            assert!(
                in_sight(&mut app, 2),
                "precondition: the edit is on screen already",
            );
            let camera = app.canvas.vantage();

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            settle(&mut app, &mut chrome, at);
            assert_eq!(
                app.canvas.vantage(),
                camera,
                "an undo of something in plain sight jumped the camera",
            );
        }

        /// The coordinator's case (b) / F6: a session that only *reopened*
        /// the document has a reconstructed stack whose points carry no
        /// camera or scope of their own — §6.2 says viewing state does not
        /// survive a reload. The undo still has to land in sight.
        #[test]
        fn a_reopened_document_undoes_into_sight_of_the_edit() {
            use crate::path::Scope;
            use blockworx_doc::{commit::Commit, opcode::OpCodes};

            let repo = blockworx_doc::repo::Repo::folding(&[Commit::new(
                "Built a scene".into(),
                vec![
                    fx::block_in(1, Scope::Root, rect(0.0, 0.0, 2400.0, 800.0)),
                    fx::top(1),
                    fx::block_in(
                        2,
                        Scope::Block(block_id(1)),
                        rect(40.0, 300.0, 400.0, 660.0),
                    ),
                    fx::block_in(
                        4,
                        Scope::Block(block_id(2)),
                        rect(80.0, 340.0, 200.0, 460.0),
                    ),
                ],
            )])
            .expect("the scene folds");
            let mut doc = blockworx_store::doc::Doc::scratch(repo);
            doc.submit(
                Commit::new(
                    "Nudged it".into(),
                    vec![OpCodes::Block(
                        block_id(4),
                        blockworx_doc::opcode::Crud::Update(
                            blockworx_doc::block_model::BlockUpdate::Rect(
                                blockworx_doc::geometry::GridRect {
                                    top_left: blockworx_doc::geometry::GridPoint { x: 8, y: 24 },
                                    size: blockworx_doc::geometry::GridSize { w: 8, h: 8 },
                                },
                            ),
                        ),
                    )],
                ),
                &blockworx_store::record::Identity::new("Ada Lovelace"),
            )
            .expect("the nudge folds");

            let mut app = App::new(super::super::AppConfig::default());
            app.session.adopt(doc);
            app.session.path = BlockPath::opening(app.session.doc.document());
            let mut chrome = chrome();
            chrome.settle(|ui| {
                app.show_canvas(ui);
            });
            assert_eq!(
                app.session.path,
                BlockPath::opening(app.session.doc.document()),
                "precondition: the session opens where the document says",
            );
            assert!(
                app.session.has_step(Direction::Back),
                "precondition: the reopened trail offers a step",
            );
            let at = settle(&mut app, &mut chrome, Duration::from_secs(1));

            frame(&mut app, &mut chrome, at, Some(Action::Undo));
            settle(&mut app, &mut chrome, at);
            assert_eq!(
                app.session.path,
                BlockPath::to_parent_of(app.session.doc.document(), block_id(4))
                    .expect("block 4 has a path"),
                "the reopened undo left the wrong scope open",
            );
            assert!(
                in_sight(&mut app, 4),
                "the reopened undo moved a block nobody could see",
            );
        }
    }

    /// The world→screen mapping a frame painted under, read off the view.
    #[derive(Clone, Copy, Debug)]
    struct Camera {
        origin: Pos2,
        zoom: f32,
    }

    impl Camera {
        fn of(view: &crate::canvas::View) -> Camera {
            Camera {
                origin: view.viewport().min + view.translation,
                zoom: view.zoom.get(),
            }
        }

        fn place(self, world: Rect) -> Rect {
            Rect::from_min_max(
                self.origin + world.min.to_vec2() * self.zoom,
                self.origin + world.max.to_vec2() * self.zoom,
            )
        }

        fn unplace(self, screen: Rect) -> Rect {
            Rect::from_min_max(
                ((screen.min - self.origin) / self.zoom).to_pos2(),
                ((screen.max - self.origin) / self.zoom).to_pos2(),
            )
        }
    }

    /// G5: a scope change reframes the canvas *in* the frame it lands on.
    /// The fit needs a render to measure, and G2 owed it to the next frame —
    /// so the new level painted once under the camera of the level just
    /// left, then jumped. Judged through real frames, on what the first one
    /// after the navigation actually painted: it must already be what the
    /// settled frames paint, and the precondition proves the old camera
    /// would have put that ink somewhere else entirely.
    #[test]
    fn a_scope_change_paints_its_first_frame_already_fitted() {
        use crate::panels::painted::Chrome;
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let at = |x: f32, w: f32| Rect::from_min_size(pos2(x, 0.0), vec2(w, w));
        let mut app = app_on(vec![
            fx::block(1, 0.0),
            // The level the editor opens on: wide, so its fit is a small zoom.
            fx::block_in(2, Scope::Block(block_id(1)), at(0.0, 40.0)),
            fx::block_in(3, Scope::Block(block_id(1)), at(600.0, 40.0)),
            // The level below it: one small block, so its fit is a large one.
            fx::block_in(4, Scope::Block(block_id(2)), at(0.0, 20.0)),
            fx::top(1),
        ]);
        let ctx = egui::Context::default();
        let mut chrome = Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        let left_behind = Camera::of(&app.canvas);

        app.dispatch_action(&ctx, Action::ExpandBlock(block_id(2)));
        chrome.frame(|ui| {
            app.show_canvas(ui);
        });
        let first: Vec<Rect> = chrome.outlines().to_vec();

        let landed = Camera::of(&app.canvas);
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        let settled: Vec<Rect> = chrome.outlines().to_vec();
        assert!(
            !settled.is_empty(),
            "the level below drew nothing, so there is no framing to judge",
        );

        // The same ink under the camera the navigation left behind: if that
        // lands where the fitted camera does, this test proves nothing.
        let ink = settled
            .iter()
            .copied()
            .reduce(Rect::union)
            .expect("the settled frame painted something");
        let stale = left_behind.place(landed.unplace(ink));
        assert!(
            stale.center().distance(ink.center()) > 20.0
                || (stale.width() - ink.width()).abs() > 20.0,
            "precondition: the scope change must move the camera far enough to see \
             ({stale:?} vs {ink:?})",
        );

        assert_eq!(
            first, settled,
            "the first frame after the scope change painted under a camera that is \
             not the new level's fit — the flash",
        );
    }

    /// G7: a block holding blocks of its own is drawn with a second line
    /// inside its outline — the classical contains-a-sheet notation — and a
    /// leaf is drawn with one. Judged on what the real canvas painted, in
    /// screen space, so a frame drawn some other way shows up here.
    #[test]
    fn a_block_holding_blocks_paints_a_second_border_inside_its_outline() {
        use crate::panels::painted::Chrome;
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;
        use blockworx_editor::render::SHEET_INSET;

        let body = |x: f32| Rect::from_min_max(pos2(x, 0.0), pos2(x + 60.0, 60.0));
        let mut app = app_on(vec![
            fx::block_in(1, Scope::Root, body(0.0)),
            fx::block_in(2, Scope::Root, body(120.0)),
            // What makes block 1 a scope and leaves block 2 a leaf.
            fx::block_in(3, Scope::Block(block_id(1)), body(0.0)),
        ]);
        let mut chrome = Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        app.canvas
            .fit_to_rect_instant(Rect::from_min_max(pos2(-20.0, -20.0), pos2(200.0, 80.0)));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });

        let camera = Camera::of(&app.canvas);
        let structured = block_rect_of(&mut app, block_id(1));
        let leaf = block_rect_of(&mut app, block_id(2));
        let inset = |world: Rect| camera.place(world.shrink(SHEET_INSET.get()));
        let painted = |chrome: &Chrome, want: Rect| {
            chrome.outlines().iter().any(|drawn| {
                drawn.min.distance(want.min) < 2.0 && drawn.max.distance(want.max) < 2.0
            })
        };
        assert!(
            camera.place(structured).min.distance(inset(structured).min) > 4.0,
            "precondition: the zoom must separate the two lines by more than the \
             tolerance, or this test cannot tell them apart",
        );

        assert!(
            painted(&chrome, camera.place(structured)),
            "the structured block painted no outline at {:?}: {:?}",
            camera.place(structured),
            chrome.outlines(),
        );
        assert!(
            painted(&chrome, inset(structured)),
            "the structured block painted no inset line at {:?}: {:?}",
            inset(structured),
            chrome.outlines(),
        );
        assert!(
            painted(&chrome, camera.place(leaf)),
            "the leaf block painted no outline at {:?}: {:?}",
            camera.place(leaf),
            chrome.outlines(),
        );
        assert!(
            !painted(&chrome, inset(leaf)),
            "the leaf block painted a second line at {:?}, which is the structured \
             block's notation: {:?}",
            inset(leaf),
            chrome.outlines(),
        );
    }

    /// The preview draws through the same shape render as the resting block,
    /// so a structured block keeps both lines while it is being dragged.
    #[test]
    fn a_dragged_structured_block_previews_with_both_its_lines() {
        use crate::grid::GRID_SIZE;
        use crate::panels::painted::Chrome;
        use crate::path::Scope;
        use crate::tools::{MoveBlock, tool::Tool};
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;
        use blockworx_editor::render::SHEET_INSET;

        let ctx = egui::Context::default();
        let body = Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0));
        let mut app = app_on(vec![
            fx::block_in(1, Scope::Root, body),
            fx::block_in(2, Scope::Block(block_id(1)), body),
        ]);
        // The canvas pass hands its action back for the app to dispatch, and
        // a body drag *is* one — a frame that drops it never leaves `Select`.
        let show = |app: &mut App, ui: &mut egui::Ui| {
            if let Some(action) = app.show_canvas(ui) {
                app.dispatch_action(&ctx, action);
            }
        };
        let mut chrome = Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)));
        chrome.settle(|ui| show(&mut app, ui));
        app.canvas
            .fit_to_rect_instant(Rect::from_min_max(pos2(-40.0, -40.0), pos2(200.0, 120.0)));
        chrome.settle(|ui| show(&mut app, ui));

        let camera = Camera::of(&app.canvas);
        let resting = block_rect_of(&mut app, block_id(1));
        // A whole number of cells, so the preview lands exactly where the grid
        // snap puts it.
        let travel = vec2(4.0 * GRID_SIZE, 0.0);
        let grab = camera.place(resting).center();
        chrome.press_at(grab, |ui| show(&mut app, ui));
        chrome.drag_to(grab + vec2(12.0, 0.0), |ui| show(&mut app, ui));
        chrome.drag_to(grab + travel * camera.zoom, |ui| show(&mut app, ui));

        assert!(
            matches!(
                app.session.tool,
                Tool::MoveBlock(MoveBlock::Dragging { .. })
            ),
            "precondition: the grab must put the block into a drag, got {:?}",
            {
                use crate::tools::tool::ToolTrait as _;
                app.session.tool.name()
            },
        );
        let previewed = resting.translate(travel);
        let painted = |want: Rect| {
            chrome.outlines().iter().any(|drawn| {
                drawn.min.distance(want.min) < 2.0 && drawn.max.distance(want.max) < 2.0
            })
        };
        assert!(
            painted(camera.place(previewed)),
            "mid-drag, the block previewed no outline at {:?}: {:?}",
            camera.place(previewed),
            chrome.outlines(),
        );
        assert!(
            painted(camera.place(previewed.shrink(SHEET_INSET.get()))),
            "mid-drag, the block previewed no inset line at {:?}: {:?}",
            camera.place(previewed.shrink(SHEET_INSET.get())),
            chrome.outlines(),
        );
    }

    fn block_rect_of(app: &mut App, block: blockworx_doc::id::BlockId) -> Rect {
        app.session
            .drawing()
            .shape(crate::shape::ShapeId::Rect(block))
            .expect("the block is in this scope")
            .gui_rect()
    }

    /// "Go up" pops the block path, and that is all it does. At the
    /// document root there is nowhere above, so a writable session gets
    /// nothing at all — and the registry withholds the command there, so
    /// the toolbar's Up button is drawn dead rather than doing something
    /// else instead (docs/ui-issues-2.md, item 8).
    #[test]
    fn going_up_from_the_root_does_nothing_and_is_not_offered() {
        use crate::widget::test_fixtures as fx;
        let ctx = egui::Context::default();
        let mut app = app_on(vec![fx::block(1, 0.0), fx::top(1)]);
        let named_top = app.session.doc.document().title_block().top;
        assert_eq!(
            named_top,
            blockworx_doc::fixtures::block_id(1),
            "the fixture names its own top, so a changed one means this wrote it",
        );
        assert_eq!(
            app.session.may_write(),
            blockworx_store::doc::Writability::Writable,
            "precondition: nothing but the root is refusing here",
        );
        assert!(
            !app.session.path.segments().is_empty(),
            "an editor opens inside the top block",
        );
        assert!(
            app.session
                .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                .contains(crate::tools::commands::CommandId::GoUp),
            "precondition: inside a block there is a level to rise to",
        );

        app.dispatch_action(&ctx, Action::GoUp);
        assert!(
            app.session.path.segments().is_empty(),
            "the first go-up pops to the root",
        );

        let before = app.session.doc.repo().rev();
        app.dispatch_action(&ctx, Action::GoUp);
        assert!(
            app.session.path.segments().is_empty(),
            "and the root is where it stops"
        );
        assert_eq!(
            app.session.doc.document().title_block().top,
            named_top,
            "a go-up at the root wrapped the document",
        );
        assert_eq!(
            app.session.doc.repo().rev(),
            before,
            "and something reached the log"
        );
        assert!(
            !app.session
                .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                .contains(crate::tools::commands::CommandId::GoUp),
            "the root offers a way up, so the toolbar draws its button live",
        );
    }

    /// An arrow key moves the selected shape by one cell. The delta rides on
    /// the action; the *selection* comes from the tool, which is why this
    /// cannot be driven through the document-scoped dispatch.
    #[test]
    fn an_arrow_key_nudges_the_selected_shape_by_a_cell() {
        use crate::widget::test_fixtures as fx;
        let block = blockworx_doc::fixtures::block_id(1);
        let mut app = app_on(vec![fx::block(1, 0.0), fx::block(2, 120.0)]);
        app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
            shape: crate::shape::ShapeId::Rect(block),
        }
        .into();
        let before = block_rect_of(&mut app, block);

        app.dispatch_action(&egui::Context::default(), Action::Nudge { dx: 1, dy: 0 });

        let after = block_rect_of(&mut app, block);
        assert_eq!(
            after.min.x - before.min.x,
            crate::grid::GRID_SIZE,
            "the nudge moved the block {} px, not one cell",
            after.min.x - before.min.x,
        );
        assert_eq!(
            after.min.y, before.min.y,
            "a horizontal nudge moved it down"
        );
    }

    /// A pin selection nudges by whole slots instead, and only vertically —
    /// a separate emitter (`nudge_pins`) reached through the same arm.
    #[test]
    fn an_arrow_key_nudges_a_pin_selection_by_a_slot() {
        use crate::widget::test_fixtures as fx;
        let pin = blockworx_doc::fixtures::pin_id(3);
        let mut app = app_on(vec![
            fx::block_in(
                1,
                crate::path::Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(90.0, 300.0)),
            ),
            fx::pin(3, 1, crate::shape::pin::PinSide::West, 0),
        ]);
        app.session.tool = crate::tools::MultiPinSelect::Selected { pins: vec![pin] }.into();
        let slot_of = |app: &App| {
            app.session
                .doc
                .repo()
                .document()
                .pin(&pin)
                .expect("the pin is in the document")
                .slot
        };
        let before = slot_of(&app);

        app.dispatch_action(&egui::Context::default(), Action::Nudge { dx: 0, dy: 1 });

        let after = slot_of(&app);
        assert_ne!(
            after.offset, before.offset,
            "the pin kept slot {before:?} through a vertical nudge",
        );
    }

    // ── The clipboard arms ───────────────────────────────────────────────────
    //
    // These looked blocked on the OS clipboard and are not: `Action::Cut` and
    // `Action::CutPins` write the document *before* handing the payload to
    // `ctx.copy_text`, and `Action::Paste` takes the text as an argument. So
    // the whole round trip runs against a bare `egui::Context`, whose
    // `CopyText` command is the clipboard as far as the app is concerned.

    /// What the app just put on the clipboard.
    fn copied(ctx: &egui::Context) -> Option<String> {
        ctx.output(|out| {
            out.commands.iter().rev().find_map(|command| match command {
                egui::OutputCommand::CopyText(text) => Some(text.clone()),
                _ => None,
            })
        })
    }

    fn holds_block(app: &App, block: blockworx_doc::id::BlockId) -> bool {
        app.session.doc.repo().document().block(&block).is_some()
    }

    fn live_blocks(app: &App) -> usize {
        app.session.doc.repo().document().blocks().count()
    }

    fn live_routes(app: &App) -> usize {
        app.session.doc.repo().document().routes().count()
    }

    /// Cut writes the document and *then* copies, so the two halves are one
    /// gesture. Pasting the payload back completes the move: the same ids come
    /// back rather than a duplicate appearing, which is what makes the pair
    /// one displacement in the log and one thing for an undo to address.
    #[test]
    fn cutting_a_block_removes_it_and_pasting_moves_it_back() {
        use crate::widget::test_fixtures as fx;
        let ctx = egui::Context::default();
        let block = blockworx_doc::fixtures::block_id(2);
        let mut app = app_on(vec![fx::block(1, 0.0), fx::block(2, 120.0)]);
        assert!(
            holds_block(&app, block),
            "precondition: there is a block to cut"
        );
        let before = live_blocks(&app);

        app.dispatch_action(&ctx, Action::Cut(vec![crate::shape::ShapeId::Rect(block)]));

        assert!(!holds_block(&app, block), "the cut left the block in place");
        let payload = copied(&ctx).expect("a cut puts its snapshot on the clipboard");

        app.dispatch_action(&ctx, Action::Paste(payload));

        assert!(
            holds_block(&app, block),
            "pasting a cut did not bring it back"
        );
        assert_eq!(
            live_blocks(&app),
            before,
            "pasting a cut duplicated it instead of moving it",
        );
    }

    /// Paste with the original still alive is a second copy, not a move — the
    /// rule that keeps a second paste from minting a duplicate id.
    #[test]
    fn pasting_beside_a_live_original_duplicates_it() {
        use crate::widget::test_fixtures as fx;
        let ctx = egui::Context::default();
        let block = blockworx_doc::fixtures::block_id(2);
        let mut app = app_on(vec![fx::block(1, 0.0), fx::block(2, 120.0)]);
        let before = live_blocks(&app);
        let payload = app
            .session
            .drawing()
            .copy_selection(&[crate::shape::ShapeId::Rect(block)])
            .and_then(|clip| clip.to_json())
            .expect("a selected block copies");

        app.dispatch_action(&ctx, Action::Paste(payload));

        assert!(
            holds_block(&app, block),
            "the original was consumed by a copy"
        );
        assert_eq!(
            live_blocks(&app),
            before + 1,
            "the paste added no second block",
        );
    }

    /// A multi-select copied out of one document and pasted into another must
    /// land whole: every block, the wire between two of them, their pins, and
    /// the icon artwork — alive in the document *and* in the level's spatial
    /// index, which is what the canvas draws and hit-tests from.
    #[test]
    fn a_cross_document_paste_lands_every_block() {
        use crate::path::Scope;
        use crate::shape::ShapeId;
        use crate::widget::spatial::{HitId, SpatialIndex};
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let sheet = Rect::from_min_max(pos2(0.0, 0.0), pos2(900.0, 400.0));
        let body = |x: f32| Rect::from_min_max(pos2(x, 40.0), pos2(x + 60.0, 100.0));
        let mut source = app_on(vec![
            fx::block_in(1, Scope::Root, sheet),
            fx::top(1),
            fx::block_in(2, Scope::Block(block_id(1)), body(40.0)),
            fx::block_in(3, Scope::Block(block_id(1)), body(200.0)),
            fx::block_in(4, Scope::Block(block_id(1)), body(360.0)),
            fx::pin(5, 2, crate::shape::pin::PinSide::East, 0),
            fx::pin(6, 3, crate::shape::pin::PinSide::West, 0),
            fx::route(7, Scope::Block(block_id(1)), 5, 6, &[]),
            fx::asset().1,
            fx::icon(4, Rect::from_min_max(pos2(370.0, 50.0), pos2(390.0, 70.0))),
        ]);
        let copied_blocks = [
            ShapeId::Rect(block_id(2)),
            ShapeId::Rect(block_id(3)),
            ShapeId::Rect(block_id(4)),
        ];
        assert_eq!(
            source.session.path.segments(),
            [block_id(1)],
            "precondition: the source editor is inside its top block",
        );

        source.dispatch_action(&ctx, Action::Copy(copied_blocks.to_vec()));
        let payload = copied(&ctx).expect("a multi-select copy reaches the clipboard");

        let mut target = app_on(vec![
            fx::block_in(10, Scope::Root, sheet),
            fx::top(10),
            fx::block_in(11, Scope::Block(block_id(10)), body(40.0)),
        ]);
        let before = live_blocks(&target);
        target.dispatch_action(&ctx, Action::Paste(payload));

        assert_eq!(
            live_blocks(&target),
            before + 3,
            "the paste did not land all three blocks",
        );
        let doc = target.session.doc.repo().document();
        assert_eq!(doc.pins().count(), 2, "the pasted pins did not arrive");
        assert_eq!(doc.routes().count(), 1, "the pasted wire did not arrive");
        assert!(
            doc.asset(&fx::asset().0).is_some(),
            "the icon's artwork did not travel with the paste",
        );

        let mut probe = app_on(vec![]);
        std::mem::swap(&mut probe, &mut target);
        let drawn: Vec<HitId> = {
            let drawing = probe.session.drawing();
            SpatialIndex::from_drawing(&drawing)
                .in_rect(Rect::EVERYTHING)
                .collect()
        };
        let blocks_drawn = drawn
            .iter()
            .filter(|id| matches!(id, HitId::Shape(ShapeId::Rect(_))))
            .count();
        assert_eq!(
            blocks_drawn, 4,
            "the pasted blocks are in the log but not on the level: {drawn:?}",
        );
    }

    /// A paste wider than the viewport, then a pan to the part that landed
    /// off-screen — with no further commit of any kind. Everything pasted
    /// must paint and hit-test out there.
    ///
    /// The caches the canvas derives from — the level's spatial index and
    /// the solved wire geometry — are keyed by the document *value*, so the
    /// paste's own commit is what re-derives them; a later camera move must
    /// never be what a pasted entity was waiting for. The control asserts
    /// culling was live, or the pan would prove nothing.
    #[test]
    fn a_paste_wider_than_the_viewport_paints_where_it_landed_off_screen() {
        use crate::panels::painted::Chrome;
        use crate::path::Scope;
        use crate::shape::ShapeId;
        use crate::tools::tool::ToolTrait as _;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let sheet = Rect::from_min_max(pos2(0.0, 0.0), pos2(2400.0, 800.0));
        let body = |x: f32| Rect::from_min_max(pos2(x, 300.0), pos2(x + 60.0, 360.0));
        let mut app = app_on(vec![
            fx::block_in(1, Scope::Root, sheet),
            fx::top(1),
            fx::block_in(2, Scope::Block(block_id(1)), body(40.0)),
            fx::block_in(3, Scope::Block(block_id(1)), body(640.0)),
            fx::block_in(4, Scope::Block(block_id(1)), body(1240.0)),
            fx::pin(5, 3, crate::shape::pin::PinSide::East, 0),
            fx::pin(6, 4, crate::shape::pin::PinSide::West, 0),
            fx::route(7, Scope::Block(block_id(1)), 5, 6, &[]),
        ]);
        let selection = [
            ShapeId::Rect(block_id(2)),
            ShapeId::Rect(block_id(3)),
            ShapeId::Rect(block_id(4)),
        ];

        let mut chrome = Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        // A viewport far narrower than what is about to be pasted, so the
        // paste lands mostly outside it.
        app.canvas.fit_to_rect_instant(Rect::from_center_size(
            pos2(800.0, 330.0),
            vec2(700.0, 500.0),
        ));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });

        app.dispatch_action(&ctx, Action::Copy(selection.to_vec()));
        let payload = copied(&ctx).expect("a multi-select copy reaches the clipboard");
        app.dispatch_action(&ctx, Action::Paste(payload));
        // A paste now frames what it landed; this test is about what paints
        // *outside* the view, so put the narrow window back — which also
        // cancels the framing the paste asked for.
        app.canvas.fit_to_rect_instant(Rect::from_center_size(
            pos2(800.0, 330.0),
            vec2(700.0, 500.0),
        ));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });

        let landed: Vec<ShapeId> = app
            .session
            .tool
            .selection()
            .and_then(|d| d.shapes())
            .expect("the paste selects what it landed");
        let visible = app.canvas.visible_world_rect();
        let mut off_screen = landed
            .iter()
            .copied()
            .map(|id| (id, block_rect_of(&mut app, id.block().expect("a block"))))
            .filter(|(_, world)| !visible.intersects(*world));
        let (off_id, off_world) = off_screen.next().expect(
            "precondition: something the paste landed must be outside the viewport, or this \
             test proves nothing",
        );

        // The control: culling has to be live in the harness, or panning
        // proves nothing.
        assert!(
            !chrome.outlines().iter().any(|drawn| drawn
                .min
                .distance(Camera::of(&app.canvas).place(off_world).min)
                < 4.0),
            "precondition: the off-screen block painted without a pan — nothing is culling",
        );

        // The pan: no commit, no edit — only the camera moves to what the
        // paste put out there.
        app.canvas.fit_to_rect_instant(off_world.expand(80.0));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });

        let camera = Camera::of(&app.canvas);
        let want = camera.place(off_world);
        let near = |a: Rect, b: Rect| a.min.distance(b.min) < 4.0 && a.max.distance(b.max) < 4.0;
        assert!(
            chrome.outlines().iter().any(|drawn| near(*drawn, want)),
            "panning to a pasted block ({off_id:?}, world {off_world:?}) painted nothing at \
             {want:?}: {:?}",
            chrome.outlines(),
        );

        // The wire between two pasted blocks, at the same camera: its
        // geometry must be materialized and it must actually paint.
        let route = app
            .session
            .doc
            .repo()
            .document()
            .routes()
            .filter(|(id, _)| *id != blockworx_doc::fixtures::route_id(7))
            .map(|(id, _)| id)
            .next()
            .expect("the paste landed a wire of its own");
        assert!(
            app.session.drawing().route_geometry(route).is_some(),
            "the pasted wire {route:?} has no solved geometry after the pan",
        );
        let wire_world = {
            let drawing = app.session.drawing();
            let geometry = drawing.route_geometry(route).expect("just checked");
            blockworx_editor::render::bounds::route_bounds(
                &drawing
                    .auto_route(route)
                    .expect("the wire is on this level"),
                geometry,
            )
        };
        let wire_screen = camera.place(wire_world);
        assert!(
            chrome
                .segments()
                .iter()
                .any(|[a, b]| wire_screen.contains(*a) && wire_screen.contains(*b)),
            "the pasted wire {route:?} (world {wire_world:?}) painted no line inside \
             {wire_screen:?}",
        );

        // The other consumer of the same index: the cached index the frames
        // just used must answer a point query where the block was panned to,
        // or a click out here would select nothing.
        let center = off_world.center();
        let doc = super::viewed(&app.session.doc, app.session.time_machine.as_ref()).document();
        let hits: Vec<crate::widget::spatial::HitId> = app
            .session
            .spatial
            .get(
                &mut app.session.doc_index,
                doc,
                &app.session.path,
                &mut app.session.presentation,
            )
            .in_rect(Rect::from_min_max(center, center))
            .collect();
        assert!(
            hits.contains(&crate::widget::spatial::HitId::Shape(off_id)),
            "the index the frame drew from does not hold {off_id:?} at {center:?}: {hits:?}",
        );
        let on_wire = wire_world.center();
        let wire_hits: Vec<crate::widget::spatial::HitId> = app
            .session
            .spatial
            .get(
                &mut app.session.doc_index,
                doc,
                &app.session.path,
                &mut app.session.presentation,
            )
            .in_rect(Rect::from_min_max(on_wire, on_wire))
            .collect();
        assert!(
            wire_hits.contains(&crate::widget::spatial::HitId::Route(route)),
            "the index does not hold the pasted wire {route:?} at {on_wire:?}: {wire_hits:?}",
        );
    }

    /// G6b: a group whose members are committed *outside* the viewport,
    /// dragged until their preview is inside it. Mid-drag — before any
    /// release — the off-screen members must paint where the preview puts
    /// them, and so must both kinds of wire the drag moves: one between two
    /// dragged members, and one from a dragged member to a stationary block
    /// still off screen.
    ///
    /// The cull set comes from the spatial index, which is keyed by the
    /// document value and so knows only committed rects; a drag moves where a
    /// shape paints without moving its rect, so the preview has to be counted
    /// in the visibility question or it cannot draw at all. The release is the
    /// control: once the move commits, the same content paints from the index.
    #[test]
    fn a_drag_paints_off_screen_content_where_its_preview_lands() {
        use crate::panels::painted::Chrome;
        use crate::path::Scope;
        use crate::shape::ShapeId;
        use crate::tools::{MultiSelect, tool::Tool};
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let sheet = Rect::from_min_max(pos2(0.0, 0.0), pos2(2400.0, 800.0));
        let body = |x: f32| Rect::from_min_max(pos2(x, 300.0), pos2(x + 50.0, 360.0));
        let mut app = app_on(vec![
            fx::block_in(1, Scope::Root, sheet),
            fx::top(1),
            fx::block_in(2, Scope::Block(block_id(1)), body(600.0)),
            fx::block_in(3, Scope::Block(block_id(1)), body(900.0)),
            fx::block_in(4, Scope::Block(block_id(1)), body(1100.0)),
            fx::block_in(8, Scope::Block(block_id(1)), body(1500.0)),
            fx::pin(5, 3, crate::shape::pin::PinSide::East, 0),
            fx::pin(6, 4, crate::shape::pin::PinSide::West, 0),
            fx::route(7, Scope::Block(block_id(1)), 5, 6, &[]),
            fx::pin(9, 4, crate::shape::pin::PinSide::East, 0),
            fx::pin(10, 8, crate::shape::pin::PinSide::West, 0),
            fx::route(11, Scope::Block(block_id(1)), 9, 10, &[]),
        ]);
        let group = vec![
            ShapeId::Rect(block_id(2)),
            ShapeId::Rect(block_id(3)),
            ShapeId::Rect(block_id(4)),
        ];

        let mut chrome = Chrome::new(Rect::from_min_size(Pos2::ZERO, vec2(800.0, 600.0)));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        // A window over the left of the sheet: block 2 is inside it; blocks 3,
        // 4 and 8 and both wires are well outside.
        app.canvas.fit_to_rect_instant(Rect::from_center_size(
            pos2(300.0, 330.0),
            vec2(700.0, 500.0),
        ));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        app.session.tool = Tool::MultiSelect(MultiSelect::Selected { shapes: group });

        // The wire between two dragged members, and the one tethering a
        // dragged member to the block that stays behind.
        let (inner, tether) = (
            blockworx_doc::fixtures::route_id(7),
            blockworx_doc::fixtures::route_id(11),
        );
        let wire_world = |app: &mut App, route| {
            let drawing = app.session.drawing();
            let geometry = drawing
                .route_geometry(route)
                .expect("the wire has solved geometry");
            blockworx_editor::render::bounds::route_bounds(
                &drawing
                    .auto_route(route)
                    .expect("the wire is on this level"),
                geometry,
            )
        };
        let visible = app.canvas.visible_world_rect();
        let grabbed = block_rect_of(&mut app, block_id(2));
        let (far, farther) = (
            block_rect_of(&mut app, block_id(3)),
            block_rect_of(&mut app, block_id(4)),
        );
        let behind = block_rect_of(&mut app, block_id(8));
        let wire = wire_world(&mut app, inner);
        assert!(
            visible.contains_rect(grabbed),
            "precondition: the group needs an on-screen member to grab ({grabbed:?} in \
             {visible:?})",
        );
        for (what, rect) in [
            ("block 3", far),
            ("block 4", farther),
            ("block 8", behind),
            ("the inner wire", wire),
            ("the tether", wire_world(&mut app, tether)),
        ] {
            assert!(
                !visible.intersects(rect),
                "precondition: {what} ({rect:?}) must start outside {visible:?}, or the drag \
                 proves nothing",
            );
        }

        // The drag: grab the on-screen member and pull the group left until the
        // off-screen half is in view. No release.
        let camera = Camera::of(&app.canvas);
        let start = camera.place(grabbed).center();
        let pull = -640.0 * camera.zoom;
        chrome.press_at(start, |ui| {
            app.show_canvas(ui);
        });
        chrome.drag_to(start + vec2(-24.0, 0.0), |ui| {
            app.show_canvas(ui);
        });
        chrome.drag_to(start + vec2(pull, 0.0), |ui| {
            app.show_canvas(ui);
        });

        let Tool::MultiSelect(MultiSelect::Moving { delta_pos, .. }) = &app.session.tool else {
            panic!("the grab did not put the group into a drag: {:?}", {
                use crate::tools::tool::ToolTrait as _;
                app.session.tool.name()
            });
        };
        let delta = *delta_pos;
        let previewed_wire = wire.translate(delta);
        for (what, rect) in [
            ("block 3", far.translate(delta)),
            ("block 4", farther.translate(delta)),
            ("the inner wire", previewed_wire),
        ] {
            assert!(
                visible.contains_rect(rect),
                "precondition: the drag must bring {what} fully into {visible:?}, but it \
                 previews at {rect:?}",
            );
        }

        let near = |a: Rect, b: Rect| a.min.distance(b.min) < 4.0 && a.max.distance(b.max) < 4.0;
        // A line kept inside `within` that still spans its middle: the wire runs
        // the whole gap between the blocks it joins, where a pin stub reaches
        // only part way and an alignment guide runs off both ends.
        let spans = |within: Rect| {
            let middle = within.center();
            move |[a, b]: &[Pos2; 2]| {
                within.contains(*a)
                    && within.contains(*b)
                    && a.x.min(b.x) <= middle.x
                    && middle.x <= a.x.max(b.x)
            }
        };
        for (what, rect) in [
            ("block 3", far.translate(delta)),
            ("block 4", farther.translate(delta)),
        ] {
            let want = camera.place(rect);
            assert!(
                chrome.outlines().iter().any(|drawn| near(*drawn, want)),
                "mid-drag, {what} previewing at world {rect:?} painted nothing at {want:?}: \
                 {:?}",
                chrome.outlines(),
            );
        }
        let wire_screen = camera.place(previewed_wire);
        assert!(
            chrome.segments().iter().any(spans(wire_screen)),
            "mid-drag, the inner wire previewing at world {previewed_wire:?} painted no line \
             spanning {wire_screen:?}: {:?}",
            chrome.segments(),
        );
        // The tether: only one of its ends moved, so it previews as the run
        // from block 4's new position out to the block that stayed behind —
        // crossing the viewport on the way, having been wholly outside it.
        let previewed_tether = farther.translate(delta).union(behind);
        assert!(
            visible.intersects(previewed_tether),
            "precondition: the tether must cross {visible:?} mid-drag",
        );
        let tether_screen = camera.place(previewed_tether);
        assert!(
            chrome.segments().iter().any(spans(tether_screen)),
            "mid-drag, the tether from the dragged block to the one left behind painted no \
             line spanning {tether_screen:?}: {:?}",
            chrome.segments(),
        );

        // The control: the release commits the move, and the same content
        // paints from the refreshed index.
        chrome.release_at(start + vec2(pull, 0.0), |ui| {
            app.show_canvas(ui);
        });
        for (what, id) in [("block 3", block_id(3)), ("block 4", block_id(4))] {
            let want = camera.place(block_rect_of(&mut app, id));
            assert!(
                chrome.outlines().iter().any(|drawn| near(*drawn, want)),
                "after the release, {what} painted nothing at {want:?}: {:?}",
                chrome.outlines(),
            );
        }
        for (what, route) in [("the inner wire", inner), ("the tether", tether)] {
            let committed = camera.place(wire_world(&mut app, route));
            assert!(
                chrome.segments().iter().any(spans(committed)),
                "after the release, {what} painted no line spanning {committed:?}",
            );
        }
    }

    /// A settled canvas showing a known window of a sheet, with one small
    /// block inside it to copy — the scene the paste-framing tests share.
    /// They differ only in where the paste is aimed and what lands.
    fn a_view_to_paste_into() -> (App, crate::panels::painted::Chrome) {
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let mut app = app_on(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(2400.0, 800.0)),
            ),
            fx::top(1),
            fx::block_in(
                2,
                Scope::Block(block_id(1)),
                Rect::from_min_max(pos2(40.0, 300.0), pos2(120.0, 380.0)),
            ),
        ]);
        let mut chrome = crate::panels::painted::Chrome::new(Rect::from_min_size(
            Pos2::ZERO,
            vec2(800.0, 600.0),
        ));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        app.canvas.fit_to_rect_instant(Rect::from_center_size(
            pos2(800.0, 330.0),
            vec2(700.0, 500.0),
        ));
        chrome.settle(|ui| {
            app.show_canvas(ui);
        });
        (app, chrome)
    }

    /// Frames enough for a camera easing toward its target to arrive.
    fn settle_camera(app: &mut App, chrome: &mut crate::panels::painted::Chrome) {
        for _ in 0..16 {
            chrome.settle(|ui| {
                app.show_canvas(ui);
            });
        }
    }

    /// The world box around everything the selection holds.
    fn selection_bounds(app: &mut App) -> Rect {
        use crate::tools::tool::ToolTrait as _;
        let shapes = app
            .session
            .tool
            .selection()
            .and_then(|d| d.shapes())
            .expect("the paste selects what it landed");
        shapes
            .iter()
            .filter_map(|&id| Some(app.session.drawing().shape(id)?.gui_rect()))
            .reduce(Rect::union)
            .expect("what landed has bounds")
    }

    fn camera(app: &App) -> (f32, Vec2) {
        (app.canvas.zoom.get(), app.canvas.translation)
    }

    /// A copied selection pasted into the far corner of the view: paste puts
    /// the group's top-left under the pointer, so most of it lands outside.
    /// What a paste drops has never been on screen before, which makes
    /// content that lands out of sight indistinguishable from content that
    /// never landed (G6).
    #[test]
    fn a_paste_that_lands_off_screen_is_brought_into_view() {
        use crate::shape::ShapeId;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let (mut app, mut chrome) = a_view_to_paste_into();
        let before = app.canvas.visible_world_rect();
        app.session
            .note_pointer(Some(blockworx_paint::Event::HoverAt(
                before.max - vec2(4.0, 4.0),
            )));

        app.dispatch_action(&ctx, Action::Copy(vec![ShapeId::Rect(block_id(2))]));
        let payload = copied(&ctx).expect("the copy reaches the clipboard");
        app.dispatch_action(&ctx, Action::Paste(payload));

        let landed = selection_bounds(&mut app);
        assert!(
            !before.contains_rect(landed),
            "precondition: {landed:?} landed inside {before:?}, so this test proves nothing",
        );

        settle_camera(&mut app, &mut chrome);
        assert!(
            app.canvas.visible_world_rect().contains_rect(landed),
            "the paste left {landed:?} outside the view: {:?}",
            app.canvas.visible_world_rect(),
        );
        assert_eq!(
            crate::tools::tool::ToolTrait::selection(&app.session.tool)
                .and_then(|d| d.shapes())
                .unwrap_or_default()
                .len(),
            1,
            "framing what landed must not disturb the selection it left",
        );
    }

    /// The other half of the policy: a paste that lands where it can already
    /// be seen moves the camera not one pixel. A gratuitous jump on every
    /// paste would be its own bug.
    #[test]
    fn a_paste_that_lands_in_view_does_not_move_the_camera() {
        use crate::shape::ShapeId;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let (mut app, mut chrome) = a_view_to_paste_into();
        let before = app.canvas.visible_world_rect();
        app.session
            .note_pointer(Some(blockworx_paint::Event::HoverAt(before.center())));
        let camera_before = camera(&app);

        app.dispatch_action(&ctx, Action::Copy(vec![ShapeId::Rect(block_id(2))]));
        let payload = copied(&ctx).expect("the copy reaches the clipboard");
        app.dispatch_action(&ctx, Action::Paste(payload));

        let landed = selection_bounds(&mut app);
        assert!(
            before.contains_rect(landed),
            "precondition: {landed:?} landed outside {before:?}, so this test proves nothing",
        );

        settle_camera(&mut app, &mut chrome);
        assert_eq!(
            camera(&app),
            camera_before,
            "a paste that landed in plain sight moved the camera",
        );
    }

    /// The same pair for the document insert (D19), which lands through the
    /// same door a paste does.
    #[test]
    fn an_inserted_document_is_brought_into_view_only_when_it_needs_to_be() {
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;

        let ctx = egui::Context::default();
        let repo = blockworx_doc::repo::Repo::folding(&[blockworx_doc::commit::Commit::new(
            "Built a document".into(),
            vec![
                fx::block_in(
                    1,
                    Scope::Root,
                    Rect::from_min_max(pos2(0.0, 0.0), pos2(120.0, 120.0)),
                ),
                fx::top(1),
            ],
        )])
        .expect("the document folds");
        let payload = blockworx_store::projection::export_text(
            repo.document(),
            blockworx_store::projection::Stamp::at(
                repo.rev(),
                blockworx_store::record::Digest::of(&[]),
            ),
            blockworx_store::projection::Source {
                document: "inserted".into(),
                author: "tester".into(),
                tags: Vec::new(),
            },
        );
        assert!(
            blockworx_editor::import::from_clipboard(&payload).is_some(),
            "precondition: an export reads as a document insert",
        );

        let (mut app, mut chrome) = a_view_to_paste_into();
        let before = app.canvas.visible_world_rect();
        app.session
            .note_pointer(Some(blockworx_paint::Event::HoverAt(
                before.max - vec2(4.0, 4.0),
            )));
        app.dispatch_action(&ctx, Action::Paste(payload.clone()));
        let landed = selection_bounds(&mut app);
        assert!(
            !before.contains_rect(landed),
            "precondition: the insert landed inside the view it was aimed past",
        );
        settle_camera(&mut app, &mut chrome);
        assert!(
            app.canvas.visible_world_rect().contains_rect(landed),
            "the insert left {landed:?} outside the view",
        );

        let (mut app, mut chrome) = a_view_to_paste_into();
        let before = app.canvas.visible_world_rect();
        app.session
            .note_pointer(Some(blockworx_paint::Event::HoverAt(before.center())));
        let camera_before = camera(&app);
        app.dispatch_action(&ctx, Action::Paste(payload));
        let landed = selection_bounds(&mut app);
        assert!(
            before.contains_rect(landed),
            "precondition: {landed:?} landed outside {before:?}",
        );
        settle_camera(&mut app, &mut chrome);
        assert_eq!(
            camera(&app),
            camera_before,
            "an insert that landed in plain sight moved the camera",
        );
    }

    /// A whole document arriving on the clipboard (D19) must bring every block
    /// it holds. `top` names the level the editor opens on, not the outermost
    /// block: this document was wrapped twice without re-pointing it, so
    /// following `top` leaves the two blocks above it behind.
    #[test]
    fn pasting_a_whole_document_lands_every_block_it_holds() {
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let sheet = Rect::from_min_max(pos2(0.0, 0.0), pos2(600.0, 400.0));
        let repo = blockworx_doc::repo::Repo::folding(&[blockworx_doc::commit::Commit::new(
            "Built a document".into(),
            vec![
                fx::block_in(1, Scope::Root, sheet),
                fx::block_in(2, Scope::Block(block_id(1)), sheet),
                fx::block_in(
                    3,
                    Scope::Block(block_id(2)),
                    Rect::from_min_max(pos2(40.0, 40.0), pos2(120.0, 120.0)),
                ),
                // The stale pointer: `top` still names the inner sheet the two
                // wraps above it demoted.
                fx::top(2),
            ],
        )])
        .expect("the document folds");
        let held = repo.document().blocks().count();
        assert_eq!(held, 3, "precondition: the document holds three blocks");
        assert_ne!(
            repo.document().title_block().top,
            block_id(1),
            "precondition: `top` is not the outermost block",
        );

        let payload = blockworx_store::projection::export_text(
            repo.document(),
            blockworx_store::projection::Stamp::at(
                repo.rev(),
                blockworx_store::record::Digest::of(&[]),
            ),
            blockworx_store::projection::Source {
                document: "wrapped".into(),
                author: "tester".into(),
                tags: Vec::new(),
            },
        );
        assert!(
            blockworx_editor::import::from_clipboard(&payload).is_some(),
            "precondition: an export reads as a document insert",
        );

        let mut target = app_on(vec![]);
        let before = live_blocks(&target);
        target.dispatch_action(&ctx, Action::Paste(payload));

        assert_eq!(
            live_blocks(&target) - before,
            held,
            "the inserted document did not bring every block it holds",
        );
    }

    /// The other way a document outgrows its `top`: a block drawn beside the
    /// sheet, at the document root. The insert takes the root scope, so it
    /// travels too.
    #[test]
    fn pasting_a_document_brings_the_blocks_beside_its_top() {
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::fixtures::block_id;

        let ctx = egui::Context::default();
        let sheet = Rect::from_min_max(pos2(0.0, 0.0), pos2(600.0, 400.0));
        let repo = blockworx_doc::repo::Repo::folding(&[blockworx_doc::commit::Commit::new(
            "Built a document".into(),
            vec![
                fx::block_in(1, Scope::Root, sheet),
                fx::top(1),
                fx::block_in(
                    2,
                    Scope::Root,
                    Rect::from_min_max(pos2(700.0, 0.0), pos2(800.0, 100.0)),
                ),
            ],
        )])
        .expect("the document folds");
        let at_root = repo
            .document()
            .blocks()
            .filter(|(_, block)| block.parent == blockworx_doc::id::BlockId::NULL)
            .count();
        assert_eq!(at_root, 2, "precondition: the root holds two blocks");
        assert_eq!(
            repo.document().title_block().top,
            block_id(1),
            "precondition: `top` is only one of them",
        );

        let payload = blockworx_store::projection::export_text(
            repo.document(),
            blockworx_store::projection::Stamp::at(
                repo.rev(),
                blockworx_store::record::Digest::of(&[]),
            ),
            blockworx_store::projection::Source {
                document: "beside".into(),
                author: "tester".into(),
                tags: Vec::new(),
            },
        );
        let mut target = app_on(vec![]);
        let before = live_blocks(&target);
        target.dispatch_action(&ctx, Action::Paste(payload));

        assert_eq!(
            live_blocks(&target) - before,
            2,
            "the block beside the document's top did not travel with it",
        );
    }

    /// The third thing a document's root scope holds: the wires between the
    /// blocks in it. The insert reads the exported file, so a wire the export
    /// could not spell arrived as nothing at all — every root block landing
    /// unconnected, which is not a rendering failure but a missing wire.
    #[test]
    fn pasting_a_document_brings_the_wires_of_its_root_scope() {
        use crate::path::Scope;
        use crate::shape::pin::PinSide;
        use crate::widget::test_fixtures as fx;

        let ctx = egui::Context::default();
        let body = |x: f32| Rect::from_min_max(pos2(x, 100.0), pos2(x + 80.0, 180.0));
        let repo = blockworx_doc::repo::Repo::folding(&[blockworx_doc::commit::Commit::new(
            "Wired two blocks at the root".into(),
            vec![
                fx::block_in(1, Scope::Root, body(0.0)),
                fx::block_in(2, Scope::Root, body(400.0)),
                fx::top(1),
                fx::pin(3, 1, PinSide::East, 0),
                fx::pin(4, 2, PinSide::West, 0),
                fx::route(5, Scope::Root, 3, 4, &[]),
            ],
        )])
        .expect("the document folds");
        assert_eq!(
            repo.document()
                .routes()
                .filter(|(_, route)| route.owner == blockworx_doc::id::BlockId::NULL)
                .count(),
            1,
            "precondition: the wire this test follows is owned by the root scope",
        );

        let payload = blockworx_store::projection::export_text(
            repo.document(),
            blockworx_store::projection::Stamp::at(
                repo.rev(),
                blockworx_store::record::Digest::of(&[]),
            ),
            blockworx_store::projection::Source {
                document: "wired".into(),
                author: "tester".into(),
                tags: Vec::new(),
            },
        );

        let mut target = app_on(vec![]);
        let before = live_routes(&target);
        target.dispatch_action(&ctx, Action::Paste(payload));

        assert_eq!(
            live_blocks(&target),
            2,
            "precondition: both ends of the wire landed",
        );
        assert_eq!(
            live_routes(&target) - before,
            1,
            "the inserted document's root-scope wire did not travel with it",
        );
    }

    /// Pins cut and paste on their own gesture, onto a boundary rather than at
    /// a drop point — a separate pair of emitters reached through the same two
    /// actions. Note the asymmetry with the block above: `paste_pins` always
    /// mints fresh ids, so a cut pin never *moves* back the way a cut block
    /// does. It lands on whichever boundary the paste is aimed at, in the next
    /// free slot.
    #[test]
    fn cutting_pins_removes_them_and_pasting_slots_them_back() {
        use crate::widget::test_fixtures as fx;
        let ctx = egui::Context::default();
        let pin = blockworx_doc::fixtures::pin_id(3);
        let owner = blockworx_doc::fixtures::block_id(1);
        let mut app = app_on(vec![
            fx::block_in(
                1,
                crate::path::Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(90.0, 300.0)),
            ),
            fx::pin(3, 1, crate::shape::pin::PinSide::West, 0),
        ]);
        let alive = |app: &App| app.session.doc.repo().document().pin(&pin).is_some();
        assert!(alive(&app), "precondition: there is a pin to cut");
        // The paste lands on the selected block's boundary, so the block is
        // what must be selected when it happens.
        app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
            shape: crate::shape::ShapeId::Rect(owner),
        }
        .into();

        app.dispatch_action(&ctx, Action::CutPins(vec![pin]));
        assert!(!alive(&app), "the cut left the pin on the block");
        let payload = copied(&ctx).expect("a pin cut puts its snapshot on the clipboard");

        app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
            shape: crate::shape::ShapeId::Rect(owner),
        }
        .into();
        app.dispatch_action(&ctx, Action::Paste(payload));

        assert!(
            !alive(&app),
            "the cut pin's own id came back; paste_pins mints"
        );
        let on_owner: Vec<_> = app
            .session
            .doc
            .repo()
            .document()
            .pins()
            .filter(|(_, pin)| pin.owner == owner)
            .collect();
        assert_eq!(
            on_owner.len(),
            1,
            "the paste put no pin back on the block's boundary",
        );
    }

    // ── The drawing's chrome ─────────────────────────────────────────────────

    /// The title block reads the document *on the canvas*, so an edit moves
    /// the rev it shows and the time machine moves it back — padlocked, since
    /// a past rev is nobody's to edit.
    #[test]
    fn the_title_block_follows_the_rev_on_the_canvas() {
        use crate::widget::test_fixtures as fx;
        let ctx = egui::Context::default();
        let mut app = app_on(vec![fx::block(1, 0.0), fx::top(1)]);
        let rev = |app: &App| {
            app.title_block()
                .grid(&[])
                .cells()
                .find(|cell| cell.caption == "Rev:")
                .map(|cell| cell.value.text())
                .expect("the title block names a rev")
        };
        let stamped = app.title_block();
        assert_eq!(
            stamped.author, app.session.identity.name,
            "the author is the session's"
        );
        assert_eq!(
            app.session.may_write(),
            blockworx_store::doc::Writability::Writable
        );
        let before = rev(&app);

        app.session.submit(blockworx_doc::commit::Commit::new(
            "Moved a block".to_owned(),
            vec![blockworx_store::fixture::block_move(1, 5)],
        ));

        let after = rev(&app);
        assert_ne!(before, after, "a commit did not move the title block's rev");
        assert_eq!(after, app.session.doc.repo().rev().get().to_string());

        app.dispatch_action(&ctx, Action::ViewRev(blockworx_doc::fixtures::rev(1)));
        assert_eq!(
            rev(&app),
            "1",
            "the title block is not stamped with the rev on the canvas"
        );
        assert_eq!(
            app.session.may_write(),
            blockworx_store::doc::Writability::ReadOnly,
            "a past rev is padlocked",
        );
    }

    /// The Date row is the log's, not the clock's: it is the day the rev on
    /// the canvas was written, so walking back in time walks the date back
    /// with it — and two exports of one rev say the same thing forever. A
    /// scratch session records no wall times at all, and then the block
    /// simply has no date to give.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn the_date_is_the_written_day_of_the_rev_on_the_canvas() {
        use crate::widget::test_fixtures as fx;
        use blockworx_store::handle::{Clock, Store};
        use blockworx_store::record::{Identity, WallTime};
        use blockworx_store::temp::TempDir;

        let ctx = egui::Context::default();
        assert!(
            app_on(vec![fx::block(1, 0.0), fx::top(1)])
                .title_block()
                .date
                .is_none(),
            "a scratch session has no wall times, so it can have no date",
        );

        let dir = TempDir::new("app-title-block-date");
        let root = dir.join("doc.bwx");
        // Two days apart, so the two revs cannot land on one date in any zone.
        let mut store = Store::create(
            &root,
            Clock::Pinned {
                at: WallTime::from_unix_millis(1_756_000_000_000),
                step: std::time::Duration::from_hours(48),
            },
        )
        .expect("the container");
        for (n, ops) in [
            (1, vec![fx::block(1, 0.0), fx::top(1)]),
            (2, vec![blockworx_store::fixture::block_move(1, 5)]),
        ] {
            store
                .submit_edit(
                    blockworx_doc::commit::Commit::new(format!("Edit {n}"), ops),
                    &Identity::new("ada"),
                )
                .expect("the edit lands");
        }
        let written: Vec<String> = store
            .rows()
            .iter()
            .map(|row| blockworx_store::history::date(row.wall_time))
            .collect();
        assert_eq!(written.len(), 2, "precondition: two rows were written");
        assert_ne!(
            written[0], written[1],
            "precondition: the two revs must fall on different days",
        );
        drop(store);

        let mut app = App::new(AppConfig {
            opening: crate::app::Opening::Path(root),
            ..Default::default()
        });
        assert_eq!(app.title_block().date.as_deref(), Some(written[1].as_str()));
        app.dispatch_action(&ctx, Action::ViewRev(blockworx_doc::fixtures::rev(1)));
        assert_eq!(
            app.title_block().date.as_deref(),
            Some(written[0].as_str()),
            "the time machine showed one rev and the block dated another",
        );
    }

    /// The bug the notices strip was rebuilt for: a load failure the user
    /// cannot get rid of. Acknowledged through the real click, it is gone —
    /// and stays gone, while the standing read-only line would not have been
    /// dismissible at all.
    #[test]
    fn an_acknowledged_failure_does_not_come_back() {
        use crate::panels::notices::Notice;
        use crate::panels::painted::Chrome;
        let viewport = Rect::from_min_size(pos2(0.0, 0.0), vec2(900.0, 700.0));
        let toolbar = Rect::from_min_size(pos2(330.0, 8.0), vec2(240.0, 40.0));
        let mut app = app_on(Vec::new());
        app.report_failure("Failed to open /tmp/whatever.bwx: it is not a container".to_owned());
        assert!(
            matches!(app.notices().as_slice(), [Notice::Failure(_)]),
            "the failure did not reach the canvas",
        );

        let mut chrome = Chrome::new(viewport);
        chrome.settle(|ui| app.show_document_notices(ui, viewport, toolbar));
        let dismiss = chrome
            .rect(crate::panels::notices::DISMISS)
            .expect("the failure drew an acknowledgement");
        chrome.click_at(dismiss.center(), |ui| {
            app.show_document_notices(ui, viewport, toolbar);
        });

        assert!(
            app.notices().is_empty(),
            "the acknowledged failure came back"
        );
        chrome.settle(|ui| app.show_document_notices(ui, viewport, toolbar));
        assert!(
            chrome.texts().is_empty(),
            "the strip is still drawing: {:?}",
            chrome.texts(),
        );
    }

    // ── The time machine (F7) ────────────────────────────────────────────────
    //
    // Every case here drives the real dispatch and the real registry: what
    // is withheld is withheld because the registry withheld it, and the
    // document on the canvas is whatever `viewed_document` hands the
    // drawing.

    mod time_machine {
        use super::{Action, App};
        use crate::canvas::convert::IntoEgui as _;
        use crate::kernel::saturation;
        use crate::path::BlockPath;
        use crate::tools::commands::CommandId;
        use crate::tools::tool::ToolTrait as _;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::{commit::Commit, fixtures::block_id, repo::Repo, rev::Rev};
        use blockworx_geom::{Rect, pos2, vec2};
        use blockworx_paint::Saturation;
        use blockworx_store::doc::{Viewing, Writability};

        /// The lens drains the canvas's color and the present restores it
        /// (spec §3.2).
        #[test]
        fn the_past_is_drawn_drained_of_color_and_the_present_is_not() {
            assert_eq!(saturation(Viewing::Head), Saturation::Full);
            assert_eq!(saturation(Viewing::Past(rev(23))), Saturation::Drained);
        }

        /// The projection of what is on the canvas — the oracle for "which
        /// document is being shown". `content_hash` cannot serve: it covers
        /// the rev, and a rev-2 prefix fold and a rev-2 head are the same
        /// document only in what they hold.
        fn shown(app: &App) -> String {
            blockworx_store::document_file::to_json(app.session.viewed_repo().document())
        }

        fn head(app: &App) -> String {
            blockworx_store::document_file::to_json(app.session.doc.repo().document())
        }

        /// Three revs over one child block: draw it, move it, move it
        /// again — so rev 1 is visibly different from rev 3, and the block
        /// that moves is *inside* the top the editor opens on, where the
        /// canvas can see and select it.
        fn app_with_three_revs() -> App {
            let mut app = super::app_on(vec![
                fx::block(1, 0.0),
                fx::block_in(
                    2,
                    crate::path::Scope::Block(block_id(1)),
                    Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
                ),
                fx::top(1),
            ]);
            for x in [5, 9] {
                app.session.submit(Commit::new(
                    format!("Moved to {x}"),
                    vec![blockworx_store::fixture::block_move(2, x)],
                ));
            }
            assert_eq!(
                app.session.doc.repo().rev(),
                rev(3),
                "three commits, three revs"
            );
            app
        }

        fn rev(n: u64) -> Rev {
            blockworx_doc::fixtures::rev(n)
        }

        fn commands(app: &mut App) -> crate::tools::commands::CommandSet {
            app.session
                .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
        }

        /// Selecting a rev puts *that* document on the canvas and takes the
        /// writing half of the registry away — while leaving everything a
        /// reader needs: select, navigate, zoom, copy, export.
        #[test]
        fn viewing_a_past_rev_shows_the_prefix_fold_and_withholds_the_writes() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let at_head = head(&app);
            let at_two = blockworx_store::document_file::to_json(
                Repo::folding(&app.session.doc.repo().log()[..2])
                    .unwrap()
                    .document(),
            );
            assert_ne!(at_head, at_two, "precondition: the two revs differ");

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));

            assert_eq!(app.session.viewing(), Viewing::Past(rev(2)));
            assert_eq!(shown(&app), at_two, "the canvas is not showing rev 2");
            assert_eq!(head(&app), at_head, "viewing the past moved the head");
            assert_eq!(app.session.may_write(), Writability::ReadOnly);

            let set = commands(&mut app);
            let authoring_tools = crate::tools::names::band_tools()
                .filter(|tool| tool.arming_writes_the_document())
                .map(CommandId::Arm);
            assert!(
                authoring_tools.clone().count() > 1,
                "the toolbar must carry authoring tools for this to check any",
            );
            for withheld in [
                CommandId::Undo,
                CommandId::Redo,
                CommandId::Delete,
                CommandId::Import,
            ]
            .into_iter()
            .chain(authoring_tools)
            {
                assert!(
                    !set.contains(withheld),
                    "{withheld:?} is invocable while viewing the past",
                );
            }
            for kept in [
                CommandId::Export(crate::export::ExportFormat::Json),
                CommandId::ZoomIn,
                CommandId::GoUp,
                CommandId::Arm(crate::tools::names::ToolName::Select),
            ] {
                assert!(set.contains(kept), "{kept:?} was withheld from a reader");
            }
        }

        /// Export writes what is on screen, and while the time machine is
        /// open what is on screen is the past — under a stamp naming that
        /// rev, since every whole-document export is D19's artifact.
        #[test]
        fn export_writes_the_rev_on_the_canvas() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            let exported = app
                .export_content(crate::export::ExportFormat::Json, None)
                .text()
                .expect("a JSON export is text")
                .to_owned();
            assert_eq!(
                blockworx_store::document_file::parse(&exported, "the export")
                    .expect("the export parses as a document"),
                blockworx_store::document_file::parse(&shown(&app), "the canvas")
                    .expect("and so does the canvas"),
                "the export is not the document being viewed",
            );
            let stamp = blockworx_store::projection::exported_stamp_in(&exported)
                .expect("the export is stamped");
            assert_eq!(stamp.rev, rev(1));
            assert_eq!(
                stamp.provenance.expect("and stamped with provenance").rev,
                rev(1),
                "the export names a rev other than the one on the canvas",
            );
        }

        /// Copy-from-history, end to end: copy at a past rev, return to the
        /// present, paste. What lands is what rev 1 held — which is the
        /// whole point of the feature, and what the honest version of the
        /// undo/copy/redo dance buys.
        #[test]
        fn copy_out_of_the_past_pastes_into_the_present() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let block = block_id(2);
            let rect_at = |app: &mut App| {
                app.session
                    .drawing()
                    .shape(crate::shape::ShapeId::Rect(block))
                    .expect("the block is on the canvas")
                    .gui_rect()
            };
            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            // The pick opens the level rev 1 worked on (R57), which for this
            // fixture's one seeding commit is the root. The block being
            // copied lives a level in, so the reader goes back to it — which
            // is what a hand would do, and what this test is about.
            app.session.path = BlockPath::opening(app.session.viewed_document());
            let was = rect_at(&mut app);

            app.dispatch_action(&ctx, Action::Copy(vec![crate::shape::ShapeId::Rect(block)]));
            let payload =
                super::copied(&ctx).expect("a copy in the past still reaches the clipboard");

            app.dispatch_action(&ctx, Action::ViewHead);
            assert_eq!(app.session.viewing(), Viewing::Head);
            let before = super::live_blocks(&app);
            app.dispatch_action(&ctx, Action::Paste(payload));
            assert_eq!(
                super::live_blocks(&app),
                before + 1,
                "the paste did not land in the present",
            );

            // The pasted copy is a fresh id carrying rev 1's geometry.
            let pasted = app
                .session
                .tool
                .selection()
                .and_then(|sel| sel.shapes())
                .and_then(|shapes| shapes.first().copied())
                .expect("the paste selects what it landed");
            let landed = app
                .session
                .drawing()
                .shape(pasted)
                .expect("the pasted block is on the canvas")
                .gui_rect();
            assert_eq!(
                landed.size(),
                was.size(),
                "what came back is not the block as rev 1 held it",
            );
        }

        /// Going up is navigation, so a reader keeps it — but at the
        /// document root there is nowhere to go, the registry says so, and
        /// looking at the past is not something a dead button drops you
        /// out of. The writable half of this claim is
        /// `going_up_from_the_root_does_nothing_and_is_not_offered`.
        #[test]
        fn going_up_from_the_root_does_nothing_while_viewing_the_past() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            // An editor opens inside the top block, so the root takes one
            // go-up to reach — and that first one is pure navigation.
            assert!(
                !app.session.path.segments().is_empty(),
                "an editor opens inside the top"
            );
            assert!(
                commands(&mut app).contains(CommandId::GoUp),
                "precondition: rising a level is navigation, which a reader keeps",
            );
            app.dispatch_action(&ctx, Action::GoUp);
            assert!(
                app.session.path.segments().is_empty(),
                "the first go-up pops to the root"
            );

            let named_top = app.session.doc.document().title_block().top;
            let before = app.session.doc.repo().rev();
            app.dispatch_action(&ctx, Action::GoUp);

            assert!(
                !commands(&mut app).contains(CommandId::GoUp),
                "the root offered a way up",
            );
            assert_eq!(
                app.session.doc.document().title_block().top,
                named_top,
                "a reader's go-up at the root wrapped the document",
            );
            assert_eq!(
                app.session.doc.repo().rev(),
                before,
                "and nothing reached the log"
            );
            assert_eq!(
                app.session.viewing(),
                Viewing::Past(rev(2)),
                "and left the time machine",
            );
        }

        /// A rev whose blocks the current path descends through may predate
        /// them entirely; the path falls back rather than showing an empty
        /// scope that does not exist.
        #[test]
        fn a_path_that_the_viewed_rev_never_held_falls_back() {
            let ctx = egui::Context::default();
            let mut app = super::app_on(vec![fx::block(1, 0.0), fx::top(1)]);
            let deeper = Commit::new(
                "Added a child".into(),
                vec![fx::block_in(
                    2,
                    crate::path::Scope::Block(block_id(1)),
                    Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
                )],
            );
            app.session.submit(deeper);
            app.session.path = BlockPath::to_parent_of(app.session.doc.document(), block_id(2))
                .expect("the child has a parent path");
            app.session.path.push(block_id(2));
            assert!(
                !app.session.path.segments().is_empty(),
                "precondition: the path descends"
            );

            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            assert!(
                app.session.path.is_held_by(app.session.viewed_document()),
                "the path still names a block rev 1 never held: {}",
                app.session.path,
            );
        }

        /// A 1280×800 shell, wide enough for every band to lay out.
        fn screen() -> Rect {
            Rect::from_min_size(pos2(0.0, 0.0), vec2(1280.0, 800.0))
        }

        /// How many of band 2's creators this session would arm — the
        /// registry's own answer, which is what draws each button live or
        /// dead. Select is not counted: it authors nothing, and looking
        /// around a past rev is the whole point of the lens.
        fn armable_creators(app: &mut App) -> usize {
            let set = commands(app);
            crate::tools::names::band_tools()
                .filter(|name| name.arming_writes_the_document())
                .filter(|name| set.contains(CommandId::Arm(*name)))
                .count()
        }

        /// Spec §3.2's three redundant signals, raised together in one real
        /// frame of the shell: the band names the rev on the canvas, the tool
        /// band goes inert, and the canvas drains its color. The failure the
        /// redundancy is for — modeling against a state that is not live — is
        /// severe, so all three are asserted at once and none may lapse alone.
        #[test]
        fn the_read_only_lens_raises_all_three_signals() {
            let ctx = super::shell_ctx();
            let mut app = app_with_three_revs();
            super::shell_frames(&mut app, &ctx, screen(), 4);
            let present = super::shell_text(&mut app, &ctx, screen());
            assert!(
                !present.iter().any(|said| said.starts_with("Rev ")),
                "precondition: the writable present raises no pill: {present:?}",
            );
            assert!(
                armable_creators(&mut app) > 0,
                "precondition: the present arms its creators",
            );
            assert_eq!(saturation(app.session.viewing()), Saturation::Full);

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            super::shell_frames(&mut app, &ctx, screen(), 4);
            let past = super::shell_text(&mut app, &ctx, screen());
            assert!(
                past.iter().any(|said| said == "Rev 2"),
                "the pill does not name the rev on the canvas: {past:?}",
            );
            assert_eq!(
                armable_creators(&mut app),
                0,
                "the tool band is still live under the lens",
            );
            assert_eq!(
                saturation(app.session.viewing()),
                Saturation::Drained,
                "the canvas is still drawn in its own colors",
            );
        }

        /// §2.0: the mode is a *state of the bar*, not a second object. The
        /// bar is the same box either way — nothing below it moves when the
        /// lens opens — and the region the canvas frames inside is unchanged
        /// with it, so a fit taken under the lens lands exactly where the
        /// same fit lands at the head.
        #[test]
        fn the_lens_changes_the_bars_state_and_moves_nothing_under_it() {
            let ctx = super::shell_ctx();
            let mut app = app_with_three_revs();
            super::shell_frames(&mut app, &ctx, screen(), 4);
            let live = app.canvas.viewport();
            let clear = app.safe.region();
            let bar = crate::shell::berth_rect(&ctx, crate::shell::Berth::TopBar)
                .expect("the top bar never laid out");
            assert!(live.is_positive(), "precondition: the canvas laid out");
            assert!(
                clear.top() >= bar.bottom(),
                "the safe region at {clear:?} runs under the bar at {bar:?}",
            );

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            super::shell_frames(&mut app, &ctx, screen(), 4);
            assert_eq!(
                crate::shell::berth_rect(&ctx, crate::shell::Berth::TopBar),
                Some(bar),
                "the mode resized the bar instead of filling its centre",
            );
            assert_eq!(app.canvas.viewport(), live, "the lens reflowed the canvas");
            assert_eq!(
                app.safe.region(),
                clear,
                "the lens moved the region the drawing frames inside",
            );
        }

        /// Escape returns to the present from anywhere (spec §3.2) — driven
        /// as a real key event through a real frame, so a handler that never
        /// sees the key fails here.
        #[test]
        fn escape_returns_to_the_present_from_anywhere() {
            let ctx = super::shell_ctx();
            let mut app = app_with_three_revs();
            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            super::shell_frames(&mut app, &ctx, screen(), 4);
            assert_eq!(
                app.session.viewing(),
                Viewing::Past(rev(2)),
                "precondition: the lens is open",
            );

            press(&mut app, &ctx, screen(), egui::Key::Escape);
            assert_eq!(
                app.session.viewing(),
                Viewing::Head,
                "Escape did not close the lens",
            );
        }

        /// §8's ordering, which is the whole of why the navigator claims the
        /// key: Escape closes the panel *before* anything else reads it, and
        /// the next press is the lens's. Two presses, two effects, in the
        /// spec's order.
        #[test]
        fn escape_closes_the_navigator_before_it_closes_the_lens() {
            use crate::shell::workspace::PanelView;
            let ctx = super::shell_ctx();
            let mut app = app_with_three_revs();
            app.workspace.show(PanelView::History);
            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            super::shell_frames(&mut app, &ctx, screen(), 4);
            assert!(
                app.workspace.open() && app.session.viewing() == Viewing::Past(rev(2)),
                "precondition: the panel is up over an open lens",
            );

            press(&mut app, &ctx, screen(), egui::Key::Escape);
            assert!(!app.workspace.open(), "Escape left the panel standing");
            assert_eq!(
                app.session.viewing(),
                Viewing::Past(rev(2)),
                "the same press closed the lens as well as the panel",
            );

            press(&mut app, &ctx, screen(), egui::Key::Escape);
            assert_eq!(
                app.session.viewing(),
                Viewing::Head,
                "the second press did not reach the lens",
            );
        }

        /// One shell frame in which `key` is pressed and released.
        fn press(app: &mut App, ctx: &egui::Context, screen: Rect, key: egui::Key) {
            ctx.clone()
                .run_ui(
                    egui::RawInput {
                        screen_rect: Some(screen.egui()),
                        events: vec![egui::Event::Key {
                            key,
                            physical_key: None,
                            pressed: true,
                            repeat: false,
                            modifiers: egui::Modifiers::NONE,
                        }],
                        ..Default::default()
                    },
                    |ui| app.shell_frame(ui),
                )
                .drop_without_applying_deltas();
        }

        /// A session with band 2's second tool armed, through the digit that
        /// arms it — the real path, so a slot that only fills when a test
        /// assigns the field fails here.
        fn app_holding_the_block_tool(ctx: &egui::Context) -> App {
            use crate::tools::names::ToolName;
            let mut app = app_with_three_revs();
            press(&mut app, ctx, screen(), egui::Key::Num2);
            super::shell_frames(&mut app, ctx, screen(), 2);
            assert_eq!(
                app.session.tool.name(),
                ToolName::NewBlock,
                "precondition: the digit armed the cluster's second tool",
            );
            app
        }

        /// The mode answers to the lens and to nothing else: arming a tool
        /// leaves the bar's centre empty — nothing shifts under the user's
        /// hand when a tool is picked — and only a past rev on the canvas
        /// fills it. Walked through a whole session, so a frame that fills
        /// the centre on the wrong condition or leaves it filled fails here.
        #[test]
        fn only_the_lens_fills_the_bars_centre() {
            let ctx = super::shell_ctx();
            let mut app = app_holding_the_block_tool(&ctx);
            let showing = |app: &mut App| {
                super::shell_frames(app, &ctx, screen(), 4);
                let said = super::shell_text(app, &ctx, screen());
                let up = said.iter().any(|word| word.starts_with("Rev "));
                (up, said)
            };

            let (up, said) = showing(&mut app);
            assert!(!up, "an armed tool filled the bar's centre: {said:?}");

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            let (up, said) = showing(&mut app);
            assert!(up, "the lens did not fill the centre: {said:?}");

            app.dispatch_action(&ctx, Action::ViewHead);
            let (up, said) = showing(&mut app);
            assert!(!up, "the centre outlived the lens: {said:?}");
        }

        /// Tagging from the panel is not an edit: it reaches the tags and
        /// nothing else — not the log's revs, not the undo stack — so
        /// Ctrl+Z after naming a rev still takes back the last edit.
        #[test]
        fn tagging_a_rev_moves_neither_the_log_nor_the_undo_stack() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let before = head(&app);
            let at = app.session.doc.repo().rev();
            let depth = app.session.doc.trail().undo_depth();

            // Tagging is offered while *viewing* the past, which is where
            // the panel is used from — and viewing withholds every write.
            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            app.dispatch_action(
                &ctx,
                Action::TagRev {
                    at: rev(1),
                    name: "Initial Draft".to_owned(),
                    how: blockworx_store::tags::Tagging::Added,
                },
            );

            assert_eq!(app.session.doc.tags().of(rev(1)), ["Initial Draft"]);
            assert_eq!(app.session.doc.repo().rev(), at, "a tag spent a rev");
            assert_eq!(app.session.doc.trail().undo_depth(), depth);
            assert_eq!(head(&app), before, "a tag changed the document");

            // §8.1's rev carries a set, so a second name joins the first
            // rather than replacing it.
            app.dispatch_action(
                &ctx,
                Action::TagRev {
                    at: rev(1),
                    name: "vendor".to_owned(),
                    how: blockworx_store::tags::Tagging::Added,
                },
            );
            assert_eq!(
                app.session.doc.tags().of(rev(1)),
                ["Initial Draft", "vendor"]
            );

            app.dispatch_action(
                &ctx,
                Action::TagRev {
                    at: rev(1),
                    name: "Initial Draft".to_owned(),
                    how: blockworx_store::tags::Tagging::Removed,
                },
            );
            assert_eq!(
                app.session.doc.tags().of(rev(1)),
                ["vendor"],
                "an untag took off more than the name it gave",
            );
        }

        /// The cluster's two step buttons, through the policy both they and
        /// the dispatch read: bounded at the oldest rev, and off the end of
        /// the log into the writable present.
        #[test]
        fn stepping_walks_back_through_the_log_and_forward_into_the_present() {
            use blockworx_store::doc::{At, TimeStep};

            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let head = app.session.doc.repo().rev();
            let step = |app: &App, dir| app.session.viewing().stepped(head, dir);

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            assert_eq!(step(&app, TimeStep::Back), Some(At::Rev(rev(1))));

            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            assert_eq!(
                step(&app, TimeStep::Back),
                None,
                "there is nothing before the first rev",
            );
            assert_eq!(step(&app, TimeStep::Forward), Some(At::Rev(rev(2))));

            app.dispatch_action(&ctx, Action::ViewRev(rev(3)));
            assert_eq!(
                step(&app, TimeStep::Forward),
                Some(At::Current),
                "forward off the end of the log is the writable present",
            );
            app.dispatch_action(&ctx, Action::ViewHead);
            assert_eq!(step(&app, TimeStep::Back), None, "the present is not a rev");
        }

        /// A container this session may not write can still be walked
        /// through — viewing costs nothing — and the walk changes nothing
        /// about what it may write, which under R37 is nothing at all.
        #[cfg(not(target_arch = "wasm32"))]
        #[test]
        fn a_read_only_container_walks_its_own_past() {
            use blockworx_store::handle::{Clock, Store};
            use blockworx_store::record::Identity;
            use blockworx_store::temp::TempDir;

            let ctx = egui::Context::default();
            let dir = TempDir::new("app-time-machine-read-only");
            let root = dir.join("doc.bwx");
            let mut store = Store::create(&root, Clock::System).expect("the container");
            for (n, ops) in [
                (1, vec![fx::block(1, 0.0), fx::top(1)]),
                (2, vec![blockworx_store::fixture::block_move(1, 5)]),
            ] {
                store
                    .submit_edit(
                        Commit::new(format!("Edit {n}"), ops),
                        &Identity::new("test"),
                    )
                    .expect("the edit lands");
            }
            drop(store);

            let _held = Store::open(&root, Clock::System).expect("the first session holds it");
            let mut app = App::new(super::AppConfig {
                opening: crate::app::Opening::Path(root.clone()),
                ..Default::default()
            });
            assert!(
                app.session.doc.read_only_reason().is_some(),
                "precondition: the container is locked by another session",
            );

            app.dispatch_action(&ctx, Action::ViewRev(rev(1)));
            assert_eq!(
                app.session.viewing(),
                Viewing::Past(rev(1)),
                "viewing is free"
            );
            let set = commands(&mut app);
            assert!(
                set.contains(CommandId::Export(crate::export::ExportFormat::Json)),
                "a reader may not take the rev it is looking at out of the log",
            );
            assert!(
                !set.contains(CommandId::Delete),
                "a container this session may not write offered an edit",
            );

            // And the door itself refuses, not merely the registry.
            let before = app.session.doc.repo().rev();
            app.dispatch_action(&ctx, Action::ViewHead);
            app.session.submit(Commit::new(
                "An edit this session may not make".into(),
                vec![blockworx_store::fixture::block_move(1, 9)],
            ));
            assert_eq!(
                app.session.doc.repo().rev(),
                before,
                "a read-only container took an edit anyway",
            );
        }
    }

    // ── Provenance exports (D19) ─────────────────────────────────────────────
    //
    // One artifact, three consumers. Everything here drives the real
    // dispatch: the export is the action the history row fires, the paste is
    // the action the keyboard fires, and the clipboard between them is the
    // `CopyText` command the app actually emitted.

    mod provenance {
        use super::{Action, App, copied};
        use crate::tools::tool::ExportTo;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::{commit::Commit, fixtures::rev, id::BlockId, rev::Rev};
        use blockworx_geom::{Rect, pos2};
        use blockworx_store::projection::{Found, Provenance, stamp_in};

        /// Three revs over one child block, the block moving each time, so
        /// rev 1 differs visibly from rev 3.
        fn app_with_three_revs() -> App {
            let mut app = super::app_on(vec![
                fx::block(1, 0.0),
                fx::block_in(
                    2,
                    crate::path::Scope::Block(blockworx_doc::fixtures::block_id(1)),
                    Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
                ),
                fx::top(1),
            ]);
            for x in [5, 9] {
                app.session.submit(Commit::new(
                    format!("Moved to {x}"),
                    vec![blockworx_store::fixture::block_move(2, x)],
                ));
            }
            assert_eq!(
                app.session.doc.repo().rev(),
                rev(3),
                "precondition: three revs"
            );
            app
        }

        /// What the history row's Copy put on the clipboard.
        fn copy_rev(app: &mut App, ctx: &egui::Context, at: Rev) -> String {
            app.dispatch_action(
                ctx,
                Action::ExportRev {
                    at,
                    to: ExportTo::Clipboard,
                },
            );
            copied(ctx).expect("the rev reached the clipboard")
        }

        fn provenance_of(text: &str) -> Provenance {
            match stamp_in(text) {
                Found::Stamped(stamp) => stamp.provenance.expect("the export carries provenance"),
                found => panic!("the export carries no stamp this build reads: {found:?}"),
            }
        }

        /// The blocks a scope holds, in the head document.
        fn children_of(app: &App, parent: BlockId) -> Vec<BlockId> {
            app.session
                .doc
                .repo()
                .document()
                .blocks()
                .filter(|(_, block)| block.parent == parent)
                .map(|(id, _)| id)
                .collect()
        }

        /// The blocks in the level the canvas is open on — the *active
        /// scope*, which is where D19 says an insert lands.
        fn blocks_in_scope(app: &App) -> Vec<BlockId> {
            children_of(app, app.session.path.scope().wire_id())
        }

        /// D19: an export taken at a rev names *that* rev, the name the rev
        /// carries (D18), and the session that took it — and the document
        /// under the stamp is that rev's fold, not the head's.
        #[test]
        fn an_export_at_a_rev_is_stamped_with_that_rev_its_tag_and_this_session() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            app.dispatch_action(
                &ctx,
                Action::TagRev {
                    at: rev(2),
                    name: "Initial Draft".to_owned(),
                    how: blockworx_store::tags::Tagging::Added,
                },
            );
            assert_eq!(
                app.session.doc.tags().of(rev(2)),
                ["Initial Draft"],
                "precondition: rev 2 is tagged",
            );

            let text = copy_rev(&mut app, &ctx, rev(2));
            let from = provenance_of(&text);
            assert_eq!(from.rev, rev(2));
            assert_eq!(from.author, app.session.identity.name);
            assert_eq!(from.tags, ["Initial Draft"]);
            assert_eq!(from.line(), format!("Rev 2 of {}", app.document_name()));

            let at_two = app.session.document_at(rev(2)).expect("rev 2 reads back");
            assert_eq!(
                blockworx_store::document_file::parse(&text, "the export").expect("it parses"),
                at_two,
                "the export is not the document at the rev it names",
            );
            assert_ne!(
                blockworx_store::document_file::to_json(&at_two),
                blockworx_store::document_file::to_json(app.session.doc.repo().document()),
                "precondition: rev 2 and the head are different documents",
            );

            // The head's own export names the head, with no tag it has none of.
            let head = provenance_of(&copy_rev(&mut app, &ctx, rev(3)));
            assert_eq!(head.rev, rev(3));
            assert!(head.tags.is_empty());
        }

        /// The loop D19 exists for: copy a rev out of the history, paste it
        /// into the writable present, and the old document is standing there
        /// as one block holding what it held then.
        #[test]
        fn copying_a_rev_and_pasting_it_at_head_inserts_it_as_one_block() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let before = blocks_in_scope(&app);
            assert_eq!(before.len(), 1, "precondition: one block in the open level");

            let scope = app.session.scope_name();
            assert!(
                !scope.is_empty(),
                "precondition: the canvas is inside a level"
            );
            let undoable = app.session.doc.trail().undo_depth();
            let text = copy_rev(&mut app, &ctx, rev(2));
            app.dispatch_action(&ctx, Action::Paste(text));

            let after = blocks_in_scope(&app);
            assert_eq!(
                after.len(),
                2,
                "the pasted document did not land as one new block in the open scope",
            );
            let inserted = *after
                .iter()
                .find(|id| !before.contains(id))
                .expect("a new block in the open scope");
            assert_eq!(
                app.session
                    .doc
                    .repo()
                    .document()
                    .block(&inserted)
                    .expect("the inserted block")
                    .title
                    .name
                    .as_str(),
                app.document_name(),
                "the inserted block is not titled after the source document",
            );
            assert_eq!(
                children_of(&app, inserted).len(),
                1,
                "the source document's top-level blocks are not the new block's children",
            );

            let label = app
                .session
                .doc
                .repo()
                .log()
                .last()
                .expect("the insert sealed a commit")
                .label()
                .to_owned();
            assert_eq!(
                label,
                format!(
                    "Insert diagram {} at rev 2 from {} into scope {scope}",
                    app.document_name(),
                    app.session.identity.name,
                ),
                "the insert did not land under D19's label",
            );
            assert_eq!(
                app.session.doc.trail().undo_depth(),
                undoable + 1,
                "the insert is an ordinary gesture and must stand ready to be undone",
            );
        }

        /// A plain `document.json` carries no provenance, so it is named by
        /// the file it arrived in — and it still inserts as a block.
        #[test]
        fn a_document_with_no_provenance_inserts_under_its_file_stem() {
            let mut app = app_with_three_revs();
            let json = blockworx_store::document_file::to_json(app.session.doc.repo().document());
            assert!(
                !json.contains("stamp"),
                "precondition: a bare projection carries no stamp",
            );
            let before = blocks_in_scope(&app);
            let scope = app.session.scope_name();

            app.session
                .handle_imported("motor-controller.json", json.into_bytes());

            assert_eq!(blocks_in_scope(&app).len(), before.len() + 1);
            assert_eq!(
                app.session
                    .doc
                    .repo()
                    .log()
                    .last()
                    .expect("the import sealed a commit")
                    .label(),
                format!("Insert diagram motor-controller into scope {scope}"),
                "an unprovenanced document is named by its file, and says no rev it has none of",
            );
        }

        /// Taking a copy is reading, so a session that may not write does it;
        /// pasting one back is writing, so the same session does not.
        #[test]
        fn a_read_only_session_may_copy_a_rev_but_not_paste_one() {
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();
            let text = copy_rev(&mut app, &ctx, rev(2));

            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            assert_eq!(
                app.session.may_write(),
                blockworx_store::doc::Writability::ReadOnly,
                "precondition: the time machine makes the session read-only",
            );

            assert!(
                !copy_rev(&mut app, &ctx, rev(1)).is_empty(),
                "a read-only session was refused a copy it writes nothing to make",
            );

            let head = app.session.doc.repo().rev();
            app.dispatch_action(&ctx, Action::Paste(text));
            assert_eq!(
                app.session.doc.repo().rev(),
                head,
                "a read-only session pasted a document into the log",
            );
        }

        /// The two clipboard payloads are disjoint, read off the real copy
        /// paths: a copied selection is never taken for a document, a copied
        /// rev is never taken for a selection, and the canvas claims both
        /// from a focused text box.
        #[test]
        fn a_copied_selection_and_a_copied_rev_cannot_be_taken_for_each_other() {
            use crate::shape::ShapeId;
            use crate::widget::clipboard::is_object_clipboard;
            let ctx = egui::Context::default();
            let mut app = app_with_three_revs();

            let shape = ShapeId::Rect(blocks_in_scope(&app)[0]);
            app.dispatch_action(&ctx, Action::Copy(vec![shape]));
            let selection = copied(&ctx).expect("the selection reached the clipboard");
            assert!(
                crate::edit::clipboard::Clipboard::from_json(&selection).is_some(),
                "precondition: a copied selection is a clipboard payload",
            );
            assert!(blockworx_editor::import::from_clipboard(&selection).is_none());

            let export = copy_rev(&mut app, &ctx, rev(2));
            assert!(blockworx_editor::import::from_clipboard(&export).is_some());
            assert!(
                crate::edit::clipboard::Clipboard::from_json(&export).is_none(),
                "an exported document was read as a copied selection",
            );

            for payload in [&selection, &export] {
                assert!(
                    is_object_clipboard(payload),
                    "the canvas would have let this fall into a text box",
                );
            }
            assert!(!is_object_clipboard("just some text"));
        }

        /// The title block says where an opened export came from, and an
        /// ordinary session says nothing at all.
        ///
        /// Driven through the command line's door, which is the only one:
        /// nothing in the chrome opens a `document.json`, because it is a
        /// projection and not a diagram (R53).
        #[cfg(not(target_arch = "wasm32"))]
        #[test]
        fn opening_an_export_shows_where_it_came_from() {
            let ctx = egui::Context::default();
            let dir = blockworx_store::temp::TempDir::new("opened-export");
            let mut app = app_with_three_revs();
            assert!(
                app.title_block()
                    .grid(&[])
                    .cells()
                    .all(|cell| cell.caption != "From:"),
                "precondition: a document authored here came from nowhere",
            );

            let source = app.document_name();
            let text = copy_rev(&mut app, &ctx, rev(2));
            let path = dir.join("shared.json");
            std::fs::write(&path, &text).expect("the export is written");
            let app = App::new(crate::app::AppConfig {
                opening: crate::app::Opening::Path(path.clone()),
                ..crate::app::AppConfig::default()
            });

            let grid = app.title_block().grid(&[]);
            let from = grid
                .cells()
                .find(|cell| cell.caption == "From:")
                .expect("the title block does not say where the document came from");
            assert_eq!(from.value.text(), format!("Rev 2 of {source}"));
            assert_eq!(
                app.document_name(),
                "shared",
                "the session is now its own document, named by the file it opened",
            );
            assert_eq!(
                app.title_block().rev,
                app.session.doc.repo().rev(),
                "the Rev row names this session's rev, not the source's",
            );
        }
    }

    // ── The container flow ───────────────────────────────────────────────────
    //
    // Everything here drives the real dispatch and the real registry against
    // a container in a temp directory. Nothing drives a dialog: `rfd` is a
    // path delivery mechanism, and what it delivers to is
    // `crate::file`'s plain functions, tested there.

    #[cfg(not(target_arch = "wasm32"))]
    mod containers {
        use super::{App, AppConfig, BlockPath};
        use crate::history::Direction;
        use crate::panels::notices::Notice;
        use crate::tools::commands::CommandId;
        use crate::tools::tool::Action;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::{
            commit::Commit,
            fixtures::{block_id, rev},
        };
        use blockworx_geom::{Rect, pos2};
        use blockworx_store::doc::Doc;
        use blockworx_store::doc::{Viewing, Writability};
        use blockworx_store::handle::{Clock, Store};
        use blockworx_store::manifest::{Row, RowKind};
        use blockworx_store::record::Identity;
        use blockworx_store::temp::TempDir;
        use std::path::Path;

        fn app_opening(path: &Path) -> App {
            App::new(AppConfig {
                opening: crate::app::Opening::Path(path.to_path_buf()),
                ..Default::default()
            })
        }

        /// A session started with no path, with the documents directory
        /// pointed at `documents` — D20's born-attached start, driven
        /// exactly as `main` drives it minus the platform lookup.
        fn app_born_in(documents: &Path) -> App {
            App::new(AppConfig {
                opening: crate::app::Opening::Born,
                documents: blockworx_store::naming::Documents::at(documents),
                ..Default::default()
            })
        }

        /// The container a born session made, which is the only thing in
        /// its documents directory.
        fn only_container_in(documents: &Path) -> std::path::PathBuf {
            let mut found: Vec<_> = std::fs::read_dir(documents)
                .expect("the documents directory")
                .map(|entry| entry.expect("an entry").path())
                .collect();
            assert_eq!(found.len(), 1, "the documents directory holds {found:?}");
            found.pop().expect("the one container")
        }

        /// The first edit a blank document can take, through the app's own
        /// write door — the door every gesture ends at, so what it proves
        /// about the log holds for the toolbar too.
        /// One edit, as a frame takes it: the session writes, and the frame
        /// that carried the write claims the container the record landed in.
        fn draw_a_block(app: &mut App) {
            app.session.submit(Commit::new(
                "Drew a block".to_owned(),
                vec![fx::block(1, 0.0), fx::top(1)],
            ));
            app.claim_if_written();
        }

        /// A second edit, on the block the first one drew.
        fn move_the_block(app: &mut App) {
            app.session.submit(Commit::new(
                "Moved a block".to_owned(),
                vec![blockworx_store::fixture::block_move(1, 5)],
            ));
            app.claim_if_written();
        }

        /// A container holding one block, closed — something an app can open
        /// and then edit.
        fn container_with_a_block(root: &Path) {
            let mut store = Store::create(root, Clock::System).expect("the container is laid out");
            store
                .submit_edit(
                    Commit::new("Built a scene".into(), vec![fx::block(1, 0.0), fx::top(1)]),
                    &Identity::new("test"),
                )
                .expect("the scene lands");
        }

        fn records(root: &Path) -> Vec<Row> {
            std::fs::read_to_string(root.join(blockworx_store::container::MANIFEST))
                .expect("the manifest is readable")
                .lines()
                .map(|line| serde_json::from_str(line).expect("every row parses"))
                .collect()
        }

        /// One frame's tail: dispatch, then close the history step, exactly
        /// as `App::ui` does — which is what makes the undo below the undo a
        /// user would get.
        fn frame(app: &mut App, ctx: &egui::Context, action: Action) {
            let before = app.session.state();
            app.dispatch_action(ctx, action);
            app.session
                .record_history(&before, core::time::Duration::ZERO);
        }

        /// The fixture block's rect, read straight out of the document: the
        /// block *is* the scope the editor opens inside, so it is not one of
        /// the shapes drawn in that scope.
        fn block_rect(app: &App) -> blockworx_doc::geometry::GridRect {
            app.session
                .doc
                .document()
                .block(&block_id(1))
                .expect("the fixture's block")
                .rect
        }

        fn select_the_block(app: &mut App) {
            app.session.tool = crate::tools::resize_block::ResizeBlock::Selected {
                shape: crate::shape::ShapeId::Rect(block_id(1)),
            }
            .into();
        }

        #[test]
        fn a_container_path_argument_opens_it_attached_and_names_the_window() {
            let dir = TempDir::new("app-opens-a-container");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);

            let app = app_opening(&root);
            assert!(
                matches!(app.session.doc, Doc::Attached { .. }),
                "a .bwx path must open the container, not a scratch session",
            );
            assert_eq!(app.window_title(), "doc.bwx - BlockWorx");
            assert_eq!(
                app.session.doc.projection(),
                Some(blockworx_store::projection::Freshness::Stale),
                "the fixture container has revs and no projection beside them — \
                 stale, but never a title marker (the revs are always current)",
            );
            assert_eq!(
                app.session.doc.repo().rev(),
                blockworx_doc::fixtures::rev(1),
                "the container's head is the rev it opened at",
            );
        }

        /// D20's start: no path means a blank canvas in a container of its
        /// own, attached and writable from the first frame — not a demo, and
        /// not a session that persists nothing.
        #[test]
        fn a_start_with_no_path_is_born_attached_on_a_blank_canvas() {
            let dir = TempDir::new("app-born-attached");
            let documents = dir.join("Documents");

            let app = app_born_in(&documents);

            assert!(
                matches!(app.session.doc, Doc::Attached { .. }),
                "a no-argument start must be born attached, not scratch",
            );
            assert_eq!(
                app.session.doc.writability(),
                blockworx_store::doc::Writability::Writable,
                "a document born here must be writable from its first edit",
            );
            assert!(
                app.session.doc.repo().log().is_empty()
                    && app.session.doc.document().blocks().next().is_none(),
                "the canvas opened on something rather than blank",
            );

            let root = only_container_in(&documents);
            assert_eq!(app.attached_root().as_deref(), Some(root.as_path()));
            let name = crate::file::document_name(&root);
            assert_eq!(
                name.split('-').count(),
                3,
                "{name} is not the three-word name D20 asks for",
            );
            assert_eq!(app.window_title(), format!("{name}.bwx - BlockWorx"));
        }

        /// The F6 property, from rev 1: the very first edit of a session
        /// that opened on nothing is in a file when the call returns. It is
        /// also what claims the container — the recent list learns the name
        /// only once the document is worth reopening.
        #[test]
        fn the_first_edit_lands_in_the_born_container_and_claims_it() {
            let dir = TempDir::new("app-born-first-edit");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let root = only_container_in(&documents);
            assert!(
                records(&root).is_empty() && !app.recent.paths().contains(&root),
                "precondition: nothing written, nothing remembered",
            );

            draw_a_block(&mut app);

            let written = records(&root);
            assert_eq!(written.len(), 1, "the first edit never reached the file");
            assert_eq!(written[0].kind, RowKind::Edit);
            assert_eq!(written[0].rev, app.session.doc.repo().rev());
            assert!(
                app.recent.paths().contains(&root),
                "a written-in container did not join the recent list",
            );
        }

        /// Launch, quit, and the documents directory is as it was: a
        /// container this session invented and nobody wrote in goes with it.
        #[test]
        fn quitting_a_session_that_wrote_nothing_removes_the_container_it_made() {
            use eframe::App as _;

            let dir = TempDir::new("app-born-pristine-exit");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let root = only_container_in(&documents);

            app.on_exit();

            assert!(!root.exists(), "quitting left {} behind", root.display());
            assert!(
                std::fs::read_dir(&documents)
                    .expect("the documents directory")
                    .next()
                    .is_none(),
                "the documents directory was littered",
            );
        }

        /// The other half of the rule: a container with an edit in it is a
        /// document, and quitting does not touch it.
        #[test]
        fn quitting_after_an_edit_keeps_the_container() {
            use eframe::App as _;

            let dir = TempDir::new("app-born-written-exit");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let root = only_container_in(&documents);
            draw_a_block(&mut app);

            app.on_exit();

            assert_eq!(records(&root).len(), 1, "the edit is still in the log");
            assert!(
                root.join(blockworx_store::container::PROJECTION).is_file(),
                "the clean exit did not leave the projection beside it",
            );
        }

        /// Only what this session created is ever swept. A container the
        /// user opened is theirs, however empty — deleting it is not ours to
        /// decide.
        #[test]
        fn a_container_the_session_only_opened_is_never_removed() {
            use eframe::App as _;

            let dir = TempDir::new("app-opened-empty-kept");
            let root = dir.join("theirs.bwx");
            drop(Store::create(&root, Clock::System).expect("their empty container"));

            let mut app = app_opening(&root);
            assert!(
                matches!(app.session.doc, Doc::Attached { .. }) && records(&root).is_empty(),
                "precondition: an empty container, opened rather than created",
            );

            app.on_exit();

            assert!(
                root.join(blockworx_store::container::MANIFEST).is_file(),
                "an empty container the user opened was swept away",
            );
        }

        /// File ▸ New twice leaves one container, not two: the one nobody
        /// wrote in goes as soon as its store is dropped.
        #[test]
        fn a_second_new_document_takes_the_first_pristine_one_with_it() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-new-twice");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let first = only_container_in(&documents);

            app.dispatch_action(&ctx, Action::NewDocument);

            let second = only_container_in(&documents);
            assert_ne!(second, first, "File ▸ New reopened the same container");
            assert_eq!(
                app.attached_root().as_deref(),
                Some(second.as_path()),
                "the session is not on the container it just made",
            );
        }

        /// Renaming the document renames its container, and the session
        /// carries straight on into it: the log it is appending to is held
        /// open across the move, lock and all.
        #[test]
        fn renaming_moves_the_container_and_the_edits_follow_it() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-rename");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let born = only_container_in(&documents);
            draw_a_block(&mut app);
            assert!(
                app.recent.paths().contains(&born),
                "precondition: the born container is written in and remembered",
            );

            app.dispatch_action(&ctx, Action::RenameDocument("motor-controller".to_owned()));

            let renamed = documents.join("motor-controller.bwx");
            assert!(!born.exists(), "the old name still stands");
            assert_eq!(app.attached_root().as_deref(), Some(renamed.as_path()));
            assert_eq!(app.document_name(), "motor-controller");
            assert_eq!(app.window_title(), "motor-controller.bwx - BlockWorx");
            assert_eq!(
                app.recent.paths().first(),
                Some(&renamed),
                "the recent list still offers the name it had: {:?}",
                app.recent.paths(),
            );
            assert!(app.notices().is_empty(), "a rename that worked complained");

            move_the_block(&mut app);
            assert_eq!(
                records(&renamed).len(),
                2,
                "the edit after the rename did not land in the renamed log",
            );
        }

        /// A rename that would land on something already there is refused,
        /// out loud, and leaves the session exactly where it was.
        #[test]
        fn renaming_onto_a_name_that_exists_is_refused() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-rename-onto");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let born = only_container_in(&documents);
            draw_a_block(&mut app);
            let taken = documents.join("taken.bwx");
            drop(Store::create(&taken, Clock::System).expect("the container in the way"));

            app.dispatch_action(&ctx, Action::RenameDocument("taken".to_owned()));

            assert!(
                matches!(app.notices().as_slice(), [Notice::Failure(_)]),
                "a refused rename said nothing the user can see",
            );
            assert_eq!(
                app.attached_root().as_deref(),
                Some(born.as_path()),
                "the session moved anyway",
            );
            assert_eq!(
                records(&taken).len(),
                0,
                "the container in the way was written"
            );
            move_the_block(&mut app);
            assert_eq!(records(&born).len(), 2, "the session stopped writing");
        }

        /// A name that is no name — blank, or one that would move the
        /// document somewhere else — is refused before the filesystem is
        /// asked.
        #[test]
        fn a_rename_to_something_that_is_not_a_name_is_refused() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-rename-nonsense");
            let documents = dir.join("Documents");
            let mut app = app_born_in(&documents);
            let born = only_container_in(&documents);

            for nonsense in ["", "   ", "../escape", "sub/engine"] {
                app.dispatch_action(&ctx, Action::RenameDocument(nonsense.to_owned()));
                assert_eq!(
                    app.attached_root().as_deref(),
                    Some(born.as_path()),
                    "{nonsense:?} was taken for a document name",
                );
            }
            assert_eq!(app.notices().len(), 4, "each refusal is said once");
        }

        #[test]
        fn an_edit_through_the_dispatch_lands_in_the_log_file() {
            let dir = TempDir::new("app-edit-reaches-the-log");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let ctx = egui::Context::default();

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);
            assert_eq!(records(&root).len(), 1, "precondition: one seeded record");

            frame(&mut app, &ctx, Action::Nudge { dx: 1, dy: 0 });

            let written = records(&root);
            assert_eq!(written.len(), 2, "the nudge never reached the file");
            assert_eq!(written[1].kind, RowKind::Edit);
            assert_eq!(written[1].rev, app.session.doc.repo().rev());
            assert_eq!(
                written[1].author.name, app.session.identity.name,
                "the record is attributed to this session's identity (D9)",
            );
        }

        /// Undo is a forward commit, so it is in the trail rather than an
        /// erasure of it (F7) — and the `of` each record names is what
        /// replay rebuilds the trail's stack movements from (F6).
        #[test]
        fn undo_and_redo_are_written_as_their_own_records() {
            let dir = TempDir::new("app-history-records");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let ctx = egui::Context::default();

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);

            frame(&mut app, &ctx, Action::Nudge { dx: 1, dy: 0 });
            let edit = app.session.doc.repo().rev();
            assert!(
                app.session.has_step(Direction::Back),
                "precondition: a step to take"
            );

            frame(&mut app, &ctx, Action::Undo);
            frame(&mut app, &ctx, Action::Redo);

            let kinds: Vec<RowKind> = records(&root).iter().map(|r| r.kind).collect();
            assert_eq!(
                kinds,
                [
                    RowKind::Edit,
                    RowKind::Edit,
                    RowKind::Undo { of: edit },
                    RowKind::Redo { of: edit.next() },
                ],
            );
        }

        /// F6, end to end and through the real dispatch: a mistake is made,
        /// the projection is written, the session ends, and the next one
        /// takes the mistake back — with the undo in the trail as its own
        /// record, since the log is an audit trail rather than a state dump.
        #[test]
        fn a_mistake_is_still_undoable_after_a_save_a_quit_and_a_reopen() {
            let dir = TempDir::new("app-f6");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let ctx = egui::Context::default();

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);
            let before = block_rect(&app);

            frame(&mut app, &ctx, Action::Nudge { dx: 1, dy: 0 });
            let mistake = block_rect(&app);
            assert_ne!(before, mistake, "precondition: the nudge moved the block");
            app.save_projection();
            drop(app);

            let mut app = app_opening(&root);
            assert!(
                app.session.has_step(Direction::Back),
                "a reopened container offered nothing to take back",
            );
            assert_eq!(
                app.session.state().stood,
                crate::history::Stood::of(app.session.doc.trail()),
                "the rebuilt editor stack does not stand where the trail does",
            );
            assert!(
                app.session
                    .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                    .contains(CommandId::Undo),
                "the registry withholds Undo on a document that has depth, so no \
                 chord, palette entry or toolbar button could reach it",
            );

            frame(&mut app, &ctx, Action::Undo);

            assert_eq!(
                block_rect(&app),
                before,
                "the mistake survived an undo taken after the reopen",
            );
            let written = records(&root);
            assert_eq!(written.len(), 3, "the undo did not reach the file");
            assert!(matches!(written[2].kind, RowKind::Undo { .. }));
        }

        /// The other half of F6: a step taken back *before* the quit is
        /// still a step forward after it, and the depth the UI shows is the
        /// reconstructed one.
        #[test]
        fn an_undo_taken_before_the_quit_is_redoable_after_the_reopen() {
            let dir = TempDir::new("app-f6-redo");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let ctx = egui::Context::default();

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);
            let before = block_rect(&app);
            frame(&mut app, &ctx, Action::Nudge { dx: 1, dy: 0 });
            let nudged = block_rect(&app);
            frame(&mut app, &ctx, Action::Undo);
            assert_eq!(block_rect(&app), before);
            drop(app);

            let mut app = app_opening(&root);
            assert!(
                app.session.has_step(Direction::Forward),
                "the forward history did not survive the restart",
            );
            frame(&mut app, &ctx, Action::Redo);
            assert_eq!(
                block_rect(&app),
                nudged,
                "redoing after the restart did not put the edit back",
            );
            assert!(
                !app.session.has_step(Direction::Forward),
                "the future is spent"
            );

            // And a fresh edit forks away from a reconstructed future the
            // same way it forks away from a live one.
            frame(&mut app, &ctx, Action::Undo);
            assert!(app.session.has_step(Direction::Forward));
            select_the_block(&mut app);
            frame(&mut app, &ctx, Action::Nudge { dx: 0, dy: 1 });
            assert!(
                !app.session.has_step(Direction::Forward),
                "a reconstructed redo outlived the edit that forked away from it",
            );
        }

        /// F1: a second session on a held container may look, not write. The
        /// registry is what enforces it — the editing commands are not in
        /// the set at all, so nothing that reads the set (a chord, the
        /// palette, a script) can invoke one.
        #[test]
        fn a_read_only_container_withholds_the_editing_commands() {
            let dir = TempDir::new("app-read-only");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let _held = Store::open(&root, Clock::System).expect("the first session holds it");

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);
            assert!(
                app.session.doc.read_only_reason().is_some(),
                "precondition: the lock is held, so this session may not write",
            );
            assert_eq!(app.window_title(), "doc.bwx - BlockWorx [read-only]");

            let commands = app
                .session
                .available_commands(crate::edit::naming::InterfaceLock::Unlocked);
            for withheld in [
                CommandId::Delete,
                CommandId::Cut,
                CommandId::Undo,
                CommandId::Arm(crate::tools::names::ToolName::NewBlock),
            ] {
                assert!(
                    !commands.contains(withheld),
                    "{withheld:?} is invocable on a container this session may not write",
                );
            }
            for kept in [
                CommandId::Copy,
                CommandId::Export(crate::export::ExportFormat::Svg),
                CommandId::FitView,
            ] {
                assert!(commands.contains(kept), "{kept:?} writes nothing");
            }
        }

        /// A read-only container refuses the writes that do not come through
        /// the registry either — the canvas still drags — and the refusal
        /// must not leave the editor's undo stack out of step with the
        /// trail.
        #[test]
        fn a_read_only_container_takes_no_edit_and_no_history_step() {
            let dir = TempDir::new("app-read-only-writes");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let _held = Store::open(&root, Clock::System).expect("the first session holds it");
            let ctx = egui::Context::default();

            let mut app = app_opening(&root);
            app.session.path = BlockPath::opening(app.session.doc.document());
            select_the_block(&mut app);
            let before = app.session.doc.document().clone();

            frame(&mut app, &ctx, Action::Nudge { dx: 1, dy: 0 });
            frame(&mut app, &ctx, Action::Undo);

            assert_eq!(
                app.session.doc.document().clone(),
                before,
                "a refused edit left the session's document ahead of the file",
            );
            assert_eq!(records(&root).len(), 1, "nothing was appended");
        }

        /// Save As is how a session that has no file gets one: the container
        /// it lays out replays to exactly the document that was on screen.
        #[test]
        fn saving_a_scratch_session_as_a_container_replays_to_the_same_document() {
            let dir = TempDir::new("app-save-as");
            let root = dir.join("saved.bwx");
            let mut app = super::app_on(vec![fx::block(1, 0.0), fx::top(1)]);
            assert!(
                matches!(app.session.doc, Doc::Scratch { .. }),
                "precondition: nothing about this session is persisted",
            );
            let scratch = app.session.doc.document().clone();
            let commits = app.session.doc.repo().log().len();

            app.save_as_container(
                &egui::Context::default(),
                &root,
                crate::file::SaveScope::Whole,
            );

            assert_eq!(
                app.session.doc.container_root(),
                Some(root.as_path()),
                "the session did not adopt the container it just wrote",
            );
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Fresh),
                "Save As writes the projection, so a container is readable from \
                 the moment it exists",
            );
            assert!(
                root.join(PROJECTION).is_file(),
                "no projection beside the log it just seeded",
            );
            assert_eq!(app.window_title(), "saved.bwx - BlockWorx");
            assert!(
                app.recent.paths().contains(&root),
                "a container we just made is one to offer reopening",
            );
            drop(app);

            let reopened = Store::open(&root, Clock::System).expect("the container reopens");
            assert_eq!(
                reopened.document().clone(),
                scratch,
                "the seeded container is not the document it was seeded from",
            );
            assert_eq!(
                reopened.rows().len(),
                commits,
                "the session's commits became the container's history",
            );
        }

        /// R37's Save-as, through the lens: the container it writes holds
        /// the document *as shown*, the session lands in it writable at
        /// that rev, and the log it left behind is untouched.
        #[test]
        fn saving_while_viewing_a_rev_writes_the_document_as_shown() {
            let dir = TempDir::new("app-save-as-through");
            let source = dir.join("source.bwx");
            let saved = dir.join("through-2.bwx");
            {
                let mut store =
                    Store::create(&source, Clock::System).expect("the container is laid out");
                let author = Identity::new("ada");
                for (n, ops) in [
                    (1, vec![fx::block(1, 0.0), fx::top(1)]),
                    (2, vec![blockworx_store::fixture::block_move(1, 5)]),
                    (3, vec![blockworx_store::fixture::block_move(1, 9)]),
                ] {
                    store
                        .submit_edit(Commit::new(format!("Edit {n}"), ops), &author)
                        .expect("the edit lands");
                }
                store
                    .tag(
                        rev(2),
                        "the good one",
                        blockworx_store::tags::Tagging::Added,
                        &author,
                    )
                    .expect("the tag");
            }
            let mut app = app_opening(&source);
            let ctx = egui::Context::default();
            app.dispatch_action(&ctx, Action::ViewRev(rev(2)));
            let shown =
                blockworx_store::document_file::to_json(app.session.viewed_repo().document());

            app.save_as_container(&ctx, &saved, crate::file::SaveScope::Through(rev(2)));

            assert_eq!(
                app.session.doc.container_root(),
                Some(saved.as_path()),
                "the session did not adopt the container it just wrote",
            );
            assert_eq!(
                app.session.viewing(),
                Viewing::Head,
                "the lens stayed open over a document that is now the head",
            );
            assert_eq!(
                app.session.doc.repo().rev(),
                rev(2),
                "the new head is not the cut"
            );
            assert_eq!(
                blockworx_store::document_file::to_json(app.session.doc.repo().document()),
                shown,
                "what was saved is not what was on the canvas",
            );
            assert_eq!(
                app.session.doc.tags().of(rev(2)),
                ["the good one"],
                "the rev's name did not come with it",
            );
            assert_eq!(app.session.may_write(), Writability::Writable);
            assert_eq!(
                records(&source).len(),
                4,
                "saving a prefix rewrote the log it was cut from",
            );
            // R43: a save that worked is routine, so the status line says
            // it and the toast stays quiet.
            assert_eq!(
                crate::shell::status_line::showing(&ctx).as_deref(),
                Some("Saved through rev 2 as through-2"),
                "the status line did not say which rev was written",
            );

            // A save that cannot happen is news too, and news is what the
            // toast is for — nothing about the session changed, so there is
            // no standing fact for a notice to carry.
            app.save_as_container(&ctx, &saved, crate::file::SaveScope::Whole);
            let said = crate::shell::toast::showing(&ctx).expect("the toast says something");
            assert!(
                said.starts_with("Could not save as through-2"),
                "a refused save said {said:?}",
            );
            assert!(
                app.notices().is_empty(),
                "a refused save left a notice standing on the canvas",
            );
        }

        /// The same door, at the head: a Save-as of an open container copies
        /// its log rather than re-authoring its commits, so the tags — and
        /// the wall times, authors and record kinds beside them — survive
        /// the move. `Store::seeded` flattened all four, and now serves only
        /// the scratch session it was written for.
        #[test]
        fn saving_a_container_at_head_carries_its_tags_across() {
            let dir = TempDir::new("app-save-as-whole");
            let source = dir.join("source.bwx");
            let saved = dir.join("copy.bwx");
            {
                let mut store =
                    Store::create(&source, Clock::System).expect("the container is laid out");
                let author = Identity::new("ada");
                store
                    .submit_edit(
                        Commit::new("Built a scene".into(), vec![fx::block(1, 0.0), fx::top(1)]),
                        &author,
                    )
                    .expect("the scene lands");
                store
                    .tag(
                        rev(1),
                        "the start",
                        blockworx_store::tags::Tagging::Added,
                        &author,
                    )
                    .expect("the tag");
            }
            let mut app = app_opening(&source);
            assert_eq!(
                app.session.doc.tags().of(rev(1)),
                ["the start"],
                "precondition: the source names its own rev",
            );

            app.save_as_container(
                &egui::Context::default(),
                &saved,
                crate::file::SaveScope::Whole,
            );

            assert_eq!(
                app.session.doc.tags().of(rev(1)),
                ["the start"],
                "a whole Save-as flattened the log's tag records",
            );
            assert_eq!(
                std::fs::read(source.join(blockworx_store::container::MANIFEST))
                    .expect("the source log"),
                std::fs::read(saved.join(blockworx_store::container::MANIFEST)).expect("the copy"),
                "a whole Save-as is not the same log",
            );
        }

        // ── The share bundle (F9, R54) ───────────────────────────────────

        /// The round trip the feature is, through the app's own doors: a
        /// diagram shared to one file, opened again somewhere else, is the
        /// same diagram — the same log bytes, the same names on its revs, a
        /// head that verifies and a projection that stamps it. The zip is
        /// left where it was, inert.
        #[test]
        fn a_shared_diagram_opens_again_as_the_diagram_it_was() {
            let dir = TempDir::new("app-share-round-trip");
            let source = dir.join("engine.bwx");
            {
                let mut store =
                    Store::create(&source, Clock::System).expect("the container is laid out");
                let author = Identity::new("ada");
                store
                    .submit_edit(
                        Commit::new("Built a scene".into(), vec![fx::block(1, 0.0), fx::top(1)]),
                        &author,
                    )
                    .expect("the scene lands");
                store
                    .tag(
                        rev(1),
                        "the start",
                        blockworx_store::tags::Tagging::Added,
                        &author,
                    )
                    .expect("the tag");
                store.save_projection().expect("the projection");
            }
            let ctx = egui::Context::default();
            let mut app = app_opening(&source);
            let shared = dir.join("outbox").join("engine.bwx.zip");
            std::fs::create_dir_all(dir.join("outbox")).expect("the outbox");

            app.share_bundle(&ctx, &shared);

            assert!(shared.is_file(), "nothing was shared");
            assert_eq!(
                crate::shell::status_line::showing(&ctx).as_deref(),
                Some("Shared as engine.bwx.zip"),
                "a share that worked is routine and belongs in the status line (R43)",
            );
            assert!(
                crate::shell::toast::showing(&ctx).is_none(),
                "a share that worked raised an attention event",
            );

            // Somewhere else entirely, the way a mail attachment arrives.
            let elsewhere = TempDir::new("app-share-inbox");
            let arrived = elsewhere.join("engine.bwx.zip");
            std::fs::copy(&shared, &arrived).expect("the bundle travels");
            let mut reader = app_opening(Path::new(""));
            reader.open_bundle(&ctx, &arrived);

            let unpacked = elsewhere.join("engine.bwx");
            assert_eq!(
                reader.session.doc.container_root(),
                Some(unpacked.as_path()),
                "the reader is not editing the diagram that was unpacked beside the zip",
            );
            assert_eq!(
                std::fs::read(source.join(blockworx_store::container::MANIFEST))
                    .expect("the source log"),
                std::fs::read(unpacked.join(blockworx_store::container::MANIFEST))
                    .expect("the unpacked log"),
                "the diagram that arrived is not the bytes that were sent",
            );
            assert_eq!(
                reader.session.doc.tags().of(rev(1)),
                ["the start"],
                "a rev's name did not survive the trip",
            );
            assert_eq!(reader.session.may_write(), Writability::Writable);
            assert_eq!(
                reader.session.doc.projection(),
                Some(Freshness::Fresh),
                "the unpacked projection does not stamp its own head",
            );
            assert!(reader.failures.is_empty(), "the open complained");
            assert!(arrived.is_file(), "opening the bundle consumed it");
        }

        /// A zip that is no diagram is refused by name, and the session it
        /// was offered to is exactly where it was.
        #[test]
        fn a_zip_that_holds_no_diagram_is_refused_and_changes_nothing() {
            let dir = TempDir::new("app-share-not-a-diagram");
            let holiday = dir.join("holiday.zip");
            std::fs::write(&holiday, b"not a zip at all").expect("the file");
            let ctx = egui::Context::default();
            let mut app = app_opening(Path::new(""));
            let before = app.session.doc.document().clone();

            app.open_bundle(&ctx, &holiday);

            let said = app.failures.last().expect("the refusal is on the canvas");
            assert!(
                said.starts_with("holiday.zip is not a shared diagram"),
                "the refusal does not name what was picked: {said}",
            );
            assert!(
                matches!(app.session.doc, Doc::Scratch { .. }),
                "a refused open moved the session",
            );
            assert_eq!(app.session.doc.document().clone(), before);
            assert!(
                !dir.join("holiday.bwx").exists(),
                "a refused unpack left a container behind",
            );
        }

        /// Nothing is ever unpacked over anything: where the name beside the
        /// zip is taken, the open becomes a second dialog and not a write.
        /// The dialog itself is not driven here — what is proved is that the
        /// session and the directory in the way are both untouched, and that
        /// a destination the user then names is honoured.
        #[test]
        fn a_shared_diagram_whose_name_is_taken_asks_rather_than_overwrites() {
            let dir = TempDir::new("app-share-collision");
            let source = dir.join("engine.bwx");
            container_with_a_block(&source);
            let bundle = dir.join("engine.bwx.zip");
            blockworx_store::bundle::pack(&source, &bundle).expect("the bundle");
            let standing = std::fs::read(source.join(blockworx_store::container::MANIFEST))
                .expect("the log that is in the way");
            assert_eq!(
                crate::file::unpacks_to(&bundle),
                crate::file::Landing::Occupied(source.clone()),
                "precondition: the bundle would land on the diagram it came from",
            );

            let ctx = egui::Context::default();
            let mut app = app_opening(Path::new(""));
            app.open_bundle(&ctx, &bundle);

            assert!(
                matches!(app.session.doc, Doc::Scratch { .. }),
                "the collision opened something",
            );
            assert_eq!(
                std::fs::read(source.join(blockworx_store::container::MANIFEST)).expect("the log"),
                standing,
                "the diagram in the way was written over",
            );
            assert!(
                app.pending_file.is_some(),
                "the collision did not become a question for the user",
            );

            // The answer the dialog would deliver, dispatched as it would be.
            let chosen = dir.join("engine (2).bwx");
            app.unpack_and_open(&bundle, &chosen);
            assert_eq!(
                app.session.doc.container_root(),
                Some(chosen.as_path()),
                "the destination the user named was not the one written",
            );
            assert_eq!(
                std::fs::read(chosen.join(blockworx_store::container::MANIFEST))
                    .expect("the new log"),
                standing,
                "the diagram that landed is not the one that was shared",
            );
        }

        /// The recent list is the File menu's shortcut, and it has to
        /// survive the process: the app writes it on save and reads it back
        /// on the next launch.
        #[test]
        fn the_recent_list_survives_the_storage_round_trip() {
            use eframe::App as _;

            let dir = TempDir::new("app-recent");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            let mut storage = crate::file::tests::MemoryStorage::default();

            let mut app = app_opening(&root);
            app.restore_preferences(&storage);
            assert!(
                app.recent.paths().contains(&root),
                "opening a container did not remember it",
            );
            app.save(&mut storage);
            drop(app);

            let mut next = app_opening(Path::new(""));
            next.restore_preferences(&storage);
            assert!(
                next.recent.paths().contains(&root),
                "the next session was not offered the container the last one opened",
            );
        }

        /// A remembered container that has gone away is reported and dropped,
        /// so a dead entry is offered once and not twice.
        #[test]
        fn opening_a_container_that_is_gone_forgets_it() {
            let dir = TempDir::new("app-recent-forgets");
            let missing = dir.join("gone.bwx");
            let mut app = app_opening(Path::new(""));
            app.recent.remember(&missing);

            app.open_container(&missing);

            assert!(
                !app.recent.paths().contains(&missing),
                "a container that will not open stayed on the list",
            );
            assert!(
                matches!(app.session.doc, Doc::Scratch { .. }),
                "a failed open must leave the session where it was",
            );
        }

        // ── The projection (D11) ─────────────────────────────────────────

        use blockworx_store::container::PROJECTION;
        use blockworx_store::projection::{Freshness, stamp_in};

        /// Invoke a command through the registry, exactly as a chord or the
        /// palette would — so the availability gate is part of what the
        /// test drives, not something it steps around.
        fn invoke(app: &mut App, ctx: &egui::Context, id: CommandId) -> bool {
            let Some(action) = app
                .session
                .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                .take(id)
            else {
                return false;
            };
            app.dispatch_action(ctx, action);
            true
        }

        #[test]
        fn saving_writes_the_projection_and_clears_the_staleness_marker() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-save-projection");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);

            let mut app = app_opening(&root);
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Stale),
                "precondition: the container has a log and nothing projected from it",
            );
            assert!(
                !app.window_title().contains('\u{2022}'),
                "staleness never reaches the title — there are no unsaved \
                 changes to warn about: {}",
                app.window_title(),
            );

            assert!(invoke(&mut app, &ctx, CommandId::Save), "Save is offered");

            assert_eq!(app.session.doc.projection(), Some(Freshness::Fresh));
            let text = std::fs::read_to_string(root.join(PROJECTION)).expect("the projection");
            assert_eq!(
                &blockworx_store::document_file::parse(&text, PROJECTION)
                    .expect("it reads back as a document"),
                app.session.doc.repo().document(),
                "the file is not the projection of the log it sits beside",
            );

            // And an edit after it puts the marker back, since the log has
            // moved on from what the file shows.
            app.dispatch_action(
                &ctx,
                Action::Delete(crate::tools::tool::Deletable::Shape(
                    crate::shape::ShapeId::Rect(block_id(1)),
                )),
            );
            assert_eq!(app.session.doc.projection(), Some(Freshness::Stale));
        }

        /// The projection follows the log by itself: once the head sits
        /// still for the settle window, a stale `document.json` is
        /// rewritten with no one asking — and a moving head is waited out,
        /// not chased.
        #[test]
        fn a_stale_projection_refreshes_itself_once_the_head_settles() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-projection-settle");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);

            let mut app = app_opening(&root);
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Stale),
                "precondition: a log with nothing projected beside it",
            );

            let opened = std::time::Instant::now();
            app.refresh_projection_at(&ctx, opened);
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Stale),
                "the first sighting arms the timer; it must not write yet",
            );
            app.refresh_projection_at(&ctx, opened + App::PROJECTION_SETTLE / 2);
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Stale),
                "half a settle window is not settled",
            );
            app.refresh_projection_at(&ctx, opened + App::PROJECTION_SETTLE);
            assert_eq!(
                app.session.doc.projection(),
                Some(Freshness::Fresh),
                "a settled head gets its projection written",
            );
        }

        /// A projection nobody's fold wrote is flagged rather than trusted,
        /// and the next save takes the file back (D11).
        #[test]
        fn a_projection_this_log_never_wrote_is_flagged_and_then_overwritten() {
            let ctx = egui::Context::default();
            let dir = TempDir::new("app-projection-hand-edited");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);
            std::fs::write(root.join(PROJECTION), "{\"top\": \"b0\", \"blocks\": []}")
                .expect("a hand-written projection");

            let mut app = app_opening(&root);
            assert_eq!(app.session.doc.projection(), Some(Freshness::Unrecognized));

            assert!(invoke(&mut app, &ctx, CommandId::Save), "Save is offered");
            assert_eq!(app.session.doc.projection(), Some(Freshness::Fresh));
            let text = std::fs::read_to_string(root.join(PROJECTION)).expect("the projection");
            assert!(
                matches!(
                    stamp_in(&text),
                    blockworx_store::projection::Found::Stamped(_)
                ),
                "the overwrite left a file with no stamp on it",
            );
        }

        /// Save refreshes a file beside a log; a session with no container,
        /// or one it may not write, has neither.
        #[test]
        fn save_is_withheld_without_a_writable_container() {
            let dir = TempDir::new("app-save-withheld");
            let root = dir.join("doc.bwx");
            container_with_a_block(&root);

            let scratch = super::app_on(vec![fx::block(1, 0.0), fx::top(1)]);
            assert_eq!(
                scratch.session.doc.saving(),
                blockworx_store::doc::Saving::Withheld
            );
            let mut scratch = scratch;
            assert!(
                !scratch
                    .session
                    .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                    .contains(CommandId::Save),
                "a scratch session has no projection to refresh",
            );

            let _held = Store::open(&root, Clock::System).expect("the first session holds it");
            let mut locked = app_opening(&root);
            assert!(
                locked.session.doc.read_only_reason().is_some(),
                "precondition: the lock is held",
            );
            assert!(
                !locked
                    .session
                    .available_commands(crate::edit::naming::InterfaceLock::Unlocked)
                    .contains(CommandId::Save),
                "a container this session may not write is not one to save into",
            );
        }

        /// The document format's own round trip, through the two paths a
        /// user takes: what Export writes is what Import reads. Since D19
        /// the whole document arrives as one block, so both of the source's
        /// blocks have to survive — the top as the new block, its child
        /// beneath it.
        #[test]
        fn a_json_export_imports_back_through_the_real_dispatch() {
            let mut source = super::app_on(vec![
                fx::block(1, 0.0),
                fx::block_in(
                    2,
                    crate::path::Scope::Block(block_id(1)),
                    Rect::from_min_max(pos2(4.0, 4.0), pos2(24.0, 24.0)),
                ),
                fx::top(1),
            ]);
            let exported = source
                .export_content(crate::export::ExportFormat::Json, None)
                .text()
                .expect("a JSON export is text")
                .to_owned();
            assert!(
                exported.contains("\"blocks\""),
                "precondition: the export is a JSON document:\n{exported}",
            );

            let mut target = super::app_on(vec![fx::block(9, 0.0), fx::top(9)]);
            let before = live_blocks(&target);
            target
                .session
                .handle_imported("exported.json", exported.into_bytes());

            assert_eq!(
                live_blocks(&target),
                before + 2,
                "the exported document did not arrive whole, as one block over its child",
            );
        }

        fn live_blocks(app: &App) -> usize {
            app.session.doc.document().blocks().count()
        }
    }

    #[test]
    fn tool_cursor_shows_only_while_canvas_hovered() {
        assert_eq!(
            effective_cursor(Some(Cursor::Crosshair), PointerOver::Canvas),
            Some(Cursor::Crosshair)
        );
        assert_eq!(
            effective_cursor(Some(Cursor::Crosshair), PointerOver::Elsewhere),
            None
        );
        assert_eq!(effective_cursor(None, PointerOver::Canvas), None);
    }
}

#[cfg(all(test, feature = "kittest"))]
mod kittest_visual {
    use super::{App, AppConfig};
    use crate::canvas::convert::IntoEgui as _;
    use crate::shell::picture::{Width, at_every_width, dress, dressed};
    use crate::shell::workspace::PanelView;
    use crate::tools::tool::Action;
    use blockworx_geom::{Vec2, vec2};
    use egui_kittest::Harness;

    /// The frame at rest: the docked top bar across the top — document menu,
    /// live dot, breadcrumb, and the right-hand actions with undo and redo
    /// drawn dead (R41) — the floating tool rail down the left with Select
    /// armed, the status line reading zoom and pointer at the bottom, and the
    /// canvas running edge to edge under all of it. The bar's centre is
    /// empty, no past rev being on the canvas.
    #[test]
    fn shell_frame() {
        at_every_width("shell_frame", |width| picture(width, Shown::Idle));
    }

    /// The navigator overlaying from the right: flush, full height under the
    /// bar, translucent, with no scrim and no close control. The 1024 picture
    /// is the narrow variant — the only thing a smaller window changes about
    /// it (§8).
    #[test]
    fn shell_navigator() {
        at_every_width("shell_navigator", |width| picture(width, Shown::History));
    }

    /// The same panel with another of its segments open: the block tree, its
    /// filter box over it, under the segments that say which of the three the
    /// navigator is showing.
    #[test]
    fn shell_navigator_hierarchy() {
        at_every_width("shell_navigator_hierarchy", |width| {
            picture(width, Shown::Hierarchy)
        });
    }

    /// §3's selection overlay: the bar of commands for one selected block,
    /// centred above it with 14px of air, its first five verbs in the row and
    /// the rest behind the ellipsis. Taken with the navigator open, so the
    /// picture also shows the bar clamping into the room the chrome left
    /// (§3.3).
    #[test]
    fn shell_selection_overlay() {
        at_every_width("shell_selection_overlay", |width| {
            picture(width, Shown::Selection)
        });
    }

    /// The toast (R38, R43): what needs attention, at the
    /// bottom of the frame. It is the one piece of chrome that leaves on its
    /// own, so the picture is taken while it holds.
    #[test]
    fn shell_toast() {
        at_every_width("shell_toast", |width| picture(width, Shown::Toast));
    }

    /// The read-only lens, and §6.2's signals in one picture: the bar tinted
    /// amber with the rev, the stepper and Return in its centre, the dot
    /// amber beside the breadcrumb, the tool rail dimmed and inert, and the
    /// canvas drained of its colour.
    #[test]
    fn shell_frame_viewing() {
        at_every_width("shell_frame_viewing", |width| picture(width, Shown::Lens));
    }

    /// Which of the frame's states a picture is taken in.
    #[derive(Clone, Copy)]
    enum Shown {
        Idle,
        History,
        Hierarchy,
        Lens,
        Selection,
        Toast,
    }

    fn picture(width: Width, shown: Shown) -> Harness<'static> {
        picture_at(vec2(width.points(), 800.0), shown)
    }

    #[expect(
        clippy::expect_used,
        reason = "a fixture that will not fold has no picture to take"
    )]
    fn picture_at(size: Vec2, shown: Shown) -> Harness<'static> {
        let mut app = App::new(AppConfig::default());
        let repo = blockworx_doc::repo::Repo::folding(&blockworx_store::fixture::edits(3))
            .expect("the edits fold");
        let _ = app.session.adopt(blockworx_store::doc::Doc::scratch(repo));
        // Every real path that adopts a document rebuilds the stack over
        // it. Without this the stack still stands on the empty document
        // the session opened with, and under the lens the undo button
        // reads that as a *document* step and draws dead.
        app.session.undo_stack =
            crate::history::UndoStack::reconstructed(app.session.doc.trail(), &app.session.state());
        match shown {
            Shown::Idle | Shown::Lens | Shown::Toast => {}
            Shown::History | Shown::Selection => app.workspace.show(PanelView::History),
            Shown::Hierarchy => app.workspace.show(PanelView::Hierarchy),
        }
        if let Shown::Selection = shown {
            let shape = crate::shape::ShapeId::Rect(blockworx_doc::fixtures::block_id(1));
            app.session.tool = crate::tools::resize_block::ResizeBlock::Selected { shape }.into();
        }
        if let Shown::Lens = shown {
            app.dispatch_action(
                &egui::Context::default(),
                Action::ViewRev(blockworx_doc::fixtures::rev(2)),
            );
        }
        let mut said = false;
        Harness::builder()
            .with_size(size.egui())
            .build_ui(move |ui| {
                dress(ui.ctx());
                if dressed(ui.ctx()) {
                    // Said once: the toast carries its own clock, and re-raising
                    // it every pass would hold it at the first frame of its rise.
                    if let Shown::Toast = shown
                        && !std::mem::replace(&mut said, true)
                    {
                        crate::shell::toast::say(ui.ctx(), "Could not export motor-controller.pdf");
                    }
                    app.shell_frame(ui);
                    // Re-framed each pass, so the picture shows §2.1 settled:
                    // an `Area` reports a stale position on the pass it is
                    // first sized in, and a single fit would be taken against
                    // that. The framing is idempotent, so this comes to rest.
                    app.dispatch_action(ui.ctx(), Action::ResetView);
                }
            })
    }
}