brep_render/engine_state/

assembly_overlay.rs

//! Assembly-constraint viewport overlays + GRABBABLE distance/angle handles
//! (build-spec §8.4) — the engine-state half of [`crate::constraint_overlays`].
//!
//! Lifecycle: [`EngineState::refresh_constraint_overlay`] pulls the kernel
//! session's `assembly_overlay_json` + `assembly_state_json`, folds them into
//! the cached [`ConstraintOverlay`] records, and bakes the leader/arrow/arc
//! triangle group. It runs after EVERY history apply (`finish_apply`) and after
//! every constraint mutation this module commits;
//! [`EngineState::ensure_constraint_overlay_current`] (called once per app
//! frame) re-bakes on a material camera-zoom change (the arc/rod sizing is
//! screen-constant) and clears/restores the group when the Show Constraint
//! Graphics setting or sketch mode toggles.
//!
//! Dragging: a press on a DISTANCE leader (capsule region) or an ANGLE arc
//! sweep-end handle (circle region) begins a drag that PREVIEWS the value
//! locally (annotation + label track the pointer; no kernel call per move).
//! A PLANE-BASED distance drag measures the SIGNED offset along the base-face
//! normal the overlay builder stashed in the annotation (negative = through
//! the face to its far side — the kernel mapper's `d = (P − base)·n̂` sign
//! convention, so drag and solver always agree);
//! release COMMITS `assembly_update_constraint_json(id, {…, distance|angle})`,
//! which auto-solves. The reply's `movedSolids` display seam is consumed
//! (re-posed resident solids re-tessellate in place) and the solved state is
//! folded back into the engine's history document (`assembly_apply_document_json`
//! — the pose-authority contract, wired here for the DRAG path; the per-run fold
//! is lane F/H's runner-altitude wiring).
//!
//! NATIVE-SAFETY RULE: the kernel's fallible `assembly_*` exports return
//! `Result<_, JsValue>`, and constructing a `JsValue` ABORTS off-wasm — so every
//! call is guarded (the constraint must exist in the LIVE session state, checked
//! through the infallible `assembly_state_json`) and the `Err` arm is reached
//! only on wasm, where `JsValue` works.

use super::feature_dims::closest_t_on_axis;
use super::*;
use crate::constraint_overlays::{
    build_constraint_overlays, constraint_overlay_buffers, status_color, ConstraintOverlay,
    ConstraintOverlayKind,
};
use brep_gizmos::hit_region::{point_region, segment_region, HitShape};

/// The world-space overlay group carrying the constraint leaders + handles.
/// Sits just under the feature-dim gizmo group (10003) so an armed feature
/// gizmo draws over constraint graphics.
const CONSTRAINT_OVERLAY_GROUP: &str = "assembly-constraint-overlay";

impl EngineState {
    // -----------------------------------------------------------------------
    // Refresh / bake
    // -----------------------------------------------------------------------

    /// Rebuild the constraint-overlay cache from the LIVE kernel session and
    /// re-bake the drawn group. Cleared (empty group) while the Show Constraint
    /// Graphics setting is off or a sketch edit is active. A live handle drag's
    /// preview survives the rebuild (re-applied onto the fresh cache).
    pub fn refresh_constraint_overlay(&mut self) {
        if !self.settings.show_constraint_graphics || self.sketch_mode() {
            self.clear_constraint_overlay();
            return;
        }
        let overlay_json = brep_kernel::assembly_overlay_json();
        let state_json = brep_kernel::assembly_state_json();
        self.refresh_constraint_overlay_from(&overlay_json, &state_json);
    }

    /// [`Self::refresh_constraint_overlay`] with explicit payloads (the parsed
    /// `assembly_overlay_json` array + `assembly_state_json` object) — the
    /// testable seam: canned payloads exercise the whole cache/pick/drag path
    /// without a kernel session.
    pub fn refresh_constraint_overlay_from(&mut self, overlay_json: &str, state_json: &str) {
        let rows: serde_json::Value =
            serde_json::from_str(overlay_json).unwrap_or(serde_json::Value::Null);
        let state: serde_json::Value =
            serde_json::from_str(state_json).unwrap_or(serde_json::Value::Null);
        let constraints = state
            .get("constraints")
            .cloned()
            .unwrap_or(serde_json::Value::Null);
        self.constraint_overlays = build_constraint_overlays(&rows, &constraints);
        self.apply_constraint_drag_preview();
        self.bake_constraint_overlay();
    }

    /// Clear the cache + the drawn group (setting off / sketch mode / no session).
    fn clear_constraint_overlay(&mut self) {
        let had = !self.constraint_overlays.is_empty() || self.constraint_overlay_wpp != 0.0;
        self.constraint_overlays.clear();
        self.constraint_overlay_wpp = 0.0;
        if had {
            let _ = self.set_overlay_json(
                &serde_json::json!({ "groups": [ { "name": CONSTRAINT_OVERLAY_GROUP } ] })
                    .to_string(),
            );
        }
    }

    /// Bake the cached overlays into the drawn triangle group at the CURRENT
    /// camera zoom (screen-constant sizing) and remember the baked
    /// `world_per_pixel` for [`Self::ensure_constraint_overlay_current`].
    fn bake_constraint_overlay(&mut self) {
        let wpp = self.camera.world_per_pixel();
        let (positions, colors) = constraint_overlay_buffers(&self.constraint_overlays, wpp);
        let _ = self.set_overlay_json(
            &serde_json::json!({
                "groups": [
                    {
                        "name": CONSTRAINT_OVERLAY_GROUP,
                        "renderOrder": 10002,
                        "tris": { "positions": positions, "colors": colors },
                    }
                ]
            })
            .to_string(),
        );
        self.constraint_overlay_wpp = if wpp > 0.0 { wpp } else { f64::MIN_POSITIVE };
    }

    /// Per-frame upkeep (the app viewport calls this once per frame): hide the
    /// group while the setting is off / sketch mode is active, restore it when
    /// they flip back, and re-bake when the camera zoom moved the
    /// `world_per_pixel` materially (>0.5%) so the screen-constant arc/rod
    /// sizing stays pixel-true. Re-bakes only on actual change, so a quiet
    /// frame stays quiet (no dirty loop).
    pub fn ensure_constraint_overlay_current(&mut self) {
        let want = self.settings.show_constraint_graphics && !self.sketch_mode();
        if !want {
            self.clear_constraint_overlay();
            return;
        }
        if self.constraint_overlay_wpp == 0.0 {
            // Hidden → shown transition (toggle flipped back on / sketch exited):
            // pull fresh session state.
            self.refresh_constraint_overlay();
            return;
        }
        if self.constraint_overlays.is_empty() {
            return;
        }
        let wpp = self.camera.world_per_pixel();
        if super::overlay_wpp_stale(self.constraint_overlay_wpp, wpp) {
            self.bake_constraint_overlay();
        }
    }

    /// The cached overlay records (read-only view for the app's label pass +
    /// tests).
    pub fn constraint_overlays(&self) -> &[ConstraintOverlay] {
        &self.constraint_overlays
    }

