brep_app/

app.rs

//! `BrepApp` — the THIN shell of the engine-native UI.
//!
//! One eframe [`App`] that hosts the EXISTING `brep-render` engine and lays out
//! the panels. The heavy lifting lives in focused modules; this file only owns
//! the shell:
//!
//! * [`Documents`] (`crate::document`) holds the OPEN MODELS — one
//!   [`EngineState`] per document plus its identity, exactly one active. Panels
//!   borrow the active engine through `self.docs.engine_mut()`, which borrows
//!   only that FIELD and so still composes with the disjoint panel borrows
//!   beside it. [`EngineState`] (`brep-render`) is still the single
//!   windowing-agnostic BRAIN per document (scene / camera / controls / settings
//!   / widgets + pointer/wheel/viewcube/pick); we do NOT fork it.
//! * [`crate::viewport::Viewport`] draws + drives the central 3D viewport (the
//!   offscreen texture, the `egui_wgpu` blit callback, input routing).
//! * [`crate::panels`] — one module per left-panel section, each a small state
//!   struct + a `show(&mut self, ui, state, …)` method. Adding a panel = add
//!   `panels/<name>.rs`, one field here, one `self.<name>.show(…)` call in
//!   [`eframe::App::ui`] below (see `README.md` → "Adding a panel").
//!
//! Native (`run_native`) and wasm (`WebRunner`) run this SAME code.

use crate::document::{Documents, EngineFactory};
use crate::panels::assembly_constraints::AssemblyConstraintsPanel;
use crate::panels::bug_report::BugReportPanel;
use crate::panels::component_actions::ComponentActionRequest;
use crate::panels::context_bar::ContextBarPanel;
use crate::panels::mode_bar::ModeBar;
use crate::panels::expressions::ExpressionsPanel;
use crate::panels::file::{FileAction, FileDialog};
use crate::panels::history::HistoryPanel;
use crate::panels::info_windows::InfoWindows;
use crate::panels::scene::ScenePanel;
use crate::panels::selection::SelectionPanel;
use crate::panels::sketch::SketchPanel;
use crate::panels::settings::SettingsPanel;
use crate::panels::toasts::Toasts;
use crate::panels::toolbar::ToolbarPanel;
use crate::panels::update_components::UpdateComponents;
use crate::panels::bom::BomPanel;
use crate::panels::dock::{DockContext, DockState, PaneKind};
#[cfg(target_arch = "wasm32")]
use crate::panels::document_tabs;
use crate::store::{default_model_store, ModelStore, SESSION_KEY, SETTINGS_KEY};
use crate::viewport::Viewport;
use brep_render::engine_state::EngineState;
use brep_render::style::ThemeMode;
use eframe::egui;

pub struct BrepApp {
    /// Every OPEN MODEL and which one is active. Each document owns a full
    /// `EngineState` (the shared viewer brain `desktop.rs` / the wasm shell
    /// wrap) plus its file identity; panels borrow the active one.
    docs: Documents,
    /// The central 3D viewport: engine render core + offscreen texture + blit +
    /// input routing.
    viewport: Viewport,
    /// The single persistence seam for settings, layout, and model documents
    /// (native filesystem / wasm IndexedDB + download/upload).
    model_store: Box<dyn ModelStore>,

    // --- one small state value per panel --------------------------------------
    /// Top toolbar: undo/redo, wireframe toggle, zoom-to-fit + standard views,
    /// and the File-actions seam (owned by the concurrent file panel).
    toolbar: ToolbarPanel,
    /// New / Open / Save / Save As of the model document (the `.BREP.json`
    /// recipe) — a reusable modal file dialog opened from the toolbar.
    file: FileDialog,
    /// The "Submit Bug" flow: on the toolbar bug button it screenshots the app
    /// (UI + 3D model) BEFORE its own dialog opens, then collects a description
    /// (+ optional email) and POSTs the model + screenshot to the public reports
    /// endpoint. Native + wasm, one path.
    bug_report: BugReportPanel,
    /// Display-settings + per-solid color panel (Phase 1): a FLOATING window
    /// (movable + resizable, toggled from the toolbar gear button), no longer a
    /// left-panel section.
    settings: SettingsPanel,
    /// History feature-tree + schema-driven feature dialog panel (Phase 2).
    /// NOTE: the editable history is NOT owned here — it lives in the engine core
    /// (`EngineState.history`), the single source of truth; this panel only reads
    /// it back to draw and calls the engine's `history_*` methods to mutate.
    history: HistoryPanel,
    /// Scene tree ("Scene Manager"): the display scene as a file-tree — per-solid
    /// visibility + Faces/Edges/Vertices with two-way selection sync. Reads the
    /// engine scene/emphasis; owns only transient expand + hit state.
    scene: ScenePanel,
    /// Assembly Structure tree (claimed by the Assembly workbench): a VIEW over
    /// the scene's component records — per-instance fixed/visibility/status
    /// adornments, actions routed to the owning ACOMP feature.
    /// The BOM panel (claimed by the Assembly workbench): the parts list on
    /// the shared column-tree widget, with the editable part/occurrence
    /// attribute columns the Settings "Assemblies" section configures.
    bom: BomPanel,
    /// Assembly Constraints panel (claimed by the Assembly workbench): the
    /// schema-driven constraint collection widget + Solve/auto-solve/DOF header.
    assembly_constraints: AssemblyConstraintsPanel,
    /// Update-components checker (build-spec §8.6): compares each parts-library
    /// entry's `sourceSignature` against the model store's current content.
    /// Kept current once per frame (cheap generation key: applied run + store
    /// save); the constraints header reads the count + runs the batch refresh,
    /// the structure tree reads per-part badges.
    update_components: UpdateComponents,
    /// Expressions / parameters panel: the variable sheet (engine-owned history
    /// `expressions`) feature params reference. Owns only its editor buffer.
    expressions: ExpressionsPanel,
    /// Info windows: MULTIPLE pinned per-entity inspector windows opened from the
    /// selection-driven context bar's Info action. Each floating (movable +
    /// resizable) window is PINNED to one object name at open time — a Metadata
    /// (editable attribute) tab + a read-only Info (measurements + provenance) tab —
    /// and keeps showing that entity regardless of later selection changes. Replaces
    /// the old single Properties window.
    info_windows: InfoWindows,
    /// Interference results window (assemblies build-spec §9): opened by the
    /// Assembly workbench's `∩` toolbar button, which runs the engine's
    /// pairwise-intersect check; a floating window like the Info windows with a
    /// row per interfering pair (click = select both components), a green
    /// all-clear pass line, and a Re-run button.
    interference: crate::panels::interference::InterferenceWindow,
    /// step.parts online model library browser (Assembly workbench): a ctx-level
    /// window (opened by the library toolbar button) that searches the public
    /// step.parts v1 API, shows results with thumbnails, and imports a chosen
    /// STEP model as a new part document + adds it to the assembly as an ACOMP.
    step_parts: crate::panels::step_parts::StepPartsPanel,
    /// Selection panel: the pickable-kinds filter (which entity kinds a viewport
    /// click may select — honored by the engine's `select_top_at`). The filter +
    /// selection live in `EngineState`; this panel only reads/writes them.
    selection: SelectionPanel,
    /// Context action toolbar: the selection-driven action bar (Clear / Hide /
    /// Edit-owning-feature + the feature-from-selection actions whose primary
    /// reference accepts the selected kind). Shown only while something is
    /// selected; drives the engine directly and returns a feature id for the shell
    /// to expand in the history tree.
    context_bar: ContextBarPanel,
    /// Sketch (S0): a seeded, read-only sketch preview — pushes a solved rectangle
    /// + circle to the `set_overlay` channel colored by solver mobility, and shows
    /// the DOF status readout. The engine-native sketcher's foundation surface.
    sketch: SketchPanel,
    /// Special-mode EXIT controls (Finish/Cancel), always pinned to the top-right
    /// corner — reference-selection, sketch mode, and any future special mode.
    mode_bar: ModeBar,
    /// Transient toast overlay: drains the engine's queued notices each frame
    /// (e.g. a sketch solve that failed after an edit) and shows each briefly.
    toasts: Toasts,
    /// Dockable / tabbed side-panel layout (egui_tiles): the shared, persisted
    /// tree that hosts every side-panel section AND the 3D viewport as tiles the
    /// user can split, tab, resize, and drag-rearrange. Owns the layout; borrows
    /// each panel + the engine per frame through [`DockContext`]. Drawn in normal
    /// modeling mode; sketch / ref-select mode bypasses it (viewport drawn direct).
    dock: DockState,

