brep_render/engine_state/

history_ops.rs

use super::*;

// --- Scene feed (R10) -------------------------------------------------

impl EngineState {
    /// Run a whole history and reconcile the display scene (R10 incremental):
    /// reused solids keep their buffers, the rest re-tessellate. `overrides_json`
    /// is an optional `{name: "#rrggbb"}` metadata-color map. Returns the build
    /// report JSON (`{featureErrors, unresolved, displayErrors}`). Marks dirty.
    pub fn run_history_json(
        &mut self,
        request_json: &str,
        overrides_json: Option<&str>,
    ) -> Result<String, String> {
        let request: HistoryRequest = serde_json::from_str(request_json)
            .map_err(|error| format!("history request parse: {error}"))?;
        let overrides = overrides_json
            .map(parse_color_overrides)
            .transpose()?
            .unwrap_or_default();
        let report = crate::pipeline::update_scene_from_history(
            &mut self.scene,
            &request,
            Some(&overrides),
        )?;
        self.dirty = true;
        Ok(serde_json::json!({
            "featureErrors": report.feature_errors,
            "unresolved": report.unresolved,
            "displayErrors": report.display_errors,
        })
        .to_string())
    }

    // --- Engine-owned history (roll-to-step + edit + add/delete/reorder) ---
    //
    // The editable model recipe lives HERE (`self.history`) — the UI keeps no
    // copy of it. It edits + reads the model exclusively through these methods,
    // so the history is UI-agnostic and converges with the "whole history in
    // Rust" pipeline migration.

    /// (Re)run the current rolled-to prefix of the engine's history through the
    /// SAME kernel pipeline and reconcile the display scene. Stores + returns the
    /// build report JSON.
    pub(super) fn rerun_history(&mut self) -> String {
        // Roll-to-step re-runs a TRUNCATED prefix each time and RELIES on the
        // kernel's incremental history cache so an unchanged upstream prefix (a
        // heavy STEP import + primitives) replays instantly (`reused`, timing 0.0)
        // instead of cold re-executing — that is what makes rollback/edit feel
        // instant. The cache is NOT cleared here.
        //
        // Correctness of rolling BEFORE a boolean that consumed its target: a
        // consumed input handle is freed exactly when its PRODUCING cache entry is
        // invalidated (`free_entry`), never by a downstream consumer — a boolean
        // clones its inputs and frees only its own intermediates (verified across
        // boolean/transform/hole/pattern/…). So the box's handle is still resident
        // and rolling to it shows the box, not a freed/re-used handle. Regression
        // guard: `history_cache_rollback_tests`. A wholesale document switch
        // (`set_history_json`) still clears the cache — the roll/edit hot path does
        // NOT.
        //
        // The M2a seam: SUBMIT the history run tagged with a monotonic generation,
        // then `pump` drains its completed reply and APPLIES the delta. For the
        // synchronous [`InlineRunner`](crate::runner::InlineRunner) the submit runs
        // immediately and `pump` applies it in THIS call, so behavior stays
        // byte-identical to the pre-seam in-place reconcile; a later milestone makes
        // the runner a background thread/worker whose reply `pump` applies a frame
        // later (the per-frame `pump` in the app drives that path).
        let request_value = self.history.prefix_request();
        match serde_json::from_value::<HistoryRequest>(request_value) {
            Ok(mut request) => {
                // Carry the live display LOD to the runner (the request is the run
                // boundary the thread/worker receives). The runner re-tessellates
                // every resident mesh when this differs from its last run's lod.
                request.display_lod = self.settings.lod_factor;
                self.run_generation += 1;
                // The PARTS-LIBRARY CHANNEL. A background runner (native
                // thread / browser worker) owns its own kernel store, so it
                // needs the library — but sending it WITH every run meant
                // stringifying every embedded part payload on the UI thread
                // for every edit, which froze the browser on an imported STEP
                // assembly. It is sent only when it CHANGES; `fetch` does not
                // run in the steady state. Inline shares this thread's store
                // and no-ops.
                self.runner.sync_parts_library(
                    brep_kernel::parts_library_revision(),
                    &mut brep_kernel::parts_library_map,
                );
                self.runner.submit_run(request, self.run_generation);
            }
            // A parse failure runs nothing: clear the surfaced frames/profiles (so
            // stale construction geometry does not linger — the scene keeps its
            // previous solids) and set an error report, then run the shared
            // post-apply tail synchronously (no kernel work), so this branch shares
            // the dirty/gizmo/overlay continuation verbatim with a real apply.
            Err(error) => {
                self.construction_frames.clear();
                self.sketch_profiles.clear();
                self.sketch_paths.clear();
                self.sketch_axes.clear();
                self.finish_apply(
                    serde_json::json!({ "error": format!("history request: {error}") }).to_string(),
                );
            }
        }
        // Inline applies the submitted run NOW; a thread impl would defer it to a
        // later frame's `pump`. Either way `history_report` is fresh once the reply
        // is applied — for Inline that is before this call returns.
        self.pump();
        self.history_report.clone()
    }

    /// Drain every completed run reply and APPLY it — the POLL/APPLY half of the
    /// M2a seam. Called from [`rerun_history`](Self::rerun_history) for the Inline
    /// runner's immediate apply, and once per frame from the app so a future async
    /// runner's completed runs land on the main thread. A reply older than
    /// [`applied_generation`](Self::applied_generation) (a newer run that finished
    /// first) is dropped.
    pub fn pump(&mut self) {
        // The runner REFUSED a run because its resident parts library could not
        // serve it (see `Reply::NeedPartsLibrary`). It has already forgotten
        // its copy, so re-running re-installs the library and re-submits. This
        // is a real path, not just a tripwire: the kernel's orphan GC drops
        // entries at the end of every run, so an undo to zero components empties
        // the RUNNER's store while this side's (which never ran) keeps
        // everything — no revision bookkeeping can see that, only the runner's
        // content preflight can. `library_resync` breaks the rerun→pump→rerun
        // recursion (the reinstall makes the second attempt succeed, but a
        // guard beats relying on that). The guard is tested FIRST because
        // `poll_library_request` CONSUMES the flag — polling it while a resync
        // is already in flight would swallow a second refusal.
        if !self.library_resync && self.runner.poll_library_request() {
            self.library_resync = true;
            self.rerun_history();
            self.library_resync = false;
        }
        while let Some(reply) = self.runner.poll_mesh_import() {
            // A document switch clears this set. Ignore any older reconstruction
            // reply that was already running when its Reset crossed the queue.
            if !self.pending_mesh_imports.remove(&reply.id) {
                continue;
            }
            match reply.result {
                Ok(step_text) => match self.import_step_feature(&step_text) {
                    Ok(_) => self.push_notice(
                        "RANSAC reconstruction complete; building imported CAD body",
                    ),
                    Err(error) => self.push_notice(format!("mesh import failed: {error}")),
                },
                Err(error) => self.push_notice(format!("mesh import failed: {error}")),
            }
        }
        while let Some(reply) = self.runner.poll_run() {
            if reply.generation >= self.applied_generation {
                self.applied_generation = reply.generation;
                self.apply_run_output(reply.output);
            }
        }
        // Deferred one-shot framing (Import / Open): frame the scene the moment the
        // run they submitted has fully landed. Consumed unconditionally once the run
        // is no longer pending — even when it produced no solids (bbox empty →
        // `zoom_to_fit` no-ops) — so a later unrelated run never inherits a stale fit.
        if self.pending_fit && !self.run_pending() {
            self.pending_fit = false;
            self.zoom_to_fit();
        }
        // Drain any completed measurement replies too (a background runner surfaces
        // them a frame after selection); for Inline this is a no-op each frame since
        // `object_info_json` already pumped its own query same-call.
        self.pump_queries();
    }

    /// Whether a measurement query is still in flight (its reply not yet drained) —
    /// the query analogue of [`run_pending`](Self::run_pending), so the app keeps the
    /// frame loop alive until a background runner's measurement lands and displays.
    /// Always `false` for the synchronous Inline runner.
    pub fn queries_pending(&self) -> bool {
        !self.pending_query.is_empty()
    }

