brep_app/

store.rs

//! The persistent-storage / filesystem seam — the ONE platform exception in
//! the engine-native UI. Settings, dock layout, and model documents all use the
//! same [`ModelStore::read`] / [`ModelStore::write`] API. Only its backend differs:
//! desktop writes files; the browser mirrors an ASYNC, swappable
//! [`mirror_store::StoreBackend`] — IndexedDB today, a remote server next — into
//! memory and writes behind it, which is what keeps this whole API synchronous.

/// Reserved persistent-object names used internally for application state.
pub const SETTINGS_KEY: &str = "@settings";
pub const FEATURE_PALETTE_DISPLAY_KEY: &str = "@feature_palette_display";
pub const DOCK_LAYOUT_KEY: &str = "@dock_layout";
/// The open-document SESSION (which models are in tabs and which one is active
/// — see `crate::document`), so a reload comes back to the desk you left.
pub const SESSION_KEY: &str = "@session";
/// Pinned explorer locations (a JSON array of navigable location strings),
/// persisted through the ordinary `read`/`write` CRUD like the other reserved
/// keys so the sidebar needs no dedicated trait surface.
pub const PINNED_KEY: &str = "@pinned";
/// The AUTOSAVE blob: every open document that had unsaved changes the last
/// time the shell's autosave fired (see `crate::recovery`), so a crash, a
/// closed tab or a reload can offer that work back. Written debounced, removed
/// the moment nothing is dirty; never listed as a document.
pub const RECOVERY_KEY: &str = "@recovery";

/// A file selected outside the model store. Keeping bytes verbatim allows the
/// same upload channel to carry binary STL as well as text CAD formats.
pub struct ImportedFile {
    pub name: String,
    pub bytes: Vec<u8>,
}

/// One entry exposed to the common in-application filesystem browser.
#[derive(Clone, Debug, PartialEq)]
pub struct BrowserEntry {
    pub name: String,
    pub identity: String,
    pub is_dir: bool,
    /// File size in bytes for the Size column. `None` for directories or where
    /// the backend cannot report it.
    pub size: Option<u64>,
    /// Last-modified time as whole Unix seconds for the Date column. `None` where
    /// unavailable — the browser key/value backends store values, not timestamps.
    pub modified: Option<f64>,
}

/// A quick-access destination for the explorer's left sidebar.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BrowserPlace {
    /// Human label shown in the sidebar (e.g. `"Home"`, `"Models"`, a disk name).
    pub label: String,
    /// The navigable location — pass to [`ModelStore::browser_navigate`].
    pub location: String,
    /// Which built-in glyph the widget draws for this place.
    pub kind: PlaceKind,
}

/// The category of a [`BrowserPlace`], so the widget owns the icon styling.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PlaceKind {
    Home,
    Documents,
    Downloads,
    Models,
    Root,
}
// A MODEL is a whole document
// (the engine-owned `HistoryRequest` JSON — one `.BREP.json` recipe), and the
// file panel needs to *enumerate*, read, and write NAMED documents, plus (in the
// browser) hand a file to / take a file from the user's real filesystem. The same
// trait also stores reserved application-state blobs. Platform-specific behavior
// remains behind two `#[cfg]`-gated implementations.
//
// The trait is deliberately a **named-document CRUD** (`list` / `read` / `write`
// / `remove`) plus a poll-based **file-interchange** side-channel. That shape is
// exactly what a later **GitHub backend** needs: `list` = a repo directory
// listing, `read` = fetch a file's contents, `write` = create/update (commit)
// a file, `remove` = delete a file — the model name is the path within the repo.
// An async backend (GitHub over HTTP, or the browser File System Access API /
// OPFS whose main-thread API is async) slots in behind the SAME trait by driving
// its request on a background task and surfacing the result through the
// `begin_import` → `take_import` poll pattern used here for uploads, so the
// synchronous panel code never changes. GitHub itself is a deferred follow-up;
// this lands the seam it plugs into.

/// The application's single persistent-storage abstraction. Reserved application
/// keys and named model documents are read and written through the same methods.
/// All methods take `&self`; mutable backend state lives behind interior mutability.
pub trait ModelStore {
    /// A short human label of where documents persist, for the panel header
    /// (e.g. `"filesystem: ~/.config/brep-app/models"` or `"browser storage"`).
    fn backend_label(&self) -> String {
        "persistent storage".into()
    }

    /// The names of the documents currently available to **Open** (bare names,
    /// no extension). May be empty on a backend that cannot enumerate — then the
    /// panel falls back to the name field / import.
    fn list(&self) -> Vec<String> {
        Vec::new()
    }

    /// Read a stored document by name, or `None` if absent/unreadable.
    fn read(&self, name: &str) -> Option<String>;

    /// Create or overwrite the document `name` with `contents`. `Err` carries a
    /// message the panel surfaces in its status line.
    fn write(&self, name: &str, contents: &str) -> Result<(), String>;

    /// Delete the document `name` (best-effort; `Ok` if it is already gone).
    fn remove(&self, _name: &str) -> Result<(), String> {
        Ok(())
    }

    /// Persistence failures that surfaced AFTER a `write` / `remove` already
    /// returned `Ok` — the price of a WRITE-BEHIND backend (see
    /// [`mirror_store`]). The app shell drains this once per frame into the toast
    /// overlay, so a save that never reached storage is never silent: the
    /// in-memory copy means nothing is lost mid-session, but the user has to know
    /// it will not survive a reload. Empty on a backend that writes synchronously
    /// (native files), which reports through `write`'s `Err` instead.
    fn take_persistence_errors(&self) -> Vec<String> {
        Vec::new()
    }

    // --- common file-browser filesystem --------------------------------------

    /// Current directory shown by the embedded explorer.
    fn browser_location(&self) -> String {
        self.backend_label()
    }

    /// Directories and matching files at the current explorer location.
    /// Directories are never filtered. The default implementation presents the
    /// backend's named model collection as a flat virtual directory.
    fn browser_entries(&self, _extensions: &[&str]) -> Vec<BrowserEntry> {
        self.list()
            .into_iter()
            .map(|name| BrowserEntry {
                identity: name.clone(),
                name,
                is_dir: false,
                size: None,
                modified: None,
            })
            .collect()
    }

    fn browser_enter(&self, _identity: &str) -> Result<(), String> {
        Err("this storage backend has no directories".into())
    }

    fn browser_up(&self) -> Result<(), String> {
        Ok(())
    }

    fn browser_home(&self) -> Result<(), String> {
        Ok(())
    }

    fn browser_root(&self) -> Result<(), String> {
        Ok(())
    }

    /// Navigate the explorer directly to `location` — a value previously returned
    /// by [`Self::browser_location`], a [`BrowserPlace::location`], a breadcrumb
    /// ancestor, or a user-typed path. `Err` if it is not a directory this backend
    /// can browse. Powers the breadcrumb, the sidebar, back/forward, and the
    /// path-edit field. Default: unsupported.
    fn browser_navigate(&self, _location: &str) -> Result<(), String> {
        Err("this storage backend cannot navigate to a path".into())
    }

    /// Quick-access places for the explorer's left sidebar (home, documents, the
    /// models root, disks…). Default: none, and the sidebar hides itself.
    fn browser_places(&self) -> Vec<BrowserPlace> {
        Vec::new()
    }

    /// Create a child directory at the current browser location.
    fn browser_create_dir(&self, _name: &str) -> Result<(), String> {
        Err("this storage backend cannot create directories".into())
    }

    /// Write a filename at the current browser location and return its stable
    /// identity for subsequent plain Save operations.
    fn browser_write(&self, name: &str, contents: &str) -> Result<String, String> {
        self.write(name, contents)?;
        Ok(name.to_string())
    }

    /// Files available to the in-app explorer for a foreign-format import.
    /// Names retain their extension. Browser storage returns none and offers an
    /// Upload button instead; desktop enumerates its application files directory.
    fn list_external_files(&self, _extensions: &[&str]) -> Vec<String> {
        Vec::new()
    }

    /// Read one entry returned by [`Self::list_external_files`].
    fn read_external_file(&self, _name: &str) -> Option<Vec<u8>> {
        None
    }

    // --- real-file interchange (the platform "fallback") ----------------------
    // The browser cannot silently write to an arbitrary path; these methods let
    // it move a document to/from the user's real filesystem. Desktop instead
    // browses and writes its application files directory directly.

    /// Whether this backend can exchange files with the user's real filesystem
    /// (browser download+upload). The panel shows the Upload affordance only when
    /// this is `true`.
    fn supports_file_interchange(&self) -> bool {
        false
    }

    /// Hand `contents` to the user as a file named after `name` (browser: a
    /// download; native w/ dialog: a Save-As). Returns the saved document's
    /// identity — the full path the user chose on native (so the caller can
    /// re-save straight to it), the bare download name on the web — or `None`
    /// when the user cancelled. No-op (`None`) by default.
    fn export_file(&self, name: &str, contents: &str) -> Result<Option<String>, String> {
        let _ = (name, contents);
        Ok(None)
    }

