brep_render/engine_state/

feature_dims.rs

use super::*;
use super::sketch_edit_ops::is_plain_number_literal;
use brep_gizmos::hit_region::{point_region, segment_region, HitShape};

/// The world-space overlay group carrying the FD leaders + arrowheads.
const FEATURE_DIM_OVERLAY: &str = "feature-dim-leaders";

/// The role a dimension-gizmo hit region plays. An `Arrow` is a value-drag handle
/// (a linear leader or the angular arc handle, keyed by its `field_key`); `Origin`
/// is the shared origin/center sphere (the mode toggle). Both share ONE region
/// list so the pick + the drawn outline can never drift.
#[derive(Clone, Debug)]
enum DimRole {
    Arrow(String),
    Origin,
}

impl EngineState {
    /// The armed ◎ gizmo mode: `"none"`, `"transform"`, or `"dimension"`. Drives
    /// the ◎ highlight + the app's dimension-overlay draw / input routing.
    pub fn gizmo_mode(&self) -> &'static str {
        match self.transform_gizmo.mode {
            GizmoMode::None => "none",
            GizmoMode::Transform => "transform",
            GizmoMode::Dimension => "dimension",
        }
    }

    /// Whether the DIMENSION gizmo is armed for THIS feature (drives the ◎
    /// dimension-mode highlight).
    pub fn dimension_armed_for(&self, feature_id: &str) -> bool {
        matches!(self.transform_gizmo.mode, GizmoMode::Dimension)
            && self.transform_gizmo.feature_id.as_deref() == Some(feature_id)
    }

    /// The dimension-armed feature id (empty unless in dimension mode).
    pub fn dimension_armed_feature(&self) -> String {
        if matches!(self.transform_gizmo.mode, GizmoMode::Dimension) {
            self.transform_gizmo.feature_id.clone().unwrap_or_default()
        } else {
            String::new()
        }
    }

    /// Arm the DIMENSION gizmo for `feature_id`: hide the transform widget, show
    /// the annotation overlay. Re-arming a different feature moves it.
    pub fn arm_dimension(&mut self, feature_id: &str) {
        // The widget slot is shared — an armed component Move gizmo yields.
        self.component_move_reset();
        self.transform_gizmo.feature_id = Some(feature_id.to_string());
        self.transform_gizmo.mode = GizmoMode::Dimension;
        self.transform_gizmo.drag = None;
        // The transform widget and the dimension overlay are mutually exclusive.
        let _ = self.widgets.set_transform_json("null");
        self.refresh_feature_dimension_overlay();
        self.dirty = true;
    }

    // --- The orange center-sphere ◎ TOGGLE (dimension ↔ transform) ---------
    //
    // A single orange sphere sits at the gizmo center in BOTH modes: the
    // transform gizmo's `HANDLE_CENTER` sphere and the dimension arrows' shared
    // origin sphere project to the same point. Clicking it flips the two modes,
    // mirroring the old app's `CombinedTransformControls` center-handle toggle
    // (pointer-down on `HANDLE_CENTER` calls
    // `toggleDisplayMode`). The viewport routes a bare CLICK here; a DRAG on the
    // center still free-moves via `transform_press` (unchanged).

    /// Whether a screen-px pick in TRANSFORM mode lands on the orange CENTER
    /// free-move sphere (`HANDLE_CENTER`). The viewport uses this to make a bare
    /// click on the center TOGGLE to the dimension arrows (via
    /// [`toggle_to_dimension`](Self::toggle_to_dimension)) instead of swallowing
    /// it as a generic handle click. False in any other gizmo mode.
    pub fn transform_center_pick(&self, x: f64, y: f64) -> bool {
        matches!(self.transform_gizmo.mode, GizmoMode::Transform)
            && self.transform_pick(x, y) == brep_gizmos::transform::HANDLE_CENTER
    }

    /// Whether a screen-px pick in DIMENSION mode lands on an orange ORIGIN
    /// sphere of the armed feature's dimension arrows. Each distinct annotation
    /// draws such a sphere — a LINEAR dim at its `point_a` (a cube's three axis
    /// dims share one, a cone/pyramid draw two), an ANGULAR dim at its arc
    /// `center` (the vertex; its sweep-END sphere is the angle DRAG handle, not a
    /// toggle) — so every one is projected via the camera and hit-tested against
    /// the screen-constant sphere radius. The viewport uses this to TOGGLE back to
    /// the transform gizmo (via [`toggle_to_transform`](Self::toggle_to_transform)),
    /// which is the ONLY way an angular-only feature (a revolve) reaches transform.
    /// False in any other gizmo mode. The hit radius mirrors the gizmo center's own
    /// tolerance (`PX_CENTER_RAD + 2.0`, transform.rs) so the two toggle targets match.
    pub fn dimension_origin_pick(&self, x: f64, y: f64) -> bool {
        // The origin sphere (LINEAR at `point_a`, ANGULAR at the arc `center`) is an
        // `Origin`-role region. 2D-test the cursor against the SAME screen-space
        // regions the outline draws — a point-in-circle test, so what is outlined
        // is exactly what toggles.
        let p = [x as f32, y as f32];
        self.dimension_hit_regions()
            .into_iter()
            .any(|(role, shape)| matches!(role, DimRole::Origin) && shape.contains(p))
    }

    /// Whether a screen-px pick in DIMENSION mode lands on a dimension ARROWHEAD
    /// (a linear leader's orange cone TIP at `point_b`, or an angular arc's orange
    /// sweep-END handle sphere). Returns the grabbed annotation's `field_key` — the
    /// viewport routes a DRAG that starts here to [`feature_dimension_drag`](Self::
    /// feature_dimension_drag), editing that param live (Fix 4). `None` in any other
    /// gizmo mode / when no arrowhead is under the pointer. Distinct from
    /// [`dimension_origin_pick`](Self::dimension_origin_pick): that grabs the SHARED
    /// origin sphere (a mode toggle), this grabs an arrowHEAD (a value edit). The
    /// nearest arrowhead within the screen-constant hit radius wins.
    pub fn dimension_arrow_pick(&self, x: f64, y: f64) -> Option<String> {
        // The NEAREST `Arrow`-role region containing the cursor wins. LINEAR: the
        // WHOLE leader CAPSULE (`point_a → point_b`) is grabbable, so a cursor
        // anywhere on the visible shaft grabs it — even when `point_b` crosses
        // BEHIND the eye (the reported sizeY failure), because in ortho the whole
        // leader still projects (and in perspective the region is front-clipped to
        // its visible part). ANGULAR: the arc sweep-END handle CIRCLE. These are
        // the SAME screen-space regions the outline draws, so what is outlined is
        // exactly what grabs.
        let p = [x as f32, y as f32];
        let mut best: Option<(f32, String)> = None;
        for (role, shape) in self.dimension_hit_regions() {
            if let DimRole::Arrow(key) = role {
                let d = shape.spine_distance(p);
                if d <= shape.radius() && best.as_ref().map(|(bd, _)| d < *bd).unwrap_or(true) {
                    best = Some((d, key));
                }
            }
        }
        best.map(|(_, key)| key)
    }

    /// The authoritative SCREEN-space (viewport-local px) pickable regions of the
    /// armed feature's dimension gizmo, each paired with its [`DimRole`]. The
    /// SINGLE source `dimension_arrow_pick` (its `Arrow` regions), `dimension_origin_pick`
    /// (its `Origin` regions), and `dimension_hit_areas_json` (draws them ALL) all
    /// consume — so the grabbable area is exactly the drawn outline. Projection +
    /// the perspective front-clip happen ONCE in [`brep_gizmos::hit_region`].
    ///   * LINEAR → a leader CAPSULE (`point_a → point_b`, `ARROW_HANDLE_HIT_RAD_PX`)
    ///     with role `Arrow` + an origin CIRCLE (`point_a`, `ORIGIN_SPHERE_RAD_PX + 2`)
    ///     with role `Origin`.
    ///   * ANGULAR → an arc-handle CIRCLE (`arrow_handle_point`,
    ///     `ARROW_HANDLE_HIT_RAD_PX`) with role `Arrow` + an arc-center origin
    ///     CIRCLE (`center`, `ORIGIN_SPHERE_RAD_PX + 2`) with role `Origin`.
    /// Origin balls are deduped by world position (a torus's linear origin + its
    /// angular center coincide) so they match the single drawn sphere. `[]` unless
    /// the DIMENSION gizmo is armed for a feature.
    fn dimension_hit_regions(&self) -> Vec<(DimRole, HitShape)> {
        if !matches!(self.transform_gizmo.mode, GizmoMode::Dimension) {
            return Vec::new();
        }
        let feature = self.dimension_armed_feature();
        if feature.is_empty() {
            return Vec::new();
        }
        let wpp = self.camera.world_per_pixel();
        let arrow_px = crate::feature_dimensions::ARROW_HANDLE_HIT_RAD_PX as f32;
        let origin_px = (crate::feature_dimensions::ORIGIN_SPHERE_RAD_PX + 2.0) as f32;
        let cam = &self.camera;
        let mut out: Vec<(DimRole, HitShape)> = Vec::new();
        let mut origins: Vec<[f64; 3]> = Vec::new();
        for ann in self.feature_dimension_annotations(&feature) {
            match ann.kind {
                crate::feature_dimensions::FeatureDimKind::Linear => {
                    if let Some(shape) = segment_region(cam, ann.point_a, ann.point_b, arrow_px) {
                        out.push((DimRole::Arrow(ann.field_key.clone()), shape));
                    }
                    push_origin_region(&mut out, &mut origins, cam, ann.point_a, origin_px);
                }
                crate::feature_dimensions::FeatureDimKind::Angular => {
                    let handle = crate::feature_dimensions::arrow_handle_point(&ann, wpp);
                    if let Some(shape) = point_region(cam, handle, arrow_px) {
                        out.push((DimRole::Arrow(ann.field_key.clone()), shape));
                    }
                    push_origin_region(&mut out, &mut origins, cam, ann.center, origin_px);
                }
            }
        }
        out
    }

    /// DEBUG overlay: the EXACT SCREEN-space (viewport-local px) pickable regions
    /// of the armed feature's dimension gizmo — the SAME regions
    /// `dimension_arrow_pick` + `dimension_origin_pick` 2D-test the cursor against
    /// ([`dimension_hit_regions`](Self::dimension_hit_regions)) — so the red
    /// outline can NEVER drift from the grabbable area. Each item is a
    /// `{ kind:"capsule", a:[x,y], b:[x,y], r }` (linear leaders) or
    /// `{ kind:"circle", c:[x,y], r }` (origin / arc-handle spheres); the app only
    /// offsets by `rect.min`. `[]` unless the DIMENSION gizmo is armed.
    pub fn dimension_hit_areas_json(&self) -> String {
        let regions = self.dimension_hit_regions();
        super::camera_widgets::hit_shapes_json(regions.iter().map(|(_, shape)| shape))
    }

    /// Toggle the armed ◎ gizmo from TRANSFORM to DIMENSION for the currently
    /// transform-armed feature (the orange center-sphere click). No-op unless a
    /// feature is transform-armed.
    pub fn toggle_to_dimension(&mut self) {
        let feature = self.transform_armed_feature();
        if !feature.is_empty() && self.feature_dimension_annotations_json(&feature) != "[]" {
            self.arm_dimension(&feature);
        }
    }

    /// Toggle the armed ◎ gizmo from DIMENSION to TRANSFORM for the currently
    /// dimension-armed feature (the orange origin-sphere click). No-op unless a
    /// feature is dimension-armed.
    pub fn toggle_to_transform(&mut self) {
        let feature = self.dimension_armed_feature();
        if feature.is_empty() {
            return;
        }
        // A PLANE has NO transform — its placement is fully the orientation +
        // `offset_distance` the offset dimension gizmo drives — so it never gets a
        // transform gizmo: the origin-sphere toggle stays in dimension mode. (Other
        // dim features, e.g. a revolve, still toggle to their transform gizmo.)
        if let Some(index) = self.history.index_of(&feature) {
            if self.history.feature_type(index).as_deref() == Some("P") {
                return;
            }
        }
        self.arm_transform(&feature);
    }

    /// The linear dimension annotations for `feature_id` (resolving expression
    /// params against the live history env first). `[]` for a feature type with
    /// no FD-1 builder / a missing feature.
    fn feature_dimension_annotations(
        &self,
        feature_id: &str,
    ) -> Vec<crate::feature_dimensions::FeatureDimAnnotation> {
        let Some(index) = self.history.index_of(feature_id) else {
            return Vec::new();
        };
        let Some(feature_type) = self.history.feature_type(index) else {
            return Vec::new();
        };
        let Some(params) = self.history.feature_params(index) else {
            return Vec::new();
        };
        let resolved = self.resolve_param_expressions(&params);
        // Resolve any scene references the builder needs (extrude profile plane,
        // revolve axis line) from the run report's profiles/axes — keyed off the
        // ORIGINAL params so reference-name strings are read verbatim.
        let refs = self.feature_dimension_refs(&feature_type, &params);
        crate::feature_dimensions::build_annotations_with_refs(&feature_type, &resolved, &refs)
    }

    /// Resolve the scene references a feature-dimension builder needs beyond its
    /// pure params: the extrude/revolve profile PLANE (center + normal) and the
    /// revolve AXIS line. Sourced from the run report the engine already holds —
    /// `sketch_profiles` (the sketch's world profile, which survives being
    /// consumed by the extrude/revolve since only solids honor `removed`) and
    /// `sketch_axes` (a sketch's published axis lines) — with resident-scene
    /// fallbacks for a profile that is a solid FACE (its display-mesh plane, see
    /// [`Self::lookup_profile_plane`]) and an axis that is a solid EDGE (its
    /// polyline). Empty for any other feature type; missing pieces stay `None`
    /// so the builder degrades to `[]` gracefully.
    fn feature_dimension_refs(
        &self,
        feature_type: &str,
        params: &serde_json::Value,
    ) -> crate::feature_dimensions::ResolvedRefs {
        let mut refs = crate::feature_dimensions::ResolvedRefs::default();
        match feature_type {
            "E" => {
                if let Some((center, normal)) = self.lookup_profile_plane(params.get("profile")) {
                    refs.profile_center = Some(center);
                    refs.profile_normal = Some(normal);
                }
            }
            "R" => {
                if let Some((center, normal)) = self.lookup_profile_plane(params.get("profile")) {
                    refs.profile_center = Some(center);
                    refs.profile_normal = Some(normal);
                }
                if let Some((point, dir)) = self.lookup_axis_line(params.get("axis")) {
                    refs.axis_point = Some(point);
                    refs.axis_dir = Some(dir);
                }
            }
            "P" => {
                // The plane feature registers ONE scene frame under its own id; the
                // offset dim hangs off that resolved plane (origin + z-axis normal).
                if let Some(id) = params.get("id").and_then(|v| v.as_str()) {
                    if let Some((_, frame)) =
                        self.construction_frames.iter().find(|(name, _)| name == id)
                    {
                        refs.plane_origin = Some(vec3_to_arr(frame.origin));
                        refs.plane_normal = Some(fd_normalize3(vec3_to_arr(frame.z_axis)));
                        // Screen-constant handle stub for the offset ≈ 0 case (~48 px).
                        refs.plane_dim_length = Some(self.camera.world_per_pixel() * 48.0);
                    }
                }
            }
            _ => {}
        }
        refs
    }

    /// Resolve a `profile` reference param to the world plane the extrude/revolve
    /// gizmo hangs off, as `(center, unit normal)`. A SKETCH profile first (its
    /// outer-loop centroid + `z_axis`), else a resident solid FACE named by the
    /// reference (the area-weighted centroid + outward normal of its display
    /// mesh) — the same two sources the kernel's extrude/revolve accept for
    /// `profile` (`scene.resolve_profile`, then `resolve_face` →
    /// `face_profile`, whose `z_axis` is likewise the OUTWARD face normal, so the
    /// arc's `orient_revolve_axis` sign matches the kernel's sweep direction).
    /// `None` when neither resolves — a face whose owning solid was later
    /// consumed (a boolean target) is no longer in the scene, and the builder
    /// then degrades to `[]` as before.
    fn lookup_profile_plane(
        &self,
        profile_param: Option<&serde_json::Value>,
    ) -> Option<([f64; 3], [f64; 3])> {
        if let Some(profile) = self.lookup_sketch_profile(profile_param) {
            return Some((sketch_profile_centroid(profile), vec3_to_arr(profile.z_axis)));
        }
        let name = first_reference_name(profile_param?)?;
        self.scene.face_plane_world(&name)
    }

    /// Resolve a `profile` reference param to the sketch profile the engine holds
    /// (exact name, or the `:PROFILE`-suffixed form — mirrors `SceneMap::resolve_profile`).
    fn lookup_sketch_profile(
        &self,
        profile_param: Option<&serde_json::Value>,
    ) -> Option<&brep_kernel::SketchProfile> {
        let name = first_reference_name(profile_param?)?;
        // A committed sketch is surfaced as a render display sheet aliased
        // `{sketch}:FACE`, and profile consumers may reference the `{sketch}:PROFILE`
        // form; both alias the base sketch id the run report keys `sketch_profiles`
        // by. Strip either so the extrude/revolve gizmo resolves the same profile the
        // kernel does (mirrors `common::normalize_profile_alias` / `resolve_profile`).
        let base = name
            .strip_suffix(":FACE")
            .or_else(|| name.strip_suffix(":PROFILE"))
            .unwrap_or(&name);
        self.sketch_profiles
            .iter()
            .find(|(id, _)| id == &name || id == base)
            .map(|(_, profile)| profile)
    }

    /// Resolve an `axis` reference param to a world line `(point, unit direction)`:
    /// a published sketch axis first (`sketch_axes`), else a resident solid EDGE's
    /// polyline endpoints (`scene.edge_polyline_world`). `None` if neither resolves.
    fn lookup_axis_line(
        &self,
        axis_param: Option<&serde_json::Value>,
    ) -> Option<([f64; 3], [f64; 3])> {
        let name = first_reference_name(axis_param?)?;
        if let Some((_, axis)) = self.sketch_axes.iter().find(|(id, _)| id == &name) {
            let dir = fd_normalize3(vec3_to_arr(axis.direction));
            return Some((vec3_to_arr(axis.point), dir));
        }
        // Fallback: a resident edge used as an axis — take its polyline endpoints.
        let poly = self.scene.edge_polyline_world(&name)?;
        let first = *poly.first()?;
        let last = *poly.last()?;
        let dir = fd_sub3(last, first);
        if fd_norm3(dir) < 1e-9 {
            return None;
        }
        Some((first, fd_normalize3(dir)))
    }

    /// A copy of `params` with each top-level STRING field evaluated against the
    /// history's `expressions` + `configurator` (the kernel `eval_expression`) and
    /// replaced by its finite numeric result — so an expression-valued param
    /// (e.g. `sizeX: "a + b"`) places its dimension at the resolved length.
    /// Non-numeric strings (ids, enum options) fail to eval and stay verbatim.
    fn resolve_param_expressions(&self, params: &serde_json::Value) -> serde_json::Value {
        let expressions = self.history.expressions();
        let configurator = self.history.configurator();
        let mut out = params.clone();
        if let Some(object) = out.as_object_mut() {
            for value in object.values_mut() {
                if let Some(source) = value.as_str() {
                    if let Ok(number) =
                        brep_kernel::eval_expression(&expressions, &configurator, source)
                    {
                        if number.is_finite() {
                            *value = serde_json::json!(number);
                        }
                    }
                }
            }
        }
        out
    }

    /// The dimension annotations for `feature_id` as JSON:
    /// `[{ fieldKey, pointA, pointB, value, label, mid }]` (world-space points;
    /// `mid` is the leader midpoint the app anchors the label at). `[]` when the
    /// feature type has no FD-1 builder.
    pub fn feature_dimension_annotations_json(&self, feature_id: &str) -> String {
        use crate::feature_dimensions::FeatureDimKind;
        let annotations = self.feature_dimension_annotations(feature_id);
        let wpp = self.camera.world_per_pixel();
        let out: Vec<serde_json::Value> = annotations
            .iter()
            .map(|a| {
                // The chip anchor: a linear leader's midpoint, or an angular arc's
                // mid-sweep point at the screen-constant radius (camera-dependent,
                // so computed here with the live `world_per_pixel`). `kind` lets the
                // app format the chip (`A 234°` for an angular value in DEGREES).
                let (kind, mid) = match a.kind {
                    FeatureDimKind::Linear => ("linear", a.midpoint()),
                    FeatureDimKind::Angular => {
                        ("angular", crate::feature_dimensions::angular_chip_anchor(a, wpp))
                    }
                };
                serde_json::json!({
                    "fieldKey": a.field_key,
                    "pointA": a.point_a,
                    "pointB": a.point_b,
                    "value": a.value,
                    "label": a.label,
                    "mid": mid,
                    "kind": kind,
                })
            })
            .collect();
        serde_json::to_string(&out).unwrap_or_else(|_| "[]".to_string())
    }

    /// The `{ mode, feature, annotations }` snapshot the headless verifier reads
    /// (published as `__brepFeatureDim`).
    pub fn feature_dimension_state_json(&self) -> String {
        let feature = self.dimension_armed_feature();
        let annotations: serde_json::Value = if feature.is_empty() {
            serde_json::json!([])
        } else {
            serde_json::from_str(&self.feature_dimension_annotations_json(&feature))
                .unwrap_or_else(|_| serde_json::json!([]))
        };
        serde_json::json!({
            "mode": self.gizmo_mode(),
            "feature": feature,
            "annotations": annotations,
        })
        .to_string()
    }

    /// The `set_overlay` JSON for the `feature-dim-leaders` group — the annotation
    /// leaders + arrowheads for the dimension-armed feature (empty when not in
    /// dimension mode, so a stale group is cleared).
    fn feature_dimension_overlay_json(&self) -> String {
        let feature = self.dimension_armed_feature();
        let annotations = if feature.is_empty() {
            Vec::new()
        } else {
            self.feature_dimension_annotations(&feature)
        };
        let (positions, colors) = crate::feature_dimensions::leaders_buffers(
            &annotations,
            self.camera.world_per_pixel(),
        );
        serde_json::json!({
            "groups": [
                {
                    "name": FEATURE_DIM_OVERLAY,
                    "renderOrder": 10003,
                    "tris": { "positions": positions, "colors": colors },
                }
            ]
        })
        .to_string()
    }

    /// (Re)project the dimension leaders onto the current geometry. Called on arm
    /// + after every param change (drag / value edit / rerun in dimension mode)
    /// + on a material ZOOM ([`Self::ensure_feature_dimension_overlay_current`]).
    /// Remembers the `world_per_pixel` it baked at, which is what lets that
    /// per-frame ensure fire on change ONLY.
    pub fn refresh_feature_dimension_overlay(&mut self) {
        let json = self.feature_dimension_overlay_json();
        let _ = self.set_overlay_json(&json);
        let wpp = self.camera.world_per_pixel();
        self.feature_dim_overlay_wpp = if wpp > 0.0 { wpp } else { f64::MIN_POSITIVE };
    }

    /// Clear the dimension overlay (an empty group), e.g. when disarming or
    /// switching to transform mode.
    pub(super) fn clear_feature_dimension_overlay(&mut self) {
        let _ = self.set_overlay_json(&serde_json::json!({
            "groups": [ { "name": FEATURE_DIM_OVERLAY } ]
        }).to_string());
        self.feature_dim_overlay_wpp = 0.0;
    }

    /// Per-frame upkeep for the DIMENSION gizmo (driven by
    /// [`Self::ensure_overlays_current`]).
    ///
    /// The group is baked into pre-expanded vertices at feed time, and its
    /// rod/cone/origin-sphere sizing — plus the angular arc's entire world
    /// RADIUS (`ANGLE_ARC_RAD_PX × world_per_pixel`) — is screen-constant. So a
    /// zoom that is not followed by a re-bake leaves the handles drawn at the old
    /// pixel size, and the angular sweep handle drawn at the old world position
    /// while [`Self::dimension_hit_regions`] (which projects against the LIVE
    /// camera) grabs at the new one: the outline and the drawn handle drift apart.
    ///
    /// Re-bakes ONLY on a material `world_per_pixel` change
    /// ([`overlay_wpp_stale`](super::overlay_wpp_stale)) — a quiet frame does not
    /// touch the overlay, so there is no per-frame dirty loop. Nothing armed →
    /// nothing baked, and the remembered zoom is dropped so re-arming re-bakes.
    pub(super) fn ensure_feature_dimension_overlay_current(&mut self) {
        if !matches!(self.transform_gizmo.mode, GizmoMode::Dimension)
            || self.dimension_armed_feature().is_empty()
        {
            self.feature_dim_overlay_wpp = 0.0;
            return;
        }
        let wpp = self.camera.world_per_pixel();
        if super::overlay_wpp_stale(self.feature_dim_overlay_wpp, wpp) {
            self.refresh_feature_dimension_overlay();
        }
    }

    /// Drag a dimension handle: project the pointer pixel `(x, y)` onto the
    /// annotation's world axis (`pointA → pointB`), take the distance along the
    /// axis from `pointA` as the new value (correcting for any transform scale so
    /// the PARAM — not the scaled world length — is what changes), set the param,
    /// and re-run the history live. Degenerate projections (parallel ray / zero
    /// axis) no-op.
    pub fn feature_dimension_drag(&mut self, feature_id: &str, field_key: &str, x: f64, y: f64) {
        let annotations = self.feature_dimension_annotations(feature_id);
        let Some(annotation) = annotations.iter().find(|a| a.field_key == field_key) else {
            return;
        };
        if annotation.kind == crate::feature_dimensions::FeatureDimKind::Angular {
            if let Some(degrees) = self.angular_drag_degrees(annotation, x, y) {
                self.write_feature_dimension_param(feature_id, field_key, serde_json::json!(degrees));
                // Live-follow: re-bake the world-space leaders onto the rebuilt
                // geometry so the arc tracks the pointer this frame (Fix 3).
                self.refresh_feature_dimension_overlay();
            }
            return;
        }
        let a = annotation.point_a;
        let b = annotation.point_b;
        let axis = fd_sub3(b, a);
        let len = fd_norm3(axis);
        if len < 1e-9 {
            return;
        }
        let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
        let ray = self.camera.pick_ray(x, y);
        let ray_dir = fd_normalize3(ray.dir);
        let Some(t_world) = closest_t_on_axis(a, dir, ray.origin, ray_dir) else {
            return;
        };
        // World distance → param value: correct for the local axis scale via the
        // CURRENT ratio (world length / current param). Under unit scale this is
        // the identity; when the param is ~0 there is no ratio, so use the world
        // distance directly (unit-scale assumption).
        let scale_recip = if annotation.value.abs() > 1e-9 && len > 1e-9 {
            annotation.value / len
        } else {
            1.0
        };
        // Preserve SIGN so a linear dim can be dragged through the origin to the
        // negative side (a directional dim — cube size, height — then extends the
        // other way; the kernel takes |value| for magnitude dims). A small dead-zone
        // keeps it off an exact 0 (a degenerate extent the builders reject).
        let raw = t_world * scale_recip;
        let new_value = if raw >= 0.0 { raw.max(1e-4) } else { raw.min(-1e-4) };
        self.write_feature_dimension_param(feature_id, field_key, serde_json::json!(new_value));
        // Live-follow: re-bake the world-space leaders onto the rebuilt geometry so
        // the arrow tracks the pointer this frame (Fix 3).
        self.refresh_feature_dimension_overlay();
    }

    /// Map a pointer pixel to a swept angle (DEGREES) for an ANGULAR annotation:
    /// search the sweep for the degree whose arc-end projects nearest the pointer
    /// (a coarse 2° pass, then a ±2° refine at 0.25°), snap to 1°, clamp to
    /// `[-360, 360]`. Ported from the overlay `angle` drag. The magnitude is
    /// floored off exactly 0 so a torus `arc` drag never lands on 0 — which the
    /// kernel's `|| 360` falsy fallback would flip to a FULL torus mid-drag.
    /// `None` if the arc never projects in front of the camera.
    ///
    /// `pub(super)`: the assembly-constraint angle-arc drag
    /// (`assembly_overlay.rs`) maps its pointer through this SAME search so the
    /// two angle gizmos share one drag feel.
    pub(super) fn angular_drag_degrees(
        &self,
        ann: &crate::feature_dimensions::FeatureDimAnnotation,
        x: f64,
        y: f64,
    ) -> Option<f64> {
        let radius = crate::feature_dimensions::ANGLE_ARC_RAD_PX * self.camera.world_per_pixel();
        if radius <= 1e-9 {
            return None;
        }
        // A sweep of `deg` and `deg - 360` share the SAME arc-end world point, so
        // the screen-nearest search alone can't tell them apart at the wrap. Break
        // the tie toward the CURRENT value (angle-unwrap
        // continuity) with a tiny bias `~1e-6·Δ°²` — decisive only when screen
        // errors are essentially equal, negligible against any real pointer move.
        let current = ann.value;
        let combined = |screen_err: f64, deg: f64| -> f64 {
            let d = deg - current;
            screen_err + 1e-6 * d * d
        };
        let mut best_deg = current;
        let mut best_err = f64::INFINITY;
        // Coarse sweep over the full range.
        let mut deg = -360.0;
        while deg <= 360.0 {
            if let Some(err) = self.angle_arc_end_err(ann, radius, deg, x, y) {
                let err = combined(err, deg);
                if err < best_err {
                    best_err = err;
                    best_deg = deg;
                }
            }
            deg += 2.0;
        }
        if !best_err.is_finite() {
            return None;
        }
        // Refine around the coarse best.
        let center = best_deg;
        let mut deg = center - 2.0;
        while deg <= center + 2.0 {
            if (-360.0..=360.0).contains(&deg) {
                if let Some(err) = self.angle_arc_end_err(ann, radius, deg, x, y) {
                    let err = combined(err, deg);
                    if err < best_err {
                        best_err = err;
                        best_deg = deg;
                    }
                }
            }
            deg += 0.25;
        }
        let clamped = best_deg.round().clamp(-360.0, 360.0);
        let floored = if clamped.abs() < 0.1 {
            if clamped < 0.0 { -0.1 } else { 0.1 }
        } else {
            clamped
        };
        Some(floored)
    }

    /// Squared screen-pixel distance from `(x, y)` to the arc-end at `deg` for an
    /// angular annotation (`center + rotate(ref_dir, axis, deg) * radius`), or
    /// `None` when that point is behind the camera.
    fn angle_arc_end_err(
        &self,
        ann: &crate::feature_dimensions::FeatureDimAnnotation,
        radius: f64,
        deg: f64,
        x: f64,
        y: f64,
    ) -> Option<f64> {
        let dir = fd_normalize3(crate::feature_dimensions::rotate_about_axis(
            ann.ref_dir,
            ann.axis,
            deg.to_radians(),
        ));
        let p = [
            ann.center[0] + dir[0] * radius,
            ann.center[1] + dir[1] * radius,
            ann.center[2] + dir[2] * radius,
        ];
        let (sx, sy, depth) = self.camera.project(p);
        if depth <= 0.0 {
            return None;
        }
        Some((sx - x) * (sx - x) + (sy - y) * (sy - y))
    }

    /// Edit a dimension value from a label field: a plain numeric literal sets the
    /// param to that number; otherwise the input is treated as an EXPRESSION —
    /// evaluated LIVE against the history's `expressions` + `configurator` (the
    /// kernel `eval_expression`) and, on success, STORED as the expression string
    /// (the kernel re-evaluates it via `ctx.number`, so it stays live). A blank /
    /// bad-expression input no-ops (never corrupts the feature). Re-runs live.
    pub fn feature_dimension_set_value(&mut self, feature_id: &str, field_key: &str, input: &str) {
        let trimmed = input.trim();
        if trimmed.is_empty() {
            return;
        }
        if is_plain_number_literal(trimmed) {
            let Ok(number) = trimmed.parse::<f64>() else {
                return;
            };
            if !number.is_finite() {
                return;
            }
            self.write_feature_dimension_param(feature_id, field_key, serde_json::json!(number));
        } else {
            // Validate the expression before storing it (a bad expression no-ops).
            let expressions = self.history.expressions();
            let configurator = self.history.configurator();
            match brep_kernel::eval_expression(&expressions, &configurator, trimmed) {
                Ok(number) if number.is_finite() => {
                    self.write_feature_dimension_param(
                        feature_id,
                        field_key,
                        serde_json::Value::String(trimmed.to_string()),
                    );
                }
                _ => {}
            }
        }
    }

    /// Set one `inputParams` field of `feature_id` (a number or an expression
    /// string) and re-run the history (which re-projects the leaders in dimension
    /// mode). No-op when the feature is absent.
    fn write_feature_dimension_param(
        &mut self,
        feature_id: &str,
        field_key: &str,
        value: serde_json::Value,
    ) {
        let Some(index) = self.history.index_of(feature_id) else {
            return;
        };
        let mut params = self
            .history
            .feature_params(index)
            .unwrap_or_else(|| serde_json::json!({}));
        let Some(object) = params.as_object_mut() else {
            return;
        };
        object.insert(field_key.to_string(), value);
        let _ = self.update_feature_params(feature_id, &params.to_string());
    }
}