    /// Whether RANSAC reconstruction is still executing on the native runner
    /// thread or browser worker.
    pub fn mesh_imports_pending(&self) -> bool {
        !self.pending_mesh_imports.is_empty()
    }

    /// Whether a submitted run has not yet been applied (`run_generation !=
    /// applied_generation`). Always `false` for the synchronous Inline runner
    /// (submit → immediate `pump` keeps the two in lockstep); a background runner
    /// uses it to keep the frame loop alive until its reply lands.
    pub fn run_pending(&self) -> bool {
        self.run_generation != self.applied_generation
    }

    /// The generation of the last APPLIED run — bumps once per applied history
    /// run (document loads, edits, constraint mutations, solves). A cheap
    /// staleness key for app-side caches derived from the applied document
    /// (the update-components outdated badge keys on it).
    pub fn applied_generation(&self) -> u64 {
        self.applied_generation
    }

    /// Whether the display scene currently holds at least one solid. Used by the
    /// app's async-safe first-frame framing: under a background runner (thread /
    /// worker) the seed run lands a frame (or many) after boot, so the shell waits
    /// for `has_solids() && !run_pending()` before its one-shot `zoom_to_fit`.
    pub fn has_solids(&self) -> bool {
        !self.scene.solids().is_empty()
    }

    /// Swap in a different history runner (the platform injects its own — the native
    /// app installs a [`ThreadRunner`](crate::runner::ThreadRunner); wasm keeps the
    /// default Inline until M3's worker). Resets the new runner's delta baseline so
    /// the next run rebuilds fully. Call BEFORE seeding a document so the seed builds
    /// through the installed runner.
    pub fn set_runner(&mut self, runner: Box<dyn crate::runner::HistoryRunner>) {
        self.runner = runner;
        self.runner.reset();
        self.pending_mesh_imports.clear();
    }

    /// Apply a [`SceneRunner`](crate::pipeline::SceneRunner) delta to the display
    /// scene and build the history report JSON — the APPLY half of the M2a seam.
    ///
    /// Reconcile preserving ORDER + reuse: MOVE every current display out of the
    /// scene ([`RenderScene::drain`](crate::scene::RenderScene::drain)) into a
    /// name-keyed `kept` map, then reinsert in snapshot order — a fresh entry
    /// (`Some`) replaces, an UNCHANGED entry (`None`) reuses its moved-out display
    /// (stable `revision` ⇒ GPU-buffer reuse, Task-1; its `source_handle` equals
    /// the run's handle by the monotonic-handle reuse invariant). Leftovers in
    /// `kept` — departed kernel solids AND the previous run's sketch sheets — are
    /// dropped; `refresh_committed_sketches` (run in the shared continuation after)
    /// re-adds the sheets, so dropping them here is correct.
    ///
    /// Then the report continuation (identical to the pre-seam run): keep the run's
    /// resolved frames + solved sketch profiles and fold the per-feature timings /
    /// output-names into the id-keyed report JSON, then hand it to
    /// [`finish_apply`](Self::finish_apply) — the shared dirty/gizmo/overlay tail
    /// that the parse-error branch in [`rerun_history`](Self::rerun_history) also
    /// calls, so both paths share the continuation verbatim.
    fn apply_run_output(&mut self, output: crate::pipeline::RunOutput) {
        let crate::pipeline::RunOutput {
            snapshot,
            report,
            provenance,
            entity_origin,
            assembly_poses,
            assembly_fixed,
            moved_solids,
            imported_colors,
        } = output;
        // The runner already forced fresh displays for the solver-moved solids
        // (their snapshot entries arrive `Some`); nothing extra to do main-side.
        let _ = moved_solids;

        // --- assembly pose-authority fold (build-spec §6 step 4 / §13) --------
        // Adopt the solver's pose / isFixed write-backs into the owning ACOMP
        // features by `inputParams.id` BEFORE anything persists or re-runs this
        // document. Deliberately NOT `update_feature_params`: the fold must not
        // mint an undo entry nor trigger a rerun (rerun → solve → fold → rerun
        // would loop); `fold_param_no_undo` writes the param silently, and the
        // next run's request simply carries the solved pose (a no-motion solve
        // emits no updates, so fingerprints never churn).
        for (id, pose) in assembly_poses {
            self.history.fold_param_no_undo(&id, "transform", pose);
        }
        for (id, fixed) in assembly_fixed {
            self.history
                .fold_param_no_undo(&id, "isFixed", serde_json::Value::Bool(fixed));
        }

        // Adopt the run's eager provenance (SOLID last-writer) + entity origin
        // (face/edge first-writer) wholesale (both drive `creating_feature` + the
        // Info tab's `creatingFeature` with no cold re-run), and INVALIDATE the
        // object-info measurement cache + any in-flight query: the geometry changed,
        // so cached measurements are stale and a pending reply is superseded (a
        // re-selection re-queries against the fresh geometry).
        self.provenance = provenance.into_iter().collect();
        self.entity_origin = entity_origin.into_iter().collect();
        self.info_cache.clear();
        self.pending_query.clear();

        // Fold the run's IMPORTED COLOURS into the engine's own metadata store —
        // the seam between the kernel's (thread-local, never persisted by us)
        // name-keyed store and the one the Info window edits and the document
        // saves. NON-overwriting on purpose: an import re-stamps its colour on
        // every replay, and a colour the user changed in the panel must win.
        for (name, hex) in imported_colors {
            if self.metadata.attribute(&name, "color").is_none() {
                self.metadata.set_attribute(&name, "color", &hex);
            }
        }

        // Reconcile the scene: move current displays out, reinsert in order.
        let mut kept: std::collections::HashMap<String, crate::scene::SolidDisplay> = self
            .scene
            .drain()
            .into_iter()
            .map(|solid| (solid.name.clone(), solid))
            .collect();
        for (name, _handle, maybe) in snapshot {
            match maybe {
                Some(display) => self.scene.insert_solid(display),
                None => self
                    .scene
                    .insert_solid(kept.remove(&name).expect("keep target present")),
            }
        }

        // Keep every plane frame the run resolved (DATUM/PLANE/SKETCH);
        // `refresh_construction_datums` filters to the D/P producers.
        self.construction_frames = report.frames.clone();
        // Keep every solved sketch profile so `refresh_committed_sketches` can
        // synthesize the committed sketch sheet solids.
        self.sketch_profiles = report.profiles.clone();
        // ...and every path chain, so a sketch whose geometry closes NO region (an
        // open chain — the reported single line) still has something to draw.
        self.sketch_paths = report.paths.clone();
        // Keep every axis line the run published so the angle gizmo can resolve a
        // revolve `axis` reference to a world line without re-running.
        self.sketch_axes = report.axes.clone();
        // Fold the per-feature timing / output-name pairs into id-keyed maps so the
        // history-tree UI can look them up by feature id.
        let timings: serde_json::Map<String, serde_json::Value> = report
            .feature_timings
            .iter()
            .map(|(id, ms)| (id.clone(), serde_json::json!(ms)))
            .collect();
        let outputs: serde_json::Map<String, serde_json::Value> = report
            .feature_outputs
            .iter()
            .map(|(id, names)| (id.clone(), serde_json::json!(names)))
            .collect();
        let report_json = serde_json::json!({
            "featureErrors": report.feature_errors,
            "unresolved": report.unresolved,
            "displayErrors": report.display_errors,
            "featureTimings": timings,
            "featureOutputs": outputs,
        })
        .to_string();
        self.finish_apply(report_json);
    }