    /// Begin importing a real file — opens the platform picker. The result is
    /// retrieved later via [`Self::take_import`] (upload/read is async in the
    /// browser). No-op by default.
    fn begin_import(&self) -> Result<(), String> {
        Ok(())
    }

    /// Poll for a completed import, consuming it.
    /// `None` until a `begin_import` finishes. Default: never any.
    fn take_import(&self) -> Option<ImportedFile> {
        None
    }

    // --- format-typed interchange (CAD / mesh) --------------------------------
    // The model lanes above trade the `.BREP.json` recipe; import/export of a
    // foreign format (STEP text, ASCII STL) needs a DIFFERENT picker filter and
    // must NOT mangle the file extension. These two methods add that lane while
    // leaving the model lanes byte-for-byte. They share the SAME `take_import`
    // pickup channel — the panel routes the result by its filename extension.

    /// Begin importing a real file behind a specific picker `filter` (a human
    /// label + dot-less extensions, e.g. `("STEP", &["step","stp"])`). The chosen
    /// file's contents + its FULL name (extension preserved, so the panel can
    /// route it) arrive via [`Self::take_import`]. Default: reuse [`Self::begin_import`].
    fn begin_import_filtered(&self, _filter: (&str, &[&str])) -> Result<(), String> {
        self.begin_import()
    }

    /// Hand `contents` to the user under EXACTLY `file_name` (extension included,
    /// no model-extension munging) — the Save-As / download for a foreign export
    /// format. Default no-op (interchange unsupported).
    fn export_file_named(&self, _file_name: &str, _contents: &str) -> Result<(), String> {
        Ok(())
    }
}

/// Construct the platform's one persistent store for application state and models.
/// A native file store rooted at `dir` — the seam an automation host uses to
/// keep a session's settings, autosave and recovery blob out of the user's
/// own config directory (spec §8).
#[cfg(not(target_arch = "wasm32"))]
pub fn native_store_at(dir: std::path::PathBuf) -> Box<dyn ModelStore> {
    Box::new(native_model::FileModelStore::with_dir(dir))
}

pub fn default_model_store() -> Box<dyn ModelStore> {
    #[cfg(not(target_arch = "wasm32"))]
    {
        Box::new(native_model::FileModelStore::new())
    }
    #[cfg(target_arch = "wasm32")]
    {
        // Already built and HYDRATED by [`hydrate_web_store`] inside the async
        // wasm entry point, so this is a hand-off, not a construction.
        web_model::take_boot_store()
    }
}

/// wasm: bring up browser persistence and pull the whole key space into memory.
/// MUST be awaited before `eframe::WebRunner::start`, because everything
/// downstream of it — [`default_model_store`], every `read` in `BrepApp::new` and
/// in the frame loop — is synchronous and assumes a complete mirror.
#[cfg(target_arch = "wasm32")]
pub async fn hydrate_web_store() {
    web_model::hydrate().await;
}

/// wasm: wake the reactive frame loop when an async file upload completes (see
/// [`web_model::set_repaint_ctx`]). Re-exported here so the app shell reaches it
/// as `store::set_repaint_ctx` without knowing the platform module.
#[cfg(target_arch = "wasm32")]
pub use web_model::set_repaint_ctx;

/// The document extension for a model recipe (`<name>.BREP.json`).
pub const MODEL_EXT: &str = ".BREP.json";

// BREP private tests: 70dbc0a2bff45147

// BREP private tests: cca838fb46080473

// BREP private tests: cb54805f276f1b7e

// BREP private tests: 3e292cde0ccd1207

/// Strip the model extension (and any directory) from a filename to get the
/// bare display name — shared by both platform impls (and the file panel, which
/// shows the bare name while keeping the raw identity for re-saves).
pub(crate) fn model_display_name(file_name: &str) -> String {
    let base = file_name
        .rsplit(['/', '\\'])
        .next()
        .unwrap_or(file_name);
    base.strip_suffix(MODEL_EXT)
        .or_else(|| base.strip_suffix(".json"))
        .unwrap_or(base)
        .to_string()
}

// --- Desktop: application models/files directory -------------------------------
#[cfg(not(target_arch = "wasm32"))]
mod native_model {
    use super::{
        model_display_name, BrowserEntry, BrowserPlace, ModelStore, PlaceKind, DOCK_LAYOUT_KEY,
        FEATURE_PALETTE_DISPLAY_KEY, MODEL_EXT, PINNED_KEY, RECOVERY_KEY, SESSION_KEY, SETTINGS_KEY,
    };
    use std::cell::RefCell;
    use std::path::{Path, PathBuf};

    /// Persist models as `<config>/brep-app/models/<name>.BREP.json` and reserved
    /// application state as files under `<config>/brep-app`. Enumerable (for the
    /// Open list) and unit-testable without a display.
    ///
    /// Open, Save As, import, and export are all driven by the application's
    /// common egui explorer; no OS-native dialog is involved.
    pub struct FileModelStore {
        app_dir: PathBuf,
        dir: PathBuf,
        browser_dir: RefCell<PathBuf>,
    }