    /// Whether the ONE-SHOT first-model framing has fired. The seed run is async
    /// under a background runner (native thread / wasm worker), so the boot
    /// `zoom_to_fit` can run before the first solids exist → an unframed first
    /// model. Once the seed run has landed (`has_solids() && !run_pending()`), the
    /// `ui` loop frames it once and sets this. Under the synchronous Inline runner
    /// (tests) the scene is already populated, so this fires on the very first frame.
    first_run_framed: bool,

    /// A model fetch kicked off at boot from a `?loadModel=<url>` query param
    /// (wasm only — the cadDev admin "Launch model in CAD app" opens the app with
    /// a report's model URL). When the fetch lands it REPLACES the seed model.
    /// `None` on native and once applied.
    pending_boot_load: Option<std::sync::mpsc::Receiver<Result<String, String>>>,

    /// The document handle the shared panels were last reset for. Compared to
    /// `docs.active_id()` at the top of every frame: ONE check catches a switch
    /// from any source (a tab click, a close, New, Open, Edit Part) instead of a
    /// hook per call site, and it runs BEFORE any panel draws this frame.
    active_document: u64,

    /// The DOCUMENT TAB STRIP's per-tab hit-rects from the last dock frame,
    /// published for the headed verifier. The strip is drawn inside the dock's
    /// viewport pane, so its rects have to ride back out through the outcome.
    #[cfg(target_arch = "wasm32")]
    document_tab_hits: Vec<(String, egui::Rect)>,

    /// The last session blob written through the store — the change detector for
    /// the open-document list, so persisting cannot be forgotten at a mutation
    /// site (there is no "session dirty" flag to set).
    session_saved: String,

    /// The UI zoom scale CURRENTLY applied to the egui context. Tracks
    /// `settings.ui_scale` but is only synced to it while the pointer is up, so
    /// dragging the Settings "UI scale" slider doesn't rescale the whole UI under
    /// the cursor mid-drag — the settled value is committed on release. See the
    /// zoom-apply block in `ui`.
    applied_ui_scale: f32,
}