    /// The label feed for the app's chip pass:
    /// `[{id, type, icon, text, status, message, color:[r,g,b], world:[x,y,z],
    /// draggable, selected}]`. `text` leads with `icon` (the type's glyph), so
    /// the chip is a picture plus the measure; `id` is for the hover tooltip. One row per cached overlay with a resolvable label anchor
    /// (the leader midpoint / arc mid-sweep / anchor midpoint). `selected`
    /// marks the label-click-selected constraint (thicker chip border). Empty
    /// while hidden.
    pub fn constraint_labels_json(&self) -> String {
        let wpp = self.camera.world_per_pixel();
        let rows: Vec<serde_json::Value> = self
            .constraint_overlays
            .iter()
            .filter_map(|overlay| {
                let world = overlay.label_anchor(wpp)?;
                let color = status_color(&overlay.status);
                Some(serde_json::json!({
                    "id": overlay.id,
                    "type": overlay.constraint_type,
                    "icon": overlay.icon,
                    "text": overlay.label_text(),
                    "status": overlay.status,
                    "message": overlay.message,
                    "color": [color[0], color[1], color[2]],
                    "world": world,
                    "draggable": overlay.draggable,
                    "selected": self.selected_constraint.as_deref() == Some(overlay.id.as_str()),
                }))
            })
            .collect();
        serde_json::Value::Array(rows).to_string()
    }

    // -----------------------------------------------------------------------
    // Label hover (highlight referenced geometry) + click (expand in panel)
    // -----------------------------------------------------------------------

    /// Hover a constraint LABEL: highlight the referenced elements
    /// (`inputParams.elements`) through the existing emphasis machinery —
    /// faces/edges by kernel name, a `{solid}@x,y,z` vertex ref or a bare
    /// component id by its owning solid(s). Deduped by constraint id so a held
    /// hover never re-bumps the emphasis generation. Sets the one-frame
    /// [`Self::take_constraint_label_hover`] flag either way so the viewport's
    /// scene-hover pass yields.
    pub fn constraint_hover(&mut self, id: &str) {
        self.constraint_label_hover_active = true;
        if self.constraint_hovered.as_deref() == Some(id) {
            return;
        }
        let elements = match self.constraint_overlays.iter().find(|o| o.id == id) {
            Some(overlay) => overlay.elements.clone(),
            None => Vec::new(),
        };
        // Classify each element against the display scene FIRST (immutable
        // reads), then write the emphasis in one go.
        let mut solids: Vec<String> = Vec::new();
        let mut faces: Vec<String> = Vec::new();
        let mut edges: Vec<String> = Vec::new();
        for element in &elements {
            if let Some(at) = element.find('@') {
                // Vertex ref "{solid}@x,y,z" → highlight the owning solid.
                solids.push(element[..at].to_string());
                continue;
            }
            if self.scene_has_face(element) {
                faces.push(element.clone());
            } else if self.scene_has_edge(element) {
                edges.push(element.clone());
            } else if self.scene.solids().iter().any(|s| s.name == *element) {
                solids.push(element.clone());
            } else {
                // A bare component ref (`ACOMP2`) → its member solids
                // (`ACOMP2:…`, the namespaced-prefix convention).
                let prefix = format!("{element}:");
                solids.extend(
                    self.scene
                        .solids()
                        .iter()
                        .filter(|s| s.name.starts_with(&prefix))
                        .map(|s| s.name.clone()),
                );
            }
        }
        self.clear_hover();
        self.emphasis.hovered_solids.extend(solids);
        self.emphasis.hovered_faces.extend(faces);
        self.emphasis.hovered_edges.extend(edges);
        self.emphasis.generation = self.emphasis.generation.wrapping_add(1);
        self.constraint_hovered = Some(id.to_string());
        self.dirty = true;
    }

    /// The pointer left the constraint labels: drop the element highlight (only
    /// if a label hover set one — never clobbers an unrelated scene hover).
    pub fn constraint_hover_end(&mut self) {
        if self.constraint_hovered.take().is_some() {
            self.clear_hover();
        }
    }

    /// Consume the one-frame "a constraint label is hovering elements" flag —
    /// the viewport's modeling hover branch skips its scene re-hover while set
    /// (mirrors [`Self::take_sketch_list_hover`]) so the label-driven highlight
    /// survives the frame without a per-frame clobber/re-apply dirty loop.
    pub fn take_constraint_label_hover(&mut self) -> bool {
        std::mem::take(&mut self.constraint_label_hover_active)
    }

    /// A constraint LABEL was clicked: SELECT that constraint (the chip gains
    /// its selected accent, the context bar offers Delete constraint) and OPEN
    /// it through the ACCORDION open ([`Self::assembly_set_constraint_open`] —
    /// every other constraint closes, so the clicked one is the ONE open
    /// constraint, which is what puts the panel into its dialog). Guarded on the
    /// id existing in the live session (the fallible export's error path would
    /// abort off-wasm).
    pub fn constraint_label_clicked(&mut self, id: &str) {
        if !live_constraint_exists(id) {
            return;
        }
        self.selected_constraint = Some(id.to_string());
        let _ = self.assembly_set_constraint_open(id, true);
        self.dirty = true;
    }

    /// The constraint SELECTED via its viewport label (or `None`), pruned
    /// against the live session — a deleted / undone constraint never lingers
    /// as selected.
    pub fn selected_constraint(&self) -> Option<String> {
        let id = self.selected_constraint.as_deref()?;
        live_constraint_exists(id).then(|| id.to_string())
    }

    /// Drop the constraint selection (the Clear action, Esc, and the context
    /// bar's delete all route here — directly or via `clear_selection`).
    pub fn constraint_deselect(&mut self) {
        if self.selected_constraint.take().is_some() {
            self.dirty = true;
        }
    }

    fn scene_has_face(&self, name: &str) -> bool {
        self.scene
            .solids()
            .iter()
            .any(|solid| solid.faces.iter().any(|face| face.name == name))
    }

    fn scene_has_edge(&self, name: &str) -> bool {
        self.scene
            .solids()
            .iter()
            .any(|solid| solid.edges.iter().any(|edge| edge.name == name))
    }

    // -----------------------------------------------------------------------
    // Grabbable handles: pick + drag preview + commit
    // -----------------------------------------------------------------------

    /// The SCREEN-space pickable regions of the DRAGGABLE constraint handles,
    /// each paired with its constraint id: a distance leader's whole CAPSULE
    /// (`point_a → point_b`), an angle arc's sweep-end handle CIRCLE — the same
    /// region family (and the same generous `ARROW_HANDLE_HIT_RAD_PX`) as the
    /// feature-dimension arrows, built by the shared `brep_gizmos::hit_region`
    /// projectors. Non-draggable overlays (expression-valued params, leader-only
    /// types) contribute nothing.
    fn constraint_hit_regions(&self) -> Vec<(String, HitShape)> {
        if !self.settings.show_constraint_graphics || self.sketch_mode() {
            return Vec::new();
        }
        let wpp = self.camera.world_per_pixel();
        let radius = crate::feature_dimensions::ARROW_HANDLE_HIT_RAD_PX as f32;
        let cam = &self.camera;
        let mut out = Vec::new();
        for overlay in &self.constraint_overlays {
            if !overlay.draggable {
                continue;
            }
            let Some(annotation) = &overlay.annotation else {
                continue;
            };
            let shape = match overlay.kind {
                ConstraintOverlayKind::Distance => {
                    segment_region(cam, annotation.point_a, annotation.point_b, radius)
                }
                ConstraintOverlayKind::Angle => point_region(
                    cam,
                    crate::feature_dimensions::arrow_handle_point(annotation, wpp),
                    radius,
                ),
                ConstraintOverlayKind::Leader => None,
            };
            if let Some(shape) = shape {
                out.push((overlay.id.clone(), shape));
            }
        }
        out
    }