    impl FileModelStore {
        pub fn new() -> Self {
            let base = std::env::var_os("XDG_CONFIG_HOME")
                .map(PathBuf::from)
                .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".config")))
                .unwrap_or_else(|| PathBuf::from("."));
            let app_dir = base.join("brep-app");
            Self {
                dir: app_dir.join("models"),
                browser_dir: RefCell::new(app_dir.join("models")),
                app_dir,
            }
        }

        /// A store rooted at an explicit directory — used by the round-trip test.
        /// The tests stay headless and exercise the same egui explorer path.
        #[cfg_attr(not(test), allow(dead_code))]
        pub fn with_dir(dir: PathBuf) -> Self {
            Self {
                app_dir: dir.clone(),
                browser_dir: RefCell::new(dir.clone()),
                dir,
            }
        }

        /// Resolve a name to a path. Explicit paths remain supported for existing
        /// callers; a bare name maps to `<dir>/<sanitized>.BREP.json`.
        fn resolve(&self, name: &str) -> PathBuf {
            match name {
                SETTINGS_KEY => return self.app_dir.join("settings.json"),
                FEATURE_PALETTE_DISPLAY_KEY => return self.app_dir.join("feature_palette_display.json"),
                DOCK_LAYOUT_KEY => return self.app_dir.join("dock_layout.json"),
                SESSION_KEY => return self.app_dir.join("session.json"),
                PINNED_KEY => return self.app_dir.join("pinned.json"),
                RECOVERY_KEY => return self.app_dir.join("recovery.json"),
                _ => {}
            }
            if name.contains('/') || name.contains('\\') {
                return PathBuf::from(name);
            }
            let safe: String = name
                .strip_suffix(MODEL_EXT)
                .unwrap_or(name)
                .chars()
                .map(|c| {
                    if c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.' {
                        c
                    } else {
                        '_'
                    }
                })
                .collect();
            self.dir.join(format!("{safe}{MODEL_EXT}"))
        }

        fn home_dir() -> PathBuf {
            std::env::var_os("HOME")
                .map(PathBuf::from)
                .or_else(|| std::env::current_dir().ok())
                .unwrap_or_else(|| PathBuf::from("."))
        }

        fn matches_extension(path: &Path, extensions: &[&str]) -> bool {
            extensions.is_empty()
                || extensions.iter().any(|extension| {
                    let wanted = extension.trim_start_matches('.').to_ascii_lowercase();
                    let name = path
                        .file_name()
                        .unwrap_or_default()
                        .to_string_lossy()
                        .to_ascii_lowercase();
                    name.ends_with(&format!(".{wanted}"))
                })
        }
    }

    impl ModelStore for FileModelStore {
        fn backend_label(&self) -> String {
            format!("filesystem: {}", self.dir.display())
        }

        fn list(&self) -> Vec<String> {
            let mut names: Vec<String> = std::fs::read_dir(&self.dir)
                .into_iter()
                .flatten()
                .flatten()
                .filter_map(|entry| {
                    let name = entry.file_name().to_string_lossy().into_owned();
                    name.ends_with(MODEL_EXT).then(|| model_display_name(&name))
                })
                .collect();
            names.sort();
            names
        }

        fn read(&self, name: &str) -> Option<String> {
            std::fs::read_to_string(self.resolve(name)).ok()
        }

        fn write(&self, name: &str, contents: &str) -> Result<(), String> {
            let path = self.resolve(name);
            if let Some(parent) = path.parent() {
                std::fs::create_dir_all(parent).map_err(|e| format!("create models dir: {e}"))?;
            }
            std::fs::write(&path, contents).map_err(|e| format!("write {}: {e}", path.display()))
        }

        fn remove(&self, name: &str) -> Result<(), String> {
            match std::fs::remove_file(self.resolve(name)) {
                Ok(()) => Ok(()),
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
                Err(e) => Err(format!("remove: {e}")),
            }
        }

        fn browser_location(&self) -> String {
            self.browser_dir.borrow().display().to_string()
        }

        fn browser_entries(&self, extensions: &[&str]) -> Vec<BrowserEntry> {
            let mut entries: Vec<BrowserEntry> = std::fs::read_dir(&*self.browser_dir.borrow())
                .into_iter()
                .flatten()
                .flatten()
                .filter_map(|entry| {
                    let path = entry.path();
                    let is_dir = path.is_dir();
                    if !(is_dir || (path.is_file() && Self::matches_extension(&path, extensions))) {
                        return None;
                    }
                    let meta = entry.metadata().ok();
                    let size = meta.as_ref().filter(|m| m.is_file()).map(|m| m.len());
                    let modified = meta
                        .as_ref()
                        .and_then(|m| m.modified().ok())
                        .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                        .map(|d| d.as_secs_f64());
                    Some(BrowserEntry {
                        name: entry.file_name().to_string_lossy().into_owned(),
                        identity: path.to_string_lossy().into_owned(),
                        is_dir,
                        size,
                        modified,
                    })
                })
                .collect();
            entries.sort_by(|a, b| {
                b.is_dir
                    .cmp(&a.is_dir)
                    .then_with(|| a.name.to_ascii_lowercase().cmp(&b.name.to_ascii_lowercase()))
            });
            entries
        }

        fn browser_enter(&self, identity: &str) -> Result<(), String> {
            let path = PathBuf::from(identity);
            if !path.is_dir() {
                return Err(format!("not a directory: {}", path.display()));
            }
            *self.browser_dir.borrow_mut() = path;
            Ok(())
        }

        fn browser_up(&self) -> Result<(), String> {
            let parent = self.browser_dir.borrow().parent().map(Path::to_path_buf);
            if let Some(parent) = parent {
                *self.browser_dir.borrow_mut() = parent;
            }
            Ok(())
        }

        fn browser_home(&self) -> Result<(), String> {
            *self.browser_dir.borrow_mut() = Self::home_dir();
            Ok(())
        }

        fn browser_root(&self) -> Result<(), String> {
            let current = self.browser_dir.borrow().clone();
            let root = current
                .ancestors()
                .last()
                .map(Path::to_path_buf)
                .unwrap_or_else(|| PathBuf::from(std::path::MAIN_SEPARATOR.to_string()));
            *self.browser_dir.borrow_mut() = root;
            Ok(())
        }

        fn browser_navigate(&self, location: &str) -> Result<(), String> {
            let path = PathBuf::from(location);
            if path.is_dir() {
                *self.browser_dir.borrow_mut() = path;
                Ok(())
            } else {
                Err(format!("not a directory: {location}"))
            }
        }

        fn browser_places(&self) -> Vec<BrowserPlace> {
            let home = Self::home_dir();
            let mut places = vec![BrowserPlace {
                label: "Home".into(),
                location: home.display().to_string(),
                kind: PlaceKind::Home,
            }];
            for (label, sub, kind) in [
                ("Documents", "Documents", PlaceKind::Documents),
                ("Downloads", "Downloads", PlaceKind::Downloads),
            ] {
                let path = home.join(sub);
                if path.is_dir() {
                    places.push(BrowserPlace {
                        label: label.into(),
                        location: path.display().to_string(),
                        kind,
                    });
                }
            }
            places.push(BrowserPlace {
                label: "Models".into(),
                location: self.dir.display().to_string(),
                kind: PlaceKind::Models,
            });
            places.push(BrowserPlace {
                label: "/".into(),
                location: "/".into(),
                kind: PlaceKind::Root,
            });
            places
        }

        fn browser_create_dir(&self, name: &str) -> Result<(), String> {
            let name = PathBuf::from(name);
            if name.components().count() != 1 {
                return Err("folder name must be one path component".into());
            }
            let path = self.browser_dir.borrow().join(name);
            std::fs::create_dir(&path)
                .map_err(|e| format!("create folder {}: {e}", path.display()))
        }

        fn browser_write(&self, name: &str, contents: &str) -> Result<String, String> {
            let mut file_name = PathBuf::from(name)
                .file_name()
                .ok_or("invalid file name")?
                .to_os_string();
            if !name.to_ascii_lowercase().ends_with(".json") {
                file_name.push(MODEL_EXT);
            }
            let path = self.browser_dir.borrow().join(file_name);
            std::fs::write(&path, contents)
                .map_err(|e| format!("write {}: {e}", path.display()))?;
            Ok(path.to_string_lossy().into_owned())
        }

        fn list_external_files(&self, extensions: &[&str]) -> Vec<String> {
            let wanted: Vec<String> = extensions
                .iter()
                .map(|extension| extension.trim_start_matches('.').to_ascii_lowercase())
                .collect();
            let mut names: Vec<String> = std::fs::read_dir(&self.dir)
                .into_iter()
                .flatten()
                .flatten()
                .filter_map(|entry| {
                    let path = entry.path();
                    path.is_file().then_some(path)
                })
                .filter_map(|path| {
                    let extension = path.extension()?.to_string_lossy().to_ascii_lowercase();
                    wanted.contains(&extension).then(|| {
                        path.file_name()
                            .unwrap_or_default()
                            .to_string_lossy()
                            .into_owned()
                    })
                })
                .collect();
            names.sort();
            names
        }

        fn read_external_file(&self, name: &str) -> Option<Vec<u8>> {
            let path = PathBuf::from(name);
            let path = if path.is_absolute() || path.components().count() > 1 {
                path
            } else {
                self.browser_dir.borrow().join(path)
            };
            std::fs::read(path).ok()
        }

        fn export_file_named(&self, file_name: &str, contents: &str) -> Result<(), String> {
            std::fs::create_dir_all(&self.dir)
                .map_err(|e| format!("create models dir: {e}"))?;
            let name = PathBuf::from(file_name)
                .file_name()
                .ok_or("invalid export file name")?
                .to_owned();
            let path = self.dir.join(name);
            std::fs::write(&path, contents)
                .map_err(|e| format!("write {}: {e}", path.display()))
        }
    }
}

// --- The mirrored store: a synchronous facade over an ASYNC backend ------------
//
// The browser has no synchronous storage big enough for this application. The
// measured numbers that forced this module into existence: one imported STEP
// part serialises to a ~35 MB native BREP payload, and an imported assembly
// document runs 1.0x-12.8x its source STEP text — against `localStorage`'s
// ~5-10 MB per-origin quota. Every backend with room (IndexedDB today, a remote
// server tomorrow) is ASYNC, while [`ModelStore`] is synchronous and the egui
// frame loop that calls it is immediate-mode.
//
// The reconciliation is this module: an in-memory `BTreeMap` MIRROR of the whole
// key space, hydrated ONCE from the backend inside the already-async wasm entry
// point (`lib.rs::start`) BEFORE the app is constructed. Because hydration
// completes before the first `read` can happen, a synchronous read never has a
// "not loaded yet" state to represent, and none of the ~55 call sites change.
// Writes mutate the mirror synchronously (so the very next `read` sees them) and
// are pushed to the backend WRITE-BEHIND; a push that fails afterwards surfaces
// through [`ModelStore::take_persistence_errors`].
#[cfg(any(target_arch = "wasm32", test))]
pub(crate) mod mirror_store {
    use super::{
        model_display_name, BrowserEntry, BrowserPlace, ModelStore, PlaceKind, DOCK_LAYOUT_KEY,
        FEATURE_PALETTE_DISPLAY_KEY, MODEL_EXT, PINNED_KEY, RECOVERY_KEY, SESSION_KEY, SETTINGS_KEY,
    };
    use std::cell::{Cell, RefCell};
    use std::collections::BTreeMap;
    use std::future::Future;
    use std::pin::Pin;
    use std::rc::Rc;

    /// The persisted key scheme, VERBATIM from the `localStorage` era so an
    /// existing origin's keys keep their meaning under any backend: model
    /// documents live at `brep-app:model:<relative name>`, explorer folders at
    /// `brep-app:dir:<relative path>/`, and the three reserved application blobs
    /// at `brep-app:settings` / `:dock_layout` / `:pinned` (see [`MirrorStore::key`]).
    pub(crate) const PREFIX: &str = "brep-app:model:";
    pub(crate) const DIR_PREFIX: &str = "brep-app:dir:";

    /// How many distinct persistence failures the error log keeps before the
    /// oldest is dropped. The log is a user-facing notice channel, not telemetry.
    const MAX_ERRORS: usize = 64;

    /// The future a [`StoreBackend`] hands back. Boxed (not `async fn` in the
    /// trait) because the store is used as `dyn StoreBackend`, and deliberately
    /// NOT `Send`: every host is single-threaded (the browser main thread; the
    /// native test executor below).
    pub(crate) type BackendFuture<T> = Pin<Box<dyn Future<Output = Result<T, String>>>>;