impl BrepApp {
    pub fn new(cc: &eframe::CreationContext<'_>) -> Result<Self, String> {
        let render_state = cc
            .wgpu_render_state
            .as_ref()
            .ok_or_else(|| "eframe was not created with a wgpu render state".to_string())?;

        // The viewport owns the render core + blit pipeline, built from eframe's
        // SHARED device/queue/format.
        let viewport = Viewport::new(render_state);

        // --- storage seam: load the persisted settings ------------------------
        let model_store = default_model_store();
        // wasm: hand the store the egui context so an async file-upload load
        // callback can wake the reactive frame loop (see `store::set_repaint_ctx`).
        #[cfg(target_arch = "wasm32")]
        crate::store::set_repaint_ctx(cc.egui_ctx.clone());
        let saved_settings = model_store.read(SETTINGS_KEY);

        // --- how a document's engine is built --------------------------------
        // Every tab gets its OWN engine, and therefore its own history runner —
        // a runner owns the resident kernel state of the document it executes,
        // so one shared between documents would apply a background run against
        // the wrong registry. See `crate::document`.
        let engine_factory: EngineFactory = Box::new(move || {
            let mut state = EngineState::new();
            // Native: run the whole history — and per-object measurement queries — on a
            // persistent background thread so the UI never freezes during a run or a
            // selection (M2b). Installed BEFORE anything loads so it builds through it.
            #[cfg(not(target_arch = "wasm32"))]
            state.set_runner(Box::new(brep_render::runner::ThreadRunner::new()));
            // wasm: the browser-thread analogue — a dedicated web worker (M3b) so the
            // single-threaded wasm UI stays responsive during a run. Same seam. Tests
            // (which never hit this wasm path) keep the default synchronous InlineRunner.
            #[cfg(target_arch = "wasm32")]
            state.set_runner(Box::new(crate::worker::WorkerRunner::new()));
            state.set_viewcube_enabled(true);
            // Partial-override apply: unknown/absent keys keep their defaults.
            if let Some(saved) = &saved_settings {
                let _ = state.apply_settings_json(saved);
            }
            state
        });

        // --- the open documents: last session, else the seed model -----------
        // A returning user comes back to the desk they left. Only NAMED
        // documents can be restored (a never-saved one has no file), and a name
        // whose file has gone is skipped — so an empty or unusable session
        // falls through to the demo seed exactly as a first run does.
        let mut docs = Documents::new(engine_factory);
        let restored = model_store
            .read(SESSION_KEY)
            .map(|json| docs.restore_session(model_store.as_ref(), &json))
            .unwrap_or(0);
        if restored == 0 {
            let _ = docs.engine_mut().set_history_json(&seed_history_json());
            docs.engine_mut().zoom_to_fit();
            docs.active_mut().mark_clean();
        }
        let session_saved = docs.session_json();

        // The settings panel seeds its working JSON from the (post-load) engine
        // settings so the widgets reflect the persisted state on first paint.
        let settings = SettingsPanel::new();

        // New / Open / Save / Save As. Holds no document identity — that lives
        // on each `Document`.
        let file = FileDialog::new();

        // Boot at the saved UI scale.
        let applied_ui_scale = docs.engine().settings.ui_scale;
        let active_document = docs.active_id();

        // The dock layout (loads the persisted tree, or the default). Built before
        // `model_store` is moved into `Self`.
        let dock = DockState::new(model_store.as_ref());

        // Boot-load: if the page URL carries `?loadModel=<url>` (wasm only), start
        // fetching that model NOW; the seed still loads this frame and the fetched
        // model REPLACES it when it lands (drained in `ui`). See the drain block.
        #[cfg(target_arch = "wasm32")]
        let pending_boot_load = web_sys::window()
            .and_then(|w| w.location().search().ok())
            .and_then(|search| web_sys::UrlSearchParams::new_with_str(&search).ok())
            .and_then(|params| params.get("loadModel"))
            .filter(|url| !url.is_empty())
            .map(|url| fetch_model(&cc.egui_ctx, url));
        #[cfg(not(target_arch = "wasm32"))]
        let pending_boot_load: Option<std::sync::mpsc::Receiver<Result<String, String>>> = None;

        Ok(Self {
            docs,
            viewport,
            toolbar: ToolbarPanel::new(),
            model_store,
            file,
            bug_report: BugReportPanel::new(),
            settings,
            history: HistoryPanel::new(),
            scene: ScenePanel::new(),
            bom: BomPanel::new(),
            assembly_constraints: AssemblyConstraintsPanel::new(),
            update_components: UpdateComponents::new(),
            expressions: ExpressionsPanel::new(),
            info_windows: InfoWindows::new(),
            interference: crate::panels::interference::InterferenceWindow::new(),
            step_parts: crate::panels::step_parts::StepPartsPanel::new(),
            selection: SelectionPanel::new(),
            context_bar: ContextBarPanel::new(),
            sketch: SketchPanel::new(),
            mode_bar: ModeBar::new(),
            toasts: Toasts::new(),
            dock,
            first_run_framed: false,
            pending_boot_load,
            active_document,
            #[cfg(target_arch = "wasm32")]
            document_tab_hits: Vec::new(),
            session_saved,
            applied_ui_scale,
        })
    }

    /// Global keyboard shortcuts (egui input): **Ctrl/Cmd+Z** undo,
    /// **Ctrl/Cmd+Shift+Z** or **Ctrl/Cmd+Y** redo, **Esc** clears the selection.
    ///
    /// `Modifiers::COMMAND` is Ctrl on Windows/Linux and ⌘ on macOS, so one map
    /// covers both. Skipped entirely while an egui TEXT edit is focused so typing
    /// (and text-field Ctrl+Z / Esc-to-defocus) is never hijacked. Redo is
    /// consumed BEFORE undo because egui's `consume_key` matches modifiers
    /// logically (a plain `COMMAND+Z` pattern would also swallow `COMMAND+Shift+Z`).
    fn handle_shortcuts(&mut self, ctx: &egui::Context) {
        if ctx.text_edit_focused() {
            return;
        }
        use egui::{Key, Modifiers};
        let (redo, undo, esc) = ctx.input_mut(|i| {
            let redo = i.consume_key(Modifiers::COMMAND | Modifiers::SHIFT, Key::Z)
                || i.consume_key(Modifiers::COMMAND, Key::Y);
            let undo = i.consume_key(Modifiers::COMMAND, Key::Z);
            let esc = i.consume_key(Modifiers::NONE, Key::Escape);
            (redo, undo, esc)
        });
        // While editing a sketch, Ctrl+Z / Ctrl+Shift+Z drive the PER-SESSION sketch
        // history (S6a), not the model-level undo — this global router consumes the
        // keys first (before the viewport), so it must intercept here. Esc drops the
        // active draw/trim/pick tool back to Select/drag (clearing any in-progress
        // placement): this is the ONLY reliable capture point, since `consume_key`
        // above already swallowed the Escape before the viewport can see it.
        if self.docs.engine().sketch_mode() {
            if redo {
                self.docs.engine_mut().sketch_redo();
            }
            if undo {
                self.docs.engine_mut().sketch_undo();
            }
            if esc {
                self.docs.engine_mut().sketch_set_tool(Some("select"));
            }
            return;
        }
        if redo {
            self.docs.engine_mut().redo();
        }
        if undo {
            self.docs.engine_mut().undo();
        }
        if esc {
            // An open pick-list popup owns the first Escape: close it WITHOUT
            // clearing the selection (a popup-built multi-selection must survive
            // dismissing the list); the next Escape clears as before.
            if !self.viewport.close_candidate_popup() {
                self.docs.engine_mut().clear_selection();
            }
        }
    }

    /// EDIT PART (assemblies §8.5): open the component's SOURCE document in its
    /// own tab — or focus the tab already holding it. Editing a component IS
    /// opening its part now; the assembly picks the change up through the
    /// outdated badge / Update Components once the part is saved, so there is no
    /// session to finish and nothing to stash.
    ///
    /// A part with no store document under its `sourceKey` (an embedded-only
    /// part — a headless STEP import, or one whose write failed) has no file to
    /// open, and says so rather than doing nothing.
    fn edit_part(&mut self, component_id: &str) {
        let source =
            crate::panels::component_actions::part_source_key(self.docs.engine(), component_id);
        match source {
            Some(key) if self.model_store.read(&key).is_some() => {
                self.file
                    .open_document(&mut self.docs, self.model_store.as_ref(), &key);
            }
            Some(key) => self.docs.engine_mut().push_notice(format!(
                "This part's source document '{key}' is no longer in storage — nothing to open"
            )),
            None => self.docs.engine_mut().push_notice(
                "This part is embedded in the assembly — it has no source document to open"
                    .to_string(),
            ),
        }
    }

