brep_render/

pipeline.rs

//! History → scene: run a whole feature history through the kernel's native
//! `execute_history` (same process, same thread — the solid registry is
//! thread-local) and populate a [`RenderScene`] from the resident handles via
//! the kernel's native display payload accessor. No JSON, no typed-array
//! boundary — the R1 promise.

use crate::scene::{solid_display_from_payload, RenderScene, SolidDisplay};
use brep_kernel::{display_payload_handle_native, execute_history, HistoryRequest};
use std::collections::HashMap;

/// Non-fatal diagnostics from a scene build (mirrors the previous app's run-history
/// reporting: a failed feature halts the remaining features but the solids
/// built so far still display — seeing what a failing history DID build is the
/// point of the artifact).
#[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize)]
pub struct SceneBuildReport {
    /// Per-feature hard errors, as `"<feature id>: <message>"`.
    pub feature_errors: Vec<String>,
    /// Unresolved reference-selection names, as `"<feature id>: <name>"`.
    pub unresolved: Vec<String>,
    /// Solids whose display payload (tessellation) failed, as
    /// `"<solid name>: <message>"` — the solid is skipped, not fatal.
    pub display_errors: Vec<String>,
    /// Per-feature wall-clock execution time `(feature id, milliseconds)` in run
    /// order, carried through from the kernel's [`brep_kernel::HistoryResult`]
    /// timings — the history tree's "N ms" readout.
    pub feature_timings: Vec<(String, f64)>,
    /// Per-feature output solid names `(feature id, [solid names])` in run order —
    /// the history tree's read-only "Outputs" node.
    pub feature_outputs: Vec<(String, Vec<String>)>,
    /// Named plane FRAMES this run resolved `(frame name, frame)`, in run order —
    /// every DATUM registers three (`{id}:XY|XZ|YZ`), every PLANE one (`{id}`), and
    /// a SKETCH its own plane (`{id}`). Surfaced here so the engine can DISPLAY the
    /// construction datum/plane frames (filtered to the D/P producing features) as
    /// first-class scene citizens — the resolved frames ride
    /// [`brep_kernel::FeatureResult::frames`] straight through, no kernel change.
    pub frames: Vec<(String, brep_kernel::Frame)>,
    /// Solved sketch PROFILES this run produced `(sketch id, profile)`, in run
    /// order — every SKETCH feature publishes one under its own id. Surfaced here
    /// (exactly like [`Self::frames`]) so the engine can display each committed
    /// sketch as a SHEET SOLID (planar face + named boundary edges + corner
    /// vertices) via `sketch_display_payload`, no kernel-contract change.
    pub profiles: Vec<(String, brep_kernel::SketchProfile)>,
    /// Named axis LINES this run produced `(axis name, line)`, in run order — a
    /// SKETCH publishes one per line geometry (construction included). Surfaced
    /// here (exactly like [`Self::frames`]/[`Self::profiles`]) so the engine can
    /// resolve a revolve/sweep `axis` reference to a world line at annotation-build
    /// time, fully headless. `#[serde(default)]` keeps older serialized reports
    /// (pre-`axes`) deserializing cleanly across the worker boundary.
    #[serde(default)]
    pub axes: Vec<(String, brep_kernel::Axis)>,
    /// Named PATH chains this run produced `(path name, curves)`, in run order — a
    /// SKETCH publishes its whole ordered chain under `{id}` and EACH model segment
    /// under `{id}:G{gid}`. Surfaced here (exactly like [`Self::profiles`]) so the
    /// engine can draw a committed sketch's OPEN geometry: an open chain closes no
    /// region, so it publishes no profile, and before this the sheet builder had
    /// nothing to draw it from — an open sketch was invisible in 3D. `#[serde(default)]`
    /// keeps older serialized reports (pre-`paths`) deserializing cleanly across the
    /// worker boundary.
    #[serde(default)]
    pub paths: Vec<(String, Vec<brep_kernel::NurbsCurve>)>,
    /// Named world POINTS this run produced `(point name, point)`, in run order —
    /// a SKETCH publishes every solved point under `{id}:P{pid}` with its
    /// construction flag. Surfaced here (exactly like [`Self::paths`]) so the
    /// engine can draw a committed sketch's STANDALONE points: a points-only
    /// sketch (a hole-placement sketch) has no segment and no profile, so before
    /// this the sheet builder had nothing to draw it from — it was invisible and
    /// unpickable in 3D. `#[serde(default)]` keeps older serialized reports
    /// (pre-`points`) deserializing cleanly across the worker boundary.
    #[serde(default)]
    pub points: Vec<(String, brep_kernel::ScenePoint)>,
}

/// Execute a serialized `HistoryRequest` (the `execute_history_json` request
/// shape — a saved part file parses as one) and build the display scene from
/// the final resident solids.
pub fn scene_from_history_json(
    request_json: &str,
) -> Result<(RenderScene, SceneBuildReport), String> {
    let request: HistoryRequest = serde_json::from_str(request_json)
        .map_err(|error| format!("history request parse: {error}"))?;
    scene_from_history(&request)
}

/// Typed-request variant of [`scene_from_history_json`].
pub fn scene_from_history(
    request: &HistoryRequest,
) -> Result<(RenderScene, SceneBuildReport), String> {
    let mut scene = RenderScene::new();
    let report = update_scene_from_history(&mut scene, request)?;
    Ok((scene, report))
}