    /// Where a [`MirrorStore`]'s bytes actually live — the swappable persistence
    /// seam.
    ///
    /// The contract is deliberately narrow and platform-free: **string keys,
    /// string values, `String` errors, async everywhere**. No `JsValue`, no
    /// `web_sys` type, no IndexedDB concept crosses it, and the mirror above it
    /// knows nothing about how a key is stored. [`IdbBackend`](super::web_model)
    /// is the only implementation today; the intended SECOND one is a remote
    /// HTTP/AJAX backend that pushes and pulls the same key space to a central
    /// server, and it must be able to land without touching this module.
    ///
    /// Two obligations an implementation carries:
    ///
    /// * **Per-key FIFO.** Two `put`s of the same key must land in call order,
    ///   whatever order their futures are polled in — the mirror issues them from
    ///   a synchronous `write` and never sequences them itself. IndexedDB gets
    ///   this for free (a `readwrite` transaction commits in creation order, and
    ///   [`IdbBackend`](super::web_model) creates the transaction and issues the
    ///   request synchronously inside `put`). An HTTP backend has no such
    ///   guarantee and will need its own per-key send queue.
    /// * **Whole-key-space `load_all`.** Hydration is all-or-nothing today.
    ///
    /// ## The known ceiling (stated, not solved)
    ///
    /// A full hydrate holds EVERY saved document resident for the session. That
    /// is a non-issue for an origin migrating off `localStorage` (its whole
    /// corpus fit in ~5 MB), but a user with ten 30 MB assemblies pays ~300 MB at
    /// boot, and a remote backend makes it untenable outright — you cannot pull a
    /// server-side library of hundreds of parts at start-up. The escape hatch,
    /// when it is needed: make the mirror's value a `{ Resident(String), OnDisk {
    /// bytes: u64 } }` enum so `list` / `browser_entries` / sizes still answer
    /// from metadata alone, add a prefetch that resolves `OnDisk` entries in the
    /// background, and give `StoreBackend` a `load_index` + `get(key)` pair
    /// beside `load_all`. All of that sits behind THIS trait and behind
    /// [`ModelStore`], so no call site moves. **Do not build it until a real
    /// corpus needs it.**
    pub(crate) trait StoreBackend {
        /// A short human label for the storage panel header (see
        /// [`ModelStore::backend_label`]).
        fn label(&self) -> String;

        /// Pull the entire key space. Called ONCE, during the async boot, before
        /// any [`MirrorStore`] exists.
        fn load_all(&self) -> BackendFuture<Vec<(String, String)>>;

        /// Persist `value` under `key`, creating or overwriting.
        fn put(&self, key: &str, value: &str) -> BackendFuture<()>;

        /// Delete `key`. Succeeding on an absent key is correct.
        fn delete(&self, key: &str) -> BackendFuture<()>;
    }

    /// The backend installed when persistence could NOT be brought up (IndexedDB
    /// blocked in a private window, storage denied, the boot hydrate never ran).
    ///
    /// There is deliberately no quiet fallback to `localStorage`: a 5 MB backend
    /// silently standing in for a hundreds-of-megabytes one is the failure mode
    /// this whole change exists to end. Instead the session stays fully usable
    /// IN MEMORY — the mirror still holds everything written this session — while
    /// every write reports, loudly and repeatedly, that nothing is being saved.
    pub(crate) struct UnavailableBackend {
        reason: String,
    }

    impl UnavailableBackend {
        pub(crate) fn new(reason: impl Into<String>) -> Self {
            Self {
                reason: reason.into(),
            }
        }
    }

    impl StoreBackend for UnavailableBackend {
        fn label(&self) -> String {
            format!("NOT SAVING — {} · use Download to keep your work", self.reason)
        }

        fn load_all(&self) -> BackendFuture<Vec<(String, String)>> {
            let reason = self.reason.clone();
            Box::pin(async move { Err(reason) })
        }

        fn put(&self, _key: &str, _value: &str) -> BackendFuture<()> {
            let reason = self.reason.clone();
            Box::pin(async move { Err(reason) })
        }

        fn delete(&self, _key: &str) -> BackendFuture<()> {
            let reason = self.reason.clone();
            Box::pin(async move { Err(reason) })
        }
    }

    /// Persistence failures that happened AFTER the synchronous `write` returned
    /// `Ok` — the price of write-behind. Nothing is lost mid-session (the mirror
    /// holds it), but the user MUST learn that it did not persist, so the log is
    /// drained into the toast overlay every frame.
    ///
    /// The cursor (rather than a `Vec::drain`) keeps the full history addressable
    /// for the `__brepStoreErrors` verification hook while still handing the UI
    /// each message exactly once.
    pub(crate) struct ErrorLog {
        log: RefCell<Vec<String>>,
        drained: Cell<usize>,
        /// Wakes the reactive frame loop so a failure recorded from an async
        /// callback is toasted THIS frame instead of waiting for stray input.
        wake: Option<Rc<dyn Fn()>>,
    }

    impl ErrorLog {
        fn new(wake: Option<Rc<dyn Fn()>>) -> Self {
            Self {
                log: RefCell::new(Vec::new()),
                drained: Cell::new(0),
                wake,
            }
        }

        /// Record one failure. An identical message that is still UNDRAINED is
        /// collapsed (a burst of failing writes shows one toast, not six); once
        /// the UI has shown it, the same message can be recorded again — every
        /// failed save is reported.
        pub(crate) fn record(&self, message: String) {
            {
                let mut log = self.log.borrow_mut();
                let undrained = log.len() > self.drained.get();
                if undrained && log.last().map(|last| *last == message).unwrap_or(false) {
                    return;
                }
                log.push(message);
                if log.len() > MAX_ERRORS {
                    log.remove(0);
                    self.drained.set(self.drained.get().saturating_sub(1));
                }
            }
            if let Some(wake) = &self.wake {
                wake();
            }
        }

        /// Messages recorded since the last drain (what the UI has not shown yet).
        fn drain(&self) -> Vec<String> {
            let log = self.log.borrow();
            let from = self.drained.get().min(log.len());
            self.drained.set(log.len());
            log[from..].to_vec()
        }

        /// Every message recorded this session (verification hook).
        fn all(&self) -> Vec<String> {
            self.log.borrow().clone()
        }
    }

    /// Drive one write-behind push to completion.
    ///
    /// wasm: hand it to the browser's microtask queue, which is the whole point —
    /// the caller's `write` already returned. Native: the mirror only exists under
    /// `cfg(test)`, where the test backend's futures are already resolved, so a
    /// single poll with a no-op waker finishes them. Keeping the shape identical
    /// means the native tests exercise the REAL write-behind path (spawn, await,
    /// record the error) rather than a synchronous stand-in.
    #[cfg(target_arch = "wasm32")]
    fn spawn(task: impl Future<Output = ()> + 'static) {
        wasm_bindgen_futures::spawn_local(task);
    }

    #[cfg(not(target_arch = "wasm32"))]
    fn spawn(task: impl Future<Output = ()> + 'static) {
        let mut task = Box::pin(task);
        let mut cx = std::task::Context::from_waker(std::task::Waker::noop());
        let _ = task.as_mut().poll(&mut cx);
    }

    /// A synchronous [`ModelStore`] over an asynchronous [`StoreBackend`]: the
    /// hydrated mirror plus write-behind. Cheap to clone — every field is shared,
    /// so a clone is another handle on the SAME session state (used by the
    /// verification hooks).
    #[derive(Clone)]
    pub(crate) struct MirrorStore {
        /// The whole key space, keyed EXACTLY as the backend keys it.
        entries: Rc<RefCell<BTreeMap<String, String>>>,
        /// The explorer's current virtual directory (`/` or `/models/...`).
        browser_dir: Rc<RefCell<String>>,
        backend: Rc<dyn StoreBackend>,
        errors: Rc<ErrorLog>,
        /// Pushes issued but not yet settled. Zero means everything written so
        /// far is durable — which is what makes a "save, reload, still there"
        /// check non-racy (see the `__brepStorePending` hook).
        pending: Rc<Cell<usize>>,
    }

    impl MirrorStore {
        /// Build the session store from an already-hydrated key space.
        /// `wake` (`None` off-browser) is called when a write-behind failure is
        /// recorded, to repaint the reactive frame loop.
        pub(crate) fn new(
            backend: Rc<dyn StoreBackend>,
            entries: Vec<(String, String)>,
            wake: Option<Rc<dyn Fn()>>,
        ) -> Self {
            Self {
                entries: Rc::new(RefCell::new(entries.into_iter().collect())),
                browser_dir: Rc::new(RefCell::new("/models".into())),
                backend,
                errors: Rc::new(ErrorLog::new(wake)),
                pending: Rc::new(Cell::new(0)),
            }
        }

        /// The persisted key for a document/reserved name. UNCHANGED from the
        /// `localStorage` implementation this replaced, so an existing origin's
        /// data keeps its identity.
        pub(crate) fn key(name: &str) -> String {
            match name {
                SETTINGS_KEY => "brep-app:settings".into(),
                FEATURE_PALETTE_DISPLAY_KEY => "brep-app:feature_palette_display".into(),
                DOCK_LAYOUT_KEY => "brep-app:dock_layout".into(),
                SESSION_KEY => "brep-app:session".into(),
                PINNED_KEY => "brep-app:pinned".into(),
                RECOVERY_KEY => "brep-app:recovery".into(),
                _ => format!("{PREFIX}{}", Self::model_relative(name)),
            }
        }

        /// A document name reduced to its store-relative form: no leading `/`, no
        /// `/models` root, no model extension.
        fn model_relative(name: &str) -> String {
            let name = name
                .trim_start_matches('/')
                .strip_prefix("models/")
                .unwrap_or_else(|| name.trim_start_matches('/'));
            name.strip_suffix(MODEL_EXT)
                .or_else(|| name.strip_suffix(".json"))
                .unwrap_or(name)
                .trim_matches('/')
                .to_string()
        }