// --- FD-1 geometry helpers (self-contained, `fd_` prefixed to avoid clashes) ---

fn fd_sub3(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
    [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
}

fn fd_dot3(a: [f64; 3], b: [f64; 3]) -> f64 {
    a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
}

fn fd_norm3(v: [f64; 3]) -> f64 {
    fd_dot3(v, v).sqrt()
}

fn fd_normalize3(v: [f64; 3]) -> [f64; 3] {
    let n = fd_norm3(v);
    if n < 1e-12 {
        [0.0, 0.0, 1.0]
    } else {
        [v[0] / n, v[1] / n, v[2] / n]
    }
}

/// Push an origin-ball region at world `p` unless a ball already sits there (dedup
/// by world position, matching `leaders_buffers`' single drawn sphere). The shared
/// point-region builder projects it to a screen circle; a behind-eye (perspective)
/// origin is omitted — invisible, so not grabbable — matching the outline.
fn push_origin_region(
    out: &mut Vec<(DimRole, HitShape)>,
    seen: &mut Vec<[f64; 3]>,
    cam: &crate::view::ViewCamera,
    p: [f64; 3],
    px: f32,
) {
    if seen.iter().any(|o| fd_norm3(fd_sub3(*o, p)) < 1e-6) {
        return;
    }
    seen.push(p);
    if let Some(shape) = point_region(cam, p, px) {
        out.push((DimRole::Origin, shape));
    }
}

/// The parameter `t` of the point on the axis line `a + t*dir` (dir UNIT) closest
/// to the ray `ray_o + s*ray_d` (ray_d UNIT). `None` when the two are parallel
/// (no well-defined projection). `t` is the signed world distance along `dir`
/// from `a`. (`pub(super)`: shared with the constraint distance-arrow drag.)
pub(super) fn closest_t_on_axis(
    a: [f64; 3],
    dir: [f64; 3],
    ray_o: [f64; 3],
    ray_d: [f64; 3],
) -> Option<f64> {
    let w0 = fd_sub3(a, ray_o);
    let b = fd_dot3(dir, ray_d);
    let d = fd_dot3(dir, w0);
    let e = fd_dot3(ray_d, w0);
    let denom = 1.0 - b * b;
    if denom.abs() < 1e-9 {
        return None;
    }
    Some((b * e - d) / denom)
}

fn vec3_to_arr(v: brep_kernel::Vec3) -> [f64; 3] {
    [v.x, v.y, v.z]
}

/// The FIRST reference NAME in a `reference_selection` param: a bare string, an
/// object's `name`, or the first name in an array (port of the kernel
/// `first_reference_name`). Trims + drops empties.
fn first_reference_name(value: &serde_json::Value) -> Option<String> {
    match value {
        serde_json::Value::String(text) => {
            let trimmed = text.trim();
            (!trimmed.is_empty()).then(|| trimmed.to_string())
        }
        serde_json::Value::Object(map) => map
            .get("name")
            .and_then(|v| v.as_str())
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty()),
        serde_json::Value::Array(items) => items.iter().find_map(first_reference_name),
        _ => None,
    }
}