    /// Reset everything the shared panels and the viewport hold ABOUT ONE
    /// DOCUMENT, run at the top of the first frame that sees a different active
    /// document.
    ///
    /// Panel state is deliberately NOT per-document (one History panel, one
    /// Scene tree, …): a second copy per tab would double every panel's state
    /// for a benefit — remembering which feature form was open in a background
    /// tab — nobody asked for. The price is that the transient state has to be
    /// dropped on a switch, because every bit of it (expansion sets, hit maps,
    /// an open feature form, a pinned Info window's object name) refers to the
    /// document that just went away.
    fn reset_document_scoped_state(&mut self) {
        self.history = HistoryPanel::new();
        self.scene = ScenePanel::new();
        self.bom = BomPanel::new();
        self.assembly_constraints = AssemblyConstraintsPanel::new();
        self.expressions = ExpressionsPanel::new();
        // Pinned to object NAMES of the old document ("Box" exists in most of
        // them), so these would silently retarget rather than go blank.
        self.info_windows = InfoWindows::new();
        self.interference = crate::panels::interference::InterferenceWindow::new();
        // The outdated-parts cache keys on `(applied_generation, save_generation)`,
        // and two documents' generations are unrelated — a switch can land on the
        // same key with an entirely different parts library.
        self.update_components.invalidate();
        self.viewport.forget_document();
    }

    /// A signature of the CURRENT rendered model (rolled-to step) — solid count,
    /// per-solid triangle count + bbox, and total triangles. Published to JS so
    /// the headed verifier can prove each roll / edit produced different geometry
    /// (names alone don't: a SUBTRACT reuses the target's name).
    #[cfg_attr(not(target_arch = "wasm32"), allow(dead_code))]
    fn model_signature_json(&self) -> String {
        let solids: Vec<serde_json::Value> = self
            .docs
            .engine()
            .scene
            .solids()
            .iter()
            .map(|s| {
                serde_json::json!({
                    "name": s.name,
                    "tris": s.mesh.indices.len() / 3,
                    "min": s.bbox.min,
                    "max": s.bbox.max,
                })
            })
            .collect();
        let total_tris: usize = self
            .docs
            .engine()
            .scene
            .solids()
            .iter()
            .map(|s| s.mesh.indices.len() / 3)
            .sum();
        serde_json::json!({
            "step": self.docs.engine().history_rollback(),
            "solidCount": solids.len(),
            "totalTris": total_tris,
            "solids": solids,
        })
        .to_string()
    }
}

impl eframe::App for BrepApp {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        // --- global keyboard shortcuts (undo/redo/clear-selection) ------------
        // Handled before any panel draws so a Ctrl+Z etc. this frame takes effect
        // this frame. `ctx` is a cheap Arc clone (avoids borrowing `ui` across the
        // `&mut self` call).
        let ctx = ui.ctx().clone();

        // --- a different document is active than the panels were drawn for ----
        // Checked FIRST, before anything draws: the switch itself happened late
        // in some earlier frame (a tab click, a close, an Open), and every
        // shared panel is still holding the previous document's transient state.
        if self.active_document != self.docs.active_id() {
            self.active_document = self.docs.active_id();
            self.reset_document_scoped_state();
        }

        // --- GUI chrome theme -------------------------------------------------
        // Apply the user's theme preference to the egui chrome every frame
        // (idempotent: `set_theme` just stores the preference). Auto follows the
        // OS/system theme (prefers-color-scheme on web); egui falls back to dark
        // when no OS signal is available. This controls panels/windows/toolbar/
        // text only — the 3D viewport `background` is a separate setting.
        ctx.set_theme(match self.docs.engine().settings.theme {
            ThemeMode::Auto => egui::ThemePreference::System,
            ThemeMode::Light => egui::ThemePreference::Light,
            ThemeMode::Dark => egui::ThemePreference::Dark,
        });

        // --- global UI size scale --------------------------------------------
        // Apply the user's "UI scale" to the whole egui chrome every frame. This
        // is idempotent when unchanged (`set_zoom_factor` only repaints on an
        // actual change) and composes with the native device pixel ratio
        // (pixels_per_point = zoom_factor * native_pixels_per_point).
        //
        // Defer live UI rescale while the user drags the Settings "UI scale" slider:
        // the slider value updates continuously, but only commit it to the actual egui
        // zoom once the pointer is released, so the whole UI doesn't rescale under the
        // cursor mid-drag.
        let pointer_down = ctx.input(|i| i.pointer.any_down());
        if !pointer_down {
            self.applied_ui_scale = self.docs.engine().settings.ui_scale;
        }
        ctx.set_zoom_factor(self.applied_ui_scale);

        // --- history-runner pump ---------------------------------------------
        // Apply any completed background history run BEFORE panels read the scene.
        // For the synchronous InlineRunner this is a no-op (`rerun_history` already
        // pumped its own submit), so nothing changes today; it is the seam a future
        // native-thread / wasm-worker runner lands its reply through. While a run is
        // still in flight, keep the frame loop alive so its reply gets pumped — for
        // Inline `run_pending()` is always false, so this never fires.
        //
        // EVERY open document is pumped, not just the active one: a run belongs
        // to the engine that submitted it (each document owns its own runner —
        // see `crate::document`), so a run still in flight when the user switches
        // tabs must land in ITS document rather than be dropped or, worse,
        // applied to whatever is on screen. An idle document's pump is a couple
        // of empty `try_recv`s.
        let mut work_in_flight = false;
        for doc in self.docs.iter_mut() {
            doc.engine.pump();
            work_in_flight |= doc.engine.run_pending()
                || doc.engine.queries_pending()
                || doc.engine.mesh_imports_pending();
        }
        if work_in_flight {
            ctx.request_repaint();
        }
        // The tab strip's dirty dots, refreshed once per frame (cheap — see
        // `Document::refresh_dirty_marker`).
        self.docs.refresh_dirty_markers();