    /// The shared post-apply TAIL: mark dirty, store the report JSON, re-sync an
    /// armed gizmo, and rebuild the persistent committed-sketch + construction-datum
    /// overlays. Called after a real run's [`apply_run_output`](Self::apply_run_output)
    /// AND from [`rerun_history`](Self::rerun_history)'s parse-error branch, so both
    /// paths run the identical continuation. Callers read the result via
    /// [`Self::history_report`](Self::history_report_json).
    fn finish_apply(&mut self, report_json: String) {
        self.dirty = true;
        self.history_report = report_json;
        // Keep an armed gizmo glued to its feature as the model rebuilds. During a
        // transform drag the re-sync is driven by `transform_drag_to` itself (which
        // resolves the delta against the frozen grab frame first, then syncs), so
        // skip it here to avoid a redundant double-feed per drag frame. Transform
        // mode re-feeds the widget frame; dimension mode re-projects the annotation
        // leaders onto the rebuilt (param-changed) geometry.
        if self.transform_gizmo.drag.is_none() {
            match self.transform_gizmo.mode {
                GizmoMode::Transform => self.sync_transform_gizmo(),
                GizmoMode::Dimension => self.refresh_feature_dimension_overlay(),
                GizmoMode::None => {}
            }
        }
        // Keep an armed COMPONENT Move gizmo glued to its (possibly re-solved)
        // component: re-anchor at the fresh member bbox. Never during its own
        // drag — the drag feed owns the widget frame (free-move live-follow).
        if self.component_move.drag.is_none() {
            self.component_move_sync();
        }
        // Rebuild the persistent committed-sketch overlays against the reconciled
        // scene (also covers `set_history_json`, which returns this call's result).
        self.refresh_committed_sketches();
        // Rebuild the persistent construction datum/plane overlays from the frames
        // the run just surfaced (D/P features only; sketches render as curves).
        self.refresh_construction_datums();
        // Assembly documents: refresh the main-side session + component
        // projection and fold the solved poses back into the document (the
        // pose-authority contract — see `assembly_ops`). Componentless
        // documents return immediately inside.
        self.sync_assembly();
        // Rebuild the assembly-constraint viewport overlays from the kernel
        // session `sync_assembly` just (re)installed main-side (an inert no-op
        // — empty group — for a document with no assembly state). ORDER
        // MATTERS: the overlay read must follow the session install.
        self.refresh_constraint_overlay();
    }

    /// Load a whole history document (a saved part file parses as one); the
    /// engine now OWNS this recipe. Rolls to the last feature and builds it.
    ///
    /// The document's top-level `metadata` field (the Properties-panel
    /// name-keyed store) is lifted out into [`Self::metadata`] before the feature
    /// list is handed to the kernel — loading a part REPLACES the store wholesale
    /// (a document with no `metadata` clears it), mirroring the previous metadata
    /// manager's load semantics. Round-trips with [`Self::history_request_json`].
    ///
    /// The top-level `workbench` field (the ACTIVE-WORKBENCH id the save embedded
    /// — see [`Self::history_request_json`]) is lifted off the kernel recipe the
    /// same way and applied through [`Self::apply_settings_json`] — the SAME seam
    /// the toolbar's workbench dropdown writes through — so the palette / context
    /// offers / workbench buttons react to a restored workbench exactly as they
    /// do to a manual switch (settings generation bump included). Tolerances:
    ///
    /// * a legacy document WITHOUT the field (or with a non-string value) leaves
    ///   the current workbench untouched — opening an old file never yanks the
    ///   user out of their workbench;
    /// * an unknown/stale id is stored RAW (never an error): the settings layer
    ///   deliberately doesn't validate ids, and every consumer resolves through
    ///   the app-side registry's `resolve()`, which falls back to the default
    ///   workbench — so a file saved by a build with a workbench this build
    ///   doesn't know still opens cleanly;
    /// * the restored id is deliberately NOT persisted to the settings blob —
    ///   that blob stays the user's boot preference; a document's workbench is
    ///   session-scoped (the next explicit dropdown change persists as usual).
    pub fn set_history_json(&mut self, request_json: &str) -> Result<String, String> {
        // A document switch is a wholesale model replacement: drop the incremental
        // cache so the new model starts from a clean slate (no cross-document
        // staleness, no unbounded cache growth across many opens). The roll/edit
        // hot path (`rerun_history`) deliberately KEEPS the cache for instant
        // rollback; this is the ONE place the full clear belongs.
        brep_kernel::clear_history_cache();
        // Reset the delta runner's baseline in lockstep with the cache clear so the
        // new document is a FULL rebuild (no reuse against the prior model's names).
        self.runner.reset();
        self.pending_mesh_imports.clear();
        // A probed-but-unconsumed STEP assembly belongs to the document being
        // replaced: importing it into the NEW one would land a file the user never
        // chose here (and hold its solids resident until they did).
        self.pending_step_assembly = None;
        let mut document: serde_json::Value = serde_json::from_str(request_json)
            .map_err(|error| format!("history parse: {error}"))?;
        // Pull `metadata` out of the document so the engine holds the single copy
        // (kept off the History recipe the kernel executes).
        let metadata_value = document
            .as_object_mut()
            .and_then(|object| object.remove("metadata"));
        self.metadata.load_json(metadata_value.as_ref());
        // Lift the saved active-workbench id off the kernel recipe (`metadata`'s
        // sibling — the kernel would ignore the extra field, but the engine owns
        // it) and apply it through the shared settings seam; see the doc comment
        // for the legacy/unknown-id tolerances. Applied BEFORE the rebuild below
        // so anything reading the settings post-run already sees the restored id.
        if let Some(workbench_id) = document
            .as_object_mut()
            .and_then(|object| object.remove("workbench"))
            .as_ref()
            .and_then(serde_json::Value::as_str)
        {
            let _ = self.apply_settings_json(
                &serde_json::json!({ "workbench": workbench_id }).to_string(),
            );
        }
        // Stamp each sketch's per-loop ids onto its geometries before the model
        // is built. Deriving already yields the right ids, so this renames
        // nothing — it PERSISTS them, which is what lets a loop keep its identity
        // when the edge the id came from is deleted. Doing it here (rather than
        // only on sketch commit) covers every document, including one built by a
        // script that never enters sketch mode. See the kernel's
        // `features/sketch/loop_ids`.
        stamp_sketch_loop_ids(&mut document);
        // SEED this thread's kernel parts library from the document's block.
        // The per-run request no longer carries the block (see
        // `History::parts_library`), so this explicit install is the ONE door
        // that seeds a loaded document — it is what `parts_library_json()`
        // (SAVE), the main-side `sync_assembly` re-run and the export lanes all
        // resolve ACOMPs against, and it bumps the revision so the next run
        // hands the fresh library to the background runner.
        let library = document
            .get("partsLibrary")
            .and_then(|block| serde_json::from_value(block.clone()).ok())
            .unwrap_or_default();
        brep_kernel::install_parts_library(&library);
        self.history = History::from_request_json(&document.to_string())?;
        Ok(self.rerun_history())
    }

    /// The whole history request document (persistence / debugging), with the
    /// engine-owned extras folded back in on top of the kernel recipe so
    /// save→open round-trips them:
    ///
    /// * `metadata` — the Properties-panel store, written only when non-empty so
    ///   an un-annotated model persists as before;
    /// * `workbench` — the CURRENT active-workbench id
    ///   (`self.settings.workbench`), ALWAYS written so a saved part reopens in
    ///   the workbench it was saved from (restored by
    ///   [`Self::set_history_json`]). Always-embed keeps the invariant simple:
    ///   the serialized field tracks the LIVE setting, never a stale stored copy
    ///   — the load lifts it off the kernel recipe entirely, so this is the ONE
    ///   place it is (re)written. Note the deliberate consequence: switching
    ///   workbench changes this document, so the file panel's dirty flag flips —
    ///   consistent with the `metadata` precedent, and semantically true now
    ///   that the workbench is part of the saved file.
    pub fn history_request_json(&self) -> String {
        let mut document: serde_json::Value =
            serde_json::from_str(&self.history.request_json())
                .unwrap_or_else(|_| serde_json::json!({}));
        if let Some(object) = document.as_object_mut() {
            if !self.metadata.is_empty() {
                object.insert("metadata".into(), self.metadata.to_json());
            }
            object.insert(
                "workbench".into(),
                serde_json::Value::String(self.settings.workbench.clone()),
            );
        }
        document.to_string()
    }

    /// The tree listing `{ step, features:[{index,type,id}] }` for the UI panel.
    pub fn history_listing_json(&self) -> String {
        self.history.listing_json()
    }

    /// The last build report JSON.
    pub fn history_report_json(&self) -> String {
        self.history_report.clone()
    }

    pub fn history_len(&self) -> usize {
        self.history.len()
    }

    /// The rolled-to (selected) feature index.
    pub fn history_rollback(&self) -> usize {
        self.history.rollback()
    }