/// The fold of a history run into an ordered scene layout: each entry is the
/// solid's final name, its resident handle, and whether the feature that
/// produced it REPLAYED from the incremental cache (R10 — a reused solid is the
/// same resident geometry, so its display can be kept verbatim and its GPU
/// buffers reused).
struct SceneLayout {
    order: Vec<String>,
    handles: std::collections::HashMap<String, u32>,
    reused: std::collections::HashSet<String>,
    /// `name -> creating-feature id` of the FINAL resident SOLIDS (last writer
    /// wins; a `removed` name drops its entry) — the eager provenance the runner
    /// ships so the main thread never has to re-run the history to answer
    /// "what feature produced this SOLID?". Matches the resident semantics of the
    /// old `resident_handles_and_creators`.
    creators: std::collections::HashMap<String, String>,
    /// `face/edge NAME -> ORIGINATING feature id` — the FIRST feature (timeline
    /// order) to emit each face/edge name, i.e. the entity's TRUE origin (the
    /// feature that gave it its name). Unlike `creators` this is FIRST-writer-wins
    /// and is NEVER pruned on `removed`: a boolean removes its target solid and
    /// re-adds the same solid name carrying mostly the same face names, so pruning
    /// then re-adding would reset those origins to the boolean feature — the same
    /// last-writer bug one level down. Accepted edge case: a fully-deleted solid
    /// whose name later recurs on unrelated geometry keeps its old origin — but
    /// under this app's DETERMINISTIC naming a recurring name is the same
    /// conceptual entity, and the whole map is rebuilt every run, so it can never
    /// point at a feature that was deleted from the history.
    entity_origin: std::collections::HashMap<String, String>,
}

fn fold_history(result: &brep_kernel::HistoryResult, report: &mut SceneBuildReport) -> SceneLayout {
    // Removals first (a boolean result reuses a removed target's name), then
    // additions, insertion-ordered — mirrors SceneMap::apply.
    let mut order: Vec<String> = Vec::new();
    let mut handles: std::collections::HashMap<String, u32> = std::collections::HashMap::new();
    let mut reused: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut creators: std::collections::HashMap<String, String> = std::collections::HashMap::new();
    let mut entity_origin: std::collections::HashMap<String, String> =
        std::collections::HashMap::new();
    for feature in &result.results {
        for removed in &feature.removed {
            if handles.remove(removed).is_some() {
                order.retain(|name| name != removed);
            }
            reused.remove(removed);
            creators.remove(removed);
            // NOTE: `entity_origin` is deliberately NOT pruned here — see its doc on
            // `SceneLayout`. First-writer-with-no-pruning is the whole point.
        }
        for added in &feature.added {
            if handles.insert(added.name.clone(), added.handle).is_none() {
                order.push(added.name.clone());
            }
            creators.insert(added.name.clone(), feature.id.clone());
            // The FIRST feature to emit a given face/edge name IS its origin (this
            // loop is in timeline order). `entry(..).or_insert_with` keeps that
            // first writer — using `insert` here would be last-writer and silently
            // reproduce the exact bug this map exists to fix.
            for (_, name) in &added.face_names {
                entity_origin
                    .entry(name.clone())
                    .or_insert_with(|| feature.id.clone());
            }
            for (_, name) in &added.edge_names {
                entity_origin
                    .entry(name.clone())
                    .or_insert_with(|| feature.id.clone());
            }
            // A solid displays as reused only when its whole producing feature
            // replayed unchanged; a re-run feature re-tessellates.
            if feature.reused {
                reused.insert(added.name.clone());
            } else {
                reused.remove(&added.name);
            }
        }
        if let Some(error) = &feature.error {
            report.feature_errors.push(format!("{}: {error}", feature.id));
        }
        for name in &feature.unresolved {
            report.unresolved.push(format!("{}: {name}", feature.id));
        }
        // The feature's output solid name(s) — the history tree's Outputs node.
        report.feature_outputs.push((
            feature.id.clone(),
            feature.added.iter().map(|a| a.name.clone()).collect(),
        ));
        // The named plane frames this feature resolved (DATUM three / PLANE one /
        // SKETCH its own). Carried straight through so the engine can display the
        // construction datum/plane frames (it filters to the D/P producers).
        for (name, frame) in &feature.frames {
            report.frames.push((name.clone(), *frame));
        }
        // The solved sketch profile (SKETCH features publish one under `{id}`) —
        // carried straight through so the engine can synthesize its sheet solid.
        for (name, profile) in &feature.profiles {
            report.profiles.push((name.clone(), profile.clone()));
        }
        // The named axis lines this feature published (a SKETCH emits one per line
        // geometry) — carried through so the engine can resolve a revolve `axis`
        // reference to a world line for the angle gizmo.
        for (name, axis) in &feature.axes {
            report.axes.push((name.clone(), *axis));
        }
        // The named path chains this feature published (a SKETCH emits its whole
        // chain under `{id}` and every model segment under `{id}:G{gid}`) — carried
        // through so the engine can draw the segments no closed profile covers.
        for (name, curves) in &feature.paths {
            report.paths.push((name.clone(), curves.clone()));
        }
        // The named world points this feature published (a SKETCH emits every
        // solved point under `{id}:P{pid}`) — carried through so the engine can
        // draw a sketch's standalone points, which no segment covers.
        for (name, point) in &feature.points {
            report.points.push((name.clone(), *point));
        }
    }
    // Per-feature timing rides the kernel result straight through.
    report.feature_timings = result.timings.clone();
    SceneLayout { order, handles, reused, creators, entity_origin }
}

