brep_render/engine_state/

transform_gizmo.rs

use super::*;

/// Which of the two gizmos is currently armed for the feature. `Transform` shows
/// the move/rotate gizmo; `Dimension` shows the on-canvas draggable dimension
/// annotations (feature-dimensions FD-1). Expanding a feature arms `Dimension`;
/// the viewport sphere/center toggle flips to `Transform` and back. The two modes
/// are EXCLUSIVE — the transform gizmo never renders in `Dimension` mode and
/// vice-versa.
#[derive(Default, Clone, Copy, PartialEq, Eq, Debug)]
pub enum GizmoMode {
    /// Neither gizmo armed (`feature_id` is `None`).
    #[default]
    None,
    /// The move/rotate transform gizmo is armed.
    Transform,
    /// The dimension-annotation gizmo is armed (FD-1).
    Dimension,
}

/// The transform-controls gizmo controller state (see the impl block below).
#[derive(Default)]
pub struct TransformArm {
    /// The feature id whose gizmo is armed (for EITHER mode), or `None`
    /// (disarmed → `mode == None`).
    pub(super) feature_id: Option<String>,
    /// Which gizmo is armed for `feature_id` (transform vs dimension). `None`
    /// exactly when `feature_id` is `None`.
    pub(super) mode: GizmoMode,
    /// The live handle drag, captured on pointer-down over a gizmo handle.
    pub(super) drag: Option<TransformDrag>,
}

/// A grab snapshot for an in-flight transform-gizmo drag: the grabbed handle,
/// the grab screen point, and the feature's pose AT GRAB. Every drag move
/// resolves an absolute delta from this grab (against the pinned grab-time
/// frame) and re-applies it to `start`, so the drag never accumulates error.
#[derive(Clone, Copy)]
pub(super) struct TransformDrag {
    handle: u32,
    sx: f32,
    sy: f32,
    start: TransformPose,
}

/// A TRS pose read from / written to a feature's `inputParams.transform`
/// (`rotation` in DEGREES, intrinsic XYZ Euler order — the kernel `transform_bake`
/// convention, `M = T·R·S`).
#[derive(Clone, Copy, PartialEq, Debug)]
struct TransformPose {
    position: [f64; 3],
    rotation_deg: [f64; 3],
    scale: [f64; 3],
}

/// A resolved gizmo drag delta in WORLD space (the ported drag-delta mapping).
#[derive(Clone, Copy, PartialEq, Debug)]
enum TransformDelta {
    /// World-space translation, added to `position`.
    Translate([f64; 3]),
    /// Rotation about a WORLD axis by `radians`, pre-multiplied onto the pose's
    /// orientation (so it spins about the feature's own axis).
    Rotate { axis: [f64; 3], radians: f64 },
    /// No usable delta (unknown handle / degenerate drag).
    None,
}

impl EngineState {
    /// Whether the TRANSFORM gizmo (move/rotate) is armed for ANY feature. False
    /// in dimension mode — the two ◎ modes are exclusive, so the transform gizmo
    /// arms/handles never render while dimensions are shown.
    pub fn transform_armed(&self) -> bool {
        matches!(self.transform_gizmo.mode, GizmoMode::Transform)
    }

    /// The transform-gizmo-armed feature id (empty unless in transform mode).
    pub fn transform_armed_feature(&self) -> String {
        if self.transform_armed() {
            self.transform_gizmo.feature_id.clone().unwrap_or_default()
        } else {
            String::new()
        }
    }

    /// Whether the TRANSFORM gizmo is armed for THIS feature.
    pub fn transform_armed_for(&self, feature_id: &str) -> bool {
        self.transform_armed() && self.transform_gizmo.feature_id.as_deref() == Some(feature_id)
    }

    /// Arm the TRANSFORM gizmo for `feature_id` and feed it at the feature's
    /// transform frame. Re-arming a different feature moves the gizmo to it.
    /// Clears any dimension overlay (the modes are exclusive).
    ///
    /// An ACOMP (assembly component) feature ROUTES to the component Move gizmo
    /// instead: its `transform` is the component pose (`{translate,
    /// rotateEulerDeg}`, a different shape), its gizmo attaches at the member
    /// bbox center, commits on release, and refuses fixed instances — the
    /// generic position/rotationEuler gizmo must never write its keys into an
    /// ACOMP's params. This covers the history panel's arm-on-expand path too.
    pub fn arm_transform(&mut self, feature_id: &str) {
        let is_acomp = self
            .history
            .index_of(feature_id)
            .and_then(|index| self.history.feature_type(index))
            .is_some_and(|ty| super::components::is_acomp_feature_type(&ty));
        if is_acomp {
            self.component_move_arm(feature_id);
            return;
        }
        self.component_move_reset();
        self.transform_gizmo.feature_id = Some(feature_id.to_string());
        self.transform_gizmo.mode = GizmoMode::Transform;
        self.transform_gizmo.drag = None;
        self.clear_feature_dimension_overlay();
        self.sync_transform_gizmo();
    }