    pub fn feature_type_at(&self, index: usize) -> Option<String> {
        self.history.feature_type(index)
    }

    pub fn feature_id_at(&self, index: usize) -> Option<String> {
        self.history.feature_id(index)
    }

    /// The `inputParams` document of feature `index` (`"null"` if none) — the
    /// dialog's editing-buffer source.
    pub fn feature_params_json(&self, index: usize) -> String {
        self.history
            .feature_params(index)
            .map(|v| v.to_string())
            .unwrap_or_else(|| "null".to_string())
    }

    /// Mint the id for a NEW feature: `{base}{N}` where `base` is the feature's
    /// shortName ([`crate::features::feature_short_name`]) and `N` is the part
    /// history's persistent GLOBAL counter (monotonic, never reused, round-trips
    /// save/load — see [`History::next_feature_id`]). `&mut` because the counter
    /// advances; if the caller's `add_feature` then fails the number is simply
    /// skipped (monotonic-with-gaps is the contract, not an error).
    pub fn next_feature_id(&mut self, base: &str) -> String {
        self.history.next_feature_id(base)
    }

    /// Roll the model to feature `index`: re-run `features[0..=index]`.
    pub fn roll_to(&mut self, index: usize) -> String {
        self.history.set_rollback(index);
        self.rerun_history()
    }

    /// Replace feature `id`'s input params and re-run at the current rollback →
    /// the viewport updates live.
    pub fn update_feature_params(
        &mut self,
        id: &str,
        input_params_json: &str,
    ) -> Result<String, String> {
        let params: serde_json::Value = serde_json::from_str(input_params_json)
            .map_err(|e| format!("feature params parse: {e}"))?;
        let index = self
            .history
            .index_of(id)
            .ok_or_else(|| format!("no feature with id '{id}'"))?;
        self.history.set_feature_params(index, params);
        Ok(self.rerun_history())
    }

    /// Replace the `inputParams` of MANY features as ONE model edit — the
    /// [`Self::update_feature_params`] batch sibling ([`Self::add_features`] is
    /// the append-only one). ONE undo checkpoint and ONE history re-run for the
    /// whole set.
    ///
    /// The lane that needs it: a PACKED BOM row rolls up every occurrence whose
    /// occurrence data matches, so editing one of its cells writes the same key
    /// into N ACOMP features. Looping `update_feature_params` would cost N
    /// re-runs and — worse — N undo entries, so taking back one visible edit
    /// would need N presses of undo.
    ///
    /// Unknown ids are reported (the whole batch is refused before anything is
    /// written, so a typo can never half-apply); an empty batch is a no-op that
    /// neither checkpoints nor runs.
    pub fn update_many_feature_params(
        &mut self,
        edits: &[(String, serde_json::Value)],
    ) -> Result<String, String> {
        if edits.is_empty() {
            return Ok(self.history_report.clone());
        }
        let mut resolved: Vec<(usize, serde_json::Value)> = Vec::with_capacity(edits.len());
        for (id, params) in edits {
            let index = self
                .history
                .index_of(id)
                .ok_or_else(|| format!("no feature with id '{id}'"))?;
            resolved.push((index, params.clone()));
        }
        self.history.set_many_feature_params(&resolved);
        Ok(self.rerun_history())
    }

    /// Append a feature (a full `{type, inputParams, …}` descriptor) and roll to
    /// it. The caller assigns a unique `id` (see [`Self::next_feature_id`]).
    pub fn add_feature(&mut self, feature_json: &str) -> Result<String, String> {
        let feature: serde_json::Value =
            serde_json::from_str(feature_json).map_err(|e| format!("feature parse: {e}"))?;
        self.history.push_feature(feature);
        let last = self.history.len().saturating_sub(1);
        self.history.set_rollback(last);
        Ok(self.rerun_history())
    }

    /// Append MANY features and roll to the last — [`Self::add_feature`]'s batch
    /// sibling, and the reason it exists: `add_feature` re-runs the WHOLE history
    /// per call, so a lane that appends N features by looping it costs N rebuilds
    /// (O(N²) work on an N-part STEP-assembly import). This pushes all of them,
    /// then re-runs ONCE — one rebuild, one undo checkpoint, one
    /// [`applied_generation`](Self::applied_generation) bump.
    ///
    /// Deliberately NOT [`Self::set_history_json`]: that is the document-SWITCH
    /// path (it clears the kernel history cache and resets the runner's delta
    /// baseline, forcing a full cold rebuild), which is the wrong mechanism for an
    /// append onto the live document.
    ///
    /// An empty batch is a no-op — no checkpoint, no run, no generation bump —
    /// and returns the standing report. The caller assigns each feature's unique
    /// `id` (see [`Self::next_feature_id`]).
    pub fn add_features(&mut self, features: &[serde_json::Value]) -> String {
        if features.is_empty() {
            return self.history_report.clone();
        }
        self.history.push_features(features.to_vec());
        let last = self.history.len().saturating_sub(1);
        self.history.set_rollback(last);
        self.rerun_history()
    }

    /// Delete the feature with id `id` (no-op if absent) and re-run, clamping the
    /// rolled-to step.
    pub fn delete_feature(&mut self, id: &str) -> String {
        if let Some(index) = self.history.index_of(id) {
            self.history.remove_feature(index);
            let step = self
                .history
                .rollback()
                .min(self.history.len().saturating_sub(1));
            self.history.set_rollback(step);
        }
        self.rerun_history()
    }

    /// Move feature `index` one slot up/down (reorder), keeping it selected.
    pub fn reorder_feature(&mut self, index: usize, up: bool) -> String {
        let len = self.history.len();
        if len >= 2 {
            let target = if up {
                index.checked_sub(1)
            } else if index + 1 < len {
                Some(index + 1)
            } else {
                None
            };
            if let Some(target) = target {
                self.history.swap(index, target);
                self.history.set_rollback(target);
            }
        }
        self.rerun_history()
    }

}

impl EngineState {
    /// Whether an undo step is available (to enable the toolbar's Undo button).
    pub fn can_undo(&self) -> bool {
        self.history.can_undo()
    }

    /// Whether a redo step is available.
    pub fn can_redo(&self) -> bool {
        self.history.can_redo()
    }

    /// Undo the last model mutation: restore the previous document + rolled-to
    /// step, then re-run + reconcile the scene. Returns the build report; a no-op
    /// (empty undo stack) returns the last report unchanged.
    pub fn undo(&mut self) -> String {
        if self.history.undo() {
            self.reinstall_rewound_parts_library();
            self.rerun_history()
        } else {
            self.history_report.clone()
        }
    }

    /// Redo the last undone model mutation (symmetric with [`Self::undo`]).
    pub fn redo(&mut self) -> String {
        if self.history.redo() {
            self.reinstall_rewound_parts_library();
            self.rerun_history()
        } else {
            self.history_report.clone()
        }
    }

    /// Push the just-rewound `partsLibrary` block back into the kernel's
    /// main-side store, so time travel moves the LIBRARY with the document.
    ///
    /// Without this, undo only half-works on anything that edits a library
    /// entry. The undo snapshot carries the block (`History::Snapshot`), but the
    /// block is a MIRROR: the per-run request does not carry it
    /// ([`History::prefix_request`] omits it) and `sync_assembly` re-serializes
    /// the kernel store back over it after every run. So a rewound block that
    /// was never pushed into the store is simply overwritten again, and the
    /// undo silently does nothing — which is what
    /// [`Self::set_part_attribute`](crate::engine_state::EngineState::set_part_attribute)
    /// would hit on its first undo.
    ///
    /// `install_parts_library` matches the store to the block BY CONTENT
    /// IDENTITY: an identical entry is kept verbatim (so a heal this side
    /// derived is not clobbered), a changed one is replaced and marked dirty
    /// (so the ACOMP self-heal re-derives every instance), and one absent from
    /// the block is dropped. An unchanged block is therefore a no-op, which is
    /// the overwhelmingly common undo.
    fn reinstall_rewound_parts_library(&mut self) {
        let library = serde_json::from_value(self.history.parts_library().clone())
            .unwrap_or_default();
        brep_kernel::install_parts_library(&library);
    }

    // --- Selection (Esc clears / viewport click selects) ------------------

}