        fn virtual_model_path(relative: &str) -> String {
            format!("/models/{}{MODEL_EXT}", relative.trim_matches('/'))
        }

        fn child_path(parent: &str, child: &str) -> String {
            if parent == "/" {
                format!("/{child}")
            } else {
                format!("{}/{child}", parent.trim_end_matches('/'))
            }
        }

        /// Hand one backend push to the executor, counting it in `pending` and
        /// routing its eventual failure to the error log.
        fn push(&self, name: &str, request: BackendFuture<()>) {
            self.pending.set(self.pending.get() + 1);
            let pending = self.pending.clone();
            let errors = self.errors.clone();
            let name = name.to_string();
            spawn(async move {
                let outcome = request.await;
                pending.set(pending.get().saturating_sub(1));
                if let Err(message) = outcome {
                    errors.record(format!("'{name}' was NOT saved: {message}"));
                }
            });
        }

        /// Seed the log with a boot-time failure so the very first frame toasts it.
        pub(crate) fn report(&self, message: String) {
            self.errors.record(message);
        }

        /// Backend pushes issued but not yet settled (verification hook).
        pub(crate) fn pending(&self) -> usize {
            self.pending.get()
        }

        /// Every persistence failure this session (verification hook).
        pub(crate) fn error_history(&self) -> Vec<String> {
            self.errors.all()
        }

        /// Byte length of a stored document, or `None` if absent (verification
        /// hook — a multi-megabyte payload is not worth marshalling into JS just
        /// to measure it).
        pub(crate) fn len_of(&self, name: &str) -> Option<usize> {
            self.entries.borrow().get(&Self::key(name)).map(|v| v.len())
        }
    }

    impl ModelStore for MirrorStore {
        fn backend_label(&self) -> String {
            self.backend.label()
        }

        fn list(&self) -> Vec<String> {
            // `BTreeMap` iterates in key order, so the names come out sorted.
            self.entries
                .borrow()
                .keys()
                .filter_map(|key| key.strip_prefix(PREFIX).map(str::to_string))
                .collect()
        }

        fn read(&self, name: &str) -> Option<String> {
            self.entries.borrow().get(&Self::key(name)).cloned()
        }

        fn write(&self, name: &str, contents: &str) -> Result<(), String> {
            let key = Self::key(name);
            self.entries
                .borrow_mut()
                .insert(key.clone(), contents.to_string());
            // The mirror is authoritative for this session, so `Ok` is honest:
            // every subsequent read sees the new bytes. Durability is the
            // backend's job and its failure arrives via `take_persistence_errors`.
            self.push(name, self.backend.put(&key, contents));
            Ok(())
        }

        fn remove(&self, name: &str) -> Result<(), String> {
            let key = Self::key(name);
            self.entries.borrow_mut().remove(&key);
            self.push(name, self.backend.delete(&key));
            Ok(())
        }

        fn take_persistence_errors(&self) -> Vec<String> {
            self.errors.drain()
        }

        fn browser_location(&self) -> String {
            // The RAW navigable path (breadcrumb / back-forward / path-edit rely on
            // this being feed-able straight back to `browser_navigate`); the human
            // "virtual filesystem" context lives in `backend_label`.
            self.browser_dir.borrow().clone()
        }

        fn browser_entries(&self, extensions: &[&str]) -> Vec<BrowserEntry> {
            let current = self.browser_dir.borrow().clone();
            if current == "/" {
                return vec![BrowserEntry {
                    name: "models".into(),
                    identity: "/models".into(),
                    is_dir: true,
                    size: None,
                    modified: None,
                }];
            }
            let relative_dir = current
                .strip_prefix("/models")
                .unwrap_or("")
                .trim_matches('/');
            let prefix = if relative_dir.is_empty() {
                String::new()
            } else {
                format!("{relative_dir}/")
            };
            let wanted: Vec<String> = extensions
                .iter()
                .map(|extension| extension.trim_start_matches('.').to_ascii_lowercase())
                .collect();
            let mut entries: BTreeMap<String, BrowserEntry> = BTreeMap::new();
            for (key, value) in self.entries.borrow().iter() {
                let (item, is_model) = if let Some(item) = key.strip_prefix(PREFIX) {
                    (item, true)
                } else if let Some(item) = key.strip_prefix(DIR_PREFIX) {
                    (item.trim_end_matches('/'), false)
                } else {
                    continue;
                };
                let Some(rest) = item.strip_prefix(&prefix) else {
                    continue;
                };
                if rest.is_empty() {
                    continue;
                }
                if let Some((child, _)) = rest.split_once('/') {
                    entries
                        .entry(child.to_string())
                        .or_insert_with(|| BrowserEntry {
                            name: child.to_string(),
                            identity: Self::child_path(&current, child),
                            is_dir: true,
                            size: None,
                            modified: None,
                        });
                } else if is_model {
                    let name = format!("{rest}{MODEL_EXT}");
                    let lower = name.to_ascii_lowercase();
                    if wanted.is_empty()
                        || wanted
                            .iter()
                            .any(|extension| lower.ends_with(&format!(".{extension}")))
                    {
                        // Size = the mirrored JSON's byte length. `modified` stays
                        // None: the key space carries values, not timestamps.
                        entries.insert(
                            name.clone(),
                            BrowserEntry {
                                name,
                                identity: Self::virtual_model_path(item),
                                is_dir: false,
                                size: Some(value.len() as u64),
                                modified: None,
                            },
                        );
                    }
                } else {
                    entries
                        .entry(rest.to_string())
                        .or_insert_with(|| BrowserEntry {
                            name: rest.to_string(),
                            identity: Self::child_path(&current, rest),
                            is_dir: true,
                            size: None,
                            modified: None,
                        });
                }
            }
            let mut entries: Vec<_> = entries.into_values().collect();
            entries.sort_by(|a, b| b.is_dir.cmp(&a.is_dir).then_with(|| a.name.cmp(&b.name)));
            entries
        }

        fn browser_enter(&self, identity: &str) -> Result<(), String> {
            if identity == "/models" || identity.starts_with("/models/") {
                *self.browser_dir.borrow_mut() = identity.trim_end_matches('/').to_string();
                Ok(())
            } else {
                Err("the browser virtual filesystem is rooted at /models".into())
            }
        }

        fn browser_up(&self) -> Result<(), String> {
            let current = self.browser_dir.borrow().clone();
            if current == "/" {
                return Ok(());
            }
            let parent = current
                .rsplit_once('/')
                .map(|(parent, _)| parent)
                .unwrap_or("");
            *self.browser_dir.borrow_mut() = if parent.is_empty() {
                "/".into()
            } else {
                parent.into()
            };
            Ok(())
        }

        fn browser_home(&self) -> Result<(), String> {
            *self.browser_dir.borrow_mut() = "/models".into();
            Ok(())
        }

        fn browser_root(&self) -> Result<(), String> {
            *self.browser_dir.borrow_mut() = "/".into();
            Ok(())
        }

        fn browser_navigate(&self, location: &str) -> Result<(), String> {
            let loc = location.trim_end_matches('/');
            let loc = if loc.is_empty() { "/" } else { loc };
            if loc == "/" || loc == "/models" || loc.starts_with("/models/") {
                *self.browser_dir.borrow_mut() = loc.to_string();
                Ok(())
            } else {
                Err("the browser virtual filesystem is rooted at /models".into())
            }
        }

        fn browser_places(&self) -> Vec<BrowserPlace> {
            vec![
                BrowserPlace {
                    label: "Models".into(),
                    location: "/models".into(),
                    kind: PlaceKind::Models,
                },
                BrowserPlace {
                    label: "/".into(),
                    location: "/".into(),
                    kind: PlaceKind::Root,
                },
            ]
        }

        fn browser_create_dir(&self, name: &str) -> Result<(), String> {
            if name.is_empty()
                || name == "."
                || name == ".."
                || name.contains('/')
                || name.contains('\\')
            {
                return Err("folder name must be one path component".into());
            }
            let current = self.browser_dir.borrow().clone();
            if !current.starts_with("/models") {
                return Err("folders can only be created under /models".into());
            }
            let relative = Self::child_path(&current, name)
                .trim_start_matches("/models/")
                .to_string();
            // A folder is a zero-length marker key; the explorer derives the tree
            // from the key prefixes alone.
            let key = format!("{DIR_PREFIX}{relative}/");
            self.entries.borrow_mut().insert(key.clone(), String::new());
            self.push(name, self.backend.put(&key, ""));
            Ok(())
        }

        fn browser_write(&self, name: &str, contents: &str) -> Result<String, String> {
            let file = model_display_name(name);
            if file.is_empty() {
                return Err("invalid file name".into());
            }
            let current = self.browser_dir.borrow().clone();
            if !current.starts_with("/models") {
                return Err("select a folder under /models".into());
            }
            let identity = format!("{}{MODEL_EXT}", Self::child_path(&current, &file));
            self.write(&identity, contents)?;
            Ok(identity)
        }
    }
}