    /// Disarm: hide BOTH gizmos + drop any in-flight drag. Also resets the
    /// component Move gizmo (the widget slot is shared, so a disarm clears
    /// whichever controller was feeding it).
    pub fn disarm_transform(&mut self) {
        self.component_move_reset();
        self.transform_gizmo.feature_id = None;
        self.transform_gizmo.mode = GizmoMode::None;
        self.transform_gizmo.drag = None;
        let _ = self.widgets.set_transform_json("null");
        self.clear_feature_dimension_overlay();
        self.dirty = true;
    }

    /// The armed feature's current TRS pose (from its `inputParams.transform`),
    /// or `None` when disarmed / the feature vanished.
    fn armed_pose(&self) -> Option<TransformPose> {
        let id = self.transform_gizmo.feature_id.as_deref()?;
        let index = self.history.index_of(id)?;
        let params = self.history.feature_params(index)?;
        let transform = params.get("transform");
        Some(TransformPose {
            position: read_pose_vec3(transform, "position", [0.0, 0.0, 0.0]),
            rotation_deg: read_pose_vec3(transform, "rotationEuler", [0.0, 0.0, 0.0]),
            scale: read_pose_vec3(transform, "scale", [1.0, 1.0, 1.0]),
        })
    }

    /// (Re)feed the widget gizmo at the armed feature's frame: origin =
    /// `position`, axes = the feature's rotated basis (intrinsic XYZ Euler order, matching
    /// the kernel bake). Auto-disarms if the feature vanished. Called every drag
    /// frame from `transform_drag_to` so the widget tracks the moving pose live
    /// (Fix 3); the drag delta resolves against the frozen grab frame, so this
    /// re-sync never feeds back into the drag math.
    pub fn sync_transform_gizmo(&mut self) {
        // Only the TRANSFORM mode feeds the move/rotate widget; in dimension mode
        // the widget stays hidden (the annotations render as an overlay instead).
        if !matches!(self.transform_gizmo.mode, GizmoMode::Transform) {
            return;
        }
        let Some(pose) = self.armed_pose() else {
            self.disarm_transform();
            return;
        };
        let _ = self.widgets.set_transform_json(&transform_frame_json(&pose));
        self.dirty = true;
    }

    /// Whether feature `feature_id` carries a `transform` param (a Transform
    /// group), so it CAN show a transform gizmo. The panel's auto-arm-on-expand
    /// uses this: a feature with NO dimension gizmo but WITH a transform
    /// (datum/helix/pattern/port) arms the TRANSFORM gizmo directly on expand,
    /// instead of being left with no gizmo at all now that the ◎ arm button is
    /// gone. (`armed_pose` alone can't gate this — it defaults to identity for a
    /// transform-less feature, so a boolean/fillet would show a spurious gizmo.)
    pub fn feature_has_transform(&self, feature_id: &str) -> bool {
        self.history
            .index_of(feature_id)
            .and_then(|i| self.history.feature_params(i))
            .map(|params| params.get("transform").is_some())
            .unwrap_or(false)
    }

    /// The armed gizmo origin projected to VIEWPORT-LOCAL px (the center handle
    /// sits here). The history panel publishes it so the headed verifier can
    /// locate + drag the gizmo. `None` when disarmed / not projectable (the ONE
    /// [`crate::view::ViewCamera::projectable`] policy — ortho always projects).
    pub fn transform_gizmo_anchor(&self) -> Option<(f64, f64)> {
        let pose = self.armed_pose()?;
        let (sx, sy, _) = self.camera.project(pose.position);
        self.camera.projectable(pose.position).then_some((sx, sy))
    }