/// Parse `{name: "#rrggbb", …}` into an sRGB `name → [0..1;3]` map.
fn parse_color_overrides(json: &str) -> Result<HashMap<String, [f32; 3]>, String> {
    let value: serde_json::Value =
        serde_json::from_str(json).map_err(|error| format!("color overrides parse: {error}"))?;
    let object = value
        .as_object()
        .ok_or_else(|| "color overrides must be an object".to_string())?;
    let mut out = HashMap::new();
    for (name, raw) in object {
        if let Some(hex) = raw.as_str() {
            if let Some(rgb) = crate::style::parse_css_hex(hex) {
                out.insert(name.clone(), rgb);
            }
        }
    }
    Ok(out)
}

/// Stamp per-loop ids onto every SKETCH feature's geometries in a history
/// document, in place.
///
/// The persistence half of per-loop face naming. The kernel DERIVES a loop's id
/// the same way every run, so this renames nothing; what it adds is durability —
/// a stored id survives deleting the edge it was originally derived from, which
/// derivation alone cannot. Running it on document LOAD (not only on sketch
/// commit) means a model built by a script, an import, or any other path that
/// never opens the sketch editor still gets its ids written down.
///
/// Assemblies: a parts-library entry embeds a FULL sub-part history
/// (`partsLibrary[*].document`), whose features can include sketches of its own,
/// so the walk recurses into each one. Without that, a sketch inside an imported
/// assembly part would derive correct names but carry no stored ids — exactly the
/// case (deleting the edge an id came from) that persisting exists to cover.
/// Depth is bounded: a sub-document's own library is seeded from the kernel store
/// rather than nested inside the entry, so one level of recursion reaches all of
/// them, and `MAX_LIBRARY_DEPTH` stops a malformed self-referential document.
///
/// Malformed features are skipped rather than rejected: this is a best-effort
/// enrichment on the way to the kernel, which validates the document itself.
fn stamp_sketch_loop_ids(document: &mut serde_json::Value) {
    /// Depth cap for the embedded sub-document walk — a guard against a
    /// hand-edited or corrupt document that nests libraries into each other.
    const MAX_LIBRARY_DEPTH: usize = 8;
    stamp_sketch_loop_ids_to_depth(document, MAX_LIBRARY_DEPTH);
}

/// [`stamp_sketch_loop_ids`] with the remaining recursion budget.
fn stamp_sketch_loop_ids_to_depth(document: &mut serde_json::Value, depth: usize) {
    if let Some(features) = document
        .get_mut("features")
        .and_then(serde_json::Value::as_array_mut)
    {
        for feature in features {
            if feature.get("type").and_then(serde_json::Value::as_str) != Some("S") {
                continue;
            }
            let Some(sketch) = feature
                .get_mut("persistentData")
                .and_then(|data| data.get_mut("sketch"))
            else {
                continue;
            };
            brep_kernel::assign_sketch_loop_ids(sketch);
        }
    }
    if depth == 0 {
        return;
    }
    // Each library entry's embedded sub-part history gets the same treatment.
    let Some(library) = document
        .get_mut("partsLibrary")
        .and_then(serde_json::Value::as_object_mut)
    else {
        return;
    };
    for (_, entry) in library.iter_mut() {
        let Some(embedded) = entry.get_mut("document") else {
            continue;
        };
        stamp_sketch_loop_ids_to_depth(embedded, depth - 1);
    }
}

// ============================================================================
// File-management convenience (appended — see the model/file-mgmt slice).
// Kept as a SEPARATE `impl` block so concurrent edits to the primary block do
// not conflict; purely additive over the existing history API.
// ============================================================================
impl EngineState {
    /// Load a whole model document (a saved `.BREP.json` recipe) and FRAME it:
    /// [`set_history_json`](Self::set_history_json) (which rolls to the last
    /// feature) followed by [`zoom_to_fit`](Self::zoom_to_fit). The one call the
    /// file panel's **Open** needs — the model IS the engine-owned history, so
    /// opening a file is loading its request JSON and reframing. Returns the
    /// build-report JSON.
    pub fn load_model_and_fit(&mut self, request_json: &str) -> Result<String, String> {
        // Frame once the run lands, not now: under a background runner (native
        // thread / wasm worker) the freshly loaded model is not resident yet when
        // `set_history_json` returns, so an immediate `zoom_to_fit` would frame the
        // OLD scene. Set BEFORE the submit so the Inline runner's in-call `pump`
        // still frames synchronously. See [`EngineState::pending_fit`].
        self.pending_fit = true;
        let result = self.set_history_json(request_json);
        if result.is_err() {
            // A rejected document submits no run, so the armed fit would otherwise
            // fire on the OLD scene next frame — disarm it.
            self.pending_fit = false;
        }
        result
    }
}


// ===========================================================================
// Per-loop face naming: a document gets its sketch loop ids on LOAD.
// ===========================================================================
//
// Deriving already yields the right ids, so loading renames nothing; what the
// stamp adds is durability. A model built by a script or an import never opens
// the sketch editor, so without this it would carry no stored ids and could not
// survive deleting the edge an id was derived from.
#[cfg(test)]
mod sketch_loop_id_stamp_tests {
    use super::*;