    /// Whether a screen-px pick lands on a draggable constraint handle; returns
    /// the grabbed constraint's id (the NEAREST containing region wins). The
    /// viewport routes a drag that starts here into the constraint drag, and
    /// swallows a bare click so the solid behind the arrow isn't selected.
    pub fn constraint_arrow_pick(&self, x: f64, y: f64) -> Option<String> {
        let p = [x as f32, y as f32];
        let mut best: Option<(f32, String)> = None;
        for (id, shape) in self.constraint_hit_regions() {
            let d = shape.spine_distance(p);
            if d <= shape.radius() && best.as_ref().map(|(bd, _)| d < *bd).unwrap_or(true) {
                best = Some((d, id));
            }
        }
        best.map(|(_, id)| id)
    }

    /// Begin a constraint-handle drag at screen `(x, y)`. Returns whether a
    /// draggable handle was grabbed (the viewport then routes the drag here
    /// instead of orbiting the camera).
    pub fn constraint_drag_begin(&mut self, x: f64, y: f64) -> bool {
        let Some(id) = self.constraint_arrow_pick(x, y) else {
            return false;
        };
        let Some(overlay) = self.constraint_overlays.iter().find(|o| o.id == id) else {
            return false;
        };
        let Some(field) = overlay.field_key() else {
            return false;
        };
        let preview = overlay
            .annotation
            .as_ref()
            .map(|a| a.value)
            .or(overlay.value)
            .unwrap_or(0.0);
        self.constraint_drag = Some(ConstraintDrag {
            id,
            field,
            params: overlay.input_params.clone(),
            preview,
        });
        true
    }

    /// Drag a grabbed constraint handle to screen `(x, y)`: map the pointer to a
    /// new value (distance: signed offset along the base-face normal for
    /// plane-based rows, magnitude along the leader otherwise; angle: the
    /// shared arc nearest-projection search, folded to the interior 0–180°),
    /// update the PREVIEW (annotation + label track live), and re-bake. No
    /// kernel call — the commit happens on [`Self::constraint_drag_release`].
    pub fn constraint_drag_to(&mut self, x: f64, y: f64) {
        let Some(id) = self.constraint_drag.as_ref().map(|d| d.id.clone()) else {
            return;
        };
        let Some(overlay) = self.constraint_overlays.iter().find(|o| o.id == id) else {
            return;
        };
        let Some(annotation) = overlay.annotation.clone() else {
            return;
        };
        let kind = overlay.kind;
        let new_value = match kind {
            ConstraintOverlayKind::Distance => {
                let a = annotation.point_a;
                let ray = self.camera.pick_ray(x, y);
                let rd = ray.dir;
                let rn = (rd[0] * rd[0] + rd[1] * rd[1] + rd[2] * rd[2]).sqrt();
                if rn < 1e-12 {
                    return;
                }
                let ray_dir = [rd[0] / rn, rd[1] / rn, rd[2] / rn];
                let n = annotation.axis;
                let raw = if n[0] * n[0] + n[1] * n[1] + n[2] * n[2] > 0.5 {
                    // PLANE-BASED row (the builder stashed the base-face
                    // outward unit normal in `axis`, and drew the arrow from
                    // the perpendicular foot in TRUE world scale): the new
                    // value is simply the pointer's SIGNED offset along that
                    // fixed normal from the foot — dragging through the base
                    // face crosses zero into negatives, the same
                    // `d = (P − base)·n̂` definition the kernel solves.
                    // Deliberately no length guard: a zero-distance arrow
                    // (foot == tip, just the origin sphere) still drags.
                    let Some(t) = closest_t_on_axis(a, n, ray.origin, ray_dir) else {
                        return;
                    };
                    t
                } else {
                    // Plane-less row (line/point pairing — no side to be on):
                    // project onto the anchor-to-anchor leader, map world
                    // distance → param via the measured-value / world-length
                    // ratio, and clamp to the MAGNITUDE domain. `value ≈ 0`
                    // (touching pair) has no ratio: use the world distance.
                    let b = annotation.point_b;
                    let axis = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
                    let len =
                        (axis[0] * axis[0] + axis[1] * axis[1] + axis[2] * axis[2]).sqrt();
                    if len < 1e-9 {
                        return;
                    }
                    let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
                    let Some(t) = closest_t_on_axis(a, dir, ray.origin, ray_dir) else {
                        return;
                    };
                    let ratio = if annotation.value.abs() > 1e-9 {
                        annotation.value / len
                    } else {
                        1.0
                    };
                    (t * ratio).max(0.0)
                };
                (raw * 1e4).round() / 1e4
            }
            ConstraintOverlayKind::Angle => {
                let Some(degrees) = self.angular_drag_degrees(&annotation, x, y) else {
                    return;
                };
                interior_degrees(degrees)
            }
            ConstraintOverlayKind::Leader => return,
        };
        if let Some(drag) = self.constraint_drag.as_mut() {
            drag.preview = new_value;
        }
        self.apply_constraint_drag_preview();
        self.bake_constraint_overlay();
    }

    /// Patch the cached overlay with the live drag's preview value so the drawn
    /// annotation + label track the pointer: a plane-based distance arrow
    /// re-plants its tip at `foot + n̂·preview` (flipping through the base face
    /// for a negative preview), a plane-less leader stretches `point_b` along
    /// its fixed direction, and an angle arc re-sweeps.
    fn apply_constraint_drag_preview(&mut self) {
        let Some(drag) = self.constraint_drag.as_ref() else {
            return;
        };
        let preview = drag.preview;
        let id = drag.id.clone();
        let Some(overlay) = self.constraint_overlays.iter_mut().find(|o| o.id == id) else {
            return;
        };
        let kind = overlay.kind;
        overlay.value = Some(preview);
        if let Some(annotation) = overlay.annotation.as_mut() {
            match kind {
                ConstraintOverlayKind::Distance => {
                    let a = annotation.point_a;
                    let n = annotation.axis;
                    if n[0] * n[0] + n[1] * n[1] + n[2] * n[2] > 0.5 {
                        // Plane-based (base normal in `axis`): the arrow is
                        // drawn in TRUE world scale, so the tip is EXACTLY
                        // `foot + n̂·value` — a negative preview lands it on
                        // the far side of the base face, exactly where the
                        // solve will put the constrained element.
                        annotation.point_b = [
                            a[0] + n[0] * preview,
                            a[1] + n[1] * preview,
                            a[2] + n[2] * preview,
                        ];
                    } else {
                        let b = annotation.point_b;
                        let axis = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
                        let len = (axis[0] * axis[0]
                            + axis[1] * axis[1]
                            + axis[2] * axis[2])
                            .sqrt();
                        if len > 1e-9 && annotation.value.abs() > 1e-9 {
                            // Keep the world-per-value scale the leader had, so
                            // the arrow tip lands where the face will end up.
                            let world_len = preview * (len / annotation.value);
                            let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
                            annotation.point_b = [
                                a[0] + dir[0] * world_len,
                                a[1] + dir[1] * world_len,
                                a[2] + dir[2] * world_len,
                            ];
                        }
                    }
                    annotation.value = preview;
                }
                _ => {
                    annotation.value = preview;
                }
            }
        }
    }