    /// The transform gizmo's axis-end labels as JSON:
    /// `[{ text:"XC"|"YC"|"ZC", rgb:[r,g,b], world:[x,y,z] }]`. The app projects
    /// each `world` point and draws the colored egui label just past the matching
    /// cone tip (X=red, Y=green, Z=blue). `[]` unless the TRANSFORM gizmo is armed.
    pub fn transform_axis_labels_json(&self) -> String {
        if !matches!(self.transform_gizmo.mode, GizmoMode::Transform) {
            return "[]".to_string();
        }
        let Some(pose) = self.armed_pose() else {
            return "[]".to_string();
        };
        let euler = [
            pose.rotation_deg[0].to_radians(),
            pose.rotation_deg[1].to_radians(),
            pose.rotation_deg[2].to_radians(),
        ];
        let axes = [
            normalize3(rotate_euler_xyz_f64([1.0, 0.0, 0.0], euler)),
            normalize3(rotate_euler_xyz_f64([0.0, 1.0, 0.0], euler)),
            normalize3(rotate_euler_xyz_f64([0.0, 0.0, 1.0], euler)),
        ];
        // Just past the cone tip, screen-constant.
        let gap_px = 12.0_f64;
        let dist = (brep_gizmos::transform::PX_AXIS_LEN as f64 + gap_px) * self.camera.world_per_pixel();
        let labels: [(&str, [f32; 3]); 3] = [
            ("XC", [0.92, 0.26, 0.28]), // red
            ("YC", [0.30, 0.78, 0.36]), // green
            ("ZC", [0.30, 0.52, 0.98]), // blue
        ];
        let out: Vec<serde_json::Value> = (0..3)
            .map(|i| {
                let o = pose.position;
                let a = axes[i];
                serde_json::json!({
                    "text": labels[i].0,
                    "rgb": labels[i].1,
                    "world": [o[0] + a[0] * dist, o[1] + a[1] * dist, o[2] + a[2] * dist],
                })
            })
            .collect();
        serde_json::to_string(&out).unwrap_or_else(|_| "[]".to_string())
    }

    /// DEBUG overlay: the EXACT SCREEN-space (viewport-local px) pickable regions
    /// of the transform gizmo — the SAME [`hit_regions`](brep_gizmos::transform::
    /// TransformGizmo::hit_regions) the hit test 2D-tests the cursor against — so
    /// the red outline can NEVER drift from the grabbable area. Each item is a
    /// `{ kind:"capsule", a:[x,y], b:[x,y], r }` (axis arrows) or
    /// `{ kind:"circle", c:[x,y], r }` (center + rotation grab spheres); the app
    /// only offsets by `rect.min` to draw. Projection + the perspective front-clip
    /// already happened in the region builder. The WIDGET FEED is authoritative —
    /// exactly like [`transform_pick`](Self::transform_pick), which has no mode
    /// gate — so this emits for EVERY controller of the shared widget gizmo (the
    /// feature TRANSFORM mode and the assembly component Move gizmo alike) and is
    /// `[]` precisely when the widget is hidden (nothing is grabbable).
    pub fn transform_hit_areas_json(&self) -> String {
        let cam = gizmo_camera(&self.camera);
        let regions = self.widgets.transform_hit_regions(&cam);
        super::camera_widgets::hit_shapes_json(regions.iter().map(|(_, shape)| shape))
    }

    /// Begin a gizmo drag at viewport px `(x, y)` when the gizmo is armed AND a
    /// handle is under the pointer. Returns whether a handle was grabbed — the
    /// viewport routes the drag to the gizmo (not the camera) when `true`; a press
    /// on empty space returns `false` and still orbits.
    pub fn transform_press(&mut self, x: f64, y: f64) -> bool {
        // Only grabbable in TRANSFORM mode — in dimension mode the dimension
        // handles own the pointer (routed by the app), and disarmed grabs nothing.
        if !matches!(self.transform_gizmo.mode, GizmoMode::Transform) {
            return false;
        }
        let handle = self.transform_pick(x, y);
        if handle == 0 {
            return false;
        }
        let Some(pose) = self.armed_pose() else {
            return false;
        };
        self.widgets.set_transform_active(handle);
        self.transform_gizmo.drag = Some(TransformDrag {
            handle,
            sx: x as f32,
            sy: y as f32,
            start: pose,
        });
        self.dirty = true;
        true
    }

    /// Whether a gizmo handle drag is in flight.
    pub fn transform_dragging(&self) -> bool {
        self.transform_gizmo.drag.is_some()
    }

    /// Continue the in-flight gizmo drag to viewport px `(cx, cy)`: resolve the
    /// world delta from the grab (against the frozen grab-time frame), apply it to
    /// the grab pose, write it back into the feature's `transform`, and re-run so
    /// the model follows live. Then re-sync the VISIBLE gizmo to the moved pose so
    /// the widget tracks the pointer in real time (Fix 3) — the delta stays
    /// anchored to `drag.start`, so this visual sync never feeds back on itself.
    pub fn transform_drag_to(&mut self, cx: f64, cy: f64) {
        let Some(drag) = self.transform_gizmo.drag else {
            return;
        };
        let delta = self.resolve_transform_delta(&drag, cx, cy);
        if matches!(delta, TransformDelta::None) {
            return;
        }
        let pose = apply_transform_delta(&drag.start, &delta);
        self.write_armed_pose(&pose);
        // Live-follow: re-feed the widget frame to the just-written pose. NB
        // `finish_apply` skips this while a drag is in flight (drag.is_some()), so
        // the sync happens here. The active-handle gold highlight survives (the
        // widget only clears it on a `null` feed).
        self.sync_transform_gizmo();
    }