    /// A two-loop sketch (gids 10-13 and 20-23) extruded — no sketch-mode visit.
    fn two_loop_history(geometries: serde_json::Value) -> String {
        serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "S",
                    "inputParams": { "id": "Sk" },
                    "persistentData": {
                        "basis": { "origin":[0,0,0], "x":[1,0,0], "y":[0,1,0], "z":[0,0,1] },
                        "sketch": {
                            "points": [
                                { "id": 1, "x": 0.0, "y": 0.0, "fixed": true },
                                { "id": 2, "x": 1.0, "y": 0.0, "fixed": true },
                                { "id": 3, "x": 1.0, "y": 1.0, "fixed": true },
                                { "id": 4, "x": 0.0, "y": 1.0, "fixed": true },
                                { "id": 5, "x": 3.0, "y": 0.0, "fixed": true },
                                { "id": 6, "x": 4.0, "y": 0.0, "fixed": true },
                                { "id": 7, "x": 4.0, "y": 1.0, "fixed": true },
                                { "id": 8, "x": 3.0, "y": 1.0, "fixed": true }
                            ],
                            "geometries": geometries,
                            "constraints": []
                        }
                    }
                },
                {
                    "type": "E",
                    "inputParams": {
                        "id": "Ext", "profile": "Sk", "distance": 1.0,
                        "boolean": { "targets": [], "operation": "NONE" }
                    },
                    "persistentData": {}
                }
            ]
        })
        .to_string()
    }

    fn line(id: i64, a: i64, b: i64) -> serde_json::Value {
        serde_json::json!({ "id": id, "type": "line", "points": [a, b] })
    }

    /// Both loops, with the FIRST loop's anchor edge (gid 10) present.
    fn both_loops() -> serde_json::Value {
        serde_json::json!([
            line(10, 1, 2), line(11, 2, 3), line(12, 3, 4), line(13, 4, 1),
            line(20, 5, 6), line(21, 6, 7), line(22, 7, 8), line(23, 8, 5),
        ])
    }

    /// The stored `loopId` of each geometry, in document order.
    fn stored_ids(engine: &EngineState) -> Vec<(i64, Option<i64>)> {
        let document: serde_json::Value =
            serde_json::from_str(&engine.history_request_json()).expect("document");
        document["features"][0]["persistentData"]["sketch"]["geometries"]
            .as_array()
            .expect("geometries")
            .iter()
            .map(|geometry| {
                (
                    geometry["id"].as_i64().expect("gid"),
                    geometry.get("loopId").and_then(serde_json::Value::as_i64),
                )
            })
            .collect()
    }

    /// Loading a scripted document stamps every loop's id onto ALL of its edges,
    /// and the stamp round-trips back out through `history_request_json` (so a
    /// save after a plain open persists it).
    #[test]
    fn loading_a_scripted_history_stamps_and_persists_loop_ids() {
        let mut engine = EngineState::new();
        engine
            .set_history_json(&two_loop_history(both_loops()))
            .expect("history loads");
        assert_eq!(
            stored_ids(&engine),
            vec![
                (10, Some(10)), (11, Some(10)), (12, Some(10)), (13, Some(10)),
                (20, Some(20)), (21, Some(20)), (22, Some(20)), (23, Some(20)),
            ],
        );
    }

    /// Assemblies: a sketch inside a parts-library entry's EMBEDDED sub-part
    /// history gets stamped too. That document never passes through the sketch
    /// editor (it arrives whole, from a STEP assembly import), so the load-time
    /// stamp is its only chance to get durable ids.
    #[test]
    fn a_sketch_inside_an_embedded_part_document_is_stamped() {
        let part_document = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "S",
                    "inputParams": { "id": "SubSk" },
                    "persistentData": {
                        "basis": { "origin":[0,0,0], "x":[1,0,0], "y":[0,1,0], "z":[0,0,1] },
                        "sketch": {
                            "points": [
                                { "id": 1, "x": 0.0, "y": 0.0, "fixed": true },
                                { "id": 2, "x": 1.0, "y": 0.0, "fixed": true },
                                { "id": 3, "x": 1.0, "y": 1.0, "fixed": true },
                                { "id": 4, "x": 0.0, "y": 1.0, "fixed": true }
                            ],
                            "geometries": [
                                line(40, 1, 2), line(41, 2, 3), line(42, 3, 4), line(43, 4, 1)
                            ],
                            "constraints": []
                        }
                    }
                }
            ]
        });
        let mut document = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [],
            "partsLibrary": {
                "Part-1": {
                    "sourceKey": "k",
                    "sourceSignature": "s",
                    "document": part_document,
                }
            }
        });
        stamp_sketch_loop_ids(&mut document);

        let stamped: Vec<Option<i64>> = document["partsLibrary"]["Part-1"]["document"]
            ["features"][0]["persistentData"]["sketch"]["geometries"]
            .as_array()
            .expect("embedded geometries")
            .iter()
            .map(|geometry| geometry.get("loopId").and_then(serde_json::Value::as_i64))
            .collect();
        assert_eq!(
            stamped,
            vec![Some(40), Some(40), Some(40), Some(40)],
            "the embedded part's loop got its id on every edge",
        );
    }

    /// A self-referential document terminates instead of recursing forever.
    #[test]
    fn a_self_nesting_library_terminates() {
        let mut document = serde_json::json!({ "features": [], "partsLibrary": {} });
        // Nest a library inside a library, deeper than the depth cap.
        let mut inner = serde_json::json!({ "features": [] });
        for _ in 0..20 {
            inner = serde_json::json!({
                "features": [],
                "partsLibrary": { "P": { "document": inner } }
            });
        }
        document["partsLibrary"]["P"] = serde_json::json!({ "document": inner });
        stamp_sketch_loop_ids(&mut document); // must return, not hang or overflow
    }

    /// THE POINT of persisting: delete the edge a loop's id was derived from and
    /// the loop keeps its identity, so the cap face built from it keeps its name.
    /// Derivation alone could not do this — the anchor gid is gone.
    #[test]
    fn a_loaded_document_survives_deleting_the_anchor_edge() {
        let mut engine = EngineState::new();
        engine
            .set_history_json(&two_loop_history(both_loops()))
            .expect("history loads");
        // Save as the app would: the stamped ids are now in the document.
        let saved = engine.history_request_json();

        // Edit that saved document the way the editor would: drop loop A's anchor
        // (gid 10) and close the loop with a NEW edge (gid 30, a fresh id above
        // everything). The surviving edges still carry `loopId: 10`.
        let mut edited: serde_json::Value = serde_json::from_str(&saved).expect("saved document");
        let geometries = edited["features"][0]["persistentData"]["sketch"]["geometries"]
            .as_array_mut()
            .expect("geometries");
        geometries.retain(|geometry| geometry["id"].as_i64() != Some(10));
        geometries.push(line(30, 1, 2));

        let mut reopened = EngineState::new();
        reopened
            .set_history_json(&edited.to_string())
            .expect("edited history loads");
        let ids = stored_ids(&reopened);
        assert!(
            ids.iter().all(|(_, loop_id)| matches!(
                loop_id,
                Some(10) | Some(20)
            )),
            "both loops kept their ids after the anchor edge was deleted: {ids:?}",
        );
        // The NEW edge joined loop A rather than seeding an id of its own.
        assert_eq!(
            ids.iter().find(|(gid, _)| *gid == 30).map(|(_, id)| *id),
            Some(Some(10)),
            "the replacement edge inherited loop A's id: {ids:?}",
        );
    }
}

// ===========================================================================
// Instant history-rollback: the incremental cache must survive a roll/edit.
// ===========================================================================
//
// Regression guard for the fix that made roll-to-step / edit INSTANT: the engine
// no longer sledgehammers `clear_history_cache()` before every rerun, so an
// unchanged upstream prefix (a heavy STEP import + primitives) replays from the
// kernel's incremental cache (`reused`, timing 0.0) instead of cold re-executing.
// The correctness worry the sledgehammer guarded — "roll BEFORE a boolean that
// consumed its target displays the freed/re-used handle" — cannot occur: a
// boolean clones its inputs and frees only its own intermediates; a consumed
// input handle is freed exactly when its PRODUCING cache entry is invalidated
// (never by a downstream consumer). So rolling to the box shows the box.
#[cfg(test)]
mod history_cache_rollback_tests {
    use super::*;
    use crate::scene::SolidDisplay;