    /// The pending commit `(constraint id, inputParams JSON)` a release would
    /// send — the drag's params snapshot with the dragged field set to the
    /// preview value. `None` when no drag is live. (The pure half of
    /// [`Self::constraint_drag_release`], separated for tests.)
    ///
    /// Angle display convention: the drag preview is the INTERIOR arc sweep
    /// (what the arc draws and the kernel's overlay `value` measures), but the
    /// stored `inputParams.angle` is the DISPLAY angle — exterior-remapped when
    /// the constraint's `exteriorAngle` toggle is on (`map_angle`'s contract) —
    /// so the commit remaps `interior → 180 − interior` for those.
    pub fn constraint_drag_commit_payload(&self) -> Option<(String, String)> {
        let drag = self.constraint_drag.as_ref()?;
        let mut params = drag.params.clone();
        if !params.is_object() {
            params = serde_json::json!({});
        }
        let exterior = drag.field == "angle"
            && params
                .get("exteriorAngle")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
        let committed = if exterior {
            180.0 - drag.preview
        } else {
            drag.preview
        };
        let object = params.as_object_mut().expect("object ensured above");
        object.insert(drag.field.to_string(), serde_json::json!(committed));
        object.insert("id".to_string(), serde_json::json!(drag.id));
        Some((drag.id.clone(), params.to_string()))
    }

    /// Release the constraint-handle drag: COMMIT the previewed value via
    /// `assembly_update_constraint_json` (auto-solves), consume the reply's
    /// `movedSolids` display seam (re-posed resident solids re-tessellate in
    /// place), fold the solved poses back into the engine's history document
    /// (pose-authority contract, drag path), and refresh the overlay from the
    /// post-solve session. A commit against a session that no longer has the
    /// constraint (or no session at all — canned-payload tests, the native
    /// thread-runner seam) drops the preview with a notice instead.
    pub fn constraint_drag_release(&mut self) {
        let Some((id, params_json)) = self.constraint_drag_commit_payload() else {
            self.constraint_drag = None;
            return;
        };
        self.constraint_drag = None;
        if !live_constraint_exists(&id) {
            self.notices
                .push(format!("Constraint {id}: no live assembly session to update"));
            self.refresh_constraint_overlay();
            return;
        }
        match brep_kernel::assembly_update_constraint_json(&id, &params_json) {
            Ok(report) => {
                self.consume_assembly_moved_solids(&report);
                self.adopt_assembly_fold();
            }
            // Reachable only on wasm (the guard above covers the native abort
            // hazard of constructing the error JsValue off-wasm).
            Err(error) => {
                let message = error
                    .as_string()
                    .unwrap_or_else(|| "constraint update failed".to_string());
                self.notices.push(format!("Constraint {id}: {message}"));
            }
        }
        self.refresh_constraint_overlay();
        self.dirty = true;
    }

    // -----------------------------------------------------------------------
    // Solve write-backs: movedSolids display seam + the document fold
    // -----------------------------------------------------------------------

    /// Consume a solve report's `movedSolids: [{name, handle}]` display seam:
    /// those resident solids were RE-POSED IN PLACE by the solver (their
    /// producing feature replayed `reused`, so the run delta kept the stale
    /// mesh) — re-tessellate each from its live resident handle and replace its
    /// display, preserving per-solid view state (visibility, color override).
    /// The key is absent on zero-mate reports; absence is tolerated.
    pub fn consume_assembly_moved_solids(&mut self, report_json: &str) {
        let Ok(report) = serde_json::from_str::<serde_json::Value>(report_json) else {
            return;
        };
        let Some(moved) = report.get("movedSolids").and_then(|v| v.as_array()) else {
            return;
        };
        let lod = if self.settings.lod_factor.is_finite() && self.settings.lod_factor > 0.0 {
            self.settings.lod_factor
        } else {
            1.0
        };
        let mut changed = false;
        for entry in moved {
            let Some(name) = entry.get("name").and_then(|v| v.as_str()) else {
                continue;
            };
            let Some(handle) = entry
                .get("handle")
                .and_then(|v| v.as_u64())
                .map(|h| h as u32)
            else {
                continue;
            };
            match brep_kernel::display_payload_handle_native(handle, lod) {
                Ok(payload) => {
                    let mut display = crate::scene::solid_display_from_payload(name, payload);
                    display.source_handle = handle;
                    if let Some(old) = self.scene.solids().iter().find(|s| s.name == name) {
                        display.visible = old.visible;
                    }
                    self.scene.insert_solid(display);
                    changed = true;
                }
                Err(error) => self
                    .notices
                    .push(format!("re-tessellate moved solid {name}: {error}")),
            }
        }
        if changed {
            // Colours are NOT hand-copied off the replaced display: this path
            // builds a fresh one per moved solid, whose per-face colours a copy
            // could not carry. Re-derive the whole scene from the metadata store
            // instead — the same seam every other path colours through.
            self.sync_colors_from_metadata();
            self.dirty = true;
        }
    }

    /// Fold the kernel session's solved state into the engine's history
    /// document (`assembly_apply_document_json`: the `assembly` block + solved
    /// poses/isFixed onto the owning features by `inputParams.id`) and ADOPT the
    /// result — so persisting or re-running uses the solved poses
    /// (pose-authority contract). Wired for the DRAG-COMMIT path here; callers
    /// must ensure a live session exists (this runs right after a successful
    /// mutation). No history re-run: the scene was already refreshed through
    /// the movedSolids seam.
    fn adopt_assembly_fold(&mut self) {
        let document = self.history.request_json();
        match brep_kernel::assembly_apply_document_json(&document) {
            Ok(folded) => {
                if let Err(error) = self.history.adopt_folded_request(&folded) {
                    self.notices.push(format!("assembly fold: {error}"));
                }
            }
            // Reachable only on wasm (see the native-safety rule above).
            Err(error) => {
                let message = error
                    .as_string()
                    .unwrap_or_else(|| "assembly document fold failed".to_string());
                self.notices.push(format!("assembly fold: {message}"));
            }
        }
    }
}

/// Whether the LIVE kernel session currently holds a constraint with `id` —
/// checked through the infallible `assembly_state_json` export so the guard
/// itself can never hit a fallible export's off-wasm-aborting error path.
fn live_constraint_exists(id: &str) -> bool {
    serde_json::from_str::<serde_json::Value>(&brep_kernel::assembly_state_json())
        .ok()
        .and_then(|state| {
            state.get("constraints").and_then(|list| {
                list.as_array().map(|entries| {
                    entries.iter().any(|entry| {
                        entry
                            .get("inputParams")
                            .and_then(|p| p.get("id"))
                            .and_then(|v| v.as_str())
                            == Some(id)
                    })
                })
            })
        })
        .unwrap_or(false)
}