    /// End the drag: clear the active-handle highlight + re-sync the gizmo to the
    /// feature's final (moved) pose (unpin the frame).
    pub fn transform_release(&mut self) {
        if self.transform_gizmo.drag.take().is_some() {
            self.widgets.set_transform_active(0);
            self.sync_transform_gizmo();
        }
    }

    /// Resolve the widget gizmo's frame delta for a drag from the grab to
    /// `(cx, cy)` into a world-space [`TransformDelta`] — via
    /// `WidgetRegistry::transform_drag_json_with_frame` + the ported commit mapping.
    ///
    /// The delta is resolved against the FROZEN grab-time frame (rebuilt from
    /// `drag.start`), NOT the live widget gizmo — so `transform_drag_to` can
    /// re-sync the VISIBLE gizmo to the moving pose every frame (Fix 3 live-follow)
    /// without the visual sync feeding back into the drag math. Since a param
    /// change outside a drag always flows through `finish_apply` → `sync`, the grab
    /// pose is exactly the frame the widget held at grab, so this is behaviorally
    /// identical to the old pinned-widget-frame math — plus the live visual sync.
    fn resolve_transform_delta(&self, drag: &TransformDrag, cx: f64, cy: f64) -> TransformDelta {
        let cam = gizmo_camera(&self.camera);
        let frame_json = transform_frame_json(&drag.start);
        let json = self.widgets.transform_drag_json_with_frame(
            &cam,
            &frame_json,
            drag.handle,
            drag.sx,
            drag.sy,
            cx as f32,
            cy as f32,
        );
        let value: serde_json::Value =
            serde_json::from_str(&json).unwrap_or(serde_json::Value::Null);
        match value.get("kind").and_then(|k| k.as_str()) {
            Some("translate") => {
                TransformDelta::Translate(json_vec3(value.get("world").and_then(|a| a.as_array())))
            }
            Some("rotate") => TransformDelta::Rotate {
                axis: json_vec3(value.get("axisWorld").and_then(|a| a.as_array())),
                radians: value.get("radians").and_then(|n| n.as_f64()).unwrap_or(0.0),
            },
            _ => TransformDelta::None,
        }
    }

    /// Write `pose` into the armed feature's `inputParams.transform.{position,
    /// rotationEuler}` (preserving every other field, incl. `scale`) and re-run.
    fn write_armed_pose(&mut self, pose: &TransformPose) {
        let Some(id) = self.transform_gizmo.feature_id.clone() else {
            return;
        };
        let Some(index) = self.history.index_of(&id) else {
            return;
        };
        let mut params = self
            .history
            .feature_params(index)
            .unwrap_or_else(|| serde_json::json!({}));
        // Ensure `transform` is an object, then set the two edited vectors.
        if !params.get("transform").map(|t| t.is_object()).unwrap_or(false) {
            if let Some(object) = params.as_object_mut() {
                object.insert("transform".into(), serde_json::json!({}));
            }
        }
        if let Some(transform) = params.get_mut("transform").and_then(|t| t.as_object_mut()) {
            transform.insert("position".into(), serde_json::json!(pose.position));
            transform.insert("rotationEuler".into(), serde_json::json!(pose.rotation_deg));
        }
        let _ = self.update_feature_params(&id, &params.to_string());
    }
}

/// Apply a resolved drag delta to the grab pose → the new pose. PURE (the unit
/// test drives it directly). Translation adds the world delta to `position`;
/// rotation pre-multiplies a world-axis quaternion onto the pose's orientation
/// and re-extracts the intrinsic XYZ Euler order (degrees). `scale` is a documented seam
/// (no scale handle exists in the gizmo yet), so it is carried through unchanged.
fn apply_transform_delta(start: &TransformPose, delta: &TransformDelta) -> TransformPose {
    match delta {
        TransformDelta::Translate(world) => TransformPose {
            position: [
                start.position[0] + world[0],
                start.position[1] + world[1],
                start.position[2] + world[2],
            ],
            ..*start
        },
        TransformDelta::Rotate { axis, radians } => {
            let q0 = quat_from_euler_xyz_deg(start.rotation_deg);
            let dq = quat_from_axis_angle(*axis, *radians);
            let nq = quat_mul(dq, q0);
            TransformPose {
                rotation_deg: euler_xyz_deg_from_quat(nq),
                ..*start
            }
        }
        TransformDelta::None => *start,
    }
}

/// Read a `[x, y, z]` from a transform sub-field (numbers only; missing / short
/// arrays keep the per-index default).
fn read_pose_vec3(transform: Option<&serde_json::Value>, key: &str, default: [f64; 3]) -> [f64; 3] {
    let array = transform.and_then(|t| t.get(key)).and_then(|v| v.as_array());
    let mut out = default;
    if let Some(array) = array {
        for (index, slot) in out.iter_mut().enumerate() {
            if let Some(number) = array.get(index).and_then(|v| v.as_f64()) {
                *slot = number;
            }
        }
    }
    out
}