    /// F1 = box `Box` (side 20 → volume 8000), F2 = cylinder `Pin`, F3 = boolean
    /// `Cut` = SUBTRACT(target=Box, tools=[Pin]). The boolean CONSUMES Box (its
    /// target) and Pin, removing both names and adding one subtracted solid.
    fn box_pin_cut_history() -> 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" }
                    },
                    "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" }
                    },
                    "persistentData": {}
                },
                {
                    "type": "B",
                    "inputParams": {
                        "id": "Cut",
                        "targetSolid": "Box",
                        "boolean": { "operation": "SUBTRACT", "targets": ["Pin"] }
                    },
                    "persistentData": {}
                }
            ]
        })
        .to_string()
    }

    /// Closed-mesh volume via the divergence theorem: V = (1/6) Σ p0·(p1×p2) over
    /// triangles — the volume of the geometry the USER actually sees on screen.
    fn display_volume(solid: &SolidDisplay) -> f64 {
        let p = &solid.mesh.positions;
        let mut v = 0.0f64;
        for tri in solid.mesh.indices.chunks_exact(3) {
            let a = p[tri[0] as usize];
            let b = p[tri[1] as usize];
            let c = p[tri[2] as usize];
            let (a, b, c) = (
                [a[0] as f64, a[1] as f64, a[2] as f64],
                [b[0] as f64, b[1] as f64, b[2] as f64],
                [c[0] as f64, c[1] as f64, c[2] as f64],
            );
            // p0 · (p1 × p2)
            let cross = [
                b[1] * c[2] - b[2] * c[1],
                b[2] * c[0] - b[0] * c[2],
                b[0] * c[1] - b[1] * c[0],
            ];
            v += a[0] * cross[0] + a[1] * cross[1] + a[2] * cross[2];
        }
        (v / 6.0).abs()
    }

    /// The timing (ms) the last build reported for feature `id`. A REPLAYED
    /// (cached) feature reports EXACTLY 0.0; a re-executed one reports its real
    /// wall-clock (> 0.0 for any real geometry op).
    fn timing(report: &serde_json::Value, id: &str) -> f64 {
        report["featureTimings"][id]
            .as_f64()
            .unwrap_or_else(|| panic!("no timing for '{id}' in {report}"))
    }

    /// THE decisive test: rolling to the box BEFORE the boolean that consumed it
    /// (a) shows the box's geometry (right volume) and (b) replays it from the
    /// incremental cache (timing 0.0), i.e. instantly — not a cold re-execution.
    #[test]
    fn roll_to_step_before_boolean_is_correct_and_cached() {
        brep_kernel::clear_history_cache(); // hermetic start (shared thread-local cache)
        let mut engine = EngineState::new();
        engine.set_history_json(&box_pin_cut_history()).unwrap();

        // Full run: the boolean produced ONE subtracted solid, smaller than the box.
        assert_eq!(engine.scene.solids().len(), 1);
        let cut_vol = display_volume(&engine.scene.solids()[0]);
        assert!(
            cut_vol < 8000.0 - 1.0,
            "subtracted solid ({cut_vol}) must be smaller than the 8000 box"
        );

        // Roll to F1 (the box) — the step BEFORE the boolean.
        let report: serde_json::Value =
            serde_json::from_str(&engine.roll_to(0)).unwrap();

        // CORRECTNESS: exactly the box is displayed, full volume 8000 — the cached
        // replay shows the box's own geometry, NOT a freed/re-used handle.
        assert_eq!(engine.scene.solids().len(), 1, "only the box after rollback");
        let box_solid = engine
            .scene
            .solid("Box")
            .expect("box resident after rolling back before the boolean");
        let box_vol = display_volume(box_solid);
        assert!(
            (box_vol - 8000.0).abs() < 1.0,
            "rolled-back box volume {box_vol} != 8000 (stale/freed handle?)"
        );

        // INSTANT: the box replayed from the incremental cache (timing 0.0), not a
        // cold re-execution. THIS is what the sledgehammer removal buys.
        assert_eq!(
            timing(&report, "Box"),
            0.0,
            "rolled-back box must replay from cache (timing 0.0), not re-execute"
        );
    }

    /// Rolling to the box then FORWARD to the boolean again restores the correct
    /// subtracted geometry AND replays the entire prefix from cache (all timings
    /// 0.0) — nothing was invalidated by the round-trip, so the roll-forward is
    /// instant too. Crucially the redisplayed "Box" is the SUBTRACTED result (the
    /// name is re-bound from the cube's handle to the boolean's), NOT the stale
    /// full box left over from the rollback — the handle-gated display reuse
    /// re-tessellates it.
    #[test]
    fn roll_forward_after_rollback_restores_geometry_and_replays_all() {
        brep_kernel::clear_history_cache();
        let mut engine = EngineState::new();
        engine.set_history_json(&box_pin_cut_history()).unwrap();

        engine.roll_to(0); // back to the box
        let rolled = engine.scene.solid("Box").expect("box after rollback");
        assert!(
            (display_volume(rolled) - 8000.0).abs() < 1.0,
            "rolled-back name 'Box' shows the full box"
        );

        let report: serde_json::Value =
            serde_json::from_str(&engine.roll_to(2)).unwrap();
        // The subtracted solid is back — the name "Box" now shows the boolean
        // result (smaller than the full box), not the stale rollback display.
        assert_eq!(engine.scene.solids().len(), 1);
        let vol = display_volume(engine.scene.solid("Box").expect("boolean result"));
        assert!(
            vol < 8000.0 - 1.0,
            "boolean result restored under name 'Box' ({vol}), not the stale 8000 box"
        );
        // The WHOLE prefix replayed from cache — the round-trip invalidated nothing.
        assert_eq!(timing(&report, "Box"), 0.0, "box replayed on roll-forward");
        assert_eq!(timing(&report, "Pin"), 0.0, "pin replayed on roll-forward");
        assert_eq!(timing(&report, "Cut"), 0.0, "boolean replayed on roll-forward");
    }

    /// Editing ONLY the boolean keeps the upstream box + pin cached (timing 0.0);
    /// just the boolean re-executes — the incremental-dependency win.
    #[test]
    fn editing_boolean_keeps_upstream_cached() {
        brep_kernel::clear_history_cache();
        let mut engine = EngineState::new();
        engine.set_history_json(&box_pin_cut_history()).unwrap();

        // Flip the cut to a UNION (fingerprint + geometry both change).
        let new_params = serde_json::json!({
            "id": "Cut",
            "targetSolid": "Box",
            "boolean": { "operation": "UNION", "targets": ["Pin"] }
        })
        .to_string();
        let report: serde_json::Value =
            serde_json::from_str(&engine.update_feature_params("Cut", &new_params).unwrap())
                .unwrap();

        assert_eq!(
            timing(&report, "Box"),
            0.0,
            "box stayed cached across a boolean edit"
        );
        assert_eq!(
            timing(&report, "Pin"),
            0.0,
            "pin stayed cached across a boolean edit"
        );
        assert!(
            timing(&report, "Cut") > 0.0,
            "the edited boolean re-executed"
        );
    }

    /// STEP-1 regression — a DATUM/FACE-attached sketch's committed sheet must land
    /// EXACTLY where the live overlay is drawn. The bug: `enter_sketch_mode` built
    /// the live session plane from the persisted `basis` ALONE, while the kernel
    /// materializes the sheet against the frame it resolves LIVE from the
    /// `sketchPlane` reference (here a datum lifted to z=5). A stale/identity basis
    /// therefore drew the overlay at z=0 while the committed sheet sat at z=5 — an
    /// off-location sheet. The fix makes the live session adopt the kernel's resolved
    /// frame (published under the sketch id in `construction_frames`), so both agree.
    #[test]
    fn datum_attached_sketch_live_plane_matches_materialized_sheet() {
        brep_kernel::clear_history_cache();
        // DATUM D2 lifted to z=5; sketch S1 on `D2:XY` with a DELIBERATELY STALE
        // identity basis (origin at z=0) plus a fixed 10x6 rectangle profile.
        let history = serde_json::json!({
            "features": [
                {
                    "type": "D",
                    "inputParams": { "id": "D2",
                        "transform": { "position": [0.0, 0.0, 5.0], "rotationEuler": [0.0, 0.0, 0.0], "scale": [1.0, 1.0, 1.0] } },
                    "persistentData": {}
                },
                {
                    "type": "S",
                    "inputParams": { "id": "S1", "sketchPlane": "D2:XY" },
                    "persistentData": {
                        // Stale/identity basis at the world origin — the pre-fix live
                        // session trusted THIS and drew the overlay at z=0.
                        "basis": { "origin": [0.0, 0.0, 0.0], "x": [1.0, 0.0, 0.0], "y": [0.0, 1.0, 0.0], "z": [0.0, 0.0, 1.0] },
                        "sketch": {
                            "points": [
                                { "id": 0, "x": 0.0,  "y": 0.0, "fixed": true },
                                { "id": 1, "x": 10.0, "y": 0.0, "fixed": true },
                                { "id": 2, "x": 10.0, "y": 6.0, "fixed": true },
                                { "id": 3, "x": 0.0,  "y": 6.0, "fixed": true }
                            ],
                            "geometries": [
                                { "id": 10, "type": "line", "points": [0, 1] },
                                { "id": 11, "type": "line", "points": [1, 2] },
                                { "id": 12, "type": "line", "points": [2, 3] },
                                { "id": 13, "type": "line", "points": [3, 0] }
                            ],
                            "constraints": []
                        }
                    }
                }
            ]
        })
        .to_string();

        let mut engine = EngineState::new();
        engine.set_history_json(&history).unwrap();

        // The committed sheet was ALWAYS materialized against the kernel-resolved
        // frame (the datum at z=5) — this half was never broken. Capture its world
        // bbox center BEFORE entering (entering the sketch removes its committed
        // sheet, which the live editing overlay replaces).
        let sheet = engine
            .scene
            .solids()
            .iter()
            .find(|s| s.name == "S1")
            .expect("committed sketch S1 sheet present");
        assert!(sheet.is_sketch, "S1 is a synthesized sketch sheet");
        let sheet_center = [
            (sheet.bbox.min[0] + sheet.bbox.max[0]) * 0.5,
            (sheet.bbox.min[1] + sheet.bbox.max[1]) * 0.5,
            (sheet.bbox.min[2] + sheet.bbox.max[2]) * 0.5,
        ];
        assert!(
            (sheet_center[2] - 5.0).abs() < 1e-6,
            "committed sheet sits on the datum plane (z=5); got {sheet_center:?}"
        );

        // Enter sketch mode: the live session plane must adopt the kernel's resolved
        // frame (datum origin z=5), NOT the stale basis (z=0). Pre-fix this was z=0.
        engine.enter_sketch_mode("S1").expect("enter S1");
        let plane = engine.sketch_edit_session().expect("live session").plane;
        assert!(
            (plane.origin[2] - 5.0).abs() < 1e-6,
            "live sketch plane must sit on the datum (z=5), not the stale basis (z=0); got origin {:?}",
            plane.origin
        );
        assert!(
            (plane.z_axis[2] - 1.0).abs() < 1e-9,
            "live plane normal stays +Z; got {:?}",
            plane.z_axis
        );

        // The literal "sheet matches live" check: the live plane maps the rectangle's
        // centroid uv (5, 3) to the committed sheet's world bbox center.
        let live_center = plane.to_world(5.0, 3.0);
        for axis in 0..3 {
            assert!(
                (live_center[axis] - sheet_center[axis]).abs() < 1e-6,
                "live overlay world {live_center:?} must match the committed sheet center {sheet_center:?}"
            );
        }
    }

    /// STEP-2 regression — the FIRST edit session of a brand-new, still-EMPTY
    /// face/datum-attached sketch must open its live plane on the resolved reference,
    /// not the world origin. The bug: the app's `add_feature` seeds a sketch with an
    /// empty `persistentData: {}` (no `sketch` doc — nobody has drawn yet); the kernel
    /// SKETCH feature ERRORED on that missing doc and so never published its resolved
    /// plane frame, leaving `construction_frames` without the sketch. `enter_sketch_mode`
    /// then found no resolved frame and fell through to the persisted `basis` — which
    /// is ALSO absent on a fresh sketch — bottoming out at `PlaneFrame::xy()` (the
    /// world origin). The user saw the empty sketcher open "on the center of the part"
    /// (z=0). Only the first commit wrote the doc, after which the rerun published the
    /// frame and the SECOND entry was correct. The fix publishes the resolved frame
    /// even for a doc-less/empty sketch, so the FIRST entry already lands on the datum.
    ///
    /// This deliberately does NOT pre-populate the sketch doc and does NOT enter twice
    /// before asserting — it exercises the first-entry-of-an-empty-sketch path directly.
    #[test]
    fn first_entry_of_empty_datum_sketch_uses_resolved_frame_not_origin() {
        brep_kernel::clear_history_cache();
        // DATUM D2 lifted to z=5, then a SKETCH S1 referencing `D2:XY` with EMPTY
        // persistentData — no `sketch` doc, no `basis` — exactly what the app's
        // `add_feature_of_type` creates before the user draws anything.
        let history = serde_json::json!({
            "features": [
                {
                    "type": "D",
                    "inputParams": { "id": "D2",
                        "transform": { "position": [0.0, 0.0, 5.0], "rotationEuler": [0.0, 0.0, 0.0], "scale": [1.0, 1.0, 1.0] } },
                    "persistentData": {}
                },
                {
                    "type": "S",
                    "inputParams": { "id": "S1", "sketchPlane": "D2:XY" },
                    // Brand-new sketch nobody has drawn in yet — no `sketch`, no `basis`.
                    "persistentData": {}
                }
            ]
        })
        .to_string();

        let mut engine = EngineState::new();
        engine.set_history_json(&history).unwrap();

        // FIRST entry of the still-empty sketch: the live plane must adopt the kernel's
        // resolved datum frame (origin [0,0,5]), NOT the XY fallback at the world origin
        // (pre-fix this was [0,0,0]).
        engine.enter_sketch_mode("S1").expect("enter S1");
        let plane = engine.sketch_edit_session().expect("live session").plane;
        for (axis, expected) in [0.0_f64, 0.0, 5.0].into_iter().enumerate() {
            assert!(
                (plane.origin[axis] - expected).abs() < 1e-6,
                "first entry of an empty datum-attached sketch must sit on the datum \
                 (origin [0,0,5]), not the world origin [0,0,0]; got {:?}",
                plane.origin
            );
        }
        assert!(
            (plane.z_axis[2] - 1.0).abs() < 1e-9,
            "live plane normal stays +Z; got {:?}",
            plane.z_axis
        );
    }
}