/// A stateful, SCENE-FREE history run that emits a DELTA snapshot instead of
/// mutating a scene — the M1 seam of the off-thread history runner. It remembers,
/// in [`Self::last_sent`], the resident handle it last EMITTED per solid name, so
/// a rerun can tell the applier which displays are UNCHANGED (skip re-tessellating
/// + keep their GPU buffers) vs. which are new/rebound (freshly tessellated).
///
/// Being scene-free is the point: a later milestone runs this on a background
/// thread / worker with no access to the render scene, then ships the
/// [`RunOutput`] delta back to the main thread to apply. In M1 the run is
/// immediately applied on the same thread (see `EngineState::apply_run_output`),
/// so behavior is byte-identical to the pre-seam in-place reconcile.
pub struct SceneRunner {
    /// `name -> handle` of what was last EMITTED (the delta baseline). Handles are
    /// monotonic and never recycled (the resident registry's counter only
    /// increments, and `clear_history_cache` frees solids without resetting it),
    /// so "handle unchanged since last emit" is EXACTLY the old
    /// `reused && source_handle matches` reuse condition — a re-executed feature
    /// always registers a NEW handle, so a matching handle proves a cache replay.
    last_sent: HashMap<String, u32>,
    /// The display LOD factor the current baseline was tessellated at. When a run
    /// arrives at a DIFFERENT lod (the user moved the "LOD factor" slider) every
    /// resident mesh must be rebuilt at the new chord tolerance even though its
    /// handle is unchanged — so a lod change drops `last_sent` to defeat the
    /// handle-unchanged reuse fast path. Init `1.0` (the "Normal" default) so a
    /// first run at the default lod does NOT spuriously invalidate an empty
    /// baseline's peers.
    last_lod: f64,
    /// The parts-library revision this runner's OWN kernel store was last
    /// installed at (`None` = nothing installed, or dropped). The library no
    /// longer rides on every history request (that per-run serialize is what
    /// froze the browser UI on a large assembly) — it arrives on its own
    /// `Command::SetPartsLibrary` and this records what landed, so a run
    /// stamped for a different revision can be refused rather than executed
    /// against the wrong parts. Cleared by [`Self::reset`], which pairs with
    /// the `clear_history_cache` that empties the store.
    pub(crate) parts_library_revision: Option<u64>,
    /// The part NAMES the last install carried. A run whose ACOMP references a
    /// name in here that the store can no longer resolve was GC'd out from
    /// under us and is RECOVERABLE (ask for the library again); a name that was
    /// never installed is simply not in the document's library, and that run
    /// must go ahead so the ACOMP feature reports it — refusing forever would
    /// wedge the model on a dangling reference. Names only, so this costs
    /// nothing next to the payload it describes.
    pub(crate) parts_library_names: std::collections::BTreeSet<String>,
}

/// The delta a [`SceneRunner::run`] produces: the displayed KERNEL solids IN
/// ORDER plus the run's [`SceneBuildReport`]. The applier walks `snapshot` in
/// order, reusing or replacing each entry (see the field docs).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RunOutput {
    /// The displayed KERNEL solids IN ORDER. `display: Some` = freshly tessellated
    /// (new, or the handle changed since last emit); `None` = UNCHANGED — the
    /// applier keeps its existing [`SolidDisplay`] for this name, whose
    /// `source_handle` equals `handle`.
    pub snapshot: Vec<(String /* name */, u32 /* handle */, Option<SolidDisplay>)>,
    pub report: SceneBuildReport,
    /// Eager PROVENANCE: `name -> creating-feature id` for the run's FINAL resident
    /// SOLIDS (same last-writer-wins fold as the display snapshot). Shipped WITH the
    /// run so the main thread can answer SOLID provenance without a cold
    /// `execute_history` — critical once the run lives on a background thread and the
    /// main-side registry is cold.
    pub provenance: Vec<(String, String)>,
    /// Eager ENTITY ORIGIN: `face/edge NAME -> ORIGINATING feature id` (FIRST writer
    /// in timeline order, never pruned — see `SceneLayout::entity_origin`). Shipped
    /// beside `provenance` so `creating_feature` can answer "which feature gave this
    /// face/edge its name?" (the "Edit owning feature" context action + the Info
    /// tab's `creatingFeature`) with no cold re-run. Crosses the background-worker
    /// seam, so the serde round-trip test asserts it survives.
    pub entity_origin: Vec<(String, String)>,
    /// Assembly-solver POSE write-backs from this run's constraint tail:
    /// `(component feature id, {translate, rotateEulerDeg})` — read RUNNER-SIDE
    /// (the kernel assembly session is thread-local to the thread/worker that ran
    /// `execute_history`, so only the runner can see it) and shipped here so the
    /// engine folds them into the owning ACOMP features' `inputParams` (the
    /// pose-authority contract, build-spec §6 step 4). Empty on a no-motion
    /// solve — a satisfied assembly must not churn feature fingerprints.
    /// `#[serde(default)]` keeps pre-assembly serialized replies deserializing.
    #[serde(default)]
    pub assembly_poses: Vec<(String, serde_json::Value)>,
    /// `isFixed` write-backs riding the same fold (the Fixed-constraint lane
    /// grounds a component); shape mirrors [`Self::assembly_poses`].
    #[serde(default)]
    pub assembly_fixed: Vec<(String, bool)>,
    /// Names of solids the solve re-posed IN PLACE this run (the display seam:
    /// their producing feature may have replayed `reused`, yet their geometry
    /// moved). The runner already defeated the handle-unchanged reuse fast path
    /// for these (their snapshot entries arrive `Some`, freshly tessellated);
    /// shipped for observability/tests. Empty on zero-mate/no-motion runs.
    #[serde(default)]
    pub moved_solids: Vec<String>,
    /// IMPORTED COLOURS: `entity name -> "#RRGGBB"` for every solid/face this run
    /// left a `color` scene-metadata record on (STEP presentation entities, read
    /// by `brep_kernel::io/appearance.rs` and stamped by IMPORT3D).
    ///
    /// Read RUNNER-SIDE for the same reason as `assembly_poses`: the kernel's
    /// scene-metadata store is thread-local to whoever ran `execute_history`, so
    /// a main-thread read under a background runner sees nothing. The applier
    /// folds these into the engine's own [`crate::metadata::MetadataStore`]
    /// WITHOUT overwriting, so the Info window shows an imported colour and a
    /// user's edit of it still wins.
    ///
    /// Filtered to the names this run actually produced, so a colour left in the
    /// (never-cleared) kernel store by a previous document cannot bleed into
    /// this one.
    #[serde(default)]
    pub imported_colors: Vec<(String, String)>,
}

impl SceneRunner {
    pub fn new() -> Self {
        Self {
            last_sent: HashMap::new(),
            last_lod: 1.0,
            parts_library_revision: None,
            parts_library_names: std::collections::BTreeSet::new(),
        }
    }

    /// Reset the delta baseline (call on a wholesale document switch so the next
    /// run is a full rebuild — no stale reuse across unrelated models).
    pub fn reset(&mut self) {
        self.last_sent.clear();
        // A reset always accompanies the `clear_history_cache` that empties
        // this side's parts library, so forget what was installed — the next
        // run's stamp will not match and the library is re-sent.
        self.parts_library_revision = None;
        self.parts_library_names.clear();
    }