// --- Browser: IndexedDB documents + download / upload interchange --------------
#[cfg(target_arch = "wasm32")]
mod web_model {
    use super::mirror_store::{BackendFuture, MirrorStore, StoreBackend, UnavailableBackend};
    use super::{
        model_display_name, BrowserEntry, BrowserPlace, ImportedFile, ModelStore, MODEL_EXT,
    };
    use std::cell::RefCell;
    use std::future::Future;
    use std::pin::Pin;
    use std::rc::Rc;
    use std::task::{Context, Poll, Waker};
    use wasm_bindgen::prelude::*;
    use wasm_bindgen::JsCast;

    // The origin-private persistent store on the web is **IndexedDB**. It replaced
    // `localStorage`, whose ~5-10 MB per-origin quota cannot hold a single native
    // BREP payload (a measured STEP import: ~35 MB), and it is the only browser
    // store that is both large and enumerable without a permission gesture (unlike
    // the File System Access API, which fails headless). Its API is ASYNC, hence
    // the mirror in [`mirror_store`](super::mirror_store); the key scheme is the
    // localStorage one, byte for byte. **Download + upload** below still bridge to
    // the user's REAL filesystem for portability.
    const DB_NAME: &str = "brep-app";
    const DB_VERSION: u32 = 1;
    /// The single key/value object store; keys are the `brep-app:*` strings.
    const STORE_NAME: &str = "kv";

    thread_local! {
        /// The single hidden `<input type=file>`, created once and reused.
        static IMPORT_INPUT: RefCell<Option<web_sys::HtmlInputElement>> = const { RefCell::new(None) };
        /// The most recent completed upload, awaiting the panel's poll.
        static IMPORTED: RefCell<Option<ImportedFile>> = const { RefCell::new(None) };
        /// The egui context, so an ASYNC callback (a `FileReader` load, a failed
        /// IndexedDB write) can wake the reactive eframe loop (the app only
        /// repaints on input events + explicit requests). Without it a completed
        /// upload — or a "your model did not save" notice — sits unshown until the
        /// user happens to move the mouse. Seeded once at boot via [`set_repaint_ctx`].
        static REPAINT_CTX: RefCell<Option<eframe::egui::Context>> = const { RefCell::new(None) };
        /// The store built by [`hydrate`] inside the async wasm entry point,
        /// waiting for `BrepApp::new` to pick it up through
        /// [`default_model_store`](super::default_model_store). The hand-off is a
        /// thread-local rather than a closure capture so the app constructor keeps
        /// its platform-free signature.
        static BOOT_STORE: RefCell<Option<IdbModelStore>> = const { RefCell::new(None) };
    }

    /// Register the egui context used to wake the frame loop when an async browser
    /// upload — or a write-behind persistence failure — completes. Called once from
    /// the app shell at construction.
    pub fn set_repaint_ctx(ctx: eframe::egui::Context) {
        REPAINT_CTX.with(|c| *c.borrow_mut() = Some(ctx));
    }

    /// Ask the reactive frame loop for a repaint. Reads `REPAINT_CTX` at CALL time,
    /// so it does not matter that the store is built (during boot) before the app
    /// shell registers the context.
    fn wake_frame_loop() {
        REPAINT_CTX.with(|c| {
            if let Some(ctx) = c.borrow().as_ref() {
                ctx.request_repaint();
            }
        });
    }

    // --- IndexedDB request/transaction -> Future ----------------------------------
    // Hand-rolled rather than pulling `indexed_db_futures`: this crate deliberately
    // keeps its wasm dependency tree thin (see the `ehttp` note in Cargo.toml about
    // the `getrandom` dep-tree problem), and the whole adapter is the ~60 lines
    // below. It owns its `Closure`s — dropping the future clears the handlers — so
    // a session of saves does not leak a pair of JS closures per write, which a
    // `Closure::forget()` sketch would.

    #[derive(Default)]
    struct Settled {
        outcome: Option<Result<JsValue, String>>,
        waker: Option<Waker>,
    }

    /// Which DOM event pair the future is listening to. Kept so `Drop` can detach
    /// the handlers (and with them the Rust closures' reference back to the target).
    enum EventSource {
        Request(web_sys::IdbRequest),
        Transaction(web_sys::IdbTransaction),
    }

    /// One IndexedDB completion, as a `Future`.
    struct IdbFuture {
        source: EventSource,
        settled: Rc<RefCell<Settled>>,
        /// Owned so the closures live exactly as long as the future.
        _handlers: Vec<Closure<dyn FnMut(web_sys::Event)>>,
    }

    fn settle(settled: &Rc<RefCell<Settled>>, outcome: Result<JsValue, String>) {
        let waker = {
            let mut settled = settled.borrow_mut();
            if settled.outcome.is_none() {
                settled.outcome = Some(outcome);
            }
            settled.waker.take()
        };
        if let Some(waker) = waker {
            waker.wake();
        }
    }

    fn request_error(request: &web_sys::IdbRequest) -> String {
        request
            .error()
            .ok()
            .flatten()
            .map(|error| format!("{}: {}", error.name(), error.message()))
            .unwrap_or_else(|| "IndexedDB request failed".into())
    }

    fn js_error(value: &JsValue) -> String {
        value
            .as_string()
            .or_else(|| js_sys::Reflect::get(value, &JsValue::from_str("message")).ok()?.as_string())
            .unwrap_or_else(|| format!("{value:?}"))
    }

    /// Resolve when `request` succeeds, with its `result`.
    fn on_request(request: web_sys::IdbRequest) -> IdbFuture {
        let settled = Rc::new(RefCell::new(Settled::default()));
        let success = {
            let settled = settled.clone();
            let request = request.clone();
            Closure::wrap(Box::new(move |_event: web_sys::Event| {
                let value = request.result().unwrap_or(JsValue::UNDEFINED);
                settle(&settled, Ok(value));
            }) as Box<dyn FnMut(web_sys::Event)>)
        };
        let failure = {
            let settled = settled.clone();
            let request = request.clone();
            Closure::wrap(Box::new(move |_event: web_sys::Event| {
                settle(&settled, Err(request_error(&request)));
            }) as Box<dyn FnMut(web_sys::Event)>)
        };
        request.set_onsuccess(Some(success.as_ref().unchecked_ref()));
        request.set_onerror(Some(failure.as_ref().unchecked_ref()));
        IdbFuture {
            source: EventSource::Request(request),
            settled,
            _handlers: vec![success, failure],
        }
    }

    /// Resolve when `transaction` COMMITS.
    ///
    /// A write must be awaited here, not on the `put` request's `onsuccess`: the
    /// request succeeds before the transaction commits, and a page reload can abort
    /// an uncommitted `readwrite` transaction. For a multi-megabyte payload that
    /// window is real, and "the save is durable" is exactly the claim the pending
    /// counter and the reload test rest on.
    fn on_transaction(transaction: web_sys::IdbTransaction) -> IdbFuture {
        let settled = Rc::new(RefCell::new(Settled::default()));
        let complete = {
            let settled = settled.clone();
            Closure::wrap(Box::new(move |_event: web_sys::Event| {
                settle(&settled, Ok(JsValue::UNDEFINED));
            }) as Box<dyn FnMut(web_sys::Event)>)
        };
        let describe = {
            let transaction = transaction.clone();
            move |fallback: &str| {
                transaction
                    .error()
                    .map(|error| format!("{}: {}", error.name(), error.message()))
                    .unwrap_or_else(|| fallback.to_string())
            }
        };
        let failure = {
            let settled = settled.clone();
            let describe = describe.clone();
            Closure::wrap(Box::new(move |_event: web_sys::Event| {
                settle(&settled, Err(describe("IndexedDB transaction failed")));
            }) as Box<dyn FnMut(web_sys::Event)>)
        };
        let abort = {
            let settled = settled.clone();
            Closure::wrap(Box::new(move |_event: web_sys::Event| {
                settle(
                    &settled,
                    Err(describe("IndexedDB transaction aborted (quota?)")),
                );
            }) as Box<dyn FnMut(web_sys::Event)>)
        };
        transaction.set_oncomplete(Some(complete.as_ref().unchecked_ref()));
        transaction.set_onerror(Some(failure.as_ref().unchecked_ref()));
        transaction.set_onabort(Some(abort.as_ref().unchecked_ref()));
        IdbFuture {
            source: EventSource::Transaction(transaction),
            settled,
            _handlers: vec![complete, failure, abort],
        }
    }

    impl Future for IdbFuture {
        type Output = Result<JsValue, String>;

        fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
            let mut settled = self.settled.borrow_mut();
            if let Some(outcome) = settled.outcome.take() {
                return Poll::Ready(outcome);
            }
            settled.waker = Some(cx.waker().clone());
            Poll::Pending
        }
    }

    impl Drop for IdbFuture {
        fn drop(&mut self) {
            // Detach the handlers, breaking the target -> closure -> target cycle
            // so the closures we own are actually freed.
            match &self.source {
                EventSource::Request(request) => {
                    request.set_onsuccess(None);
                    request.set_onerror(None);
                }
                EventSource::Transaction(transaction) => {
                    transaction.set_oncomplete(None);
                    transaction.set_onerror(None);
                    transaction.set_onabort(None);
                }
            }
        }
    }

    // --- the IndexedDB backend -----------------------------------------------------

    /// [`StoreBackend`] over one IndexedDB object store. The ONLY place in the
    /// crate that knows what IndexedDB is.
    pub(super) struct IdbBackend {
        db: web_sys::IdbDatabase,
    }

    impl IdbBackend {
        /// Open (creating on first use) the application database. `Err` on any
        /// browser that blocks storage — private windows, "block all cookies"
        /// setups — which the caller turns into a loud, non-persisting session.
        async fn open() -> Result<Self, String> {
            let factory = web_sys::window()
                .ok_or("no window")?
                .indexed_db()
                .map_err(|e| js_error(&e))?
                .ok_or("no indexedDB on this window")?;
            let request = factory
                .open_with_u32(DB_NAME, DB_VERSION)
                .map_err(|e| js_error(&e))?;

            // Create the object store on first open / version bump. The request is
            // captured directly (rather than read off the event target) so no
            // `EventTarget` binding is needed.
            let upgrading = request.clone();
            let upgrade = Closure::wrap(Box::new(move |_event: web_sys::Event| {
                if let Ok(value) = upgrading.result() {
                    if let Ok(db) = value.dyn_into::<web_sys::IdbDatabase>() {
                        // Errors here mean the store already exists — harmless.
                        let _ = db.create_object_store(STORE_NAME);
                    }
                }
            }) as Box<dyn FnMut(web_sys::Event)>);
            request.set_onupgradeneeded(Some(upgrade.as_ref().unchecked_ref()));

            let opened = on_request(request.clone().unchecked_into::<web_sys::IdbRequest>()).await;
            request.set_onupgradeneeded(None);
            drop(upgrade);

            let db = opened?
                .dyn_into::<web_sys::IdbDatabase>()
                .map_err(|_| "IndexedDB open returned no database".to_string())?;
            Ok(Self { db })
        }

        /// Start a transaction and reach its object store. The transaction handle
        /// is returned so a write can await its COMMIT.
        fn transact(
            &self,
            mode: web_sys::IdbTransactionMode,
        ) -> Result<(web_sys::IdbTransaction, web_sys::IdbObjectStore), String> {
            let transaction = self
                .db
                .transaction_with_str_and_mode(STORE_NAME, mode)
                .map_err(|e| js_error(&e))?;
            let store = transaction.object_store(STORE_NAME).map_err(|e| js_error(&e))?;
            Ok((transaction, store))
        }
    }

    impl StoreBackend for IdbBackend {
        fn label(&self) -> String {
            "browser storage (IndexedDB) · download/upload for files".into()
        }

        fn load_all(&self) -> BackendFuture<Vec<(String, String)>> {
            // Two whole-store requests in ONE readonly transaction rather than a
            // cursor: `getAllKeys` and `getAll` both come back in key order, so
            // zipping them reconstructs the key space in one round trip each.
            let started = (|| -> Result<(IdbFuture, IdbFuture), String> {
                let (_transaction, store) = self.transact(web_sys::IdbTransactionMode::Readonly)?;
                let keys = store.get_all_keys().map_err(|e| js_error(&e))?;
                let values = store.get_all().map_err(|e| js_error(&e))?;
                Ok((on_request(keys), on_request(values)))
            })();
            Box::pin(async move {
                let (keys, values) = started?;
                let keys = js_sys::Array::from(&keys.await?);
                let values = js_sys::Array::from(&values.await?);
                if keys.length() != values.length() {
                    return Err("IndexedDB returned mismatched keys and values".into());
                }
                let mut entries = Vec::with_capacity(keys.length() as usize);
                for i in 0..keys.length() {
                    let (Some(key), Some(value)) =
                        (keys.get(i).as_string(), values.get(i).as_string())
                    else {
                        // A non-string entry is not ours; skipping it is safer than
                        // failing the whole hydrate.
                        continue;
                    };
                    entries.push((key, value));
                }
                Ok(entries)
            })
        }

        fn put(&self, key: &str, value: &str) -> BackendFuture<()> {
            // The transaction is created and the request issued SYNCHRONOUSLY, so
            // two writes of the same key commit in call order (IndexedDB commits
            // `readwrite` transactions in creation order) no matter how the futures
            // are later polled — the per-key FIFO obligation in `StoreBackend`.
            let started = (|| -> Result<IdbFuture, String> {
                let (transaction, store) =
                    self.transact(web_sys::IdbTransactionMode::Readwrite)?;
                store
                    .put_with_key(&JsValue::from_str(value), &JsValue::from_str(key))
                    .map_err(|e| js_error(&e))?;
                Ok(on_transaction(transaction))
            })();
            Box::pin(async move {
                started?.await?;
                Ok(())
            })
        }

        fn delete(&self, key: &str) -> BackendFuture<()> {
            let started = (|| -> Result<IdbFuture, String> {
                let (transaction, store) =
                    self.transact(web_sys::IdbTransactionMode::Readwrite)?;
                store
                    .delete(&JsValue::from_str(key))
                    .map_err(|e| js_error(&e))?;
                Ok(on_transaction(transaction))
            })();
            Box::pin(async move {
                started?.await?;
                Ok(())
            })
        }
    }

    // --- boot ----------------------------------------------------------------------

    /// Bring up browser persistence and hydrate the whole key space into memory.
    ///
    /// Called from the async wasm entry point BEFORE `eframe::WebRunner::start`, so
    /// by the time any synchronous [`ModelStore::read`] can run, the mirror is
    /// complete — that ordering is the entire reason the trait stays synchronous.
    ///
    /// On failure there is NO quiet fallback: the session gets an
    /// [`UnavailableBackend`], which keeps the app usable in memory while saying so
    /// in the panel header and toasting every write that does not persist.
    pub(super) async fn hydrate() {
        let wake: Rc<dyn Fn()> = Rc::new(wake_frame_loop);
        let core = match IdbBackend::open().await {
            Ok(backend) => {
                let backend: Rc<dyn StoreBackend> = Rc::new(backend);
                match backend.load_all().await {
                    Ok(entries) => MirrorStore::new(backend, entries, Some(wake)),
                    // The database opened but would not read. Writing against a
                    // half-known key space could overwrite documents the mirror
                    // never saw, so treat it as unavailable rather than risk that.
                    Err(message) => unavailable(
                        format!("IndexedDB could not be read ({message})"),
                        Some(wake),
                    ),
                }
            }
            Err(message) => unavailable(format!("IndexedDB unavailable ({message})"), Some(wake)),
        };
        install_verification_hooks(&core);
        BOOT_STORE.with(|c| *c.borrow_mut() = Some(IdbModelStore { core }));
    }

    /// A session with no persistence: empty, in-memory, and loud about it.
    fn unavailable(reason: String, wake: Option<Rc<dyn Fn()>>) -> MirrorStore {
        let core = MirrorStore::new(
            Rc::new(UnavailableBackend::new(reason.clone())),
            Vec::new(),
            wake,
        );
        // Seed the notice channel so the FIRST frame tells the user, before they
        // have saved anything and discovered it the hard way.
        core.report(format!(
            "{reason} — this session will not be saved; use Download to keep your work"
        ));
        core
    }

    /// Hand the hydrated store to `BrepApp::new`. If boot never ran (no code path
    /// does that today), the app still starts — non-persisting and saying so.
    pub(super) fn take_boot_store() -> Box<dyn ModelStore> {
        let store = BOOT_STORE.with(|c| c.borrow_mut().take()).unwrap_or_else(|| {
            let wake: Rc<dyn Fn()> = Rc::new(wake_frame_loop);
            IdbModelStore {
                core: unavailable("storage was never initialised".into(), Some(wake)),
            }
        });
        Box::new(store)
    }

    // --- verification hooks ---------------------------------------------------------

    /// Publish `window.__brepStore*` handles onto the LIVE store, in the same
    /// spirit as the app shell's `__brep*` state globals: the headed verifier needs
    /// to write a payload far larger than any UI gesture can type, then prove it
    /// survived a reload. `__brepStorePending` is what makes that check non-racy —
    /// it reaches zero only once the backing transaction has COMMITTED.
    /// `__brepStoreRead` is the read side of the same seam: a script that saves
    /// through the UI has to be able to look at what landed.
    fn install_verification_hooks(core: &MirrorStore) {
        let Some(window) = web_sys::window() else {
            return;
        };
        let publish = |name: &str, value: &JsValue| {
            let _ = js_sys::Reflect::set(&window, &JsValue::from_str(name), value);
        };

        let store = core.clone();
        let write = Closure::wrap(Box::new(move |name: String, contents: String| -> JsValue {
            match store.write(&name, &contents) {
                Ok(()) => JsValue::NULL,
                Err(message) => JsValue::from_str(&message),
            }
        }) as Box<dyn FnMut(String, String) -> JsValue>);
        publish("__brepStoreWrite", write.as_ref());
        write.forget();

        let store = core.clone();
        let len = Closure::wrap(Box::new(move |name: String| -> f64 {
            store.len_of(&name).map(|n| n as f64).unwrap_or(-1.0)
        }) as Box<dyn FnMut(String) -> f64>);
        publish("__brepStoreLen", len.as_ref());
        len.forget();

        // The READ sibling of `__brepStoreWrite`. Without it a headed script can
        // only prove a save happened, not WHAT was saved: the assemblies sweep
        // used to read the document straight out of `localStorage`, which the
        // IndexedDB migration silently emptied.
        let store = core.clone();
        let read = Closure::wrap(Box::new(move |name: String| -> JsValue {
            match store.read(&name) {
                Some(contents) => JsValue::from_str(&contents),
                None => JsValue::NULL,
            }
        }) as Box<dyn FnMut(String) -> JsValue>);
        publish("__brepStoreRead", read.as_ref());
        read.forget();

        let store = core.clone();
        let list = Closure::wrap(Box::new(move || -> JsValue {
            JsValue::from_str(&serde_json::to_string(&store.list()).unwrap_or_default())
        }) as Box<dyn FnMut() -> JsValue>);
        publish("__brepStoreList", list.as_ref());
        list.forget();

        let store = core.clone();
        let errors = Closure::wrap(Box::new(move || -> JsValue {
            JsValue::from_str(&serde_json::to_string(&store.error_history()).unwrap_or_default())
        }) as Box<dyn FnMut() -> JsValue>);
        publish("__brepStoreErrors", errors.as_ref());
        errors.forget();

        let store = core.clone();
        let pending = Closure::wrap(Box::new(move || -> f64 { store.pending() as f64 })
            as Box<dyn FnMut() -> f64>);
        publish("__brepStorePending", pending.as_ref());
        pending.forget();
    }

    // --- real-file interchange (download / upload) ----------------------------------
    // Free functions, not methods: they are pure browser plumbing with no store
    // state, and keeping them out of the store type leaves `IdbModelStore` as a
    // thin seam between the mirror and this lane.

    /// Lazily create the reusable hidden file input, wiring its `change` handler
    /// (which reads the chosen file and stashes it for `take_import`). `accept` is
    /// (re)applied every call so the picker's filter matches the current lane (the
    /// `.BREP.json` model lane vs. a `.step` import lane).
    fn ensure_input(accept: &str) -> Option<web_sys::HtmlInputElement> {
        if let Some(existing) = IMPORT_INPUT.with(|c| c.borrow().clone()) {
            existing.set_accept(accept);
            return Some(existing);
        }
        let document = web_sys::window()?.document()?;
        let input: web_sys::HtmlInputElement =
            document.create_element("input").ok()?.dyn_into().ok()?;
        input.set_type("file");
        input.set_accept(accept);
        input.set_hidden(true);

        // Read bytes so binary STL is not corrupted at the browser boundary.
        let input_for_cb = input.clone();
        let onchange = Closure::wrap(Box::new(move |_e: web_sys::Event| {
            let Some(files) = input_for_cb.files() else { return };
            let Some(file) = files.get(0) else { return };
            let name = file.name();
            let Ok(reader) = web_sys::FileReader::new() else { return };
            let reader_for_load = reader.clone();
            let onload = Closure::wrap(Box::new(move |_e: web_sys::Event| {
                if let Ok(value) = reader_for_load.result() {
                    let bytes = js_sys::Uint8Array::new(&value).to_vec();
                    IMPORTED.with(|c| *c.borrow_mut() = Some(ImportedFile {
                        name: model_display_name(&name),
                        bytes,
                    }));
                    // Wake the reactive frame loop so the file panel polls
                    // `take_import` THIS frame, not on the next stray input event.
                    wake_frame_loop();
                }
            }) as Box<dyn FnMut(web_sys::Event)>);
            reader.set_onload(Some(onload.as_ref().unchecked_ref()));
            // One small per-import leak (the app runs for the page lifetime).
            onload.forget();
            let _ = reader.read_as_array_buffer(&file);
        }) as Box<dyn FnMut(web_sys::Event)>);
        input.set_onchange(Some(onchange.as_ref().unchecked_ref()));
        onchange.forget(); // created once — leak is bounded

        if let Some(body) = document.body() {
            let _ = body.append_child(&input);
        }
        IMPORT_INPUT.with(|c| *c.borrow_mut() = Some(input.clone()));
        Some(input)
    }

    /// Offer `contents` to the user as a download named EXACTLY `file_name`, via a
    /// Blob object-URL + a synthetic anchor click.
    fn download(file_name: &str, mime: &str, contents: &str) -> Result<(), String> {
        let document = web_sys::window()
            .and_then(|w| w.document())
            .ok_or("no document")?;
        let parts = js_sys::Array::of1(&JsValue::from_str(contents));
        let options = web_sys::BlobPropertyBag::new();
        options.set_type(mime);
        let blob = web_sys::Blob::new_with_str_sequence_and_options(&parts, &options)
            .map_err(|_| "blob create failed".to_string())?;
        let url = web_sys::Url::create_object_url_with_blob(&blob)
            .map_err(|_| "object url failed".to_string())?;
        let anchor: web_sys::HtmlAnchorElement = document
            .create_element("a")
            .map_err(|_| "anchor create failed".to_string())?
            .dyn_into()
            .map_err(|_| "anchor cast failed".to_string())?;
        anchor.set_href(&url);
        anchor.set_download(file_name);
        anchor.click();
        let _ = web_sys::Url::revoke_object_url(&url);
        Ok(())
    }

    /// The browser model store: the mirrored key space (which owns every CRUD and
    /// explorer method) plus this platform's real-file interchange lane.
    pub(super) struct IdbModelStore {
        core: MirrorStore,
    }

    impl ModelStore for IdbModelStore {
        // --- delegated to the mirror ------------------------------------------
        fn backend_label(&self) -> String {
            self.core.backend_label()
        }
        fn list(&self) -> Vec<String> {
            self.core.list()
        }
        fn read(&self, name: &str) -> Option<String> {
            self.core.read(name)
        }
        fn write(&self, name: &str, contents: &str) -> Result<(), String> {
            self.core.write(name, contents)
        }
        fn remove(&self, name: &str) -> Result<(), String> {
            self.core.remove(name)
        }
        fn take_persistence_errors(&self) -> Vec<String> {
            self.core.take_persistence_errors()
        }
        fn browser_location(&self) -> String {
            self.core.browser_location()
        }
        fn browser_entries(&self, extensions: &[&str]) -> Vec<BrowserEntry> {
            self.core.browser_entries(extensions)
        }
        fn browser_enter(&self, identity: &str) -> Result<(), String> {
            self.core.browser_enter(identity)
        }
        fn browser_up(&self) -> Result<(), String> {
            self.core.browser_up()
        }
        fn browser_home(&self) -> Result<(), String> {
            self.core.browser_home()
        }
        fn browser_root(&self) -> Result<(), String> {
            self.core.browser_root()
        }
        fn browser_navigate(&self, location: &str) -> Result<(), String> {
            self.core.browser_navigate(location)
        }
        fn browser_places(&self) -> Vec<BrowserPlace> {
            self.core.browser_places()
        }
        fn browser_create_dir(&self, name: &str) -> Result<(), String> {
            self.core.browser_create_dir(name)
        }
        fn browser_write(&self, name: &str, contents: &str) -> Result<String, String> {
            self.core.browser_write(name, contents)
        }

        // --- the browser's real-file lane -------------------------------------
        fn supports_file_interchange(&self) -> bool {
            true
        }

        /// Offer the document as a `<name>.BREP.json` download. The returned
        /// identity is the bare name (the browser owns where the download lands).
        fn export_file(&self, name: &str, contents: &str) -> Result<Option<String>, String> {
            let name = model_display_name(name);
            download(&format!("{name}{MODEL_EXT}"), "application/json", contents)?;
            Ok(Some(name))
        }

        fn begin_import(&self) -> Result<(), String> {
            let input =
                ensure_input(".json,.BREP.json,application/json").ok_or("file input unavailable")?;
            // Clear so re-selecting the same file still fires `change`.
            input.set_value("");
            input.click();
            Ok(())
        }

        fn take_import(&self) -> Option<ImportedFile> {
            IMPORTED.with(|c| c.borrow_mut().take())
        }

        // Format-typed interchange: the same hidden input, refiltered to the
        // requested extensions. The onchange handler stashes the file's real name
        // (its extension survives `model_display_name`, since that only strips
        // `.json` / `.BREP.json`), so the panel routes STEP imports by extension.
        fn begin_import_filtered(&self, filter: (&str, &[&str])) -> Result<(), String> {
            let accept = filter
                .1
                .iter()
                .map(|ext| format!(".{ext}"))
                .collect::<Vec<_>>()
                .join(",");
            let input = ensure_input(&accept).ok_or("file input unavailable")?;
            input.set_value("");
            input.click();
            Ok(())
        }

        /// Offer `contents` as a download under EXACTLY `file_name` (extension
        /// kept) — the foreign-format sibling of [`Self::export_file`].
        fn export_file_named(&self, file_name: &str, contents: &str) -> Result<(), String> {
            download(file_name, "application/octet-stream", contents)
        }
    }
}


// BREP private tests: 0516c3c4f5aa076b

// BREP private tests: 69df063b576f11cb