// ===========================================================================
// Workbench persistence: the saved document remembers the active workbench.
// ===========================================================================
//
// The engine-owned document round-trip carries a top-level `workbench` field:
// `history_request_json` ALWAYS embeds the current `settings.workbench`, and
// `set_history_json` lifts it off the kernel recipe and applies it through the
// shared settings seam (`apply_settings_json` — the toolbar dropdown's apply
// path). Exactly the `metadata` idiom: the engine owns the field, the kernel
// never sees it, and every save/open path inherits the behavior for free.
#[cfg(test)]
mod workbench_persistence_tests {
    use super::*;

    /// A featureless-but-valid model document, optionally carrying extra
    /// top-level fields (the `workbench` under test).
    fn doc_with(extra: &[(&str, serde_json::Value)]) -> String {
        let mut doc = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": []
        });
        for (key, value) in extra {
            doc[*key] = value.clone();
        }
        doc.to_string()
    }

    /// The `workbench` field of a serialized document (None when absent).
    fn embedded_workbench(document_json: &str) -> Option<String> {
        serde_json::from_str::<serde_json::Value>(document_json)
            .ok()?
            .get("workbench")?
            .as_str()
            .map(str::to_string)
    }

    /// SAVE embeds the CURRENT workbench id as the top-level `workbench` field —
    /// the live setting, not any stored copy.
    #[test]
    fn request_json_embeds_the_current_workbench() {
        let mut engine = EngineState::new();
        engine.set_history_json(&doc_with(&[])).unwrap();
        // Default workbench serializes too (the field is ALWAYS written).
        assert_eq!(
            embedded_workbench(&engine.history_request_json()).as_deref(),
            Some("modeling"),
            "the default workbench id is embedded on save"
        );
        // Switch via the dropdown's apply path → the next save carries it.
        engine
            .apply_settings_json(r#"{"workbench":"sheetMetal"}"#)
            .unwrap();
        assert_eq!(
            embedded_workbench(&engine.history_request_json()).as_deref(),
            Some("sheetMetal"),
            "save embeds the LIVE workbench id"
        );
    }

    /// LOAD applies a stored `workbench` id to the settings and lifts the field
    /// OFF the kernel recipe: after a later switch, re-serializing emits the new
    /// live id — no stale copy survives inside the history document.
    #[test]
    fn load_restores_the_stored_workbench_and_keeps_it_live() {
        let mut engine = EngineState::new();
        engine
            .set_history_json(&doc_with(&[(
                "workbench",
                serde_json::json!("sheetMetal"),
            )]))
            .unwrap();
        assert_eq!(
            engine.settings.workbench, "sheetMetal",
            "opening the document switches the active workbench"
        );
        // The field tracks the LIVE setting (the load lifted the stored copy).
        engine
            .apply_settings_json(r#"{"workbench":"modeling"}"#)
            .unwrap();
        assert_eq!(
            embedded_workbench(&engine.history_request_json()).as_deref(),
            Some("modeling"),
            "re-serialize emits the live id — the stored copy was lifted, not kept"
        );
    }

    /// A LEGACY document (no `workbench` field) loads exactly as before: no
    /// workbench change, no error. Non-string values count as absent too.
    #[test]
    fn legacy_document_leaves_the_active_workbench_untouched() {
        let mut engine = EngineState::new();
        engine
            .apply_settings_json(r#"{"workbench":"sheetMetal"}"#)
            .unwrap();
        engine.set_history_json(&doc_with(&[])).unwrap();
        assert_eq!(
            engine.settings.workbench, "sheetMetal",
            "a legacy document must not yank the user out of their workbench"
        );
        // A malformed (non-string) field is tolerated as absent — never an error.
        engine
            .set_history_json(&doc_with(&[("workbench", serde_json::json!(42))]))
            .unwrap();
        assert_eq!(engine.settings.workbench, "sheetMetal");
    }

    /// An UNKNOWN stored id loads without error and is stored raw — the settings
    /// layer doesn't validate ids (the app-side registry's `resolve()` falls back
    /// to the default workbench at every consumption site).
    #[test]
    fn unknown_stored_workbench_id_loads_without_error() {
        let mut engine = EngineState::new();
        engine
            .set_history_json(&doc_with(&[(
                "workbench",
                serde_json::json!("conveyorBelts"),
            )]))
            .unwrap();
        assert_eq!(
            engine.settings.workbench, "conveyorBelts",
            "unknown ids pass through raw; consumers resolve them to the default"
        );
    }
}