blockworx/app/

mod.rs

//! The shell as a composition of parts. Each one owns its own state and
//! answers the actions that are its own:
//!
//! - [`Session`] — the editor itself: the document, where this session is
//!   standing, what it has selected, what one undo would take back.
//! - `Surface` — the canvas and the glass over it: the camera, the bands,
//!   the popups, the palette, the navigator.
//! - `Exchange` — what comes back into the document from outside it: the
//!   import, the image pick.
//! - `Library` — the documents on disk, and what the session has to say
//!   about them.
//! - `Appearance` — how the editor looks and what the window is called.
//!
//! `shell_frame` is one batch, one [`kernel`] call and one replay: the chrome
//! is drawn from the [`View`] the last call answered and what it raises goes
//! into the batch beside what the pointer, the keys and the text field did;
//! the call paints the canvas and answers the next frame's chrome. What a
//! frame asks for is one of two things: an [`Action`], which goes into the
//! batch for the session to execute, or an [`Effect`], which the shell
//! performs itself once the call has run. Nothing about an effect's flow
//! passes through the session, and nothing the shell wants to know is asked
//! of it: a command goes in, and whatever comes of it is on the `View` —
//! the hand-off slot included.

use blockworx_geom::Rect;
use blockworx_store::record::Identity;

use crate::appearance::{Appearance, Applied, Editors};
use crate::canvas::convert::{IntoEgui as _, IntoGeom as _};
use crate::canvas::{Canvas, CanvasChrome, Diagram};
use crate::dialogs::{Ask, Dialogs};
use crate::exchange::Exchange;
use crate::export::ExportPayload;
use crate::kernel::{Event, Handoff, Session, Sheet, View, kernel};
use crate::library::Library;
use crate::panels::notices::Notice;
use crate::panels::overlay::OpenPicker;
use crate::surface::{OverCanvas, Popup, Surface};
use crate::tools::commands::{Act, Effect};
use crate::tools::tool::Action;

#[cfg(not(target_arch = "wasm32"))]
pub use crate::library::Opening;

// 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. 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,
}

pub struct App {
    /// The editor itself. Every document read and every write goes through
    /// it, and the frame reaches it through one [`kernel`] call.
    session: Session,
    surface: Surface,
    exchange: Exchange,
    library: Library,
    appearance: Appearance,
    /// The platform's pickers. A part that opens one is handed this rather
    /// than reaching for the platform itself, so a test answers a dialog
    /// instead of opening one.
    dialogs: Dialogs,
    /// What the last call answered, which the next frame draws its chrome
    /// from. `None` before the first call.
    shown: Option<View>,
    /// What the last frame's floating chrome and dialogs asked for, which
    /// reaches the next frame's batch: the chrome over the canvas is drawn
    /// after the call so it sits over the diagram, and what it raises is a
    /// frame late by construction.
    queued: Vec<Act>,
}