/// A `[f64; 3]` from a JSON number array (zero-filled past the end).
fn json_vec3(array: Option<&Vec<serde_json::Value>>) -> [f64; 3] {
    let mut out = [0.0; 3];
    if let Some(array) = array {
        for (index, slot) in out.iter_mut().enumerate() {
            if let Some(number) = array.get(index).and_then(|v| v.as_f64()) {
                *slot = number;
            }
        }
    }
    out
}

/// The gizmo frame feed (`set_transform_json` shape) for a pose: origin =
/// `position`, axes = the feature's rotated basis (intrinsic XYZ Euler order, matching
/// the kernel bake), with the center free-move handle shown.
fn transform_frame_json(pose: &TransformPose) -> String {
    let euler = [
        pose.rotation_deg[0].to_radians(),
        pose.rotation_deg[1].to_radians(),
        pose.rotation_deg[2].to_radians(),
    ];
    let x = normalize3(rotate_euler_xyz_f64([1.0, 0.0, 0.0], euler));
    let y = normalize3(rotate_euler_xyz_f64([0.0, 1.0, 0.0], euler));
    let z = normalize3(rotate_euler_xyz_f64([0.0, 0.0, 1.0], euler));
    serde_json::json!({
        "origin": pose.position,
        "x": x,
        "y": y,
        "z": z,
        "showCenter": true,
    })
    .to_string()
}

pub(super) fn normalize3(v: [f64; 3]) -> [f64; 3] {
    let length = (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]).sqrt();
    if length < 1e-12 {
        [0.0, 0.0, 1.0]
    } else {
        [v[0] / length, v[1] / length, v[2] / length]
    }
}

/// Apply an intrinsic XYZ Euler (radians) to a vector — the EXACT matrix the kernel
/// bake (`transform_bake` / `datum::rotate_euler_xyz`) uses, so the fed gizmo
/// frame aligns with the baked solid.
pub(crate) fn rotate_euler_xyz_f64(v: [f64; 3], euler: [f64; 3]) -> [f64; 3] {
    let (c1, s1) = (euler[0].cos(), euler[0].sin());
    let (c2, s2) = (euler[1].cos(), euler[1].sin());
    let (c3, s3) = (euler[2].cos(), euler[2].sin());
    let m00 = c2 * c3;
    let m01 = -c2 * s3;
    let m02 = s2;
    let m10 = c1 * s3 + c3 * s1 * s2;
    let m11 = c1 * c3 - s1 * s2 * s3;
    let m12 = -c2 * s1;
    let m20 = s1 * s3 - c1 * c3 * s2;
    let m21 = c3 * s1 + c1 * s2 * s3;
    let m22 = c1 * c2;
    [
        m00 * v[0] + m01 * v[1] + m02 * v[2],
        m10 * v[0] + m11 * v[1] + m12 * v[2],
        m20 * v[0] + m21 * v[1] + m22 * v[2],
    ]
}

// --- quaternion helpers (ported from CombinedTransformControls) -----

pub(super) type Quat = [f64; 4]; // [x, y, z, w]

pub(super) fn quat_from_axis_angle(axis: [f64; 3], angle: f64) -> Quat {
    let n = normalize3(axis);
    let half = angle * 0.5;
    let s = half.sin();
    [n[0] * s, n[1] * s, n[2] * s, half.cos()]
}

/// Quaternion from an intrinsic XYZ Euler (degrees in).
pub(super) fn quat_from_euler_xyz_deg(deg: [f64; 3]) -> Quat {
    let (c1, s1) = ((deg[0].to_radians() * 0.5).cos(), (deg[0].to_radians() * 0.5).sin());
    let (c2, s2) = ((deg[1].to_radians() * 0.5).cos(), (deg[1].to_radians() * 0.5).sin());
    let (c3, s3) = ((deg[2].to_radians() * 0.5).cos(), (deg[2].to_radians() * 0.5).sin());
    [
        s1 * c2 * c3 + c1 * s2 * s3,
        c1 * s2 * c3 - s1 * c2 * s3,
        c1 * c2 * s3 + s1 * s2 * c3,
        c1 * c2 * c3 - s1 * s2 * s3,
    ]
}

/// Quaternion product `a * b`.
pub(super) fn quat_mul(a: Quat, b: Quat) -> Quat {
    [
        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
    ]
}