        // --- boot-load (?loadModel=): apply the fetched model once it lands ----
        // Replaces the seed with the URL-specified document (armed in `new`). The
        // ehttp callback wakes the frame loop, so a plain per-frame drain suffices.
        // `load_model_and_fit` arms deferred framing; the pump above reframes it
        // next frame. `mark_clean` opens it as a non-dirty document.
        if self.pending_boot_load.is_some() {
            let received = self
                .pending_boot_load
                .as_ref()
                .and_then(|rx| rx.try_recv().ok());
            if let Some(result) = received {
                self.pending_boot_load = None;
                match result {
                    Ok(json) => {
                        // REPLACES the seed in place rather than adding a tab:
                        // the cadDev "Launch model in CAD app" link means "show
                        // me this model", and a boot with the demo cube sitting
                        // in tab 1 beside it would be noise. It lands on the
                        // document that is already active, whatever the session
                        // restored.
                        let _ = self.docs.engine_mut().load_model_and_fit(&json);
                        self.docs.active_mut().mark_clean();
                    }
                    Err(e) => self
                        .docs
                        .engine_mut()
                        .push_notice(format!("Could not load model from URL: {e}")),
                }
            }
        }

        // --- update-components badge freshness ---------------------------------
        // Keep the outdated-parts checker current BEFORE any assembly panel draws
        // (the structure tree renders per-node badges ahead of the constraints
        // header). Cheap: a real recompute happens only when an applied run or a
        // successful store save moved the generation key.
        self.update_components.ensure_current(
            self.docs.engine_mut(),
            self.model_store.as_ref(),
            self.file.save_generation(),
        );

        // --- async-safe first-model framing -----------------------------------
        // The seed run is async under a background runner (native thread / wasm
        // worker), so the boot `zoom_to_fit` may have run before any solid existed.
        // Frame the model ONCE, the first frame the seed run has fully landed (solids
        // present AND no run still in flight). Under the synchronous Inline runner
        // (tests) both hold on the very first frame, so this is identical to today.
        if !self.first_run_framed
            && !self.docs.engine().run_pending()
            && self.docs.engine().has_solids()
        {
            self.docs.engine_mut().zoom_to_fit();
            self.first_run_framed = true;
        }

        self.handle_shortcuts(&ctx);

        // --- top toolbar: primary actions, drawn FIRST so its top strip is
        // reserved above the left panel + central viewport. A clicked File button
        // returns an action the file dialog acts on (open its modal / save / new).
        let toolbar_outcome = self.toolbar.show(
            ui,
            self.docs.engine_mut(),
            self.model_store.as_ref(),
            &mut self.settings.open,
        );
        if let Some(action) = toolbar_outcome.file {
            self.file
                .dispatch(action, &mut self.docs, self.model_store.as_ref());
        }
        // Submit Bug: begin the screenshot-capture + report flow. `request`
        // grabs the current frame (before its dialog exists) and the model, so
        // it must run THIS frame while the shot is still dialog-free.
        if toolbar_outcome.bug_report {
            self.bug_report.request(&ctx, self.docs.engine());
        }
        // A workbench toolbar button click surfaces its id here. Sheet Metal's
        // flat-pattern button opens the export modal in its DXF / SVG mode; the
        // engine reports "no sheet-metal body in the part" as a toast on export.
        match toolbar_outcome.workbench_button {
            Some("sheetmetal.flat_pattern") => {
                self.file.dispatch(
                    FileAction::ExportFlatPattern,
                    &mut self.docs,
                    self.model_store.as_ref(),
                );
            }
            // Assembly's Add Component: open the insert-component modal (the
            // same flow as the ACOMP palette pick).
            Some("assembly.add_component") => {
                self.file.dispatch(
                    FileAction::InsertComponent,
                    &mut self.docs,
                    self.model_store.as_ref(),
                );
            }
            // Assembly's interference check: run the engine's pairwise
            // intersect sweep NOW and open the results window (drawn below,
            // next to the Info windows).
            Some("assembly.interference") => {
                self.interference.open_and_run(self.docs.engine_mut());
            }
            // Assembly's step.parts library: open the online-library browser
            // (search → thumbnails → import a STEP part → add as an ACOMP).
            Some("assembly.step_parts_library") => {
                self.step_parts.open();
            }
            Some(_) | None => {}
        }

        // --- sketch mode: a slim top bar (the draw tools) drawn just below the
        // toolbar while editing a sketch. The normal side panel is hidden (below)
        // so the 3D viewport is the full-width sketching surface.
        if self.docs.engine().sketch_mode() {
            self.sketch.show_mode_bar(ui, self.docs.engine_mut());
        }

        // --- bottom STATUS BAR: a persistent, full-width strip whose CONTENT is
        // chosen by context each frame. Drawn AFTER the top bars but BEFORE the
        // left panel(s) so it reserves the FULL bottom width and the left column
        // stops above it (egui resolves reserved space by call order). It is a
        // HOST: the branch below picks what to draw. A NEW context is added by
        // extending this branch (e.g. `else if engine.some_mode() { … }`) and
        // routing through the owning panel's `show_status_bar` for DRY styling.
        egui::containers::panel::Panel::bottom("brep-status-bar")
            .resizable(false)
            .min_size(30.0)
            .show(ui, |ui| {
                ui.add_space(2.0);
                if self.docs.engine().sketch_mode() {
                    // Sketch context: the status row (title / DOF / N selected /
                    // undo-redo / Lock). The selection-filter row is NOT drawn
                    // now, so drop its stale hit-rects (the verifier must never
                    // click a phantom rect for an off-screen widget).
                    self.selection.clear_hits();
                    self.sketch.show_status_bar(ui, self.docs.engine_mut());
                } else {
                    // Modeling context: the selection filter (pickable kinds).
                    self.selection.show_status_bar(ui, self.docs.engine_mut());
                }
                ui.add_space(2.0);
            });

        // --- central region: the dock tree, OR (special modes) the bare 3D view
        // ---------------------------------------------------------------------
        // Normal modeling mode: ONE egui_tiles tree fills the whole remaining
        // area between the top toolbar and the bottom status bar. Every side-panel
        // section AND the 3D viewport are tiles the user can split / tab / resize /
        // drag-rearrange, and the layout persists. Which side panes are visible is
        // filtered per-workbench inside the dock (`workbench::panel_visible`).
        //
        // Sketch mode and reference-selection are "special modes" that take over
        // the shell: they BYPASS the tree and draw the viewport directly, so the
        // modeling side panes don't appear (sketch's own entity-list panel + the
        // top-right mode card own those flows). Drawing the viewport HERE — before
        // the top-right overlay below — keeps `viewport.last_rect()` current-frame
        // so the overlay anchors to the live 3D-view rect with no lag.
        let sketch = self.docs.engine().sketch_mode();
        let ref_select = self.docs.engine().ref_select_active();