/// The world CENTROID of a sketch profile — the average of its outer-loop curve
/// start points (the profile-polygon vertices), approximating the previous
/// face-average-center computation. Falls back to the sketch plane origin when
/// no outer loop is available. Used to anchor the extrude/revolve gizmos on the
/// geometry rather than at a possibly-far sketch-plane origin.
fn sketch_profile_centroid(profile: &brep_kernel::SketchProfile) -> [f64; 3] {
    let mut sum = [0.0f64; 3];
    let mut count = 0usize;
    if let Some(outer) = profile.regions.first().and_then(|region| region.first()) {
        for curve in &outer.curves {
            if let Ok(domain) = curve.domain() {
                if let Ok(point) = curve.evaluate(domain[0]) {
                    sum[0] += point.x;
                    sum[1] += point.y;
                    sum[2] += point.z;
                    count += 1;
                }
            }
        }
    }
    if count > 0 {
        [sum[0] / count as f64, sum[1] / count as f64, sum[2] / count as f64]
    } else {
        vec3_to_arr(profile.origin)
    }
}

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

    /// A one-primitive history request (identity transform) for the given type +
    /// params, so the engine builds it and the dimension methods can read it.
    fn primitive_request(feature_type: &str, id: &str, params: serde_json::Value) -> String {
        let mut input = params.as_object().cloned().unwrap_or_default();
        input.insert("id".into(), serde_json::json!(id));
        input.insert(
            "transform".into(),
            serde_json::json!({
                "position": [0.0, 0.0, 0.0],
                "rotationEuler": [0.0, 0.0, 0.0],
                "scale": [1.0, 1.0, 1.0]
            }),
        );
        input.insert(
            "boolean".into(),
            serde_json::json!({ "targets": [], "operation": "NONE" }),
        );
        serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": feature_type,
                "inputParams": input,
                "persistentData": {}
            }]
        })
        .to_string()
    }

    fn cube_engine() -> EngineState {
        let mut state = EngineState::new();
        state
            .set_history_json(&primitive_request(
                "P.CU",
                "Box",
                serde_json::json!({ "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0 }),
            ))
            .unwrap();
        state
    }

    #[test]
    fn annotations_json_for_a_cube_has_three_linear_dims() {
        let state = cube_engine();
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Box")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(arr.len(), 3);
        assert_eq!(arr[0]["fieldKey"], "sizeX");
        assert_eq!(arr[0]["value"].as_f64().unwrap(), 10.0);
        assert!(arr[0]["pointA"].is_array() && arr[0]["pointB"].is_array());
        assert!(arr[0]["mid"].is_array());
    }

    #[test]
    fn annotations_json_for_a_cylinder_has_radius_and_height() {
        let mut state = EngineState::new();
        state
            .set_history_json(&primitive_request(
                "P.CY",
                "Cyl",
                serde_json::json!({ "radius": 4.0, "height": 12.0 }),
            ))
            .unwrap();
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Cyl")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(arr.len(), 2);
        assert_eq!(arr[0]["fieldKey"], "radius");
        assert_eq!(arr[1]["fieldKey"], "height");
    }

    /// Task C audit — every PRIMITIVE that carries a Transform group also ships a
    /// dimension builder, so expanding it auto-arms a dimension gizmo (`HistoryPanel`
    /// guards on `feature_dimension_annotations_json != "[]"`). That gizmo's
    /// origin/center sphere is the ONLY route to the transform gizmo now that the ◎
    /// arm-button is gone, so a primitive with no dims would be stranded. Assert all
    /// six expose a non-empty dimension gizmo AND arm to dimension mode. (Datum /
    /// helix / pattern / port ALSO carry a Transform group but NO dim builder — they
    /// have no path to transform post-◎-removal; flagged in the handoff, not fixed.)
    #[test]
    fn every_transformable_primitive_auto_arms_a_dimension_gizmo() {
        let cases: [(&str, serde_json::Value); 6] = [
            ("P.CU", serde_json::json!({ "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0 })),
            ("P.CY", serde_json::json!({ "radius": 4.0, "height": 12.0 })),
            ("P.CO", serde_json::json!({ "radiusBottom": 4.0, "radiusTop": 2.0, "height": 10.0 })),
            ("P.S", serde_json::json!({ "radius": 5.0 })),
            ("P.PY", serde_json::json!({ "baseSideLength": 6.0, "height": 8.0 })),
            ("P.T", serde_json::json!({ "majorRadius": 6.0, "tubeRadius": 1.5, "arc": 120.0 })),
        ];
        for (ty, params) in cases {
            let mut state = EngineState::new();
            state
                .set_history_json(&primitive_request(ty, "Feat", params))
                .unwrap_or_else(|e| panic!("{ty} builds: {e}"));
            assert_ne!(
                state.feature_dimension_annotations_json("Feat"),
                "[]",
                "{ty} must expose a dimension gizmo so expanding it auto-arms one"
            );
            // Arming it (what expand does) lands in dimension mode.
            state.arm_dimension("Feat");
            assert_eq!(state.gizmo_mode(), "dimension", "{ty}");
        }
    }

    #[test]
    fn annotations_json_empty_for_unknown_feature() {
        let state = cube_engine();
        assert_eq!(state.feature_dimension_annotations_json("nope"), "[]");
    }

    #[test]
    fn set_value_updates_the_param_and_reruns() {
        let mut state = cube_engine();
        state.arm_dimension("Box");
        state.feature_dimension_set_value("Box", "sizeX", "25");
        let index = state.history.index_of("Box").unwrap();
        let params = state.history.feature_params(index).unwrap();
        assert_eq!(params["sizeX"].as_f64().unwrap(), 25.0);
        // The reported annotation picks up the new value.
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Box")).unwrap();
        assert_eq!(json[0]["value"].as_f64().unwrap(), 25.0);
    }

    #[test]
    fn set_value_stores_expression_string_when_not_a_literal() {
        let mut state = cube_engine();
        // Seed a variable in the history expressions.
        state.set_expressions("w = 7;");
        state.feature_dimension_set_value("Box", "sizeX", "w * 2");
        let index = state.history.index_of("Box").unwrap();
        let params = state.history.feature_params(index).unwrap();
        // The expression is stored verbatim (the kernel re-evaluates it live).
        assert_eq!(params["sizeX"].as_str().unwrap(), "w * 2");
        // …and resolves to 14 in the reported annotation.
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Box")).unwrap();
        assert_eq!(json[0]["value"].as_f64().unwrap(), 14.0);
    }

    #[test]
    fn set_value_rejects_a_bad_expression() {
        let mut state = cube_engine();
        state.feature_dimension_set_value("Box", "sizeX", "this is not valid");
        let index = state.history.index_of("Box").unwrap();
        let params = state.history.feature_params(index).unwrap();
        // Unchanged — the bad expression never landed.
        assert_eq!(params["sizeX"].as_f64().unwrap(), 10.0);
    }

    #[test]
    fn origin_sphere_and_center_sphere_toggle_the_two_modes() {
        // The single orange sphere at the gizmo center flips dimension ↔ transform:
        // clicking the dimension arrows' ORIGIN sphere arms the transform gizmo, and
        // clicking the transform gizmo's CENTER sphere arms the dimension arrows.
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        state.camera.eye = [0.0, 0.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        // Arm the DIMENSION arrows for the cube.
        state.arm_dimension("Box");
        assert_eq!(state.gizmo_mode(), "dimension");

        // The arrows share one ORIGIN sphere at the cube's min corner
        // (annotations[0].pointA). Project it the way `transform_gizmo_anchor` does.
        let anns: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Box")).unwrap();
        let pa = &anns[0]["pointA"];
        let origin = [
            pa[0].as_f64().unwrap(),
            pa[1].as_f64().unwrap(),
            pa[2].as_f64().unwrap(),
        ];
        let (ox, oy, depth) = state.camera.project(origin);
        assert!(depth > 0.0, "origin in front of camera");

        // A click on the origin sphere toggles DIMENSION → TRANSFORM (mirroring the
        // viewport click-chain). The cross-mode pick is inert here.
        assert!(state.dimension_origin_pick(ox, oy), "pick hits the origin sphere");
        assert!(
            !state.transform_center_pick(ox, oy),
            "no transform-center pick while in dimension mode"
        );
        state.toggle_to_transform();
        assert_eq!(state.gizmo_mode(), "transform");

        // The transform gizmo's orange CENTER sphere sits at the same anchor; a
        // click on it toggles TRANSFORM → DIMENSION.
        let (cx, cy) = state.transform_gizmo_anchor().expect("transform anchor");
        assert!(state.transform_center_pick(cx, cy), "pick hits the center handle");
        assert!(
            !state.dimension_origin_pick(cx, cy),
            "no dimension-origin pick while in transform mode"
        );
        state.toggle_to_dimension();
        assert_eq!(state.gizmo_mode(), "dimension");
    }

    /// A revolve is ANGULAR-ONLY: its single dimension is the sweep angle, whose
    /// mode-toggle target is the arc CENTER (there is no linear origin sphere). So
    /// the center-sphere pick is the ONLY way it reaches the transform gizmo. Assert
    /// the full round trip dimension → transform → dimension. (This guards the FD-2
    /// gap fix — restoring the old `kind != Linear { continue }` skip in
    /// `dimension_origin_pick` makes the first pick miss and fails this test.)
    #[test]
    fn plane_arms_the_offset_dim_and_never_toggles_to_transform() {
        // A plane gets the offset DIMENSION gizmo on arm; unlike a revolve, its
        // origin-sphere toggle must NOT give it a transform gizmo — a plane has no
        // transform (its placement is orientation + offset_distance).
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "P",
                "inputParams": { "id": "Pl", "orientation": "XY", "offset_distance": 3.0 },
                "persistentData": {}
            }]
        })
        .to_string();
        let mut state = EngineState::new();
        state.set_history_json(&request).expect("plane builds");

        // It emits one linear offset dim (so expand auto-arms dimension).
        let anns = state.feature_dimension_annotations("Pl");
        assert_eq!(anns.len(), 1, "plane emits its offset dim: {anns:?}");
        assert_eq!(anns[0].field_key, "offset_distance");

        state.arm_dimension("Pl");
        assert_eq!(state.gizmo_mode(), "dimension");
        // The origin-sphere toggle is a NO-OP for a plane — stays in dimension mode.
        state.toggle_to_transform();
        assert_eq!(state.gizmo_mode(), "dimension", "a plane never gets a transform gizmo");
    }

    #[test]
    fn angular_center_sphere_toggles_a_revolve_to_transform_and_back() {
        // Sketch "Sk": a radial rectangle (x∈[2,4], y∈[0,3]) profile + a +Y
        // construction line "Sk:G20" the revolve uses as its axis. The kernel
        // publishes both, and they survive the sketch being consumed by the revolve.
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "S",
                    "inputParams": { "id": "Sk" },
                    "persistentData": {
                        "basis": { "origin": [0,0,0], "x": [1,0,0], "y": [0,1,0], "z": [0,0,1] },
                        "sketch": {
                            "points": [
                                {"id":1,"x":2.0,"y":0.0}, {"id":2,"x":4.0,"y":0.0},
                                {"id":3,"x":4.0,"y":3.0}, {"id":4,"x":2.0,"y":3.0},
                                {"id":5,"x":0.0,"y":0.0}, {"id":6,"x":0.0,"y":1.0}
                            ],
                            "geometries": [
                                {"id":10,"type":"line","points":[1,2]},
                                {"id":11,"type":"line","points":[2,3]},
                                {"id":12,"type":"line","points":[3,4]},
                                {"id":13,"type":"line","points":[4,1]},
                                {"id":20,"type":"line","points":[5,6],"construction":true}
                            ],
                            "constraints": []
                        }
                    }
                },
                {
                    "type": "R",
                    "inputParams": { "id": "Rev", "profile": "Sk", "axis": "Sk:G20", "angle": 90.0 },
                    "persistentData": {}
                }
            ]
        })
        .to_string();

        let mut state = EngineState::new();
        state.set_history_json(&request).expect("revolve builds");
        state.resize(800.0, 600.0);
        state.camera.eye = [0.0, 0.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        // The revolve's ONLY dimension is angular — no linear origin sphere exists.
        let anns = state.feature_dimension_annotations("Rev");
        assert_eq!(anns.len(), 1, "revolve emits one (angular) dim: {anns:?}");
        assert_eq!(anns[0].kind, crate::feature_dimensions::FeatureDimKind::Angular);
        let center = anns[0].center;

        // Arm the dimension arrows (what expanding the feature does).
        state.arm_dimension("Rev");
        assert_eq!(state.gizmo_mode(), "dimension");

        // Clicking the arc-CENTER orange sphere toggles DIMENSION → TRANSFORM.
        let (cx, cy, depth) = state.camera.project(center);
        assert!(depth > 0.0, "arc center in front of the camera");
        assert!(
            state.dimension_origin_pick(cx, cy),
            "pick hits the angular center sphere"
        );
        state.toggle_to_transform();
        assert_eq!(state.gizmo_mode(), "transform");

        // And the transform gizmo's CENTER sphere toggles back to the arc.
        let (tx, ty) = state.transform_gizmo_anchor().expect("transform anchor");
        assert!(
            state.transform_center_pick(tx, ty),
            "pick hits the transform center handle"
        );
        state.toggle_to_dimension();
        assert_eq!(state.gizmo_mode(), "dimension");
        assert!(
            state.dimension_armed_for("Rev"),
            "round trip lands back on the revolve's dimension arrows"
        );
    }

    /// A revolve history: sketch "Sk" (radial rectangle profile x∈[2,4], y∈[0,3]
    /// plus a +Y construction line "Sk:G20" used as the axis) revolved `angle`°
    /// about that axis. Mirrors the fixture in
    /// `angular_center_sphere_toggles_a_revolve_to_transform_and_back` so the
    /// revolve's angular dim resolves against a real scene, parameterized by angle.
    fn revolve_engine(angle: f64) -> EngineState {
        revolve_engine_with_profile("Sk", angle)
    }

    /// As [`revolve_engine`] but with the revolve's `profile` reference spelled
    /// `profile` — so a test can drive the committed-sketch `{sketch}:FACE` display
    /// alias through the same live pipeline.
    fn revolve_engine_with_profile(profile: &str, angle: f64) -> EngineState {
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "S",
                    "inputParams": { "id": "Sk" },
                    "persistentData": {
                        "basis": { "origin": [0,0,0], "x": [1,0,0], "y": [0,1,0], "z": [0,0,1] },
                        "sketch": {
                            "points": [
                                {"id":1,"x":2.0,"y":0.0}, {"id":2,"x":4.0,"y":0.0},
                                {"id":3,"x":4.0,"y":3.0}, {"id":4,"x":2.0,"y":3.0},
                                {"id":5,"x":0.0,"y":0.0}, {"id":6,"x":0.0,"y":1.0}
                            ],
                            "geometries": [
                                {"id":10,"type":"line","points":[1,2]},
                                {"id":11,"type":"line","points":[2,3]},
                                {"id":12,"type":"line","points":[3,4]},
                                {"id":13,"type":"line","points":[4,1]},
                                {"id":20,"type":"line","points":[5,6],"construction":true}
                            ],
                            "constraints": []
                        }
                    }
                },
                {
                    "type": "R",
                    "inputParams": { "id": "Rev", "profile": profile, "axis": "Sk:G20", "angle": angle },
                    "persistentData": {}
                }
            ]
        })
        .to_string();

        let mut state = EngineState::new();
        state.set_history_json(&request).expect("revolve builds");
        state.resize(800.0, 600.0);
        // Look straight DOWN the revolve axis (the oriented axis is -Y for this
        // fixture; center is (0, 1.5, 0)) so the arc's (cosθ, sinθ) maps uniquely
        // to screen. An edge-on view would alias θ ↔ -θ and defeat the angular
        // drag's nearest-projection search.
        state.camera.eye = [0.0, 40.0, 0.0];
        state.camera.target = [0.0, 1.5, 0.0];
        state.camera.up = [0.0, 0.0, 1.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };
        state
    }

    /// The revolve's `angle` surfaces as an ANGULAR annotation in the JSON the app
    /// reads (so the auto-arm lights it up), and its arc arrowhead is pickable +
    /// draggable, writing the swept degrees back to `angle`. Exercises the whole
    /// revolve angle-gizmo pipeline end-to-end against a live scene: `axis`
    /// reference → oriented arc (`orient_revolve_axis`, the kernel's rule) → pick →
    /// angular drag. (The struct-level annotation + center-sphere mode toggle are
    /// covered by `angular_center_sphere_toggles_a_revolve_to_transform_and_back`;
    /// this locks in the JSON surface + the live pick/drag for the revolve.)
    #[test]
    fn revolve_angle_json_is_angular_and_drag_writes_the_swept_degrees() {
        let mut state = revolve_engine(90.0);

        // JSON surface: exactly one angular `angle` entry (what the app + auto-arm
        // read — a non-`[]` result is what auto-arms the gizmo on expand).
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Rev")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(arr.len(), 1, "revolve emits one dim: {arr:?}");
        assert_eq!(arr[0]["fieldKey"], "angle");
        assert_eq!(arr[0]["kind"], "angular");
        assert!((arr[0]["value"].as_f64().unwrap() - 90.0).abs() < 1e-9);
        assert!(arr[0]["mid"].is_array(), "angular chip anchors on the arc");

        // Arm the dimension arrows (what expanding the feature does), then grab the
        // revolve's angular dim.
        state.arm_dimension("Rev");
        let ann = state
            .feature_dimension_annotations("Rev")
            .into_iter()
            .find(|a| a.field_key == "angle")
            .expect("angle dim");
        assert_eq!(ann.kind, crate::feature_dimensions::FeatureDimKind::Angular);

        // PRESS on the arc's CURRENT (90°) arrowhead handle → pick grabs `angle`.
        let handle =
            crate::feature_dimensions::arrow_handle_point(&ann, state.world_per_pixel());
        let (hx, hy, hdepth) = state.camera.project(handle);
        assert!(hdepth > 0.0, "handle in front of the camera");
        assert_eq!(
            state.dimension_arrow_pick(hx, hy).as_deref(),
            Some("angle"),
            "pick at the arc arrowhead grabs the angle handle"
        );

        // DRAG toward the arc-end for a larger sweep; the nearest-projection search
        // must recover that degree (within the 1° snap).
        let target = 200.0_f64;
        let radius = crate::feature_dimensions::ANGLE_ARC_RAD_PX * state.world_per_pixel();
        let dir = crate::feature_dimensions::rotate_about_axis(
            ann.ref_dir,
            ann.axis,
            target.to_radians(),
        );
        let world = [
            ann.center[0] + dir[0] * radius,
            ann.center[1] + dir[1] * radius,
            ann.center[2] + dir[2] * radius,
        ];
        let (tx, ty, tdepth) = state.camera.project(world);
        assert!(tdepth > 0.0, "drag target in front of the camera");
        state.feature_dimension_drag("Rev", "angle", tx, ty);

        let after = state.feature_dimension_annotations("Rev");
        let new_angle = after.iter().find(|a| a.field_key == "angle").expect("angle dim");
        assert!(
            (new_angle.value - target).abs() < 2.0,
            "drag should sweep the angle to ~{target}°, got {}",
            new_angle.value
        );
    }

    /// Regression: a revolve (or extrude) whose `profile` references the committed
    /// sketch by its render display alias `{sketch}:FACE` must still resolve the
    /// sketch profile and auto-arm its dimension gizmo. `sketch_profiles` is keyed by
    /// the base sketch id (`Sk`), so `lookup_sketch_profile` has to strip the `:FACE`
    /// alias — exactly as the kernel's profile consumers do. Before the strip this
    /// returned `[]` and the angle arc silently never appeared (the real-world
    /// `RevolveSketch.BREP.json` symptom: profile `S4:FACE`).
    #[test]
    fn revolve_face_alias_profile_still_arms_the_angle_gizmo() {
        let state = revolve_engine_with_profile("Sk:FACE", 90.0);
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Rev")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(
            arr.len(),
            1,
            "the `:FACE`-aliased revolve profile must still emit its angular dim: {arr:?}"
        );
        assert_eq!(arr[0]["fieldKey"], "angle");
        assert_eq!(arr[0]["kind"], "angular");
        assert_eq!(arr[0]["value"].as_f64().unwrap(), 90.0);
    }

    /// DEBUG-overlay consistency + draw==hit invariant: `dimension_hit_areas_json`
    /// emits the SAME SCREEN-space regions the picks 2D-test the cursor against —
    /// three leader CAPSULES (`point_a → point_b`, `ARROW_HANDLE_HIT_RAD_PX`,
    /// projected via the camera) + ONE deduped origin CIRCLE (`point_a`,
    /// `ORIGIN_SPHERE_RAD_PX + 2`) for a cube — and a cursor inside each grabs the
    /// matching handle. `[]` outside dimension mode.
    #[test]
    fn dimension_hit_areas_are_screen_regions_matching_the_picks() {
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        // Oblique so the three leaders fan out to distinct screen directions (a
        // straight-down view foreshortens the +Z leader onto the shared corner,
        // making its midpoint ambiguous with the others).
        state.camera.eye = [30.0, 20.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        // Only populated in dimension mode.
        assert_eq!(state.dimension_hit_areas_json(), "[]");
        state.arm_transform("Box");
        assert_eq!(state.dimension_hit_areas_json(), "[]");

        state.arm_dimension("Box");
        let areas: Vec<serde_json::Value> =
            serde_json::from_str(&state.dimension_hit_areas_json()).unwrap();
        let anns = state.feature_dimension_annotations("Box");

        let close2 = |v: &serde_json::Value, want: (f64, f64)| {
            (v[0].as_f64().unwrap() - want.0).abs() < 1e-3
                && (v[1].as_f64().unwrap() - want.1).abs() < 1e-3
        };

        // Three leader CAPSULES (screen px), one per linear dim; endpoints = the
        // camera-projected point_a/point_b, radius = ARROW_HANDLE_HIT_RAD_PX.
        let capsules: Vec<&serde_json::Value> =
            areas.iter().filter(|a| a["kind"] == "capsule").collect();
        assert_eq!(capsules.len(), 3);
        assert_eq!(capsules.len(), anns.len());
        for (cap, ann) in capsules.iter().zip(anns.iter()) {
            let r = cap["r"].as_f64().unwrap();
            assert!(
                (r - crate::feature_dimensions::ARROW_HANDLE_HIT_RAD_PX).abs() < 1e-6,
                "r {r} must equal ARROW_HANDLE_HIT_RAD_PX"
            );
            let (ax, ay, _) = state.camera.project(ann.point_a);
            let (bx, by, _) = state.camera.project(ann.point_b);
            assert!(close2(&cap["a"], (ax, ay)), "leader a: {:?} vs {ax},{ay}", cap["a"]);
            assert!(close2(&cap["b"], (bx, by)), "leader b: {:?} vs {bx},{by}", cap["b"]);
        }

        // One deduped origin CIRCLE at the shared min corner (all three cube dims
        // share `point_a`), radius ORIGIN_SPHERE_RAD_PX + 2.
        let circles: Vec<&serde_json::Value> =
            areas.iter().filter(|a| a["kind"] == "circle").collect();
        assert_eq!(circles.len(), 1, "cube dims share one origin sphere");
        let want_r = crate::feature_dimensions::ORIGIN_SPHERE_RAD_PX + 2.0;
        assert!((circles[0]["r"].as_f64().unwrap() - want_r).abs() < 1e-6);
        let (ox, oy, _) = state.camera.project(anns[0].point_a);
        assert!(close2(&circles[0]["c"], (ox, oy)), "origin circle off point_a");

        // Draw==hit: a cursor at each leader MIDPOINT (uniquely owned by that leader
        // away from the shared corner) grabs THAT field; a cursor at the origin
        // circle center is an origin pick.
        for ann in &anns {
            let mid = ann.midpoint();
            let (mx, my, _) = state.camera.project(mid);
            assert_eq!(
                state.dimension_arrow_pick(mx, my).as_deref(),
                Some(ann.field_key.as_str()),
                "cursor on the {} leader midpoint grabs it",
                ann.field_key
            );
        }
        assert!(state.dimension_origin_pick(ox, oy), "cursor on the origin circle toggles");
    }

    #[test]
    fn closest_t_on_axis_projects_a_perpendicular_ray() {
        // Axis along +X from origin; a ray straight down through (7, 5, 0) hits the
        // axis at t = 7.
        let t = closest_t_on_axis(
            [0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0],
            [7.0, 5.0, 0.0],
            [0.0, -1.0, 0.0],
        )
        .unwrap();
        assert!((t - 7.0).abs() < 1e-9, "t = {t}");
    }

    #[test]
    fn closest_t_on_axis_none_when_parallel() {
        assert!(closest_t_on_axis(
            [0.0, 0.0, 0.0],
            [1.0, 0.0, 0.0],
            [0.0, 5.0, 0.0],
            [1.0, 0.0, 0.0],
        )
        .is_none());
    }

    // --- FD-2 angular: torus arc (a primitive with an angular dim) -------------

    fn torus_engine(arc: f64) -> EngineState {
        let mut state = EngineState::new();
        state
            .set_history_json(&primitive_request(
                "P.T",
                "Tor",
                serde_json::json!({ "majorRadius": 6.0, "tubeRadius": 1.5, "arc": arc }),
            ))
            .unwrap();
        state
    }

    #[test]
    fn annotations_json_for_a_torus_has_two_linear_and_one_angular() {
        let state = torus_engine(120.0);
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Tor")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(arr.len(), 3);
        assert_eq!(arr[0]["fieldKey"], "majorRadius");
        assert_eq!(arr[0]["kind"], "linear");
        assert_eq!(arr[1]["fieldKey"], "tubeRadius");
        assert_eq!(arr[1]["kind"], "linear");
        // The arc dim is ANGULAR, its value is DEGREES, and its chip anchors on
        // the arc (a world point the app projects).
        assert_eq!(arr[2]["fieldKey"], "arc");
        assert_eq!(arr[2]["kind"], "angular");
        assert_eq!(arr[2]["value"].as_f64().unwrap(), 120.0);
        assert!(arr[2]["mid"].is_array());
    }

    #[test]
    fn dragging_a_torus_arc_writes_the_swept_degrees() {
        let mut state = torus_engine(90.0);
        state.arm_dimension("Tor");
        let anns = state.feature_dimension_annotations("Tor");
        let arc = anns
            .iter()
            .find(|a| a.field_key == "arc")
            .expect("arc dim")
            .clone();
        assert_eq!(arc.kind, crate::feature_dimensions::FeatureDimKind::Angular);

        // Aim the pointer exactly at the arc-end for a target sweep; the drag's
        // nearest-projection search must recover that degree (within the 1° snap).
        let target = 210.0_f64;
        let radius = crate::feature_dimensions::ANGLE_ARC_RAD_PX * state.world_per_pixel();
        let dir = crate::feature_dimensions::rotate_about_axis(
            arc.ref_dir,
            arc.axis,
            target.to_radians(),
        );
        let world = [
            arc.center[0] + dir[0] * radius,
            arc.center[1] + dir[1] * radius,
            arc.center[2] + dir[2] * radius,
        ];
        let (sx, sy, depth) = state.camera.project(world);
        assert!(depth > 0.0, "arc-end must project in front of the camera");

        state.feature_dimension_drag("Tor", "arc", sx, sy);

        let after = state.feature_dimension_annotations("Tor");
        let new_arc = after.iter().find(|a| a.field_key == "arc").expect("arc dim");
        assert!(
            (new_arc.value - target).abs() < 2.0,
            "drag should sweep the arc to ~{target}°, got {}",
            new_arc.value
        );
    }

    // --- Fix 4: dimension-arrow pick + drag (a linear cube dim) ----------------

    #[test]
    fn dimension_arrow_pick_and_drag_edits_the_param_live() {
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        state.camera.eye = [0.0, 0.0, 40.0]; // look down -Z: +X screen-right, +Y up
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        // A pick is inert until the dimension arrows are armed.
        state.arm_transform("Box");
        assert!(
            state.dimension_arrow_pick(400.0, 300.0).is_none(),
            "no arrow pick in transform mode"
        );

        state.arm_dimension("Box");
        assert_eq!(state.gizmo_mode(), "dimension");

        // The sizeX dim runs origin → (sizeX,0,0); its orange arrowHEAD is at
        // `point_b`. A pick AT the projected arrowhead grabs the `sizeX` field.
        let ann = state
            .feature_dimension_annotations("Box")
            .into_iter()
            .find(|a| a.field_key == "sizeX")
            .expect("sizeX dim");
        let a = ann.point_a;
        let b = ann.point_b;
        let (bx, by, depth) = state.camera.project(b);
        assert!(depth > 0.0, "arrowhead in front of the camera");
        assert_eq!(
            state.dimension_arrow_pick(bx, by).as_deref(),
            Some("sizeX"),
            "pick at the arrowhead grabs sizeX"
        );
        // A far-off pixel grabs nothing.
        assert!(state.dimension_arrow_pick(10.0, 10.0).is_none(), "empty space → no arrow");

        // DRAG the arrow outward along +X to a target length; the value tracks the
        // pointer live (Fix 3 + Fix 4). Aim the pointer at a + dir*target_len.
        let len = {
            let d = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
            (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt()
        };
        let dir = [(b[0] - a[0]) / len, (b[1] - a[1]) / len, (b[2] - a[2]) / len];
        let target_len = 16.0_f64;
        let world = [
            a[0] + dir[0] * target_len,
            a[1] + dir[1] * target_len,
            a[2] + dir[2] * target_len,
        ];
        let (wx, wy, wdepth) = state.camera.project(world);
        assert!(wdepth > 0.0, "drag target in front of the camera");

        let before = state
            .history
            .feature_params(state.history.index_of("Box").unwrap())
            .unwrap()["sizeX"]
            .as_f64()
            .unwrap();
        state.feature_dimension_drag("Box", "sizeX", wx, wy);
        let after = state
            .history
            .feature_params(state.history.index_of("Box").unwrap())
            .unwrap()["sizeX"]
            .as_f64()
            .unwrap();

        // The param grew toward the drag target. The drag scales the world distance
        // by the current (value / world-length) ratio; under unit scale that is 1,
        // so the new value ≈ target_len.
        let expected = target_len * (ann.value / len);
        assert!(after > before, "sizeX grew: {before} → {after}");
        assert!(
            (after - expected).abs() < 0.5,
            "drag set sizeX to ~{expected}, got {after}"
        );
    }

    /// REGRESSION PIN — the exact logged failure (`sizeY tip depth=-3.449`). An
    /// armed cube dimension gizmo oriented so the sizeY leader's FAR end
    /// (`point_b`) has NEGATIVE view-depth while its shaft is clearly on screen.
    /// The old point-only pick + `depth <= 0.0` skip returned None for the whole
    /// handle; being ORTHOGRAPHIC, the region builder projects the WHOLE leader in
    /// full (no clip), so the capsule covers the shaft AND `point_b` — a cursor AT
    /// the projected `point_b` grabs it.
    #[test]
    fn linear_leader_with_point_b_behind_the_eye_is_grabbable_on_its_visible_shaft() {
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        state.arm_dimension("Box");

        // Locate the sizeY leader, then aim an ORTHO camera whose eye plane falls
        // BETWEEN point_a and point_b (a < L/2 perpendicular offset), so point_b is
        // behind the eye plane but the shaft's a-side is in front. Being ortho, the
        // whole leader still renders — so by the user's rule it must be grabbable.
        let anns = state.feature_dimension_annotations("Box");
        let ann = anns.iter().find(|a| a.field_key == "sizeY").expect("sizeY dim").clone();
        let a = ann.point_a;
        let b = ann.point_b;
        let dir = fd_normalize3(fd_sub3(b, a));
        let l = fd_norm3(fd_sub3(b, a));
        // Offset the eye TOWARD the sum of the OTHER leaders' directions (sizeX +
        // sizeZ), so `forward = a - eye` points AWAY from them — otherwise the pick
        // ray through point_b can coincidentally graze another leader (they all
        // share the corner `a`). Keep only the component ⟂ the sizeY direction.
        let mut off = [0.0f64; 3];
        for other in anns.iter().filter(|a| a.field_key != "sizeY") {
            let d = fd_normalize3(fd_sub3(other.point_b, other.point_a));
            off = [off[0] + d[0], off[1] + d[1], off[2] + d[2]];
        }
        let off_dot = fd_dot3(off, dir);
        let perp = fd_normalize3([
            off[0] - dir[0] * off_dot,
            off[1] - dir[1] * off_dot,
            off[2] - dir[2] * off_dot,
        ]);
        let mid = [(a[0] + b[0]) * 0.5, (a[1] + b[1]) * 0.5, (a[2] + b[2]) * 0.5];
        let d_off = l * 0.25; // < L/2 → point_b lands behind the eye plane
        let eye = [
            mid[0] + perp[0] * d_off,
            mid[1] + perp[1] * d_off,
            mid[2] + perp[2] * d_off,
        ];
        let forward = fd_normalize3(fd_sub3(a, eye)); // look toward the front (a) side
        state.camera.eye = eye;
        state.camera.target = [eye[0] + forward[0], eye[1] + forward[1], eye[2] + forward[2]];
        state.camera.up = if forward[2].abs() < 0.9 { [0.0, 0.0, 1.0] } else { [0.0, 1.0, 0.0] };
        state.camera.projection =
            crate::view::Projection::Orthographic { half_height: l.max(1.0) };

        // The pin: point_b is behind the eye plane, point_a in front.
        assert!(
            state.camera.view_depth(b) < 0.0,
            "point_b must be behind the eye: {}",
            state.camera.view_depth(b)
        );
        assert!(state.camera.view_depth(a) > 0.0, "point_a in front");

        // A cursor AT the (still on-screen, ortho) projected point_b grabs sizeY —
        // the VERY pixel the old `depth <= 0.0` skip culled the whole handle at.
        let (bx, by, bdepth) = state.camera.project(b);
        assert!(bdepth < 0.0, "the projected far-end depth the old skip rejected");
        assert_eq!(
            state.dimension_arrow_pick(bx, by).as_deref(),
            Some("sizeY"),
            "the leader is grabbable at its visible far end"
        );

        // …and on its mid shaft too.
        let (mx, my, _) = state.camera.project(mid);
        assert_eq!(
            state.dimension_arrow_pick(mx, my).as_deref(),
            Some("sizeY"),
            "the leader is grabbable on its shaft"
        );
    }

    // -----------------------------------------------------------------------
    // Zoom → the drawn gizmo follows (the reported "zoom does not update the
    // draggable gizmos" bug). The leaders/arrowheads/arc ride the GENERAL
    // `set_overlay` channel, which pre-expands its vertices AT FEED TIME — so
    // unlike the per-frame widgets (transform gizmo, datums, ViewCube) they do
    // NOT re-size against the live camera. Only a re-bake updates them.
    // -----------------------------------------------------------------------

    /// A quiet frame must not re-bake (no per-frame dirty loop), a material
    /// zoom must — the same contract `ensure_current_hides_in_sketch_mode_and_
    /// rebakes_on_zoom` holds for the assembly-constraint overlay.
    #[test]
    fn ensure_overlays_current_rebakes_the_dimension_gizmo_on_zoom_without_looping() {
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        state.camera.eye = [30.0, 20.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };
        state.arm_dimension("Box");

        // Quiet frame: nothing moved, nothing re-bakes.
        state.dirty = false;
        state.ensure_overlays_current();
        assert!(!state.dirty, "a quiet frame must not re-bake (no dirty loop)");

        // Zoom out 2x → the screen-constant rod/cone/sphere sizing is stale.
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 40.0 };
        state.ensure_overlays_current();
        assert!(state.dirty, "a zoom change re-bakes the screen-constant sizing");

        // …and it SETTLES: the re-bake recorded the new zoom, so the frames after
        // it are quiet again. (A fix that re-baked unconditionally would pin the
        // CPU and repaint forever; this is what catches it.)
        state.dirty = false;
        state.ensure_overlays_current();
        state.ensure_overlays_current();
        state.ensure_overlays_current();
        assert!(!state.dirty, "the re-bake settles — no per-frame re-bake loop");

        // Every OTHER zoom path lands on the same world-per-pixel key: a viewport
        // resize (camera.height) is a zoom too.
        state.resize(800.0, 300.0);
        state.dirty = false;
        state.ensure_overlays_current();
        assert!(state.dirty, "a viewport resize changes world-per-pixel → re-bake");

        // Pan + orbit do NOT: they leave the target-plane world-per-pixel alone,
        // the baked geometry is world-space (the GPU re-projects it every frame),
        // and the hit regions are recomputed live at pick time.
        state.dirty = false;
        state.camera.eye = [40.0, 20.0, 30.0]; // orbit (same distance)
        state.ensure_overlays_current();
        assert!(!state.dirty, "orbit needs no re-bake (world-space geometry)");
        state.camera.eye = [35.0, 25.0, 45.0];
        state.camera.target = [5.0, 5.0, 5.0]; // pan (same distance)
        state.ensure_overlays_current();
        assert!(!state.dirty, "pan needs no re-bake (world-space geometry)");
    }

    /// The DRAWN angular arc is the half of this the user sees move: its radius is
    /// `ANGLE_ARC_RAD_PX * world_per_pixel`, so a zoom that doubles the
    /// world-per-pixel must double the arc in world space to keep it a constant
    /// 120 px on screen. Before the per-frame ensure the baked group kept the OLD
    /// radius — and because `dimension_hit_regions` sizes the grab circle from the
    /// LIVE camera, the drawn sweep handle and the circle that grabs it drifted
    /// apart by the whole radius delta.
    #[test]
    fn zoom_rescales_the_drawn_angular_arc_and_keeps_the_grab_circle_on_it() {
        let mut state = revolve_engine(90.0);
        state.arm_dimension("Rev");
        assert_eq!(
            state.widgets.overlay_group_names(),
            vec!["feature-dim-leaders"],
            "only the dimension gizmo is drawn, so the overlay bbox is its own"
        );

        let extent = |s: &EngineState| {
            let b = s.widgets.overlay_groups_bbox();
            let (min, max) = (b.min, b.max);
            (max[0] - min[0]).max(max[1] - min[1]).max(max[2] - min[2])
        };
        let before = extent(&state);
        assert!(before > 0.0, "the arc is drawn");

        // The grab circle sits ON the drawn sweep handle at the baked zoom.
        let hit_center = |s: &EngineState| {
            let areas: Vec<serde_json::Value> =
                serde_json::from_str(&s.dimension_hit_areas_json()).unwrap();
            let c = areas
                .iter()
                .find(|a| a["kind"] == "circle" && a["r"].as_f64().unwrap() > 10.0)
                .expect("the arc sweep-end grab circle")
                .clone();
            [c["c"][0].as_f64().unwrap(), c["c"][1].as_f64().unwrap()]
        };
        let wpp_baked = state.camera.world_per_pixel();
        let drawn_handle = |s: &EngineState, wpp: f64| {
            let ann = s.feature_dimension_annotations("Rev");
            let ann = ann.iter().find(|a| a.field_key == "angle").unwrap();
            let p = crate::feature_dimensions::arrow_handle_point(ann, wpp);
            let (x, y, _) = s.camera.project(p);
            [x, y]
        };
        let at_arm = drawn_handle(&state, wpp_baked);
        let hit_at_arm = hit_center(&state);
        assert!(
            (at_arm[0] - hit_at_arm[0]).hypot(at_arm[1] - hit_at_arm[1]) < 1.0,
            "at arm the grab circle sits on the drawn handle"
        );

        // Zoom out 2x, then run the per-frame upkeep.
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 40.0 };
        state.ensure_overlays_current();

        // The drawn arc doubled in world size (constant on screen)…
        let after = extent(&state);
        assert!(
            (after / before - 2.0).abs() < 0.05,
            "the drawn arc must scale with the zoom: {before} → {after}"
        );
        // …and the grab circle is still ON the handle the user can see, which is
        // now the one at the NEW world-per-pixel.
        let wpp_now = state.camera.world_per_pixel();
        let drawn_now = drawn_handle(&state, wpp_now);
        let hit_now = hit_center(&state);
        assert!(
            (drawn_now[0] - hit_now[0]).hypot(drawn_now[1] - hit_now[1]) < 1.0,
            "after the zoom the grab circle still sits on the drawn handle"
        );
        // The stale-bake handle is a long way off — proof the assertion has teeth.
        let stale = drawn_handle(&state, wpp_baked);
        assert!(
            (stale[0] - hit_now[0]).hypot(stale[1] - hit_now[1]) > 20.0,
            "the OLD-zoom handle is nowhere near the live grab circle"
        );
    }

    /// EVERY zoom path, not just the wheel: they are all the same one key
    /// (`camera.world_per_pixel()`), so keying the invalidation off that quantity
    /// covers them without a per-path hook. After the upkeep frame the gizmo is
    /// baked at the LIVE zoom whichever path moved it.
    #[test]
    fn every_zoom_path_rebakes_the_dimension_gizmo() {
        type Zoom = (&'static str, fn(&mut EngineState));
        let paths: Vec<Zoom> = vec![
            ("wheel", |s| {
                assert!(s.wheel(-240.0, None), "the wheel zooms");
            }),
            ("zoom-to-fit", |s| s.zoom_to_fit()),
            ("standard view (View menu — it zoom-to-fits)", |s| {
                assert!(s.standard_view("FRONT"));
            }),
            ("viewport resize", |s| s.resize(400.0, 200.0)),
            ("projection half-height", |s| {
                s.camera.projection = crate::view::Projection::Orthographic { half_height: 7.0 };
            }),
        ];
        for (name, apply) in paths {
            let mut state = cube_engine();
            state.resize(800.0, 600.0);
            state.camera.eye = [30.0, 20.0, 40.0];
            state.camera.target = [0.0, 0.0, 0.0];
            state.camera.up = [0.0, 1.0, 0.0];
            state.camera.projection =
                crate::view::Projection::Orthographic { half_height: 200.0 };
            state.arm_dimension("Box");
            let baked = state.feature_dim_overlay_wpp;
            assert!(baked > 0.0, "{name}: armed → baked");

            apply(&mut state);
            let live = state.camera.world_per_pixel();
            assert!(
                super::overlay_wpp_stale(baked, live),
                "{name} must move world-per-pixel ({baked} → {live})"
            );
            state.ensure_overlays_current();
            assert!(
                (state.feature_dim_overlay_wpp - live).abs() < live * 1e-9,
                "{name}: the gizmo is re-baked at the LIVE zoom"
            );
        }
    }

    /// The counter-case that says WHY keying on world-per-pixel is right — the
    /// camera moves that must NOT re-bake, and don't:
    ///   * pan and orbit hold the eye→target distance;
    ///   * the ViewCube (face, corner and navigation arrow alike) is a
    ///     fixed-pivot reorient — `apply_look_direction` / `apply_viewcube_arrow`
    ///     keep `camera.distance()`, so it is an ORBIT, never a zoom;
    ///   * the ortho↔perspective toggle solves for the distance / half-height
    ///     that PRESERVES apparent size (`projection_toggle_preserves_apparent_
    ///     size` in `view`), so the screen-constant sizing is already right.
    /// Nothing needs re-baking through any of them: the baked buffers are
    /// world-space, so the GPU re-projects them, and the hit regions are rebuilt
    /// from the live camera at pick time.
    #[test]
    fn pan_orbit_viewcube_and_projection_toggle_need_no_rebake() {
        let mut state = cube_engine();
        state.resize(800.0, 600.0);
        state.camera.eye = [30.0, 20.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };
        state.arm_dimension("Box");
        let baked = state.feature_dim_overlay_wpp;

        // A ViewCube FACE click reorients at a FIXED pivot distance.
        state.apply_look_direction([0.0, 0.0, 1.0], [0.0, 1.0, 0.0]);
        // A pan slides eye + target together, so the distance holds too.
        state.camera.eye = [35.0, 25.0, 45.0];
        state.camera.target = [5.0, 5.0, 5.0];
        // …and ortho → perspective keeps the apparent size.
        assert_eq!(state.toggle_projection(), "perspective");

        let live = state.camera.world_per_pixel();
        assert!(
            !super::overlay_wpp_stale(baked, live),
            "pan/orbit/ViewCube/projection-toggle hold world-per-pixel ({baked} → {live})"
        );
        state.dirty = false;
        state.ensure_overlays_current();
        assert!(!state.dirty, "none of these must re-bake");

        // …and the gizmo still grabs where it draws, because the hit regions
        // re-project against the live camera every pick.
        let anns = state.feature_dimension_annotations("Box");
        for ann in &anns {
            let (mx, my, _) = state.camera.project(ann.midpoint());
            assert_eq!(
                state.dimension_arrow_pick(mx, my).as_deref(),
                Some(ann.field_key.as_str()),
                "after pan+orbit+toggle the {} leader still grabs on its shaft",
                ann.field_key
            );
        }
    }

    /// The revolve's END cap face + one of that cap's boundary edges, read off the
    /// built [`revolve_engine`] scene (never hardcoded — the loop key in the cap
    /// name is the kernel's). The reported model (R3: `profile: "R2:L0_END"`,
    /// `axis: "R2:L0_END|S1:G3_RV[0]"`) has exactly this shape: a feature built
    /// off a FACE of a prior revolve and one of that face's edges, no sketch
    /// behind either.
    fn revolve_end_cap_and_boundary_edge() -> (String, String) {
        let state = revolve_engine(90.0);
        let solid = state.scene.solid("Rev").expect("the revolve solid is resident");
        let cap = solid
            .faces
            .iter()
            .map(|face| face.name.clone())
            .find(|name| name.ends_with("_END"))
            .expect("the revolve names its END cap");
        let edge = solid
            .edges
            .iter()
            .map(|edge| edge.name.clone())
            .find(|name| name.split('|').any(|side| side == cap))
            .expect("the END cap has a named boundary edge");
        (cap, edge)
    }

    /// The [`revolve_engine`] history (sketch "Sk" + revolve "Rev") with one more
    /// feature appended, built into an engine.
    fn engine_with_extra_feature(feature: serde_json::Value) -> EngineState {
        let request = serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [
                {
                    "type": "S",
                    "inputParams": { "id": "Sk" },
                    "persistentData": {
                        "basis": { "origin": [0,0,0], "x": [1,0,0], "y": [0,1,0], "z": [0,0,1] },
                        "sketch": {
                            "points": [
                                {"id":1,"x":2.0,"y":0.0}, {"id":2,"x":4.0,"y":0.0},
                                {"id":3,"x":4.0,"y":3.0}, {"id":4,"x":2.0,"y":3.0},
                                {"id":5,"x":0.0,"y":0.0}, {"id":6,"x":0.0,"y":1.0}
                            ],
                            "geometries": [
                                {"id":10,"type":"line","points":[1,2]},
                                {"id":11,"type":"line","points":[2,3]},
                                {"id":12,"type":"line","points":[3,4]},
                                {"id":13,"type":"line","points":[4,1]},
                                {"id":20,"type":"line","points":[5,6],"construction":true}
                            ],
                            "constraints": []
                        }
                    }
                },
                {
                    "type": "R",
                    "inputParams": { "id": "Rev", "profile": "Sk", "axis": "Sk:G20", "angle": 90.0 },
                    "persistentData": {}
                },
                feature
            ]
        })
        .to_string();
        let mut state = EngineState::new();
        state.set_history_json(&request).expect("the face-profile feature builds");
        state
    }

    fn fd_cross3(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
        [
            a[1] * b[2] - a[2] * b[1],
            a[2] * b[0] - a[0] * b[2],
            a[0] * b[1] - a[1] * b[0],
        ]
    }

    /// Regression (the reported model): a revolve whose `profile` is a resident
    /// solid FACE and whose `axis` is one of that face's edges — no sketch behind
    /// either — gets its angle gizmo like a sketch-profile revolve does. The refs
    /// resolver used to know sketch profiles only, so such a revolve emitted `[]`
    /// and the app showed no angle gizmo. The arc must be geometrically right too:
    /// centered ON the axis edge, zero reference ⟂ the axis, and sweeping the way
    /// the kernel swept the solid (toward the cap's OUTWARD normal).
    #[test]
    fn revolve_off_a_resident_face_profile_emits_its_angle_dim() {
        let (cap, edge) = revolve_end_cap_and_boundary_edge();
        let state = engine_with_extra_feature(serde_json::json!({
            "type": "R",
            "inputParams": { "id": "Rev2", "profile": cap, "axis": edge, "angle": 120.0 },
            "persistentData": {}
        }));
        assert!(state.scene.solid("Rev2").is_some(), "the face-profile revolve built a solid");

        let anns = state.feature_dimension_annotations("Rev2");
        assert_eq!(anns.len(), 1, "a face-profile revolve emits its angle dim: {anns:?}");
        let ann = &anns[0];
        assert_eq!(ann.kind, crate::feature_dimensions::FeatureDimKind::Angular);
        assert_eq!(ann.field_key, "angle");
        assert!((ann.value - 120.0).abs() < 1e-9, "value is the angle: {}", ann.value);

        // The arc is centered ON the axis edge and sweeps ABOUT it.
        let poly = state.scene.edge_polyline_world(&edge).expect("axis edge polyline");
        let (a, b) = (poly[0], *poly.last().unwrap());
        let edge_dir = fd_normalize3(fd_sub3(b, a));
        let along = fd_dot3(fd_sub3(ann.center, a), edge_dir);
        let foot = [
            a[0] + edge_dir[0] * along,
            a[1] + edge_dir[1] * along,
            a[2] + edge_dir[2] * along,
        ];
        assert!(
            fd_norm3(fd_sub3(ann.center, foot)) < 1e-6,
            "arc center {:?} lies on the axis edge {a:?}→{b:?}",
            ann.center
        );
        assert!(
            fd_dot3(ann.axis, edge_dir).abs() > 1.0 - 1e-9,
            "arc axis {:?} is the edge direction {edge_dir:?}",
            ann.axis
        );
        assert!(fd_dot3(ann.ref_dir, ann.axis).abs() < 1e-9, "zero reference ⟂ axis");

        // Orientation: the arc's initial motion (the tangent at θ=0) carries the
        // profile toward the cap's OUTWARD normal — the kernel's own rule — so the
        // built solid sits on that side of the axis.
        let tangent = fd_cross3(ann.axis, ann.ref_dir);
        let (_, cap_normal) = state.scene.face_plane_world(&cap).expect("cap plane");
        assert!(
            fd_dot3(tangent, cap_normal) > 0.5,
            "the arc sweeps toward the cap's outward normal {cap_normal:?}: tangent {tangent:?}"
        );
        let bbox = &state.scene.solid("Rev2").unwrap().bbox;
        let bbox_center = [
            (bbox.min[0] + bbox.max[0]) * 0.5,
            (bbox.min[1] + bbox.max[1]) * 0.5,
            (bbox.min[2] + bbox.max[2]) * 0.5,
        ];
        assert!(
            fd_dot3(tangent, fd_sub3(bbox_center, ann.center)) > 0.5,
            "the built solid lies on the arc's sweep side: bbox center {bbox_center:?}"
        );

        // The JSON surface the app reads (a non-`[]` result is what auto-arms the
        // gizmo on expand) carries the one angular entry.
        let json: serde_json::Value =
            serde_json::from_str(&state.feature_dimension_annotations_json("Rev2")).unwrap();
        let arr = json.as_array().unwrap();
        assert_eq!(arr.len(), 1, "one angular dim in JSON: {arr:?}");
        assert_eq!(arr[0]["fieldKey"], "angle");
        assert_eq!(arr[0]["kind"], "angular");
    }

    /// The same resolver serves the extrude: an extrude whose `profile` is a
    /// resident solid FACE gets its distance dims, anchored at the face's centroid
    /// and running along the face's OUTWARD normal (the direction the kernel's
    /// face profile extrudes).
    #[test]
    fn extrude_off_a_resident_face_profile_emits_its_distance_dims() {
        let (cap, _) = revolve_end_cap_and_boundary_edge();
        let state = engine_with_extra_feature(serde_json::json!({
            "type": "E",
            "inputParams": { "id": "Ext", "profile": cap, "distance": 5.0 },
            "persistentData": {}
        }));
        assert!(state.scene.solid("Ext").is_some(), "the face-profile extrude built a solid");

        let anns = state.feature_dimension_annotations("Ext");
        assert_eq!(anns.len(), 2, "a face-profile extrude emits distance + distanceBack: {anns:?}");
        assert_eq!(anns[0].field_key, "distance");
        assert_eq!(anns[1].field_key, "distanceBack");
        let (centroid, normal) = state.scene.face_plane_world(&cap).expect("cap plane");
        assert!(
            fd_norm3(fd_sub3(anns[0].point_a, centroid)) < 1e-9,
            "anchored at the face centroid {centroid:?}: {:?}",
            anns[0].point_a
        );
        let leg = fd_sub3(anns[0].point_b, anns[0].point_a);
        assert!((fd_norm3(leg) - 5.0).abs() < 1e-9, "the D leg is `distance` long: {leg:?}");
        assert!(
            fd_dot3(fd_normalize3(leg), normal) > 1.0 - 1e-9,
            "the D leg runs along the outward normal {normal:?}: {leg:?}"
        );
        // The solid really extends that way: its bbox reaches `distance` past the
        // cap plane along the outward normal, and not behind it.
        let bbox = &state.scene.solid("Ext").unwrap().bbox;
        let corners = (0..8).map(|k| {
            [
                if k & 1 == 0 { bbox.min[0] } else { bbox.max[0] },
                if k & 2 == 0 { bbox.min[1] } else { bbox.max[1] },
                if k & 4 == 0 { bbox.min[2] } else { bbox.max[2] },
            ]
        });
        let heights: Vec<f64> = corners.map(|c| fd_dot3(fd_sub3(c, centroid), normal)).collect();
        let top = heights.iter().cloned().fold(f64::MIN, f64::max);
        let bottom = heights.iter().cloned().fold(f64::MAX, f64::min);
        assert!((top - 5.0).abs() < 1e-3, "solid reaches distance 5 along the normal: {top}");
        assert!(bottom.abs() < 1e-3, "solid starts at the cap plane: {bottom}");
    }

    /// The scene-side face plane the face-profile fallback reads: for every
    /// named face of an axis-aligned cube, the centroid is the face center on the
    /// bbox boundary and the normal points OUTWARD (unit); an unknown name is
    /// `None`.
    #[test]
    fn face_plane_world_of_a_cube_face_is_its_center_with_the_outward_normal() {
        let state = cube_engine();
        let solid = state.scene.solid("Box").expect("cube resident");
        let size = [10.0, 20.0, 30.0];
        let mid = [5.0, 10.0, 15.0];
        let named: Vec<&str> = solid
            .faces
            .iter()
            .map(|face| face.name.as_str())
            .filter(|name| !name.is_empty())
            .collect();
        assert_eq!(named.len(), 6, "six named cube faces: {named:?}");
        for name in named {
            let (centroid, normal) = state
                .scene
                .face_plane_world(name)
                .unwrap_or_else(|| panic!("face {name} has a plane"));
            assert!((fd_norm3(normal) - 1.0).abs() < 1e-9, "{name}: unit normal {normal:?}");
            let axis = (0..3)
                .find(|&k| normal[k].abs() > 1.0 - 1e-6)
                .unwrap_or_else(|| panic!("{name}: axis-aligned normal {normal:?}"));
            let expected_axis_coord = if normal[axis] > 0.0 { size[axis] } else { 0.0 };
            for k in 0..3 {
                let expected = if k == axis { expected_axis_coord } else { mid[k] };
                assert!(
                    (centroid[k] - expected).abs() < 1e-4,
                    "{name}: centroid {centroid:?} is the face center"
                );
            }
            assert!(
                fd_dot3(normal, fd_sub3(centroid, mid)) > 0.0,
                "{name}: normal {normal:?} points outward from {centroid:?}"
            );
        }
        assert!(state.scene.face_plane_world("Box:NOPE").is_none());
    }
}