/// Fold an arc sweep (the shared angular drag search's [-360°, 360°] output)
/// onto the INTERIOR angle domain the constraint mate targets (0–180°,
/// unsigned — `angle_between_deg` symmetry), snapping the sub-0.5° residue of
/// the search's zero-floor to an exact 0 (parallel is a legitimate target).
fn interior_degrees(degrees: f64) -> f64 {
    let folded = degrees.abs() % 360.0;
    let interior = if folded > 180.0 { 360.0 - folded } else { folded };
    if interior < 0.5 {
        0.0
    } else {
        interior
    }
}

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

    /// An 800×600 ortho engine looking down -Z at `target` (the canned-payload
    /// harness — mirrors the feature-dim test cameras).
    fn ortho_engine(target: [f64; 3]) -> EngineState {
        let mut state = EngineState::new();
        state.resize(800.0, 600.0);
        state.camera.eye = [target[0], target[1], target[2] + 40.0];
        state.camera.target = target;
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };
        state
    }

    fn distance_rows() -> String {
        serde_json::json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[0.0, 0.0, 0.0], [8.0, 0.0, 0.0]],
            "directions": [[1.0, 0.0, 0.0], [-1.0, 0.0, 0.0]],
            "value": 8.0, "unit": "mm",
        }])
        .to_string()
    }

    fn state_json(params: serde_json::Value) -> String {
        serde_json::json!({
            "constraints": [{ "type": "distance", "inputParams": params,
                              "persistentData": {}, "enabled": true, "open": false }],
            "idCounter": 1
        })
        .to_string()
    }

    #[test]
    fn canned_distance_pick_drag_preview_and_commit_payload() {
        let mut state = ortho_engine([4.0, 0.0, 0.0]);
        state.refresh_constraint_overlay_from(
            &distance_rows(),
            &state_json(serde_json::json!({
                "id": "DIST1", "elements": ["A_PX", "B_NX"], "distance": 8.0
            })),
        );
        assert_eq!(state.constraint_overlays().len(), 1);
        let ann = state.constraint_overlays()[0]
            .annotation
            .clone()
            .expect("linear annotation");

        // The WHOLE leader capsule is grabbable — pick at the projected midpoint.
        let mid = ann.midpoint();
        let (mx, my, depth) = state.camera.project(mid);
        assert!(depth > 0.0);
        assert_eq!(state.constraint_arrow_pick(mx, my).as_deref(), Some("DIST1"));
        assert!(state.constraint_arrow_pick(5.0, 5.0).is_none(), "empty corner grabs nothing");

        // Grab + drag the arrow to the world point 5 units along the leader:
        // preview tracks the pointer (ratio value/len = 1 here).
        assert!(state.constraint_drag_begin(mx, my));
        let target_world = [
            ann.point_a[0] + 5.0,
            ann.point_a[1],
            ann.point_a[2],
        ];
        let (tx, ty, tdepth) = state.camera.project(target_world);
        assert!(tdepth > 0.0);
        state.constraint_drag_to(tx, ty);
        let drag = state.constraint_drag.clone().expect("drag live");
        assert!((drag.preview - 5.0).abs() < 0.05, "preview ≈ 5, got {}", drag.preview);
        // The preview is reflected in the cached overlay (label + arrow follow).
        assert!(
            (state.constraint_overlays()[0].value.unwrap() - drag.preview).abs() < 1e-9,
            "label value tracks the preview"
        );
        let previewed = state.constraint_overlays()[0].annotation.as_ref().unwrap();
        assert!(
            (previewed.point_b[0] - 5.0).abs() < 0.05,
            "arrow tip tracks the preview: {:?}",
            previewed.point_b
        );

        // The commit payload: the original params with the dragged field set.
        let (id, params_json) = state.constraint_drag_commit_payload().expect("payload");
        assert_eq!(id, "DIST1");
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["distance"].as_f64().unwrap() - drag.preview).abs() < 1e-9);
        assert_eq!(params["elements"][0], "A_PX", "untouched params ride along");
        assert_eq!(params["id"], "DIST1");

        // Release without a live kernel session: the commit is refused with a
        // notice (never the off-wasm-aborting error path), the drag ends, and
        // the overlay re-reads the (empty) live session.
        state.constraint_drag_release();
        assert!(state.constraint_drag.is_none());
        let notices = state.take_notices();
        assert!(
            notices.iter().any(|n| n.contains("DIST1")),
            "refused commit surfaces a notice: {notices:?}"
        );
    }

    #[test]
    fn plane_based_distance_drag_is_signed_and_hit_matches_draw() {
        // A base face tilted in the view plane (n̂ = [1,1,0]/√2 — NOT axis
        // aligned) at Q with the other anchor P off the perpendicular: the
        // arrow must be the foot→P perpendicular segment, the HIT capsule must
        // be built from those SAME endpoints (draw == hit), and dragging the
        // tip THROUGH the base face must preview a NEGATIVE value.
        let mut state = ortho_engine([3.0, 0.0, 0.0]);
        let r = 1.0 / 2.0_f64.sqrt();
        let s = 8.0 / 2.0_f64.sqrt(); // (P − Q)·n̂ = (7 + 1)/√2
        let rows = serde_json::json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[0.0, 0.0, 0.0], [7.0, 1.0, 0.0]],
            "directions": [[r, r, 0.0], null],
            "geoms": ["plane", "point"],
            "value": s, "unit": "mm",
        }])
        .to_string();
        state.refresh_constraint_overlay_from(
            &rows,
            &state_json(serde_json::json!({
                "id": "DIST1", "elements": ["A_TILT", "B_PT"], "distance": s
            })),
        );
        let ann = state.constraint_overlays()[0]
            .annotation
            .clone()
            .expect("linear annotation");
        // Perpendicular-foot construction: foot = P − s·n̂ = (3, −3, 0).
        let foot = [3.0, -3.0, 0.0];
        for i in 0..3 {
            assert!((ann.point_a[i] - foot[i]).abs() < 1e-9, "foot: {:?}", ann.point_a);
            assert!((ann.axis[i] - [r, r, 0.0][i]).abs() < 1e-9, "axis: {:?}", ann.axis);
        }
        assert_eq!(ann.point_b, [7.0, 1.0, 0.0], "tip at the other anchor");

        // Draw == hit: the capsule region is built from the SAME endpoints the
        // arrow is drawn with (the red debug outline stays the pickable area).
        let regions = state.constraint_hit_regions();
        assert_eq!(regions.len(), 1);
        assert_eq!(regions[0].0, "DIST1");
        let HitShape::Capsule { a, b, r: rad } = regions[0].1 else {
            panic!("distance handle is a capsule: {:?}", regions[0].1);
        };
        let (ax, ay, _) = state.camera.project(ann.point_a);
        let (bx, by, _) = state.camera.project(ann.point_b);
        assert!((a[0] as f64 - ax).abs() < 1e-3 && (a[1] as f64 - ay).abs() < 1e-3);
        assert!((b[0] as f64 - bx).abs() < 1e-3 && (b[1] as f64 - by).abs() < 1e-3);
        assert!(rad as f64 >= crate::feature_dimensions::ARROW_HANDLE_HIT_RAD_PX - 1e-6);
        // …and the OLD naive anchor-to-anchor chord is NOT the pickable area:
        // its midpoint (2.1 world units off the perpendicular ≈ 32 px, beyond
        // the 18 px capsule radius) grabs nothing.
        let (nx, ny, _) = state.camera.project([3.5, 0.5, 0.0]);
        assert!(state.constraint_arrow_pick(nx, ny).is_none(), "stale chord must miss");

        // Grab the arrow and drag the pointer to foot + n̂·(−3), THROUGH the
        // base face: the preview is the SIGNED offset −3 and the tip flips to
        // the far side (exactly the pointer's world target).
        let (mx, my, depth) = state.camera.project(ann.midpoint());
        assert!(depth > 0.0);
        assert!(state.constraint_drag_begin(mx, my));
        let target = [foot[0] - r * 3.0, foot[1] - r * 3.0, 0.0];
        let (tx, ty, tdepth) = state.camera.project(target);
        assert!(tdepth > 0.0);
        state.constraint_drag_to(tx, ty);
        let preview = state.constraint_drag.as_ref().unwrap().preview;
        assert!((preview + 3.0).abs() < 0.01, "signed preview ≈ −3, got {preview}");
        let previewed = state.constraint_overlays()[0].annotation.as_ref().unwrap();
        for i in 0..3 {
            assert!(
                (previewed.point_b[i] - target[i]).abs() < 0.01,
                "tip on the far side of the base face: {:?}",
                previewed.point_b
            );
        }
        assert!((previewed.value - preview).abs() < 1e-9);

        // The commit payload carries the NEGATIVE distance verbatim.
        let (id, params_json) = state.constraint_drag_commit_payload().expect("payload");
        assert_eq!(id, "DIST1");
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["distance"].as_f64().unwrap() - preview).abs() < 1e-9);
        assert!(params["distance"].as_f64().unwrap() < 0.0);
    }

    #[test]
    fn expression_valued_distance_param_is_not_grabbable() {
        let mut state = ortho_engine([4.0, 0.0, 0.0]);
        state.refresh_constraint_overlay_from(
            &distance_rows(),
            &state_json(serde_json::json!({
                "id": "DIST1", "elements": [], "distance": "gap * 2"
            })),
        );
        assert_eq!(state.constraint_overlays().len(), 1);
        assert!(!state.constraint_overlays()[0].draggable);
        // The graphics exist, but no hit region is built and no drag begins.
        let ann = state.constraint_overlays()[0].annotation.clone().unwrap();
        let (mx, my, _) = state.camera.project(ann.midpoint());
        assert!(state.constraint_arrow_pick(mx, my).is_none());
        assert!(!state.constraint_drag_begin(mx, my));
    }

    #[test]
    fn angle_arc_drag_maps_to_interior_degrees() {
        // Carriers +X / +Y meeting at the origin, measured 90° — the arc sweeps
        // about +Z, so look straight down +Z (the arc plane faces the camera).
        let mut state = ortho_engine([0.0, 0.0, 0.0]);
        let rows = serde_json::json!([{
            "id": "ANGL1", "type": "angle", "status": "adjusted", "message": "",
            "anchors": [[5.0, 0.0, 0.0], [0.0, 5.0, 0.0]],
            "directions": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
            "value": 90.0, "unit": "deg",
        }])
        .to_string();
        let constraints = serde_json::json!({
            "constraints": [{ "type": "angle",
                "inputParams": { "id": "ANGL1", "elements": [], "angle": 90.0 },
                "persistentData": {}, "enabled": true, "open": false }],
            "idCounter": 1
        })
        .to_string();
        state.refresh_constraint_overlay_from(&rows, &constraints);
        let ann = state.constraint_overlays()[0]
            .annotation
            .clone()
            .expect("angular annotation");
        let wpp = state.world_per_pixel();

        // Grab the arc's sweep-end handle sphere.
        let handle = crate::feature_dimensions::arrow_handle_point(&ann, wpp);
        let (hx, hy, hdepth) = state.camera.project(handle);
        assert!(hdepth > 0.0);
        assert_eq!(state.constraint_arrow_pick(hx, hy).as_deref(), Some("ANGL1"));
        assert!(state.constraint_drag_begin(hx, hy));

        // Drag to the arc point at 135°: the shared angular search recovers the
        // swept degrees (1° snap) and the constraint folds them to the interior.
        let radius = crate::feature_dimensions::ANGLE_ARC_RAD_PX * wpp;
        let dir = crate::feature_dimensions::rotate_about_axis(
            ann.ref_dir,
            ann.axis,
            135.0_f64.to_radians(),
        );
        let world = [
            ann.center[0] + dir[0] * radius,
            ann.center[1] + dir[1] * radius,
            ann.center[2] + dir[2] * radius,
        ];
        let (sx, sy, sdepth) = state.camera.project(world);
        assert!(sdepth > 0.0);
        state.constraint_drag_to(sx, sy);
        let preview = state.constraint_drag.as_ref().unwrap().preview;
        assert!((preview - 135.0).abs() < 2.0, "interior sweep ≈ 135, got {preview}");
        let (_, params_json) = state.constraint_drag_commit_payload().expect("payload");
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["angle"].as_f64().unwrap() - preview).abs() < 1e-9);

        // A drag to the OTHER side of the zero reference (-30°) folds to the
        // interior 30° — the mate's angle domain is unsigned.
        let dir = crate::feature_dimensions::rotate_about_axis(
            ann.ref_dir,
            ann.axis,
            (-30.0_f64).to_radians(),
        );
        let world = [
            ann.center[0] + dir[0] * radius,
            ann.center[1] + dir[1] * radius,
            ann.center[2] + dir[2] * radius,
        ];
        let (sx, sy, _) = state.camera.project(world);
        state.constraint_drag_to(sx, sy);
        let preview = state.constraint_drag.as_ref().unwrap().preview;
        assert!((preview - 30.0).abs() < 2.0, "folded interior ≈ 30, got {preview}");
    }

    #[test]
    fn exterior_angle_commit_remaps_the_display_value() {
        // An angle constraint with `exteriorAngle: true` STORES the exterior
        // display angle (`map_angle` contract) while the arc previews the
        // interior sweep — the commit payload must remap `interior → 180 − x`.
        let mut state = ortho_engine([0.0, 0.0, 0.0]);
        state.constraint_drag = Some(ConstraintDrag {
            id: "ANGL1".to_string(),
            field: "angle",
            params: serde_json::json!({
                "id": "ANGL1", "elements": [], "angle": 120.0, "exteriorAngle": true
            }),
            preview: 30.0,
        });
        let (_, params_json) = state.constraint_drag_commit_payload().expect("payload");
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["angle"].as_f64().unwrap() - 150.0).abs() < 1e-9);
        // Without the toggle the interior sweep commits verbatim; a distance
        // drag never remaps regardless of stray flags.
        state.constraint_drag.as_mut().unwrap().params["exteriorAngle"] =
            serde_json::json!(false);
        let (_, params_json) = state.constraint_drag_commit_payload().unwrap();
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["angle"].as_f64().unwrap() - 30.0).abs() < 1e-9);
        state.constraint_drag = Some(ConstraintDrag {
            id: "DIST1".to_string(),
            field: "distance",
            params: serde_json::json!({ "id": "DIST1", "exteriorAngle": true }),
            preview: 4.0,
        });
        let (_, params_json) = state.constraint_drag_commit_payload().unwrap();
        let params: serde_json::Value = serde_json::from_str(&params_json).unwrap();
        assert!((params["distance"].as_f64().unwrap() - 4.0).abs() < 1e-9);
    }

    #[test]
    fn interior_degrees_folds_the_sweep_domain() {
        assert_eq!(interior_degrees(0.0), 0.0);
        assert_eq!(interior_degrees(0.3), 0.0, "sub-snap residue lands on exact 0");
        assert!((interior_degrees(90.0) - 90.0).abs() < 1e-12);
        assert!((interior_degrees(-90.0) - 90.0).abs() < 1e-12);
        assert!((interior_degrees(180.0) - 180.0).abs() < 1e-12);
        assert!((interior_degrees(210.0) - 150.0).abs() < 1e-12);
        assert!((interior_degrees(-359.0) - 1.0).abs() < 1e-12);
    }

    #[test]
    fn ensure_current_hides_in_sketch_mode_and_rebakes_on_zoom() {
        let mut state = ortho_engine([4.0, 0.0, 0.0]);
        state.refresh_constraint_overlay_from(
            &distance_rows(),
            &state_json(serde_json::json!({ "id": "DIST1", "elements": [], "distance": 8.0 })),
        );
        assert_eq!(state.constraint_overlays().len(), 1);

        // Toggle the setting off → the cache + group clear on the next ensure.
        state.settings.show_constraint_graphics = false;
        state.ensure_constraint_overlay_current();
        assert!(state.constraint_overlays().is_empty(), "hidden while toggled off");

        // Toggle back on → ensure re-pulls the LIVE session (none in this test →
        // stays empty, but the baked flag flips so it would restore).
        state.settings.show_constraint_graphics = true;
        state.ensure_constraint_overlay_current();
        assert!(state.constraint_overlays().is_empty(), "no live session to restore from");

        // Re-seed via the canned payload, then zoom the camera: a material
        // world-per-pixel change re-bakes (dirty), a quiet frame does not.
        state.refresh_constraint_overlay_from(
            &distance_rows(),
            &state_json(serde_json::json!({ "id": "DIST1", "elements": [], "distance": 8.0 })),
        );
        state.dirty = false;
        state.ensure_constraint_overlay_current();
        assert!(!state.dirty, "a quiet frame must not re-bake (no dirty loop)");
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 40.0 };
        state.ensure_constraint_overlay_current();
        assert!(state.dirty, "a zoom change re-bakes the screen-constant sizing");
    }

    // -----------------------------------------------------------------------
    // End-to-end against a LIVE kernel assembly session
    // -----------------------------------------------------------------------

    /// Two ACOMP cube instances (one fixed) + a face-face distance constraint,
    /// executed through the engine's own history lane so the kernel session is
    /// installed on THIS thread (Inline runner). The document CARRIES its
    /// `partsLibrary` block (the load path re-seeds the resident library, which
    /// `set_history_json`'s cache clear resets); the entry ships `document`
    /// only, so the first run exercises the self-heal snapshot lane.
    fn assembly_engine() -> EngineState {
        let part_doc = serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [
                { "type": "P.CU", "inputParams": { "id": "Part", "sizeX": 2.0, "sizeY": 2.0, "sizeZ": 2.0 } }
            ]
        });
        let request = serde_json::json!({
            "expressions": "", "configurator": {},
            "partsLibrary": {
                "lane-g-part": {
                    "sourceKey": "lane-g-part",
                    "sourceSignature": "lane-g-sig",
                    "document": part_doc,
                }
            },
            "features": [
                { "type": "ACOMP", "inputParams": {
                    "id": "ACOMP1", "partName": "lane-g-part",
                    "transform": { "translate": [0, 0, 0], "rotateEulerDeg": [0, 0, 0] },
                    "isFixed": true }, "persistentData": {} },
                { "type": "ACOMP", "inputParams": {
                    "id": "ACOMP2", "partName": "lane-g-part",
                    "transform": { "translate": [10, 0, 0], "rotateEulerDeg": [0, 0, 0] } },
                  "persistentData": {} }
            ],
            "assembly": {
                "constraints": [{
                    "type": "distance",
                    "inputParams": {
                        "id": "DIST1",
                        "elements": ["ACOMP1:Part_PX", "ACOMP2:Part_NX"],
                        "distance": 8.0
                    },
                    "persistentData": {}, "enabled": true, "open": false
                }],
                "idCounter": 1
            }
        });
        let mut state = EngineState::new();
        state
            .set_history_json(&request.to_string())
            .expect("assembly history builds");
        state.resize(800.0, 600.0);
        state.camera.eye = [5.0, 1.0, 40.0];
        state.camera.target = [5.0, 1.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };
        // Re-bake at the test camera (the run-tail refresh used the boot camera).
        state.refresh_constraint_overlay();
        state
    }

    fn display_bbox_lo_x(state: &EngineState, name: &str) -> f64 {
        let solid = state
            .scene
            .solids()
            .iter()
            .find(|s| s.name == name)
            .unwrap_or_else(|| panic!("{name} displayed"));
        solid.bbox.min[0]
    }

    /// Label-click selection + the ACCORDION: clicking a chip SELECTS the
    /// constraint (pruned read + the chip's `selected` flag) and expands it as
    /// the ONE open row — any other open row collapses. Clear and deletion both
    /// drop the selection (the context bar's Clear / ✕ Delete paths).
    #[test]
    fn label_click_selects_and_accordion_keeps_one_row_open() {
        let mut state = assembly_engine();
        // A second constraint so the accordion has something to collapse.
        let second = state
            .assembly_add_constraint(
                "parallel",
                &serde_json::json!({"elements": ["ACOMP1:Part_PX", "ACOMP2:Part_NX"]})
                    .to_string(),
            )
            .expect("second constraint adds");
        state.assembly_set_constraint_open(&second, true).unwrap();

        // Clicking DIST1's label selects it AND makes it the one open row.
        state.constraint_label_clicked("DIST1");
        assert_eq!(state.selected_constraint().as_deref(), Some("DIST1"));
        let session: serde_json::Value =
            serde_json::from_str(&brep_kernel::assembly_state_json()).unwrap();
        let open_ids: Vec<&str> = session["constraints"]
            .as_array()
            .unwrap()
            .iter()
            .filter(|c| c["open"] == true)
            .map(|c| c["inputParams"]["id"].as_str().unwrap())
            .collect();
        assert_eq!(open_ids, ["DIST1"], "accordion: exactly the clicked row is open");

        // The label feed marks the selected chip (thicker border in the app).
        let labels: serde_json::Value =
            serde_json::from_str(&state.constraint_labels_json()).unwrap();
        assert_eq!(labels[0]["id"], "DIST1");
        assert_eq!(labels[0]["selected"], true);

        // Clear drops the constraint selection (the context bar's Clear / Esc).
        assert!(state.clear_selection(), "constraint-only clear reports a change");
        assert_eq!(state.selected_constraint(), None);
        let labels: serde_json::Value =
            serde_json::from_str(&state.constraint_labels_json()).unwrap();
        assert_eq!(labels[0]["selected"], false);

        // Re-select, then DELETE: the pruned read never yields a dead id.
        state.constraint_label_clicked("DIST1");
        state.assembly_remove_constraint("DIST1").unwrap();
        assert_eq!(state.selected_constraint(), None, "deleted → no lingering selection");
    }

    #[test]
    fn live_distance_drag_commits_solves_retessellates_and_folds() {
        let mut state = assembly_engine();

        // The run tail installed the session; the overlay cache reflects it.
        let overlays = state.constraint_overlays();
        assert_eq!(overlays.len(), 1, "one distance overlay: {overlays:?}");
        let overlay = &overlays[0];
        assert_eq!(overlay.id, "DIST1");
        assert_eq!(overlay.kind, ConstraintOverlayKind::Distance);
        assert!(overlay.draggable);
        assert_eq!(overlay.status, "satisfied", "{}", overlay.message);
        let ann = overlay.annotation.clone().expect("linear annotation");
        assert!((ann.value - 8.0).abs() < 1e-6, "measured separation 8: {}", ann.value);

        // Labels: one status-colored row at the leader midpoint.
        let labels: serde_json::Value =
            serde_json::from_str(&state.constraint_labels_json()).unwrap();
        assert_eq!(labels[0]["id"], "DIST1");
        assert_eq!(labels[0]["draggable"], true);
        assert_eq!(labels[0]["text"], "\u{27FA} 8 mm");
        assert_eq!(labels[0]["icon"], "\u{27FA}");
        assert_eq!(labels[0]["type"], "distance");
        let green = crate::constraint_overlays::status_color("satisfied");
        assert!((labels[0]["color"][1].as_f64().unwrap() - green[1] as f64).abs() < 1e-6);

        // Label hover highlights the referenced faces through the emphasis lane;
        // hover-end clears; the one-frame viewport-yield flag is set.
        state.constraint_hover("DIST1");
        assert!(state.emphasis.hovered_faces.contains("ACOMP1:Part_PX"));
        assert!(state.emphasis.hovered_faces.contains("ACOMP2:Part_NX"));
        assert!(state.take_constraint_label_hover());
        assert!(!state.take_constraint_label_hover(), "one-frame flag");
        state.constraint_hover_end();
        assert!(state.emphasis.hovered_faces.is_empty());

        // Label click persists the panel-expansion flag in the session.
        state.constraint_label_clicked("DIST1");
        let session: serde_json::Value =
            serde_json::from_str(&brep_kernel::assembly_state_json()).unwrap();
        assert_eq!(session["constraints"][0]["open"], true);

        // The free instance sits at x ∈ [10, 12] before the drag.
        assert!((display_bbox_lo_x(&state, "ACOMP2:Part") - 10.0).abs() < 1e-6);

        // GRAB the leader and DRAG the arrow to 5 units: preview follows.
        let (mx, my, depth) = state.camera.project(ann.midpoint());
        assert!(depth > 0.0);
        assert!(state.constraint_drag_begin(mx, my), "leader grab");
        let dir = {
            let d = [
                ann.point_b[0] - ann.point_a[0],
                ann.point_b[1] - ann.point_a[1],
                ann.point_b[2] - ann.point_a[2],
            ];
            let n = (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt();
            [d[0] / n, d[1] / n, d[2] / n]
        };
        let target = [
            ann.point_a[0] + dir[0] * 5.0,
            ann.point_a[1] + dir[1] * 5.0,
            ann.point_a[2] + dir[2] * 5.0,
        ];
        let (tx, ty, tdepth) = state.camera.project(target);
        assert!(tdepth > 0.0);
        state.constraint_drag_to(tx, ty);
        let preview = state.constraint_drag.as_ref().unwrap().preview;
        assert!((preview - 5.0).abs() < 0.05, "preview ≈ 5, got {preview}");

        // RELEASE: commits assembly_update_constraint_json → auto-solve.
        state.constraint_drag_release();
        assert!(state.constraint_drag.is_none());

        // 1) The kernel session's target followed the drag.
        let session: serde_json::Value =
            serde_json::from_str(&brep_kernel::assembly_state_json()).unwrap();
        let committed = session["constraints"][0]["inputParams"]["distance"]
            .as_f64()
            .expect("numeric target");
        assert!((committed - preview).abs() < 1e-9, "committed {committed}");

        // 2) The movedSolids display seam re-tessellated the re-posed instance
        //    IN PLACE: the display mesh actually moved (bbox, not just revision).
        assert!(
            (display_bbox_lo_x(&state, "ACOMP2:Part") - 7.0).abs() < 1e-6,
            "ACOMP2:Part re-meshed at its solved pose (lo.x = {})",
            display_bbox_lo_x(&state, "ACOMP2:Part")
        );

        // 3) The pose-authority fold landed the solved pose + assembly block on
        //    the engine's history document.
        let request: serde_json::Value =
            serde_json::from_str(&state.history_request_json()).unwrap();
        let folded = &request["features"][1]["inputParams"]["transform"]["translate"];
        assert!(
            (folded[0].as_f64().unwrap() - 7.0).abs() < 1e-6,
            "folded ACOMP2 pose: {folded}"
        );
        assert_eq!(
            request["assembly"]["constraints"][0]["persistentData"]["status"],
            "satisfied"
        );

        // 4) The overlay refreshed from the post-solve session.
        let overlay = &state.constraint_overlays()[0];
        assert!(
            (overlay.value.unwrap() - preview).abs() < 0.01,
            "overlay value follows the solve: {:?}",
            overlay.value
        );

        // 5) Re-running the folded document is stable: no motion, overlay intact.
        let report = state.roll_to(1);
        assert!(!report.contains("\"error\""), "clean rerun: {report}");
        assert!((display_bbox_lo_x(&state, "ACOMP2:Part") - 7.0).abs() < 1e-6);
        assert_eq!(state.constraint_overlays().len(), 1);

        // 6) NEGATIVE distance, end to end: the refreshed arrow is the
        //    perpendicular foot→anchor segment (foot on ACOMP1's PX plane at
        //    x=2, tip on ACOMP2's NX anchor at x=7); drag the tip THROUGH the
        //    base face to −3 and release — the drag's sign convention and the
        //    solver's DistancePlanePlane residual are the SAME signed offset,
        //    so the component lands on the opposite side (NX plane at x = −1).
        let ann = state.constraint_overlays()[0]
            .annotation
            .clone()
            .expect("refreshed annotation");
        assert!((ann.point_a[0] - 2.0).abs() < 1e-6, "foot on the base plane: {:?}", ann.point_a);
        assert!((ann.point_b[0] - 7.0).abs() < 1e-6, "tip at the other anchor: {:?}", ann.point_b);
        assert!((ann.axis[0] - 1.0).abs() < 1e-9, "base normal +X: {:?}", ann.axis);
        let (mx, my, depth) = state.camera.project(ann.midpoint());
        assert!(depth > 0.0);
        assert!(state.constraint_drag_begin(mx, my), "leader re-grab");
        let (tx, ty, tdepth) = state.camera.project([-1.0, 1.0, 1.0]);
        assert!(tdepth > 0.0);
        state.constraint_drag_to(tx, ty);
        let preview = state.constraint_drag.as_ref().unwrap().preview;
        assert!((preview + 3.0).abs() < 0.05, "signed preview ≈ −3, got {preview}");
        state.constraint_drag_release();
        let session: serde_json::Value =
            serde_json::from_str(&brep_kernel::assembly_state_json()).unwrap();
        let committed = session["constraints"][0]["inputParams"]["distance"]
            .as_f64()
            .expect("numeric target");
        assert!((committed - preview).abs() < 1e-9, "committed {committed}");
        assert!(
            (display_bbox_lo_x(&state, "ACOMP2:Part") + 1.0).abs() < 1e-6,
            "ACOMP2:Part re-meshed BEHIND the base face (lo.x = {})",
            display_bbox_lo_x(&state, "ACOMP2:Part")
        );
        let request: serde_json::Value =
            serde_json::from_str(&state.history_request_json()).unwrap();
        let folded = &request["features"][1]["inputParams"]["transform"]["translate"];
        assert!(
            (folded[0].as_f64().unwrap() + 1.0).abs() < 1e-6,
            "folded negative-side pose: {folded}"
        );
        assert_eq!(
            state.constraint_overlays()[0].label_text(),
            "\u{27FA} -3 mm",
            "signed label after the negative solve"
        );
    }
}