        if sketch {
            // Sketch entity lists (Curves / Points / Constraints) + solver
            // settings — a dedicated left panel, drawn BEFORE the viewport so it
            // reserves the left and the viewport fills the rest.
            egui::containers::panel::Panel::left("sketch-entities")
                .resizable(true)
                .default_size(300.0)
                .size_range(200.0..=560.0)
                .show(ui, |ui| {
                    self.sketch.show_entity_lists(ui, self.docs.engine_mut());
                });
        }

        if sketch || ref_select {
            // Special mode: the viewport fills the remaining central area; no
            // dock, no modeling side panes — and therefore no DOCUMENT TAB
            // STRIP either, which is the guard that keeps a live sketch /
            // reference-pick session from having its document swapped out from
            // under it.
            self.viewport.show(ui, self.docs.engine_mut());
        } else {
            // Normal mode: the dock owns the whole central area (the viewport is a
            // pane). Cross-panel requests the panels can't act on while their
            // borrows are held bubble OUT via the returned outcome — the SAME
            // requests the old left-panel closure produced.
            let outcome = self.dock.ui(
                ui,
                DockContext {
                    docs: &mut self.docs,
                    viewport: &mut self.viewport,
                    history: &mut self.history,
                    bom: &mut self.bom,
                    assembly_constraints: &mut self.assembly_constraints,
                    scene: &mut self.scene,
                    expressions: &mut self.expressions,
                    update_components: &mut self.update_components,
                    model_store: self.model_store.as_ref(),
                },
            );

            // The ACOMP palette pick must open the COMPONENT SELECTOR, never a
            // bare feature dialog — the file dialog is shell-owned.
            if outcome.insert_component_requested {
                self.file.dispatch(
                    FileAction::InsertComponent,
                    &mut self.docs,
                    self.model_store.as_ref(),
                );
            }
            // The DOCUMENT TAB STRIP inside the viewport tile. Activation is
            // immediate; a close routes through the file dialog because a dirty
            // document has to be confirmed first, and that prompt lives there.
            if let Some(index) = outcome.document_tabs.activate {
                self.docs.activate(index);
            }
            if let Some(index) = outcome.document_tabs.close {
                self.file.request_close(&mut self.docs, index);
            }
            #[cfg(target_arch = "wasm32")]
            {
                self.document_tab_hits = outcome.document_tabs.hits;
            }
            // A structure-tree Edit — or a BOM row's action button, which
            // reports through the same outcome field so there is one arm and
            // not two — expands its feature in the history tree.
            if let Some(focus) = outcome.feature_focus {
                self.history.focus_feature(focus);
                // Surface History so the expanded feature is actually visible.
                self.dock.show_pane(PaneKind::History);
            }
            // Structure-tree interaction hooks route through the SAME dispatcher
            // as the context bar (one truth per action); document-level flows
            // (edit-in-place / open-part) come back as requests the shell runs.
            // A BOM row menu's document-level flow: its engine-mutating half
            // already ran inside the panel, through the same dispatcher.
            match outcome.component_request {
                Some(ComponentActionRequest::OpenPart { component_id }) => {
                    self.edit_part(&component_id);
                }
                None => {}
            }
        }

        // --- file dialog: a ctx-level modal (like the command palette), drawn
        // after the panels so its backdrop dims the whole shell. Idempotent when
        // closed; also polls for a completed async import each frame.
        self.file
            .show(&ctx, &mut self.docs, self.model_store.as_ref());

        // --- Submit Bug: the screenshot-capture state machine + report modal.
        // Drawn at ctx level like the file dialog; idempotent while idle. Draws
        // NOTHING during capture, so the screenshot it requested never contains
        // this dialog.
        self.bug_report.show(&ctx, self.docs.engine_mut());

        // --- Settings: a floating (movable + resizable) window, toggled from the
        // toolbar gear button, drawn at ctx level like Properties so it floats
        // over the shell. Idempotent when closed. Replaces the old sidebar section.
        self.settings
            .show(&ctx, self.docs.engine_mut(), self.model_store.as_ref());

        // --- top-right overlay column: the special-mode EXIT card (Finish/Cancel
        // for reference-selection / sketch mode) stacked ABOVE the selection-driven
        // CONTEXT ACTION rail. Both cards live in ONE ctx-level Area anchored
        // top-right so they never overlap, and the context rail uses the SAME
        // renderer whether it is showing modeling actions or sketch actions
        // (`panels::action_rail`). A modeling create/edit action returns a feature
        // id to expand in the history tree.
        {
            let mut focus: Option<String> = None;
            let mut info_targets: Vec<String> = Vec::new();
            let mut component_request: Option<ComponentActionRequest> = None;
            // Anchor the overlay to the RIGHT edge of the 3D VIEW (the viewport
            // tile), not the window — so it stays glued to the viewport wherever
            // docking frames it. The viewport was drawn earlier THIS frame, so its
            // rect is current. Before the first draw (`None`) fall back to the
            // window's top-right.
            let mut overlay = egui::Area::new(egui::Id::new("brep-top-right-overlay"))
                .order(egui::Order::Foreground);
            overlay = match self.viewport.last_rect() {
                Some(rect) => overlay
                    .fixed_pos(rect.right_top() + egui::vec2(-12.0, 8.0))
                    .pivot(egui::Align2::RIGHT_TOP),
                None => overlay.anchor(egui::Align2::RIGHT_TOP, egui::vec2(-12.0, 56.0)),
            };
            overlay
                .show(&ctx, |ui| {
                    // 1. Exit controls for whatever special mode is active.
                    self.mode_bar.card(ui, self.docs.engine_mut());
                    // 2. Context actions: sketch actions in sketch mode, else the
                    // modeling selection actions. Same rail, mode-appropriate items.
                    if self.docs.engine().sketch_mode() {
                        self.sketch.context_card(ui, self.docs.engine_mut());
                    } else {
                        let outcome = self.context_bar.card(ui, self.docs.engine_mut());
                        focus = outcome.focus;
                        info_targets = outcome.info_targets;
                        component_request = outcome.component;
                    }
                });
            if let Some(focus) = focus {
                self.history.focus_feature(focus);
                // Adding a feature from the context bar can happen while another
                // side tab is active — bring History forward so the new row shows.
                self.dock.show_pane(PaneKind::History);
            }
            // The Info action returns one target per selected entity — open (or, on
            // dedup, keep) a pinned Info window for each. Drawn below.
            if !info_targets.is_empty() {
                self.info_windows.open_for(&info_targets);
            }
            // Component document-level flows (the engine-mutating component
            // actions already ran inside the bar).
            match component_request {
                Some(ComponentActionRequest::OpenPart { component_id }) => {
                    self.edit_part(&component_id);
                }
                None => {}
            }
        }