/// What the frame settles before the canvas pass, for the dispatch after it.
#[derive(Default)]
struct Ahead {
    /// The picker that was open on entry, which the chrome shows as active.
    picker: Option<OpenPicker>,
    /// What an open picker reported, which outranks the chrome and the
    /// keyboard: the popup is in front, so a click that reached it was meant
    /// for it.
    picked: Option<Action>,
    /// An object paste taken ahead of a focused text editor, which wins over
    /// whatever else the frame asks for.
    pasted: Option<String>,
}

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 (library, doc, failure) = Library::opening(opening, documents);
        #[cfg(target_arch = "wasm32")]
        let (library, doc, failure) = Library::opening();

        let mut session = Session::opening(doc, Identity::from_environment());
        // Said where it happened, so it is seeded rather than reported.
        session.failures = crate::kernel::Notices::opening(failure);
        let app = Self {
            session,
            surface: Surface::default(),
            exchange: Exchange::default(),
            library,
            appearance: Appearance::new(Editors {
                theme: theme_editor,
                font: font_editor,
            }),
            dialogs: Dialogs::default(),
            shown: None,
            queued: Vec::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;
            let title = app.window_title();
            app.appearance.opens_titled(title);
            app
        };
        app
    }

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

    /// What the shell calls this document — the session's own name, or the
    /// file a scratch session was opened from.
    fn document_name(&self) -> String {
        self.library.document_name(&self.session)
    }

    /// 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
                .session
                .written_at(rev)
                .map(blockworx_store::history::date),
            from: self.library.opened_from(),
        }
    }

    /// What an export is called, which sheet it is stamped with and which
    /// palette it prints in are the shell's facts, not the document's, so
    /// the session is told them before it draws its chrome or is told to do
    /// anything.
    fn state_the_sheet(&mut self) {
        let sheet = self.sheet();
        self.session.sheet = sheet;
    }

    /// What an export says about this document, which no one part knows on
    /// its own: the library names it, the session stamps it, and the
    /// appearance decides the palette it prints in.
    fn sheet(&self) -> Sheet {
        Sheet {
            name: self.document_name(),
            block: self.title_block(),
            scheme: self.appearance.preferences.theme,
        }
    }

    /// What this session has to tell the user about its files, asked
    /// outside a frame.
    #[cfg(test)]
    fn notices(&self) -> Vec<Notice> {
        self.session.notices()
    }

    /// The notices strip, hung below `above` — the chrome band along the top
    /// of the canvas, which it may never cover. An acknowledgement is an
    /// action like any other the chrome raises.
    fn show_document_notices(
        ui: &mut egui::Ui,
        notices: &[Notice],
        viewport: Rect,
        above: Rect,
    ) -> Option<Act> {
        crate::panels::notices::draw(ui, viewport.egui(), above.egui(), notices)
            .map(|acknowledged| Action::AcknowledgeFailure(acknowledged.0).into())
    }

    pub fn apply_preferences(&mut self, ctx: &egui::Context) {
        let applied = self.appearance.apply(ctx);
        self.tell_the_palette(applied);
    }

    /// The theme is the shell's, and the drawing is painted in its palette:
    /// a change is told to the session as a command, queued for the next
    /// call, so what the canvas paints in and what the chrome draws in are
    /// one look.
    fn tell_the_palette(&mut self, applied: Applied) {
        if applied == Applied::Changed {
            let palette = self.appearance.theme.palette().clone();
            self.queued.push(Act::Edit(Action::SetPalette(palette)));
        }
    }

    /// What the dev editors authored this frame: the role table and the
    /// canvas font sizes, which are the engine's own and have no command.
    fn tell_the_tuning(&mut self, edited: Applied) {
        if edited == Applied::Changed {
            let theme = &self.appearance.theme;
            self.session.retune(theme.overrides(), theme.font_sizes());
        }
    }

    /// Restore what was persisted in 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, panel and recent list.
    pub fn restore_preferences(&mut self, storage: &dyn eframe::Storage) {
        self.appearance.restore(storage);
        let key = self.document_name();
        self.surface.restore(storage, &key);
        // A stored profile name 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.appearance.preferences.identity();
        #[cfg(not(target_arch = "wasm32"))]
        self.library.restore(storage, &self.session);
    }

    /// Do one thing outside a frame, the way a test asks for it: an action
    /// goes through a call of its own, an effect is performed.
    #[cfg(test)]
    fn act(&mut self, ctx: &egui::Context, act: Act) {
        match act {
            Act::Edit(action) => self.dispatch_action(action),
            Act::Effect(effect) => self.perform(ctx, effect),
        }
    }

    /// One action, executed by a call of its own — a test's way of doing one
    /// thing without a frame around it. What it produced is on the answer,
    /// which the next frame draws from and [`Self::hand_off`] delivers.
    #[cfg(test)]
    fn dispatch_action(&mut self, action: Action) {
        self.dispatch(vec![Event::Action(action)]);
    }

    /// A call outside a frame, fed `events` — a test's way of saying what a
    /// frame would have, at the clock it names. Laid out at one pixel per
    /// point, since there is no screen to lay out for.
    #[cfg(test)]
    fn dispatch(&mut self, events: Vec<Event>) {
        self.state_the_sheet();
        let layout = crate::canvas::EpaintLayout::new(self.appearance.preferences.font);
        let view = kernel(&mut self.session, events, &layout);
        self.shown = Some(view);
    }

    /// Deliver what the last call handed back — a test's way of draining the
    /// list without a frame around it.
    #[cfg(test)]
    fn hand_off(&mut self, ctx: &egui::Context) {
        let handoffs = self
            .shown
            .as_mut()
            .map(|shown| std::mem::take(&mut shown.handoffs))
            .unwrap_or_default();
        self.deliver(ctx, handoffs);
    }

    /// The canvas alone, without the chrome around it: what a test drives
    /// when the diagram is the question.
    #[cfg(test)]
    pub(crate) fn show_canvas(&mut self, ui: &mut egui::Ui) {
        let ctx_owned = ui.ctx().clone();
        let ctx = &ctx_owned;
        self.sync(ctx);
        let shown = self.take_shown(ctx, ui.max_rect().geom());
        let mut batch = self.open_batch(ctx);
        let canvas = self.canvas_open(ui, &shown, &mut batch);
        let mut view = self.canvas_close(ui, &canvas, batch);
        Self::settle(ctx, &mut view);
        self.shown = Some(view);
    }

    /// Run one of the shell's own effects, on the part that owns the flow. The
    /// registry (or the panel that raised it) supplies the target and nothing
    /// else: which dialog opens, how many steps it takes, and what a cancel
    /// means are this side's alone, and what a flow ends in comes back as an
    /// ordinary action.
    fn perform(&mut self, ctx: &egui::Context, effect: Effect) {
        match effect {
            Effect::Accent(target) => self.surface.open_popup(ctx, Popup::Role(target)),
            Effect::PinType(pins) => self.surface.open_popup(ctx, Popup::PinType(pins)),
            Effect::AddIcon(block) => self.exchange.pick(
                &mut Ask {
                    ctx,
                    dialogs: &mut self.dialogs,
                },
                crate::exchange::Pick::Icon(block),
            ),
            Effect::AddImage => self.exchange.pick(
                &mut Ask {
                    ctx,
                    dialogs: &mut self.dialogs,
                },
                crate::exchange::Pick::Image,
            ),
            Effect::Import => self.exchange.import(&mut Ask {
                ctx,
                dialogs: &mut self.dialogs,
            }),
            Effect::Search => self.surface.toggles_the_palette(),
            Effect::NewDocument
            | Effect::RenameDocument(_)
            | Effect::PickFile(_)
            | Effect::OpenRecent(_) => self.perform_in_library(ctx, effect),
        }
    }

    /// The doors that need somewhere to keep documents. This shell has one
    /// natively; its web build is scratch-only for now, so there they are
    /// logged and ignored — the same answer `kernel()` gives an effect no
    /// surface can perform.
    #[cfg(not(target_arch = "wasm32"))]
    fn perform_in_library(&mut self, ctx: &egui::Context, effect: Effect) {
        match effect {
            Effect::NewDocument => self
                .library
                .new_document(&mut self.session, &mut self.surface),
            Effect::RenameDocument(name) => {
                self.library
                    .rename_document(&mut self.session, &mut self.surface, &name);
            }
            Effect::PickFile(request) => {
                let mut ask = Ask {
                    ctx,
                    dialogs: &mut self.dialogs,
                };
                self.library.pick_file(&mut ask, request);
            }
            Effect::OpenRecent(named) => {
                self.library.open_container(
                    &mut self.session,
                    &mut self.surface,
                    &std::path::PathBuf::from(&named),
                );
            }
            other => tracing::error!("{} is not a library door", other.named()),
        }
    }

    #[cfg(target_arch = "wasm32")]
    #[expect(
        clippy::unused_self,
        clippy::needless_pass_by_value,
        reason = "the signature is its native twin's"
    )]
    fn perform_in_library(&mut self, _ctx: &egui::Context, effect: Effect) {
        tracing::debug!("no library to perform {} in", effect.named());
    }

    /// One frame of the whole editor: the floating chrome of
    /// `docs/cad-ui-spec.md` §2 drawn from the last call's answer, then the
    /// canvas edge to edge underneath it — one batch, one call, one replay.
    ///
    /// 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;
        self.sync(ctx);
        let mut shown = self.take_shown(ctx, ui.max_rect().geom());
        let mut batch = self.open_batch(ctx);
        let ahead = self.ahead_of_the_canvas(ctx, &shown);
        let asked = self.chrome(ui, &mut shown, &mut batch);
        // The canvas, edge to edge under the glass.
        let (mut view, effect) = egui::CentralPanel::no_frame()
            .show(ui, |ui| {
                let canvas = self.canvas_open(ui, &shown, &mut batch);
                let picker = ahead.picker;
                let effect = match Self::asked(ui.ctx(), &mut shown, ahead, asked) {
                    Some(Act::Edit(action)) => {
                        batch.push(Event::Action(action));
                        None
                    }
                    Some(Act::Effect(effect)) => Some(effect),
                    None => None,
                };
                let mut view = self.canvas_close(ui, &canvas, batch);
                if let Some(act) = self.glass(ui, &mut view, picker) {
                    self.queued.push(act);
                }
                (view, effect)
            })
            .inner;
        if let Some(effect) = effect {
            self.perform(ctx, effect);
        }
        Self::settle(ctx, &mut view);
        self.poll(ctx);
        self.shown = Some(view);
    }

    /// What the frame is drawn under, before anything is drawn: the
    /// appearance (so this frame renders with the current look), the sheet,
    /// the projection beside the log, and the window's title.
    fn sync(&mut self, ctx: &egui::Context) {
        let applied = self.appearance.apply(ctx);
        self.tell_the_palette(applied);
        self.state_the_sheet();
        #[cfg(not(target_arch = "wasm32"))]
        #[cfg(not(target_arch = "wasm32"))]
        {
            let title = self.window_title();
            self.appearance.apply_window_title(ctx, title);
        }
    }

    /// A batch as it opens: the clock, then what was queued since the last
    /// call — an effect among it is performed here rather than sent.
    fn open_batch(&mut self, ctx: &egui::Context) -> Vec<Event> {
        let mut batch = vec![Event::Tick(crate::canvas::tick(ctx))];
        for act in std::mem::take(&mut self.queued) {
            match act {
                Act::Edit(action) => batch.push(Event::Action(action)),
                Act::Effect(effect) => self.perform(ctx, effect),
            }
        }
        batch
    }

    /// The answer the chrome draws from: the last call's, or — the first
    /// frame, before any call — one made now over what is queued, so the
    /// first frame has a bar and a rail like every frame after it.
    ///
    /// The priming call takes the queue because it is where the first
    /// palette lands: a call applies its actions after it paints, so the
    /// frame's own call is the first to paint in it.
    fn take_shown(&mut self, ctx: &egui::Context, viewport: Rect) -> View {
        if let Some(shown) = self.shown.take() {
            return shown;
        }
        let layout = self.appearance.screen_layout(ctx);
        let mut events = self.open_batch(ctx);
        events.push(Event::Viewport(viewport));
        let mut primed = kernel(&mut self.session, events, &layout);
        // The session counts an asset as sent once a call hands it off, so a
        // primed answer's hand-offs are the only delivery those bytes get.
        self.deliver(ctx, std::mem::take(&mut primed.handoffs));
        primed
    }

    /// What the frame settles ahead of the canvas: the popups first, since
    /// they read the overlay corner the chrome captured last frame and the
    /// picker they report is what the chrome shows as active; then the dev
    /// editors, which edit the theme this frame paints with; then the
    /// icons; then an object paste, whose event has to be reached ahead of
    /// the focused editor.
    fn ahead_of_the_canvas(&mut self, ctx: &egui::Context, shown: &View) -> Ahead {
        let (picker, picked) =
            self.surface
                .show_popups(ctx, shown.overlay.as_ref(), &self.appearance.theme);
        let edited = self.appearance.show_editor_windows(ctx);
        self.tell_the_tuning(edited);
        Ahead {
            picker,
            picked,
            pasted: self.surface.intercept_object_paste(ctx),
        }
    }

    /// The docked chrome and the glass, drawn from `shown`, and what they
    /// asked for.
    ///
    /// 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. 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.
    fn chrome(
        &mut self,
        ui: &mut egui::Ui,
        shown: &mut View,
        batch: &mut Vec<Event>,
    ) -> Option<Act> {
        let ctx_owned = ui.ctx().clone();
        let ctx = &ctx_owned;
        let View {
            commands,
            top_bar,
            tool,
            ..
        } = &mut *shown;
        // 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 = |act: Option<Act>| {
            if act.is_some() {
                chrome_action = act;
            }
        };

        // Escape is claimed in one fixed order: the navigator closes before
        // anything else reads the key, 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.surface.workspace.open().into()) {
            self.surface.dismiss_navigator(ctx);
        } else if let blockworx_store::doc::Viewing::Past(_) = top_bar.lens.viewing {
            band(crate::shell::top_bar::escape_exits(ctx).map(Act::from));
        }
        let mut chrome = crate::shell::Chrome::over(ctx, ui.max_rect());
        band(self.surface.show_top_bar(
            &mut chrome,
            top_bar,
            commands,
            crate::surface::BarState {
                theme: &self.appearance.theme,
                preferences: &mut self.appearance.preferences,
                #[cfg(not(target_arch = "wasm32"))]
                recent: self.library.recent.paths(),
                #[cfg(not(target_arch = "wasm32"))]
                rename_draft: &mut self.library.rename_draft,
            },
        ));
        {
            let frame = crate::shell::tool_cluster::tool_cluster(
                &mut chrome,
                commands,
                crate::shell::tool_cluster::ToolCluster {
                    selected: *tool,
                    viewing: top_bar.lens.viewing,
                },
            );
            // 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.surface.dismiss_navigator(ctx);
            }
            band(frame.action);
            if let Some(carried) = frame.drag_out {
                band(crate::surface::Surface::dropped(ctx, shown, 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 surface, so the two cannot borrow it at once.
            // The state is `Copy`, so it goes in and comes back out.
            let mut state = self.surface.workspace;
            let drawn = crate::shell::navigator::navigator(&mut chrome, &mut state, |ui| {
                self.surface
                    .show_navigator_body(ui, shown, &self.appearance.theme)
            });
            self.surface.workspace = state;
            if drawn.dismissed {
                // The press is *not* spent: a canvas click dismisses and
                // performs its selection in the one gesture, so it goes on
                // to the canvas underneath.
                self.surface.dismiss_navigator(ctx);
            }
            band(drawn.action);
        }
        crate::shell::status_line::status_line(&mut chrome, shown.status.clone());
        // 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.
        crate::shell::toast::toast(ctx, &self.appearance.theme);
        // Measured, never cached: the navigator opening or closing moves this
        // in the frame it happens, and the framing this call takes reads it
        // fresh.
        self.surface.safe = chrome.safe();
        batch.push(Event::Safe(self.surface.safe.region().geom()));
        chrome_action
    }

    /// Open the canvas: allocate it, and put what the pointer, the camera
    /// gestures, the keys and the editor overlay did into the batch.
    fn canvas_open(&mut self, ui: &mut egui::Ui, shown: &View, batch: &mut Vec<Event>) -> Canvas {
        let mut canvas = self.surface.canvas.begin(ui);
        batch.push(Event::Viewport(canvas.viewport()));
        batch.extend(canvas.moves().into_iter().map(Event::Move));
        let glass = crate::shell::glass(ui.ctx());
        let input = canvas.input(ui, &glass);
        batch.extend(input.raw.into_iter().map(Event::Pointer));
        batch.push(Event::Keys(input.keys));
        batch.extend(
            self.surface
                .canvas
                .capture(ui, shown.edit_text.as_ref(), shown.vantage)
                .into_iter()
                .map(Event::Text),
        );
        canvas
    }

    /// The one thing the frame asks of the call: an object paste first, then
    /// what an open picker reported, then what the docked chrome raised,
    /// then a keyboard chord.
    fn asked(
        ctx: &egui::Context,
        shown: &mut View,
        ahead: Ahead,
        chrome_action: Option<Act>,
    ) -> Option<Act> {
        match ahead.pasted {
            Some(text) => Some(Action::Paste(text).into()),
            None => ahead
                .picked
                .map(Act::from)
                .or(chrome_action)
                .or_else(|| crate::surface::handle_keyboard(ctx, shown)),
        }
    }

    /// The glass over the diagram — the selection overlay, the palette, the
    /// notices — drawn from the call's own answer, once the diagram is
    /// painted under it. What it asks for reaches the next frame's batch.
    fn glass(
        &mut self,
        ui: &mut egui::Ui,
        view: &mut View,
        picker: Option<OpenPicker>,
    ) -> Option<Act> {
        let mut asked = self
            .surface
            .show_canvas_chrome(ui, view, OverCanvas { picker, act: None });
        // The bar is docked over the canvas's top edge, and the strip hangs
        // below it rather than under it.
        let bar = crate::shell::berth_rect(ui.ctx(), crate::shell::Berth::TopBar)
            .map_or(Rect::NOTHING, crate::canvas::convert::IntoGeom::geom);
        if let Some(act) = Self::show_document_notices(ui, &view.notices, view.viewport, bar) {
            asked = Some(act);
        }
        asked
    }

    /// The call, and the canvas painted from its answer: the display list
    /// replayed under the grid, and the cursor the pointer is left with —
    /// applied only while the pointer is over the canvas, so it never leaks
    /// over the nav bar, the toolbar or the selection overlay.
    fn canvas_close(&mut self, ui: &mut egui::Ui, canvas: &Canvas, batch: Vec<Event>) -> View {
        let layout = self.appearance.screen_layout(ui.ctx());
        let mut view = kernel(&mut self.session, batch, &layout);
        self.deliver(ui.ctx(), std::mem::take(&mut view.handoffs));
        let cursor = self.surface.canvas.show(
            ui,
            canvas,
            Diagram {
                draw_list: &view.draw_list,
                vantage: view.vantage,
                ground: CanvasChrome {
                    background: view.ground.background,
                    grid: view.ground.grid,
                },
                cursor: view.cursor,
            },
        );
        let cursor = crate::surface::effective_cursor(
            cursor,
            if self.surface.canvas.canvas_hovered() {
                crate::surface::PointerOver::Canvas
            } else {
                crate::surface::PointerOver::Elsewhere
            },
        );
        if let Some(cursor) = cursor {
            ui.output_mut(|o| {
                o.cursor_icon = cursor.egui();
            });
        }
        view
    }

    /// What the call leaves behind: the repaint it wants and what landed.
    fn settle(ctx: &egui::Context, view: &mut View) {
        if let Some(after) = view.repaint {
            ctx.request_repaint_after(after);
        }
        if let Some(said) = view.landed.take() {
            crate::shell::status_line::say(ctx, said);
        }
    }

    /// What the session handed back: one list, drained off each answer as
    /// it comes back and before its display list is replayed, since the
    /// artwork a frame first paints arrives in that same answer. The shell
    /// never asks the editor for a result — it sends a command and looks
    /// here — which is what lets a result that took a thread to compute
    /// arrive without this changing.
    fn deliver(&mut self, ctx: &egui::Context, handoffs: Vec<Handoff>) {
        for handoff in handoffs {
            match handoff {
                Handoff::Clipboard(text) => ctx.copy_text(text),
                Handoff::Export { content, name } => {
                    self.dialogs.export(ctx, ExportPayload { name, content });
                }
                Handoff::Asset { hash, asset } => {
                    self.surface.canvas.register_image(ctx, hash, &asset);
                }
            }
        }
    }

    /// The dialogs, which answer whenever they answer. What one ends in is
    /// an action, queued for the next frame's batch.
    fn poll(&mut self, ctx: &egui::Context) {
        self.exchange.poll_pending_import(ctx, &mut self.session);
        if let Some(action) = self.exchange.poll_pending_image(ctx) {
            self.queued.push(Act::Edit(action));
        }
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.library
                .poll_pending_file(ctx, &mut self.session, &mut self.surface);
            // 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.
            self.library.claim_if_written(&self.session);
        }
    }
}

impl eframe::App for App {
    /// Persist what a launch should come back to. eframe calls this
    /// periodically and on exit (the `persistence` feature is enabled); the
    /// blobs are read back in `main` on the next launch.
    fn save(&mut self, storage: &mut dyn eframe::Storage) {
        self.appearance.save(storage);
        let key = self.document_name();
        self.surface.save(storage, &key);
        #[cfg(not(target_arch = "wasm32"))]
        self.library.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, so
    // there is nothing here to write back.
    #[cfg(not(target_arch = "wasm32"))]
    fn on_exit(&mut self) {
        self.appearance.on_exit();
        self.library.on_exit(&mut self.session);
    }

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

#[cfg(test)]
mod tests;