    /// Execute `request` and fold it into an ordered delta snapshot (does NOT
    /// touch any scene). For each displayed kernel solid in order: if the handle
    /// is unchanged since the last emit, emit `(name, handle, None)` (the applier
    /// keeps its existing display); otherwise (re-)tessellate the resident handle
    /// and emit `(name, handle, Some(display))`. A display-payload error is
    /// recorded in `report.display_errors` and the entry is SKIPPED — and NOT
    /// recorded in the new baseline, so a later successful run re-tessellates it.
    ///
    ///
    /// Colours are NOT applied here. A display arrives colourless and the main
    /// side paints it from the metadata store
    /// ([`EngineState::sync_colors_from_metadata`](crate::engine_state::EngineState::sync_colors_from_metadata)),
    /// which is the only colour authority — a runner may be a background thread
    /// or worker with no view of that store.
    pub fn run(&mut self, request: &HistoryRequest) -> RunOutput {
        self.run_observed(request, &mut |_| true)
    }

    /// [`Self::run`] with a progress observer: `observe` is called before every
    /// feature the kernel actually executes (see
    /// [`brep_kernel::execute_history_observed`]); returning `false` stops the
    /// run at that boundary, and the partial result is folded like any other.
    pub fn run_observed(
        &mut self,
        request: &HistoryRequest,
        observe: &mut dyn FnMut(brep_kernel::HistoryProgress<'_>) -> bool,
    ) -> RunOutput {
        let result = brep_kernel::execute_history_observed(request, observe);
        let mut report = SceneBuildReport::default();
        let layout = fold_history(&result, &mut report);

        // --- assembly pose-authority read (RUNNER-SIDE, build-spec §6/§13) ----
        // The kernel assembly session (constraint solve tail) is THREAD-LOCAL to
        // whoever ran `execute_history` — i.e. this thread/worker — so the pose
        // and isFixed write-backs must be read HERE and shipped in the RunOutput;
        // a main-thread read under a background runner would see a cold session.
        let pose_updates: serde_json::Value =
            serde_json::from_str(&brep_kernel::assembly_pose_updates_json())
                .unwrap_or(serde_json::Value::Null);
        let assembly_poses: Vec<(String, serde_json::Value)> = pose_updates["poses"]
            .as_object()
            .map(|map| map.iter().map(|(id, pose)| (id.clone(), pose.clone())).collect())
            .unwrap_or_default();
        let assembly_fixed: Vec<(String, bool)> = pose_updates["isFixed"]
            .as_object()
            .map(|map| {
                map.iter()
                    .filter_map(|(id, flag)| flag.as_bool().map(|b| (id.clone(), b)))
                    .collect()
            })
            .unwrap_or_default();
        // The display seam: solids the solve re-posed IN PLACE keep their resident
        // handle, so the handle-unchanged reuse fast path below would wrongly skip
        // re-tessellating them even though their geometry moved. Drop them from
        // the baseline so they re-emit fresh displays. The `movedSolids` key is
        // ABSENT on zero-mate reports — tolerated (empty).
        let dof: serde_json::Value = serde_json::from_str(&brep_kernel::assembly_dof_json())
            .unwrap_or(serde_json::Value::Null);
        let moved_solids: Vec<String> = dof["movedSolids"]
            .as_array()
            .map(|items| {
                items
                    .iter()
                    .filter_map(|item| item["name"].as_str().map(String::from))
                    .collect()
            })
            .unwrap_or_default();
        for name in &moved_solids {
            self.last_sent.remove(name);
        }

        // Display LOD: a finite, positive factor (garbage from a hand-edited saved
        // file → the "Normal" 1.0, since chord = extent·1.5e-3·lod and a 0/NaN lod
        // would zero the tolerance → runaway refinement). A change since the last
        // run means every resident mesh must re-tessellate at the new chord even
        // though its handle is unchanged, so drop the reuse baseline.
        let lod = if request.display_lod.is_finite() && request.display_lod > 0.0 {
            request.display_lod
        } else {
            1.0
        };
        if lod != self.last_lod {
            self.last_sent.clear();
            self.last_lod = lod;
        }

        let mut snapshot: Vec<(String, u32, Option<SolidDisplay>)> =
            Vec::with_capacity(layout.order.len());
        let mut next_sent: HashMap<String, u32> = HashMap::with_capacity(layout.order.len());

        for name in &layout.order {
            let handle = layout.handles[name];
            if self.last_sent.get(name) == Some(&handle) {
                // Handle unchanged since last emit ⇒ same resident geometry ⇒ the
                // applier keeps its existing display. This is EXACTLY the old
                // `reused && source_handle == handle` fast path (monotonic handles):
                // the canary below verifies the implication holds.
                debug_assert!(
                    layout.reused.contains(name),
                    "handle unchanged must imply reused (monotonic handles): {name}"
                );
                snapshot.push((name.clone(), handle, None));
                next_sent.insert(name.clone(), handle);
                continue;
            }
            match display_payload_handle_native(handle, lod) {
                Ok(payload) => {
                    let mut solid = solid_display_from_payload(name, payload);
                    solid.source_handle = handle;
                    // Runner thread → the SheetTree thread-local is warm here; stamp
                    // the sheet-metal marker so the UI thread reads it off the scene
                    // (never calling the thread-local from a cold UI thread).
                    solid.is_sheet_metal = brep_kernel::is_sheet_metal_handle(handle);
                    snapshot.push((name.clone(), handle, Some(solid)));
                    next_sent.insert(name.clone(), handle);
                }
                // A tessellation failure skips the solid (non-fatal) and does NOT
                // poison the baseline — dropping it lets a later successful run
                // re-tessellate from scratch.
                Err(error) => report.display_errors.push(format!("{name}: {error}")),
            }
        }

        self.last_sent = next_sent;
        // Eager provenance for the run's final resident solids (the applier stores
        // this map main-side so per-frame provenance queries never re-run history).
        let provenance: Vec<(String, String)> = layout
            .creators
            .iter()
            .map(|(name, id)| (name.clone(), id.clone()))
            .collect();
        // Eager entity origin (face/edge NAME -> originating feature id) rides
        // alongside, so face/edge provenance survives the off-thread seam too.
        let entity_origin: Vec<(String, String)> = layout
            .entity_origin
            .iter()
            .map(|(name, id)| (name.clone(), id.clone()))
            .collect();
        // Imported colours, read HERE for the thread-local reason above and
        // filtered to this run's own entities: the solids it displays plus the
        // faces/edges it named. The kernel store is never cleared between
        // documents, so an unfiltered ship could hand the applier a colour that
        // belongs to a model the user closed.
        let imported_colors: Vec<(String, String)> = serde_json::from_str::<serde_json::Value>(
            &brep_kernel::scene_metadata_colors_json(),
        )
        .ok()
        .and_then(|value| value.as_object().cloned())
        .map(|map| {
            map.into_iter()
                .filter(|(name, _)| {
                    layout.handles.contains_key(name) || layout.entity_origin.contains_key(name)
                })
                .filter_map(|(name, hex)| hex.as_str().map(|hex| (name, hex.to_string())))
                .collect()
        })
        .unwrap_or_default();

        RunOutput {
            snapshot,
            report,
            provenance,
            entity_origin,
            assembly_poses,
            assembly_fixed,
            moved_solids,
            imported_colors,
        }
    }

    /// The resident handle last EMITTED for `name` (the delta baseline), or `None`
    /// if the runner has not emitted a solid of that name. The measurement-query
    /// path resolves an object's owning-solid handle through this so the query runs
    /// against the SAME resident geometry the last run displayed (on the runner's
    /// own thread, whose registry is warm from that run).
    pub fn handle_of(&self, name: &str) -> Option<u32> {
        self.last_sent.get(name).copied()
    }
}

impl Default for SceneRunner {
    fn default() -> Self {
        Self::new()
    }
}

/// Execute the history and reconcile `scene` in place (R10 incremental update):
/// reused solids already present keep their [`SolidDisplay`] verbatim (stable
/// `revision` ⇒ the renderer reuses their GPU buffers); everything else is
/// (re-)tessellated from the resident handle; departed solids are dropped.
///
/// Implemented on the M1 seam: a throwaway [`SceneRunner`] primed from the
/// CURRENT scene (`name → source_handle` of what is displayed) reproduces the
/// pre-seam reuse in a single synchronous call, and its [`RunOutput`] delta is
/// applied back to `scene` by MOVING existing displays out (via
/// [`RenderScene::drain`]) so a reused solid's mesh is never cloned.
pub fn update_scene_from_history(
    scene: &mut RenderScene,
    request: &HistoryRequest,
) -> Result<SceneBuildReport, String> {
    let mut runner = SceneRunner::new();
    runner.last_sent = scene
        .solids()
        .iter()
        .map(|solid| (solid.name.clone(), solid.source_handle))
        .collect();
    let output = runner.run(request);

    // Move the current displays out, then reinsert in snapshot ORDER: a fresh
    // entry replaces, an UNCHANGED entry reuses the moved-out display (whose
    // `source_handle` equals the run's handle — guaranteed by the reuse
    // invariant). Leftovers (departed names) are dropped.
    let mut kept: HashMap<String, SolidDisplay> = scene
        .drain()
        .into_iter()
        .map(|solid| (solid.name.clone(), solid))
        .collect();
    for (name, _handle, maybe) in output.snapshot {
        match maybe {
            Some(display) => scene.insert_solid(display),
            None => scene.insert_solid(
                kept.remove(&name).expect("keep target present"),
            ),
        }
    }
    Ok(output.report)
}

/// Execute `request` and return the FINAL resident solids as `(name, handle)` in
/// display order — the export lane (STEP/STL) needs the current solids' resident
/// handles, which the scene build does not itself retain. Run right after a scene
/// build (warm incremental cache) this replays the cached features, so the
/// handles it returns are the very ones the displayed scene was built from; run
/// cold it re-executes and registers fresh (still-valid) handles. Either way the
/// handles are live in the thread-local registry when this returns, ready to
/// hand to `brep_kernel::export_step_handles`.
pub fn resident_solid_handles(request: &HistoryRequest) -> Vec<(String, u32)> {
    let result = execute_history(request);
    let mut report = SceneBuildReport::default();
    let layout = fold_history(&result, &mut report);
    layout
        .order
        .iter()
        .map(|name| (name.clone(), layout.handles[name]))
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn cube_request(name: &str, size: f64) -> String {
        serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "P.CU",
                "inputParams": {
                    "id": name,
                    "sizeX": size, "sizeY": size, "sizeZ": size,
                    "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": {}
            }]
        })
        .to_string()
    }

    // A DOTTED feature id (the new `{shortName}{N}` scheme yields ids like `P.CU1`)
    // must be safe as a downstream reference: the `.` is inert everywhere (scene-map
    // resolution is exact HashMap lookup — only `:` and `|` are name delimiters).
    // Prove it at RUNTIME: a boolean SUBTRACT that targets a dotted-id solid resolves
    // (nothing lands in `report.unresolved`) and builds a scene.
    #[test]
    fn dotted_feature_id_resolves_as_a_boolean_reference() {
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "P.CU",
                    "inputParams": {
                        "id": "P.CU1",
                        "sizeX": 10.0, "sizeY": 10.0, "sizeZ": 10.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.CU",
                    "inputParams": {
                        "id": "P.CU2",
                        "sizeX": 10.0, "sizeY": 10.0, "sizeZ": 10.0,
                        "transform": { "position": [5.0, 0.0, 0.0], "rotationEuler": [0.0, 0.0, 0.0], "scale": [1.0, 1.0, 1.0] },
                        // SUBTRACT referencing the DOTTED id of the first cube.
                        "boolean": { "targets": ["P.CU1"], "operation": "SUBTRACT" }
                    },
                    "persistentData": {}
                }
            ]
        })
        .to_string();
        let (scene, report) = scene_from_history_json(&request).unwrap();
        assert!(report.feature_errors.is_empty(), "{:?}", report.feature_errors);
        // The dotted reference `P.CU1` resolved — if `.` broke name matching it would
        // appear here instead.
        assert!(report.unresolved.is_empty(), "dotted ref unresolved: {:?}", report.unresolved);
        // The subtract folded the two cubes into one resident solid.
        assert_eq!(scene.solids().len(), 1);
    }

    #[test]
    fn cube_history_populates_scene() {
        let (scene, report) = scene_from_history_json(&cube_request("P.CU1", 10.0)).unwrap();
        assert!(report.feature_errors.is_empty(), "{:?}", report.feature_errors);
        assert!(report.display_errors.is_empty(), "{:?}", report.display_errors);
        assert_eq!(scene.solids().len(), 1);
        let solid = scene.solid("P.CU1").expect("solid keyed by kernel name");
        assert_eq!(solid.faces.len(), 6);
        // Cube tessellation: 2 triangles per face.
        assert_eq!(solid.mesh.indices.len(), 6 * 2 * 3);
        for face in &solid.faces {
            assert_eq!(face.tri_count, 2, "face {} range", face.name);
            assert!(!face.name.is_empty());
        }
        // 12 boundary edges, each a straight 2-point polyline, all named.
        assert_eq!(solid.edges.len(), 12);
        for edge in &solid.edges {
            assert!(edge.polyline.len() >= 2);
            assert!(!edge.name.is_empty());
        }
        assert_eq!(solid.vertices.len(), 8);
        let bbox = scene.bbox();
        assert!((bbox.size()[0] - 10.0).abs() < 1e-6);
    }

    fn sphere_request(name: &str, radius: f64, lod: f64) -> brep_kernel::HistoryRequest {
        let mut request: brep_kernel::HistoryRequest = serde_json::from_value(serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "P.S",
                "inputParams": {
                    "id": name,
                    "radius": radius,
                    "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": {}
            }]
        }))
        .unwrap();
        request.display_lod = lod;
        request
    }

    // A LOD-factor change must re-tessellate every resident mesh at the new chord
    // tolerance EVEN THOUGH the solid's handle is unchanged (same geometry, replayed
    // from the incremental cache) — otherwise the "LOD factor" slider does nothing.
    #[test]
    fn lod_change_retessellates_reused_solid_coarser() {
        let mut runner = SceneRunner::new();

        // Fine mesh at lod 0.5.
        let fine = runner.run(&sphere_request("LodBall", 10.0, 0.5));
        let (_, fine_handle, fine_display) = &fine.snapshot[0];
        let fine_tris = fine_display.as_ref().expect("first run tessellates").mesh.indices.len();

        // SAME sphere, coarser lod 4.0: the incremental cache replays the sphere so
        // the handle is unchanged (proven below) — the ONLY reason to re-emit is the
        // lod change, and the coarser chord must drop the triangle count.
        let coarse = runner.run(&sphere_request("LodBall", 10.0, 4.0));
        let (_, coarse_handle, coarse_display) = &coarse.snapshot[0];
        assert_eq!(
            coarse_handle, fine_handle,
            "same sphere must replay to the same handle (reuse path) — else the test proves nothing"
        );
        let coarse_tris = coarse_display
            .as_ref()
            .expect("a lod change re-emits Some(display) despite the unchanged handle")
            .mesh
            .indices
            .len();
        assert!(
            coarse_tris < fine_tris,
            "coarser lod must shrink the mesh: fine(lod 0.5)={fine_tris} coarse(lod 4.0)={coarse_tris}"
        );

        // Re-running at the SAME lod reuses the baseline (None) — no spurious full
        // re-tessellation on every run once the lod is stable.
        let again = runner.run(&sphere_request("LodBall", 10.0, 4.0));
        assert!(
            again.snapshot[0].2.is_none(),
            "an unchanged lod must reuse the display baseline (None), not re-tessellate"
        );
    }

    #[test]
    fn reused_history_keeps_stable_revision() {
        let request: brep_kernel::HistoryRequest =
            serde_json::from_str(&cube_request("Keep", 8.0)).unwrap();
        let mut scene = RenderScene::new();
        update_scene_from_history(&mut scene, &request).unwrap();
        let first_rev = scene.solid("Keep").unwrap().revision;

        // A second identical run replays from the incremental cache; the reused
        // solid must keep its revision (so the renderer reuses its GPU buffers).
        update_scene_from_history(&mut scene, &request).unwrap();
        assert_eq!(scene.solid("Keep").unwrap().revision, first_rev);
    }

    #[test]
    fn scene_insert_replace_and_remove() {
        let (mut scene, _) = scene_from_history_json(&cube_request("A", 4.0)).unwrap();
        let (other, _) = scene_from_history_json(&cube_request("B", 2.0)).unwrap();
        for solid in other.solids() {
            scene.insert_solid(solid.clone());
        }
        assert_eq!(scene.solids().len(), 2);
        assert!(scene.remove_solid("A"));
        assert!(!scene.remove_solid("A"));
        assert_eq!(scene.solids().len(), 1);
        assert!(scene.solid("B").is_some());
    }

    #[test]
    fn datum_history_surfaces_three_named_frames() {
        // A single DATUM feature resolves three base-plane frames; the build report
        // surfaces them so the engine can display them as datum planes.
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "D",
                "inputParams": { "id": "Datum" },
                "persistentData": {}
            }]
        })
        .to_string();
        let (_scene, report) = scene_from_history_json(&request).unwrap();
        let names: Vec<&str> = report.frames.iter().map(|(n, _)| n.as_str()).collect();
        assert!(names.contains(&"Datum:XY"), "{names:?}");
        assert!(names.contains(&"Datum:XZ"), "{names:?}");
        assert!(names.contains(&"Datum:YZ"), "{names:?}");
    }

    /// A Box → Pin → Cut(SUBTRACT) history: the SOLID provenance is LAST-writer
    /// (`Box → Cut`) while `entity_origin` is FIRST-writer, so an ORIGINAL box face
    /// still points at `Box`. This pins the divergence the "Edit owning feature" fix
    /// relies on: the two maps must disagree for the same final solid.
    #[test]
    fn entity_origin_is_first_writer_while_provenance_is_last_writer() {
        // The app's boot seed: a 20 mm cube `Box`, a cylinder `Pin`, and
        // `Cut` = SUBTRACT(Box, [Pin]). The SUBTRACT reuses the target's name, so the
        // final solid is `Box`, produced by `Cut`.
        let request: HistoryRequest = serde_json::from_str(
            r#"{
                "expressions": "", "configurator": {},
                "features": [
                    { "type": "P.CU", "inputParams": { "id": "Box", "sizeX": 20, "sizeY": 20, "sizeZ": 20,
                        "transform": { "position": [0,0,0], "rotationEuler": [0,0,0], "scale": [1,1,1] },
                        "boolean": { "targets": [], "operation": "NONE" } }, "persistentData": {} },
                    { "type": "P.CY", "inputParams": { "id": "Pin", "radius": 6, "height": 30,
                        "transform": { "position": [10,-5,10], "rotationEuler": [0,0,0], "scale": [1,1,1] },
                        "boolean": { "targets": [], "operation": "NONE" } }, "persistentData": {} },
                    { "type": "B", "inputParams": { "id": "Cut", "targetSolid": "Box",
                        "boolean": { "operation": "SUBTRACT", "targets": ["Pin"] } }, "persistentData": {} }
                ]
            }"#,
        )
        .unwrap();

        let output = SceneRunner::new().run(&request);

        // One final solid, `Box`, whose SOLID producer is the LAST writer, `Cut`.
        let provenance: std::collections::HashMap<_, _> = output.provenance.iter().cloned().collect();
        assert_eq!(provenance.get("Box"), Some(&"Cut".to_string()));

        // Its ORIGINAL faces still ORIGINATE from `Box` (first writer, not `Cut`):
        // cross-check against the faces actually resident on the final `Box` display.
        let entity_origin: std::collections::HashMap<_, _> =
            output.entity_origin.iter().cloned().collect();
        let box_display = output
            .snapshot
            .iter()
            .find(|(name, _, _)| name == "Box")
            .and_then(|(_, _, d)| d.as_ref())
            .expect("Box freshly tessellated on first run");
        let a_box_origin_face = box_display
            .faces
            .iter()
            .any(|f| entity_origin.get(&f.name) == Some(&"Box".to_string()));
        assert!(
            a_box_origin_face,
            "at least one resident Box face must originate from `Box`, not the `Cut` \
             boolean that last produced the solid; entity_origin = {entity_origin:?}"
        );
    }

    /// The assembly display seam + pose-authority read, end-to-end at the runner:
    /// a constraint added to an ALREADY-BUILT two-instance assembly replays both
    /// ACOMP features from the cache (unchanged handles), yet the solve re-poses
    /// the free instance IN PLACE — the runner must (a) ship the solver's pose
    /// write-back in `assembly_poses`, (b) list the re-posed member in
    /// `moved_solids`, and (c) DEFEAT the handle-unchanged reuse fast path for it
    /// (a `Some`, freshly tessellated snapshot entry at the MOVED location) while
    /// the fixed instance stays a reuse (`None`).
    #[test]
    fn assembly_solve_ships_poses_and_retessellates_moved_solids() {
        let base_json = crate::engine_state::component_fixtures::two_instance_assembly_json();
        let base: HistoryRequest = serde_json::from_str(&base_json).unwrap();

        let mut runner = SceneRunner::new();
        let first = runner.run(&base);
        assert!(
            first.assembly_poses.is_empty() && first.moved_solids.is_empty(),
            "no constraints yet — no write-backs: {:?}",
            first.assembly_poses
        );
        let first_x = |name: &str| {
            first
                .snapshot
                .iter()
                .find(|(n, _, _)| n == name)
                .and_then(|(_, _, d)| d.as_ref())
                .expect("first run tessellates fresh")
                .bbox
                .min[0]
        };
        assert!((first_x("ACOMP2:Part") - 20.0).abs() < 1e-6, "authored pose");

        // SAME features + a whole-component coincident: ACOMP2 must land on ACOMP1.
        let mut doc: serde_json::Value = serde_json::from_str(&base_json).unwrap();
        doc["assembly"] = serde_json::json!({
            "constraints": [{
                "type": "coincident",
                "inputParams": { "id": "COIN1", "elements": ["ACOMP1", "ACOMP2"] },
                "persistentData": {},
                "enabled": true,
                "open": false
            }],
            "idCounter": 2
        });
        let with_constraint: HistoryRequest = serde_json::from_str(&doc.to_string()).unwrap();
        let second = runner.run(&with_constraint);

        // (a) the pose write-back for the FREE component only.
        assert!(
            second.assembly_poses.iter().any(|(id, pose)| {
                id == "ACOMP2" && pose.get("translate").is_some() && pose.get("rotateEulerDeg").is_some()
            }),
            "ACOMP2 pose shipped: {:?}",
            second.assembly_poses
        );
        assert!(
            !second.assembly_poses.iter().any(|(id, _)| id == "ACOMP1"),
            "the fixed component never writes back"
        );

        // (b) the display seam names the re-posed member.
        assert!(
            second.moved_solids.iter().any(|n| n == "ACOMP2:Part"),
            "moved solids: {:?}",
            second.moved_solids
        );

        // (c) the moved solid re-tessellated DESPITE its replayed feature; the
        // fixed one is a plain reuse.
        let entry = |name: &str| second.snapshot.iter().find(|(n, _, _)| n == name).unwrap();
        assert!(
            entry("ACOMP1:Part").2.is_none(),
            "fixed instance replays as a reuse"
        );
        let moved = entry("ACOMP2:Part")
            .2
            .as_ref()
            .expect("moved solid must re-emit a fresh display despite the unchanged handle");
        assert!(
            moved.bbox.min[0] < 15.0,
            "the fresh display sits at the SOLVED pose, not the authored one: {:?}",
            moved.bbox
        );

        // A third identical run is a settled no-motion solve: no write-backs, and
        // the moved solid goes back to reusing its (now up-to-date) display.
        let third = runner.run(&with_constraint);
        assert!(third.assembly_poses.is_empty(), "{:?}", third.assembly_poses);
        assert!(third.moved_solids.is_empty());
        assert!(third.snapshot.iter().all(|(_, _, d)| d.is_none()), "settled run reuses everything");
    }

    /// A `RunOutput` — the whole delta (tessellated `SolidDisplay` snapshot + the
    /// report's frames/profiles/provenance) — survives a serde JSON round trip.
    /// This is the wasm WorkerRunner (M3) message payload: the worker serializes
    /// the run result and the main thread reconstructs it byte-for-byte.
    #[test]
    fn run_output_round_trips_through_serde() {
        // A cube (→ a tessellated SolidDisplay) + a DATUM (→ frames) + a committed
        // rectangle SKETCH (→ a profile) exercise every side-channel of the report.
        let request: HistoryRequest = serde_json::from_str(
            r#"{
                "expressions": "", "configurator": {},
                "features": [
                    { "type": "P.CU", "inputParams": { "id": "Box", "sizeX": 10, "sizeY": 10, "sizeZ": 10,
                        "transform": { "position": [0,0,0], "rotationEuler": [0,0,0], "scale": [1,1,1] },
                        "boolean": { "targets": [], "operation": "NONE" } }, "persistentData": {} },
                    { "type": "D", "inputParams": { "id": "Datum" }, "persistentData": {} },
                    { "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":0,"x":0,"y":0},{"id":1,"x":10,"y":0},{"id":2,"x":10,"y":6},{"id":3,"x":0,"y":6}],
                          "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": [] } } }
                ]
            }"#,
        )
        .unwrap();

        let mut output = SceneRunner::new().run(&request);
        // Seed the ASSEMBLY side-channels non-empty: the wasm WorkerRunner is the
        // ONE path that serializes RunOutput (ThreadRunner ships structs over
        // mpsc), and `assembly_poses` is load-bearing there — if it dropped on
        // the wire, the pose-authority fold would silently never happen in the
        // browser while every native test stayed green.
        output.assembly_poses = vec![(
            "ACOMP2".to_string(),
            serde_json::json!({ "translate": [1.0, 2.0, 3.0], "rotateEulerDeg": [0.0, 0.0, 90.0] }),
        )];
        output.assembly_fixed = vec![("ACOMP1".to_string(), true)];
        output.moved_solids = vec!["ACOMP2:Part".to_string()];
        let output = output;
        // Sanity: the run produced the box display + the datum frames + the profile.
        assert_eq!(output.snapshot.len(), 1, "one solid (the box)");
        assert!(output.snapshot[0].2.as_ref().unwrap().mesh.positions.len() > 0);
        assert!(output.report.frames.iter().any(|(n, _)| n == "Datum:XY"));
        assert!(output.report.profiles.iter().any(|(n, _)| n == "Sk"));
        assert!(output.provenance.iter().any(|(n, id)| n == "Box" && id == "Box"));
        // Pre-serialization sanity so the round-trip assert below can't pass
        // vacuously on an empty vec: the cube's faces originate from `Box`.
        assert!(
            output.entity_origin.iter().any(|(_, id)| id == "Box"),
            "entity_origin should carry the box faces' origin"
        );

        let json = serde_json::to_string(&output).expect("RunOutput serializes");
        let back: RunOutput = serde_json::from_str(&json).expect("RunOutput deserializes");

        assert_eq!(back.snapshot.len(), output.snapshot.len());
        assert_eq!(back.snapshot[0].0, "Box");
        assert_eq!(
            back.snapshot[0].2.as_ref().unwrap().mesh.positions.len(),
            output.snapshot[0].2.as_ref().unwrap().mesh.positions.len()
        );
        assert!(back.report.frames.iter().any(|(n, _)| n == "Datum:XY"));
        let (name, profile) = back.report.profiles.iter().find(|(n, _)| n == "Sk").unwrap();
        assert_eq!(name, "Sk");
        assert_eq!(profile.regions.len(), 1, "the rectangle profile survived");
        // The sketch's per-segment PATHS cross the seam beside its profile — the
        // committed-sketch display draws an OPEN sketch from them, so a dropped
        // field would make open sketches invisible on the threaded-runner path only.
        assert!(
            back.report.paths.iter().any(|(name, _)| name == "Sk:G10"),
            "the sketch's per-segment paths survive the round trip: {:?}",
            back.report.paths.iter().map(|(n, _)| n).collect::<Vec<_>>()
        );
        assert_eq!(back.report.paths.len(), output.report.paths.len());
        assert_eq!(back.provenance, output.provenance);
        // The entity-origin map crosses the worker seam too — a dropped field would
        // silently lose face/edge origins on the threaded-runner path only.
        assert_eq!(back.entity_origin, output.entity_origin);
        // The assembly side-channels cross the worker seam (see the seed above).
        assert_eq!(back.assembly_poses, output.assembly_poses);
        assert_eq!(back.assembly_fixed, output.assembly_fixed);
        assert_eq!(back.moved_solids, output.moved_solids);
        // And a pre-assembly serialized reply (no such keys) still deserializes
        // — the `#[serde(default)]` compatibility contract.
        let legacy: RunOutput = serde_json::from_str(
            r#"{"snapshot":[],"report":{"feature_errors":[],"unresolved":[],"display_errors":[],"feature_timings":[],"feature_outputs":[],"frames":[],"profiles":[]},"provenance":[],"entity_origin":[]}"#,
        )
        .expect("legacy reply deserializes");
        assert!(legacy.assembly_poses.is_empty() && legacy.moved_solids.is_empty());
        // ...including a reply from before the report carried `paths` at all: an
        // in-flight worker message of the OLD shape still reads, with no paths.
        assert!(legacy.report.paths.is_empty() && legacy.report.axes.is_empty());
    }
}