/// Intrinsic XYZ Euler from a quaternion (via the rotation matrix) → the
/// 'XYZ' Euler in DEGREES. Uses the SAME matrix element naming as
/// `rotate_euler_xyz_f64`, so the round-trip is consistent with the kernel bake.
pub(super) fn euler_xyz_deg_from_quat(q: Quat) -> [f64; 3] {
    let [x, y, z, w] = q;
    let (x2, y2, z2) = (x + x, y + y, z + z);
    let (xx, xy, xz) = (x * x2, x * y2, x * z2);
    let (yy, yz, zz) = (y * y2, y * z2, z * z2);
    let (wx, wy, wz) = (w * x2, w * y2, w * z2);
    // Rotation matrix elements (m<row><col> naming).
    let m11 = 1.0 - (yy + zz);
    let m12 = xy - wz;
    let m13 = xz + wy;
    let m22 = 1.0 - (xx + zz);
    let m23 = yz - wx;
    let m32 = yz + wx;
    let m33 = 1.0 - (xx + yy);
    let ey = m13.clamp(-1.0, 1.0).asin();
    let (ex, ez) = if m13.abs() < 0.9999999 {
        ((-m23).atan2(m33), (-m12).atan2(m11))
    } else {
        (m32.atan2(m22), 0.0)
    };
    [ex.to_degrees(), ey.to_degrees(), ez.to_degrees()]
}

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

    /// A one-feature history document: a `P.CU` cube `name` at the origin with an
    /// identity transform (so the gizmo arms at [0,0,0], world XYZ frame).
    fn cube_request(name: &str, size: f64) -> String {
        serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "P.CU",
                "inputParams": {
                    "id": name,
                    "sizeX": size, "sizeY": size, "sizeZ": size,
                    "transform": {
                        "position": [0.0, 0.0, 0.0],
                        "rotationEuler": [0.0, 0.0, 0.0],
                        "scale": [1.0, 1.0, 1.0]
                    },
                    "boolean": { "targets": [], "operation": "NONE" }
                },
                "persistentData": {}
            }]
        })
        .to_string()
    }

    fn ident() -> TransformPose {
        TransformPose {
            position: [1.0, 2.0, 3.0],
            rotation_deg: [0.0, 0.0, 0.0],
            scale: [1.0, 1.0, 1.0],
        }
    }

    #[test]
    fn translate_delta_adds_world_to_position() {
        let pose = apply_transform_delta(&ident(), &TransformDelta::Translate([4.0, -1.0, 0.5]));
        assert_eq!(pose.position, [5.0, 1.0, 3.5]);
        assert_eq!(pose.rotation_deg, [0.0, 0.0, 0.0]);
        assert_eq!(pose.scale, [1.0, 1.0, 1.0]);
    }

    #[test]
    fn rotate_delta_about_z_yields_z_euler() {
        // +90° about world +Z from identity orientation → rotationEuler [0,0,90].
        let pose = apply_transform_delta(
            &ident(),
            &TransformDelta::Rotate {
                axis: [0.0, 0.0, 1.0],
                radians: std::f64::consts::FRAC_PI_2,
            },
        );
        assert!((pose.rotation_deg[0]).abs() < 1e-6, "{:?}", pose.rotation_deg);
        assert!((pose.rotation_deg[1]).abs() < 1e-6, "{:?}", pose.rotation_deg);
        assert!((pose.rotation_deg[2] - 90.0).abs() < 1e-4, "{:?}", pose.rotation_deg);
        // Rotation pivots about the origin → position holds.
        assert_eq!(pose.position, [1.0, 2.0, 3.0]);
    }

    #[test]
    fn euler_quat_roundtrip_is_identity() {
        // A non-gimbal compound rotation round-trips euler→quat→euler.
        let deg = [30.0, 45.0, 60.0];
        let back = euler_xyz_deg_from_quat(quat_from_euler_xyz_deg(deg));
        for k in 0..3 {
            assert!((back[k] - deg[k]).abs() < 1e-4, "axis {k}: {back:?} vs {deg:?}");
        }
    }

    #[test]
    fn rotate_about_local_axis_composes_onto_existing_orientation() {
        // Start already rotated 90° about Z; add 90° about the (world) Z axis →
        // 180° about Z. Pre-multiplying the world-Z delta gives a valid euler for
        // a 180°-about-Z orientation (±180 about Z is equivalent).
        let start = TransformPose {
            rotation_deg: [0.0, 0.0, 90.0],
            ..ident()
        };
        let pose = apply_transform_delta(
            &start,
            &TransformDelta::Rotate {
                axis: [0.0, 0.0, 1.0],
                radians: std::f64::consts::FRAC_PI_2,
            },
        );
        // Compare orientations via the quaternion (euler triples for 180°-Z can
        // be [0,0,180] or [180,0,-180]…; the quaternion is unambiguous up to sign).
        let got = quat_from_euler_xyz_deg(pose.rotation_deg);
        let want = quat_from_euler_xyz_deg([0.0, 0.0, 180.0]);
        let dot = got[0] * want[0] + got[1] * want[1] + got[2] * want[2] + got[3] * want[3];
        assert!(dot.abs() > 0.9999, "orientation mismatch: {got:?} vs {want:?}");
    }

    #[test]
    fn arm_press_drag_moves_the_feature_then_disarms() {
        let mut engine = EngineState::new();
        engine.set_history_json(&cube_request("Pin", 10.0)).unwrap();
        engine.resize(800.0, 600.0);
        engine.camera.eye = [0.0, 0.0, 40.0];
        engine.camera.target = [0.0, 0.0, 0.0];
        engine.camera.up = [0.0, 1.0, 0.0];
        engine.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        assert!(!engine.transform_armed());
        engine.arm_transform("Pin");
        assert!(engine.transform_armed() && engine.transform_armed_for("Pin"));
        assert!(engine.widgets.has_transform(), "arming feeds the widget gizmo");

        // The gizmo origin (= Pin position [0,0,0]) projects to the viewport
        // center; the center free-move handle sits there.
        let (ax, ay) = engine.transform_gizmo_anchor().expect("armed anchor");
        assert!((ax - 400.0).abs() < 1.0 && (ay - 300.0).abs() < 1.0, "anchor {ax},{ay}");

        // The VISIBLE gizmo origin starts at the grab pose (Pin at the world origin).
        let origin_before = engine.widgets.transform_origin().expect("gizmo shown");
        assert!(origin_before[0].abs() < 1e-4, "gizmo starts at x=0: {origin_before:?}");

        // Press the handle + drag screen-right → +X world translate.
        assert!(engine.transform_press(ax, ay), "press grabs a handle");
        assert!(engine.transform_dragging());
        engine.transform_drag_to(ax + 60.0, ay);

        let index = engine.history.index_of("Pin").unwrap();
        let params = engine.history.feature_params(index).unwrap();
        let moved_x = params["transform"]["position"][0].as_f64().unwrap();
        assert!(moved_x > 0.0, "Pin moved +X, got {:?}", params["transform"]["position"]);

        // Fix 3 live-follow: MID-DRAG (before release) the VISIBLE gizmo has already
        // re-synced to the moved pose — its origin tracks the feature's new +X
        // position, so the widget follows the pointer in real time. And it matches
        // the just-written param (no drift between widget + feature).
        let origin_mid = engine.widgets.transform_origin().expect("gizmo still shown");
        assert!(
            origin_mid[0] > 0.0 && (origin_mid[0] as f64 - moved_x).abs() < 1e-3,
            "gizmo should follow to x={moved_x} mid-drag, got {origin_mid:?}"
        );
        // The active-handle gold highlight survives the per-frame re-sync.
        assert!(engine.transform_dragging(), "still dragging after the live re-sync");

        engine.transform_release();
        assert!(!engine.transform_dragging());

        engine.disarm_transform();
        assert!(!engine.transform_armed());
        assert!(!engine.widgets.has_transform(), "disarm hides the gizmo");
    }

    #[test]
    fn deleting_the_armed_feature_auto_disarms() {
        let mut engine = EngineState::new();
        engine.set_history_json(&cube_request("Pin", 10.0)).unwrap();
        engine.arm_transform("Pin");
        assert!(engine.transform_armed());
        // Removing the feature and re-running should drop the gizmo (the sync
        // hook in `rerun_history` finds no pose and disarms).
        engine.delete_feature("Pin");
        assert!(!engine.transform_armed(), "armed feature gone → auto-disarm");
        assert!(!engine.widgets.has_transform());
    }

    /// DEBUG-overlay consistency + draw==hit invariant: `transform_hit_areas_json`
    /// emits the SAME SCREEN-space regions [`TransformGizmo::hit`] tests the cursor
    /// against — 3 axis-arrow CAPSULES + the center CIRCLE + 3 rotation grab
    /// CIRCLES (7 items) — with the coords being the axis-seg / grab points
    /// projected through the SAME gizmo camera, and the SAME radii. `[]` unless in
    /// transform mode.
    #[test]
    fn transform_hit_areas_are_screen_regions_matching_the_hit_test() {
        let mut engine = EngineState::new();
        engine.set_history_json(&cube_request("Pin", 10.0)).unwrap();
        engine.resize(800.0, 600.0);
        // An oblique view so the three projected axis segments are distinct.
        engine.camera.eye = [30.0, 20.0, 40.0];
        engine.camera.target = [0.0, 0.0, 0.0];
        engine.camera.up = [0.0, 1.0, 0.0];
        engine.camera.projection = crate::view::Projection::Orthographic { half_height: 20.0 };

        // Disarmed → nothing to outline.
        assert_eq!(engine.transform_hit_areas_json(), "[]");

        engine.arm_transform("Pin");
        let areas: Vec<serde_json::Value> =
            serde_json::from_str(&engine.transform_hit_areas_json()).unwrap();
        let cam = gizmo_camera(&engine.camera);

        // 3 axis-arrow CAPSULES (screen px) + 4 CIRCLES (center + 3 rings).
        let capsules: Vec<&serde_json::Value> =
            areas.iter().filter(|a| a["kind"] == "capsule").collect();
        let circles: Vec<&serde_json::Value> =
            areas.iter().filter(|a| a["kind"] == "circle").collect();
        assert_eq!(capsules.len(), 3, "one capsule per axis arrow");
        assert_eq!(circles.len(), 4, "center + 3 ring grab circles");

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

        // Each capsule's endpoints = the axis_seg projected through the SAME gizmo
        // camera, at the AXIS_HIT_THRESH_PX radius.
        for (i, cap) in capsules.iter().enumerate() {
            let r = cap["r"].as_f64().unwrap();
            assert!(
                (r - brep_gizmos::transform::AXIS_HIT_THRESH_PX as f64).abs() < 1e-6,
                "axis {i}: r {r} must equal AXIS_HIT_THRESH_PX"
            );
            let (a, b) = engine.widgets.transform_axis_seg(&cam, i).unwrap();
            let sa = cam.world_to_screen(a).unwrap();
            let sb = cam.world_to_screen(b).unwrap();
            assert!(close2(&cap["a"], sa), "axis {i} a: {:?} vs {sa:?}", cap["a"]);
            assert!(close2(&cap["b"], sb), "axis {i} b: {:?} vs {sb:?}", cap["b"]);
        }

        // The center circle = the projected center ball at PX_CENTER_RAD + 2.
        let center = engine.widgets.transform_center_grab().unwrap();
        let sc = cam.world_to_screen(center).unwrap();
        let center_r = brep_gizmos::transform::PX_CENTER_RAD as f64 + 2.0;
        assert!(
            circles
                .iter()
                .any(|c| close2(&c["c"], sc) && (c["r"].as_f64().unwrap() - center_r).abs() < 1e-6),
            "center circle at the projected origin"
        );

        // The 3 ring circles = the projected grab balls at PX_RING_GRAB_RAD + 3.
        let ring_r = brep_gizmos::transform::PX_RING_GRAB_RAD as f64 + 3.0;
        for g in engine.widgets.transform_ring_grabs(&cam).unwrap() {
            let sg = cam.world_to_screen(g).unwrap();
            assert!(
                circles
                    .iter()
                    .any(|c| close2(&c["c"], sg) && (c["r"].as_f64().unwrap() - ring_r).abs() < 1e-6),
                "ring grab circle at {sg:?}"
            );
        }

        // Draw==hit invariant: a cursor at each region's own reference point is
        // picked as SOME handle whose region contains it (regions overlap by
        // design — the center ball sits at the arrow origins — so the invariant is
        // "the picked handle's region contains the cursor").
        let regions = engine.widgets.transform_hit_regions(&cam);
        for (_, shape) in &regions {
            let probe = match shape {
                brep_gizmos::hit_region::HitShape::Circle { c, .. } => *c,
                brep_gizmos::hit_region::HitShape::Capsule { a, b, .. } => {
                    [(a[0] + b[0]) * 0.5, (a[1] + b[1]) * 0.5]
                }
            };
            let picked = engine.transform_pick(probe[0] as f64, probe[1] as f64);
            assert_ne!(picked, 0, "a handle under its own region at {probe:?}");
            let picked_shape = regions.iter().find(|(id, _)| *id == picked).unwrap().1;
            assert!(
                picked_shape.contains(probe),
                "picked handle {picked}'s region must contain the cursor {probe:?}"
            );
        }

        // Flipping to dimension mode retracts the transform hit areas.
        engine.arm_dimension("Pin");
        assert_eq!(engine.transform_hit_areas_json(), "[]");
    }
}

// ============================================================================
// Modeling selection UX — hover highlight + multi-select toggle + the
// "candidates under the cursor" list. Appended as its OWN `impl` block (purely
// additive over the existing pick/selection API) so concurrent edits to the
// primary block + the transform-gizmo block don't conflict.
//
// The three are tied together through the SAME filter-respecting engine pick
// (`pick::pick` / `pick::pick_filtered` with the selection filter's enabled
// kinds), so hover, a plain/Ctrl click, and the candidate list all agree on
// what is under the cursor and in what order.
//
// Ports the retired viewer's selection methods:
//   * hover      — `_updateHover` → `SelectionFilter.setHoverRef(primary)` /
//                  `clearHover()`; `hover_at` sets the top admitted pick HOVERED.
//   * multi-sel  — the ref-store `toggleRef` (Ctrl/Cmd add) vs `setHoverRef`
//                  replace; `select_toggle_at` adds/removes without clearing.
//   * candidates — `_collectSelectionCandidates` builds the ranked pick list and
//                  its FINAL sort (see the note on `candidates_filtered_at`).
// ============================================================================