        // --- Info windows: the pinned per-entity inspector windows, drawn at ctx
        // level like the file dialog so they float over the shell. Each is pinned to
        // its open-time object name (selection changes never retarget them); closed
        // windows (their `×`) are pruned here. Drawn AFTER the context bar so a
        // window opened THIS frame paints this frame.
        self.info_windows.show(&ctx, self.docs.engine_mut());

        // --- interference results window: same floating idiom, owned report;
        // its Re-run button re-drives the engine check.
        self.interference.show(&ctx, self.docs.engine_mut());
        self.step_parts
            .show(&ctx, self.docs.engine_mut(), self.model_store.as_ref());

        // --- transient toasts: drain the engine's queued notices (e.g. a sketch
        // solve that failed after an edit) and show each briefly. Drawn last so
        // the cards float over the whole shell.
        let now = ctx.input(|i| i.time);
        let notices = self.docs.engine_mut().take_notices();
        self.toasts.extend(notices, now);
        // Same lane for STORAGE failures the store could only discover after its
        // synchronous `write` returned `Ok` (the browser backend writes behind an
        // in-memory mirror). A save that did not persist must never be silent.
        self.toasts
            .extend(self.model_store.take_persistence_errors(), now);
        self.toasts.show(&ctx);

        // --- persist the open-document session --------------------------------
        // Compared against what was last WRITTEN rather than flagged at each
        // mutation site: New / Open / close / activate / Save As (a rename) all
        // move it, and a change detector cannot forget one of them. The blob is
        // a short name list, so the per-frame compare is free.
        let session = self.docs.session_json();
        if session != self.session_saved {
            let _ = self.model_store.write(SESSION_KEY, &session);
            self.session_saved = session;
        }

        // Verification hook (wasm only): mirror the live app + engine state to JS
        // globals so the headed verifier can assert roll-to-step / edit-re-run /
        // add / delete took effect, and locate the real egui widgets to click.
        // Purely additive; no render effect. Published AFTER the panel draws so
        // the hit-rects are for THIS frame's layout.
        #[cfg(target_arch = "wasm32")]
        {
            let ppp = ui.ctx().pixels_per_point();
            publish_to_js("__brepCamera", &self.docs.engine().camera_state_json());
            publish_to_js("__brepSettings", &self.docs.engine().settings_json());
            publish_to_js("__brepSolidColors", &self.docs.engine().solid_color_overrides_json());
            publish_to_js("__brepHistory", &self.docs.engine().history_listing_json());
            publish_to_js(
                "__brepFile",
                &self.file.file_state_json(&self.docs, self.model_store.as_ref()),
            );
            publish_to_js("__brepFileHit", &self.file.hits_json());
            publish_to_js("__brepModel", &self.model_signature_json());
            publish_to_js("__brepReport", &self.docs.engine().history_report_json());
            publish_to_js("__brepHit", &self.history.hits_json());
            publish_to_js("__brepExprHit", &self.expressions.hits_json());
            publish_to_js(
                "__brepExpr",
                &serde_json::json!({
                    "expressions": self.docs.engine().expressions_json(),
                    "variables": serde_json::from_str::<serde_json::Value>(
                        &self.docs.engine().expression_variables_json()
                    )
                    .unwrap_or(serde_json::Value::Null),
                    "configurator": serde_json::from_str::<serde_json::Value>(
                        &self.docs.engine().configurator_json()
                    )
                    .unwrap_or(serde_json::Value::Null),
                })
                .to_string(),
            );
            publish_to_js("__brepToolbar", &self.toolbar.hits_json());
            publish_to_js("__brepBug", &self.bug_report.state_json());
            publish_to_js("__brepBugHit", &self.bug_report.hits_json());
            // The workbench logical state (resolved current id + available ids) so
            // the verifier can drive the dropdown and confirm the active workbench.
            // Hit-rects for the dropdown ride in `__brepToolbar` (self.toolbar.hits).
            publish_to_js(
                "__brepWorkbench",
                &crate::workbench::workbench_state_json(&self.docs.engine().settings.workbench),
            );
            publish_to_js("__brepSelection", &self.docs.engine().selection_json());
            publish_to_js(
                "__brepInfoWindows",
                &self.info_windows.published_json(self.docs.engine_mut()),
            );
            publish_to_js("__brepInfoWindowsHit", &self.info_windows.hits_json());
            publish_to_js("__brepInterference", &self.interference.state_json());
            publish_to_js("__brepInterferenceHit", &self.interference.hits_json());
            publish_to_js("__brepStepParts", &self.step_parts.state_json());
            publish_to_js("__brepStepPartsHit", &self.step_parts.hits_json());
            publish_to_js("__brepSelectionFilter", &self.docs.engine().selection_filter_json());
            publish_to_js("__brepSelectionHit", &self.selection.hits_json());
            publish_to_js("__brepContext", &self.context_bar.state_json());
            publish_to_js("__brepContextHit", &self.context_bar.hits_json());
            publish_to_js("__brepModeBarHit", &self.mode_bar.hits_json());
            // The DOCUMENT TABS: the open models, which one is active, and the
            // strip's per-tab hit-rects, so an e2e script can switch and close
            // documents the way a user does.
            publish_to_js("__brepDocuments", &document_tabs::state_json(&self.docs));
            publish_to_js("__brepDocumentsHit", &hits_json(&self.document_tab_hits));
            publish_to_js("__brepComponentMove", &self.docs.engine().component_move_json());
            publish_to_js("__brepSketch", &self.sketch.published_json(self.docs.engine()));
            publish_to_js("__brepWireframe", &format!("{}", self.docs.engine().settings.wireframe));
            publish_to_js(
                "__brepRefSelect",
                &serde_json::json!({
                    "active": self.docs.engine().ref_select_active(),
                    "prompt": self.docs.engine().ref_select_prompt(),
                    "names": self.docs.engine().ref_select_names(),
                })
                .to_string(),
            );
            // Viewport origin + projected probe points (viewport-local logical
            // px) so the verifier can click precise spots ON the Box and ON the
            // Pin during ref-select mode. Index 0 is a Box top-corner clear of the
            // pin; indices 1..4 are points on the Pin's cylindrical stub that
            // protrudes above the Box top (y=20), on the camera-facing sides — the
            // verifier tries them until one picks "Pin".
            publish_to_js("__brepView", &self.viewport.viewport_rect_json());
            // Dock layout snapshot (per-pane visible / rendered) so the verifier
            // can see which side panels are on-screen and, once a user tabs panels
            // together, activate the right tab before asserting on its widgets.
            // `active=false` in sketch / ref-select (the dock is bypassed).
            publish_to_js("__brepDock", &self.dock.state_json(!sketch && !ref_select));
            publish_to_js(
                "__brepProbe",
                &self
                    .docs
                    .engine()
                    .world_to_screen_json(
                        "[[2.0,20.0,2.0],[14.243,22.5,14.243],[16.0,22.5,10.0],\
                          [10.0,22.5,16.0],[10.0,25.0,10.0]]",
                    )
                    .unwrap_or_else(|_| "[]".to_string()),
            );
            publish_to_js("__brepPpp", &format!("{ppp}"));
            publish_to_js("__brepStep", &format!("{}", self.docs.engine().history_rollback()));
            publish_to_js(
                "__brepParams",
                &self.docs.engine().feature_params_json(self.docs.engine().history_rollback()),
            );
        }

        // NOTE: the 3D viewport is no longer drawn here — it is a dock tile drawn
        // earlier this frame (normal mode) or drawn directly in the sketch /
        // ref-select branch above. Drawing it before the top-right overlay is what
        // keeps that overlay anchored to the live viewport rect.
    }
}

/// Fetch a `.BREP.json` document over HTTP for the `?loadModel=` boot path; the
/// reply (or a human error) arrives on the returned channel and `ctx` is
/// repainted so the frame loop drains it. Mirrors `step_parts::fetch_text`.
#[cfg(target_arch = "wasm32")]
fn fetch_model(
    ctx: &egui::Context,
    url: String,
) -> std::sync::mpsc::Receiver<Result<String, String>> {
    let (tx, rx) = std::sync::mpsc::channel();
    let ctx = ctx.clone();
    ehttp::fetch(ehttp::Request::get(url), move |result| {
        let out = match result {
            Ok(resp) if resp.ok => Ok(resp
                .text()
                .map(str::to_owned)
                .unwrap_or_else(|| String::from_utf8_lossy(&resp.bytes).into_owned())),
            Ok(resp) => Err(format!("HTTP {} {}", resp.status, resp.status_text)),
            Err(err) => Err(err),
        };
        let _ = tx.send(out);
        ctx.request_repaint();
    });
    rx
}

/// A `(key, rect)` list as the verifier's `{key: [x, y, w, h]}` map — the same
/// shape every panel's own `hits_json` publishes.
#[cfg(target_arch = "wasm32")]
fn hits_json(hits: &[(String, egui::Rect)]) -> String {
    let map: serde_json::Map<String, serde_json::Value> = hits
        .iter()
        .map(|(key, rect)| {
            (
                key.clone(),
                serde_json::json!([rect.min.x, rect.min.y, rect.width(), rect.height()]),
            )
        })
        .collect();
    serde_json::Value::Object(map).to_string()
}

/// Mirror an engine JSON string to `window.<name>` (wasm/verification only).
#[cfg(target_arch = "wasm32")]
fn publish_to_js(name: &str, json: &str) {
    if let Some(win) = web_sys::window() {
        let _ = js_sys::Reflect::set(
            &win,
            &wasm_bindgen::JsValue::from_str(name),
            &wasm_bindgen::JsValue::from_str(json),
        );
    }
}

/// The seed model handed to the engine at startup: a 3-feature history so the
/// tree / roll / edit are real —
///   0. `P.CU` "Box"  — a 20 mm cube at the origin (spans `[0,20]³`).
///   1. `P.CY` "Pin"  — a r=6, h=30 cylinder (axis +Y) positioned to pierce the
///      cube through its centre in XZ (x=10, z=10) from below (y=-5) to above.
///   2. `B`    "Cut"  — SUBTRACT: `targetSolid = Box`, tools `[Pin]` → the cube
///      with a cylindrical through-hole (the ref-select field is visible for the
///      next slice). Roll-to-step shows: cube → cube+cylinder → subtracted cube.
///
/// This is just the INITIAL document — once handed to `EngineState`, the engine
/// OWNS the mutable history; the app keeps no copy.
fn seed_history_json() -> String {
    serde_json::json!({
        "expressions": "",
        "configurator": {},
        "features": [
            {
                "type": "P.CU",
                "inputParams": {
                    "id": "Box",
                    "sizeX": 20.0, "sizeY": 20.0, "sizeZ": 20.0,
                    "transform": {
                        "position": [0.0, 0.0, 0.0],
                        "rotationEuler": [0.0, 0.0, 0.0],
                        "scale": [1.0, 1.0, 1.0]
                    },
                    "boolean": { "targets": [], "operation": "NONE", "mergeCoplanarFaces": true }
                },
                "persistentData": {}
            },
            {
                "type": "P.CY",
                "inputParams": {
                    "id": "Pin",
                    "radius": 6.0, "height": 30.0,
                    "transform": {
                        "position": [10.0, -5.0, 10.0],
                        "rotationEuler": [0.0, 0.0, 0.0],
                        "scale": [1.0, 1.0, 1.0]
                    },
                    "boolean": { "targets": [], "operation": "NONE", "mergeCoplanarFaces": true }
                },
                "persistentData": {}
            },
            {
                "type": "B",
                "inputParams": {
                    "id": "Cut",
                    "targetSolid": "Box",
                    "boolean": { "operation": "SUBTRACT", "targets": ["Pin"], "mergeCoplanarFaces": true }
                },
                "persistentData": {}
            }
        ]
    })
    .to_string()
}