brep_render/

feature_dimensions.rs

//! Feature-dimension annotations (FD-1) — the engine-native port of the original
//! `FeatureDimensionAnnotationBuilder`.
//!
//! When a primitive-solid feature is selected and its ◎ is in DIMENSION mode,
//! its key numeric params render as draggable dimension annotations: a leader
//! from world `point_a` → `point_b`, editing the param `field_key`. FD-1 covers
//! the LINEAR builders only (cube / cylinder / cone / sphere / pyramid); the
//! angular + add-material builders (torus arc, revolve/extrude, pattern, port)
//! are FD-2.
//!
//! Each local-space point convention is copied verbatim from the previous app's builder so
//! the dims land on the SAME edges it drew — and, because the kernel bakes
//! `inputParams.transform` with the exact intrinsic XYZ Euler order used here, on the
//! rebuilt solid's edges too. See the per-builder notes below for the local
//! corner conventions (e.g. the cube's minimum corner is the origin; the pyramid
//! is centered on its axis with the base at `y = -h/2`).

use serde_json::Value;

use crate::engine_state::rotate_euler_xyz_f64;

/// A dimension annotation's kind. FD-1 was all [`FeatureDimKind::Linear`]; FD-2
/// adds [`FeatureDimKind::Angular`] (torus `arc`, revolve `angle`).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FeatureDimKind {
    /// A linear distance from `point_a` → `point_b`.
    Linear,
    /// An angular sweep of `value` DEGREES about `axis`, measured in the plane
    /// ⟂ `axis` from the zero reference `ref_dir`, centered at `center`. Ported
    /// from the previous app's angle-annotation builder.
    Angular,
}

/// One editable dimension annotation.
///
/// LINEAR: a leader from world `point_a` → `point_b` whose length is the
/// (resolved) value of param `field_key`; dragging projects the pointer onto the
/// `a → b` axis.
///
/// ANGULAR: a screen-constant-radius ARC swept `value` degrees about `axis`
/// (unit), starting from `ref_dir` (unit, in the plane ⟂ `axis`), centered at
/// `center`; dragging maps the pointer to a swept angle. The `point_a`/`point_b`
/// / `midpoint()` linear surface is unused for an angular annotation (both are
/// set to `center`); the app anchors an angular chip at the arc's mid-sweep,
/// which is camera-dependent and computed engine-side.
#[derive(Clone, Debug)]
pub struct FeatureDimAnnotation {
    /// The `inputParams` key this annotation edits (e.g. `sizeX`, `radius`, `arc`).
    pub field_key: String,
    /// LINEAR: the dimension's start point in WORLD space (the leader anchor /
    /// drag base). ANGULAR: `center`.
    pub point_a: [f64; 3],
    /// LINEAR: the dimension's end point in WORLD space (the value-1 handle).
    /// ANGULAR: `center`.
    pub point_b: [f64; 3],
    /// The current (resolved) numeric value of `field_key` (a length for LINEAR,
    /// DEGREES for ANGULAR).
    pub value: f64,
    /// The short display prefix (`X`, `R`, `H`, `A`, `Arc`, …).
    pub label: String,
    /// The annotation kind.
    pub kind: FeatureDimKind,
    /// ANGULAR only: the arc center (the axis-plane vertex) in WORLD space.
    /// `[0;3]` for a linear annotation.
    pub center: [f64; 3],
    /// ANGULAR: the rotation AXIS (unit) the arc sweeps about. LINEAR: `[0;3]`
    /// for feature dims; the assembly DISTANCE overlays stash the BASE-FACE
    /// outward unit normal here (the signed drag axis — see
    /// [`crate::constraint_overlays`]'s perpendicular-foot construction).
    /// `leaders_buffers` ignores it for linear annotations either way.
    pub axis: [f64; 3],
    /// ANGULAR only: the sweep's ZERO reference (unit, in the plane ⟂ `axis`).
    /// `[0;3]` for a linear annotation.
    pub ref_dir: [f64; 3],
}

impl FeatureDimAnnotation {
    /// `pub(crate)`: the assembly-constraint overlay builder
    /// ([`crate::constraint_overlays`]) constructs the SAME annotation shape for
    /// distance constraints so `leaders_buffers` renders constraint arrows with
    /// byte-identical styling (UI-consistency directive — one arrow look).
    pub(crate) fn linear(field_key: &str, a: [f64; 3], b: [f64; 3], value: f64, label: &str) -> Self {
        Self {
            field_key: field_key.to_string(),
            point_a: a,
            point_b: b,
            value,
            label: label.to_string(),
            kind: FeatureDimKind::Linear,
            center: [0.0; 3],
            axis: [0.0; 3],
            ref_dir: [0.0; 3],
        }
    }

    /// An angular annotation: `value` DEGREES swept about `axis` from `ref_dir`,
    /// centered at `center`. `axis` is normalized and `ref_dir` is projected into
    /// the plane ⟂ `axis` then normalized (mirrors the overlay `#createAngle`
    /// pre-processing). A degenerate axis/ref falls back to an arbitrary basis so
    /// the annotation is always renderable.
    ///
    /// `pub(crate)`: also constructed by [`crate::constraint_overlays`] for angle
    /// constraints so the constraint arc reuses this exact gizmo styling.
    pub(crate) fn angular(
        field_key: &str,
        center: [f64; 3],
        axis: [f64; 3],
        ref_dir: [f64; 3],
        value: f64,
        label: &str,
    ) -> Self {
        let axis = normalize_or(axis, [0.0, 1.0, 0.0]);
        // Project the reference into the plane ⟂ axis, then normalize.
        let d = dot3(ref_dir, axis);
        let planar = [
            ref_dir[0] - axis[0] * d,
            ref_dir[1] - axis[1] * d,
            ref_dir[2] - axis[2] * d,
        ];
        let ref_dir = if norm3(planar) <= 1e-9 {
            arbitrary_perpendicular(axis)
        } else {
            normalize_or(planar, arbitrary_perpendicular(axis))
        };
        Self {
            field_key: field_key.to_string(),
            point_a: center,
            point_b: center,
            value,
            label: label.to_string(),
            kind: FeatureDimKind::Angular,
            center,
            axis,
            ref_dir,
        }
    }

    /// The world-space midpoint of the leader — where the app anchors a LINEAR
    /// label. (Angular chips anchor at the arc mid-sweep, computed engine-side
    /// with the camera's `world_per_pixel`.)
    pub fn midpoint(&self) -> [f64; 3] {
        [
            (self.point_a[0] + self.point_b[0]) * 0.5,
            (self.point_a[1] + self.point_b[1]) * 0.5,
            (self.point_a[2] + self.point_b[2]) * 0.5,
        ]
    }
}

/// Resolved scene geometry an annotation builder needs beyond the pure
/// `inputParams` — the profile plane (extrude/revolve) and the axis line
/// (revolve). These are NOT pure params (they resolve scene references), so the
/// engine resolves them from the run report's sketch profiles / axes (see
/// `EngineState::feature_dimension_refs`) and hands them in. All fields are
/// optional: a builder that can't source what it needs returns `[]` gracefully.
#[derive(Clone, Debug, Default)]
pub struct ResolvedRefs {
    /// Extrude/revolve: the profile CENTER (world centroid of the outer loop) —
    /// the anchor the distance/angle gizmo hangs off, matching the previous app's
    /// resolved profile-reference-geometry center.
    pub profile_center: Option<[f64; 3]>,
    /// Extrude/revolve: the profile plane NORMAL (unit) — the sketch `+z` basis,
    /// the authoritative sweep/revolve-orientation direction.
    pub profile_normal: Option<[f64; 3]>,
    /// Revolve: a point on the resolved axis LINE (world).
    pub axis_point: Option<[f64; 3]>,
    /// Revolve: the resolved axis line DIRECTION (unit, UNORIENTED — the builder
    /// orients it toward the profile front via the `orient_revolve_axis` port).
    pub axis_dir: Option<[f64; 3]>,
    /// Plane (`P`): the resolved plane frame's ORIGIN (world) — the plane AFTER its
    /// `offset_distance`. The offset dim's un-offset base is `origin − normal·offset`.
    pub plane_origin: Option<[f64; 3]>,
    /// Plane (`P`): the resolved plane frame's unit NORMAL (its z-axis) — the axis
    /// the signed offset dim runs along.
    pub plane_normal: Option<[f64; 3]>,
    /// Plane (`P`): a small world length for the offset dim's handle stub when the
    /// offset is ~0 (a zero-length leader can't be dragged). Screen-constant so the
    /// handle is a consistent size; ignored once the offset is non-zero.
    pub plane_dim_length: Option<f64>,
}

/// Build the linear dimension annotations for a feature `type` from its
/// `input_params`. Dispatches on the primitive-solid type; returns `[]` for any
/// type without an FD-1 builder (extrude / revolve / booleans / etc.).
///
/// `input_params` should already have its numeric fields resolved to numbers
/// (the engine resolves expression strings against the history env before
/// calling this — see `EngineState::feature_dimension_annotations`), but plain
/// numeric strings are tolerated here too so the pure geometry stays testable.
pub fn build_annotations(feature_type: &str, input_params: &Value) -> Vec<FeatureDimAnnotation> {
    build_annotations_with_refs(feature_type, input_params, &ResolvedRefs::default())
}

/// Build the dimension annotations for a feature, given any resolved scene
/// references (`ResolvedRefs`) it needs. The primitive-solid + torus builders
/// ignore `resolved` (pure params + the baked transform); extrude/revolve read
/// the resolved profile plane / axis line and return `[]` when it is
/// unavailable (a face profile, an unresolved reference — see the builders).
pub fn build_annotations_with_refs(
    feature_type: &str,
    input_params: &Value,
    resolved: &ResolvedRefs,
) -> Vec<FeatureDimAnnotation> {
    let transform = input_params.get("transform");
    match feature_type {
        "P.CU" => build_cube(input_params, transform),
        "P.CY" => build_cylinder(input_params, transform),
        "P.CO" => build_cone(input_params, transform),
        // The sphere feature type is `P.S` (the dispatch keys on `P.S`).
        "P.S" | "P.SP" => build_sphere(input_params, transform),
        "P.PY" => build_pyramid(input_params, transform),
        "P.T" => build_torus(input_params, transform),
        "E" => build_extrude(input_params, resolved),
        "R" => build_revolve(input_params, resolved),
        "P" => build_plane(input_params, resolved),
        _ => Vec::new(),
    }
}

/// Cube (`P.CU`): minimum corner at the local origin, extending `+sizeX/Y/Z`
/// (matches the kernel's `make_box_brep((0,0,0), …)`). Three linear dims from the
/// origin corner along each axis.
fn build_cube(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let sx = resolve_number(params, "sizeX");
    let sy = resolve_number(params, "sizeY");
    let sz = resolve_number(params, "sizeZ");
    let p0 = transform_point(transform, [0.0, 0.0, 0.0]);
    let px = transform_point(transform, [sx, 0.0, 0.0]);
    let py = transform_point(transform, [0.0, sy, 0.0]);
    let pz = transform_point(transform, [0.0, 0.0, sz]);
    vec![
        FeatureDimAnnotation::linear("sizeX", p0, px, sx, "X"),
        FeatureDimAnnotation::linear("sizeY", p0, py, sy, "Y"),
        FeatureDimAnnotation::linear("sizeZ", p0, pz, sz, "Z"),
    ]
}

/// Cylinder (`P.CY`): axis is local `+Y`, base at `y=0`, top at `y=height`;
/// radius along local `+X`. Two dims: radius (base → radial) + height (base → top).
fn build_cylinder(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let radius = resolve_number(params, "radius");
    let height = resolve_number(params, "height");
    let base = transform_point(transform, [0.0, 0.0, 0.0]);
    let top = transform_point(transform, [0.0, height, 0.0]);
    let radial = transform_point(transform, [radius, 0.0, 0.0]);
    vec![
        FeatureDimAnnotation::linear("radius", base, radial, radius, "R"),
        FeatureDimAnnotation::linear("height", base, top, height, "H"),
    ]
}

/// Cone (`P.CO`): base radius at `y=0`, top radius at `y=height` (both along
/// local `+X`), axis along `+Y`. Three dims: radiusBottom / radiusTop / height.
fn build_cone(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let radius_top = resolve_number(params, "radiusTop");
    let radius_bottom = resolve_number(params, "radiusBottom");
    let height = resolve_number(params, "height");
    let base_center = transform_point(transform, [0.0, 0.0, 0.0]);
    let top_center = transform_point(transform, [0.0, height, 0.0]);
    let base_radius = transform_point(transform, [radius_bottom, 0.0, 0.0]);
    let top_radius = transform_point(transform, [radius_top, height, 0.0]);
    vec![
        FeatureDimAnnotation::linear("radiusBottom", base_center, base_radius, radius_bottom, "Rb"),
        FeatureDimAnnotation::linear("radiusTop", top_center, top_radius, radius_top, "Rt"),
        FeatureDimAnnotation::linear("height", base_center, top_center, height, "H"),
    ]
}

/// Sphere (`P.S`): one radial dim from the center along local `+X`.
fn build_sphere(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let radius = resolve_number(params, "radius");
    let center = transform_point(transform, [0.0, 0.0, 0.0]);
    let radial = transform_point(transform, [radius, 0.0, 0.0]);
    vec![FeatureDimAnnotation::linear("radius", center, radial, radius, "R")]
}

/// Pyramid (`P.PY`): centered on its axis — base at `y = -h/2`, apex at `y = h/2`,
/// base edge spanning `±side/2` in local X (at `z = -side/2`). Two dims: the base
/// side edge + the axial height.
fn build_pyramid(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let side = resolve_number(params, "baseSideLength");
    let height = resolve_number(params, "height");
    let half_side = side * 0.5;
    let base_y = -height * 0.5;
    let apex_y = height * 0.5;
    let base_start = transform_point(transform, [-half_side, base_y, -half_side]);
    let base_end = transform_point(transform, [half_side, base_y, -half_side]);
    let base_center = transform_point(transform, [0.0, base_y, 0.0]);
    let apex = transform_point(transform, [0.0, apex_y, 0.0]);
    vec![
        FeatureDimAnnotation::linear("baseSideLength", base_start, base_end, side, "Side"),
        FeatureDimAnnotation::linear("height", base_center, apex, height, "H"),
    ]
}

/// Torus (`P.T`): centered on its axis (local `+Y`) at the origin; the tube
/// circle lies in the local X/Y plane centered at `(majorRadius, 0, 0)`, revolved
/// `arc` DEGREES about `+Y`. Two LINEAR dims — `majorRadius` (center → the tube
/// centerline along `+X`, `R`) and `tubeRadius` (the centerline → the outer wall,
/// `r`) — plus the `arc` sweep as an ANGULAR dim about the local `+Y` axis from
/// the `+X` reference. Ported verbatim from the previous torus-annotation builder.
fn build_torus(params: &Value, transform: Option<&Value>) -> Vec<FeatureDimAnnotation> {
    let major = resolve_number(params, "majorRadius");
    let tube = resolve_number(params, "tubeRadius");
    let arc = clamp_deg(resolve_number(params, "arc"));

    let center = transform_point(transform, [0.0, 0.0, 0.0]);
    let major_point = transform_point(transform, [major, 0.0, 0.0]);
    let tube_point = transform_point(transform, [major + tube, 0.0, 0.0]);
    // The axis / reference are the transformed local +Y / +X (subtract the
    // transformed origin then normalize, so translation cancels; a non-uniform
    // scale skews them — normalization handles magnitude).
    let axis = normalize_or(sub3(transform_point(transform, [0.0, 1.0, 0.0]), center), [0.0, 1.0, 0.0]);
    let start_dir = sub3(major_point, center);

    vec![
        FeatureDimAnnotation::linear("majorRadius", center, major_point, major, "R"),
        FeatureDimAnnotation::linear("tubeRadius", major_point, tube_point, tube, "r"),
        FeatureDimAnnotation::angular("arc", center, axis, start_dir, arc, "Arc"),
    ]
}

/// Extrude (`E`): a LINEAR distance dim from the profile CENTER along the profile
/// plane NORMAL by `distance` (`D`), plus the two-sided `distanceBack` leg along
/// `-normal` (`Db`). Needs the resolved profile center + normal (a sketch profile
/// — a resident-face profile is not sourced, so those extrudes get no dim). Ported
/// from the previous extrude-annotation builder.
fn build_extrude(params: &Value, resolved: &ResolvedRefs) -> Vec<FeatureDimAnnotation> {
    let (Some(center), Some(normal)) = (resolved.profile_center, resolved.profile_normal) else {
        return Vec::new();
    };
    let normal = normalize_or(normal, [0.0, 0.0, 1.0]);
    let distance = resolve_number(params, "distance");
    let back = resolve_number(params, "distanceBack");
    let forward = [
        center[0] + normal[0] * distance,
        center[1] + normal[1] * distance,
        center[2] + normal[2] * distance,
    ];
    let backward = [
        center[0] - normal[0] * back,
        center[1] - normal[1] * back,
        center[2] - normal[2] * back,
    ];
    vec![
        FeatureDimAnnotation::linear("distance", center, forward, distance, "D"),
        FeatureDimAnnotation::linear("distanceBack", center, backward, back, "Db"),
    ]
}

/// Plane (`P`): one SIGNED LINEAR offset dim along the plane normal, driving
/// `offset_distance`. The plane sits on either side of its base orientation/
/// reference plane, so the dim runs from the un-offset base
/// (`origin − normal·offset`) to the current plane (`origin`) and is dragged
/// through zero to flip sign (the drag preserves sign; the kernel accepts a
/// negative `offset_distance`). At offset ≈ 0 the leader collapses, so a small
/// `+normal` stub (`plane_dim_length`, screen-constant) keeps it draggable — the
/// value mapping stays 1:1 there. No resolved plane frame → `[]`.
fn build_plane(params: &Value, resolved: &ResolvedRefs) -> Vec<FeatureDimAnnotation> {
    let (Some(origin), Some(normal)) = (resolved.plane_origin, resolved.plane_normal) else {
        return Vec::new();
    };
    let offset = resolve_number(params, "offset_distance");
    // The un-offset base plane point — the dim's zero anchor.
    let base = [
        origin[0] - normal[0] * offset,
        origin[1] - normal[1] * offset,
        origin[2] - normal[2] * offset,
    ];
    // Handle at the current offset; at ~0 use a small +normal stub so the leader
    // has a direction (the drag no-ops on a zero-length axis).
    let extent = if offset.abs() > 1e-6 {
        offset
    } else {
        resolved.plane_dim_length.unwrap_or(1.0)
    };
    let handle = [
        base[0] + normal[0] * extent,
        base[1] + normal[1] * extent,
        base[2] + normal[2] * extent,
    ];
    vec![FeatureDimAnnotation::linear(
        "offset_distance",
        base,
        handle,
        offset,
        "Offset",
    )]
}

/// Revolve (`R`): one ANGULAR dim = `angle` DEGREES swept about the resolved axis
/// line, oriented toward the profile front (the `orient_revolve_axis` port — so
/// the arc rotates the SAME way the solid does), centered at the axis point
/// nearest the profile, zeroed on the radial from that vertex to the profile.
/// Needs the resolved axis line + profile; returns `[]` otherwise. Ported from
/// the previous revolve-annotation builder.
fn build_revolve(params: &Value, resolved: &ResolvedRefs) -> Vec<FeatureDimAnnotation> {
    let (Some(axis_point), Some(axis_dir)) = (resolved.axis_point, resolved.axis_dir) else {
        return Vec::new();
    };
    let Some(profile_center) = resolved.profile_center else {
        return Vec::new();
    };
    let axis = orient_revolve_axis(axis_dir, axis_point, profile_center, resolved.profile_normal);
    let vertex = closest_point_on_line(profile_center, axis_point, axis);
    // The radial from the vertex to the profile (projected ⟂ axis) is the zero
    // reference; the `angular` ctor re-projects + falls back if it degenerates.
    let start_dir = sub3(profile_center, vertex);
    let angle = clamp_deg(resolve_number(params, "angle"));
    vec![FeatureDimAnnotation::angular("angle", vertex, axis, start_dir, angle, "A")]
}

/// The signed revolve axis native Revolve uses: the profile's outward normal
/// selects between the two directions of an unoriented axis edge. Port of
/// `resolveOrientedRevolveAxisDirection`.
pub(crate) fn orient_revolve_axis(
    axis_dir: [f64; 3],
    axis_point: [f64; 3],
    profile_center: [f64; 3],
    profile_normal: Option<[f64; 3]>,
) -> [f64; 3] {
    let axis = normalize_or(axis_dir, [0.0, 1.0, 0.0]);
    let Some(normal) = profile_normal else {
        return axis;
    };
    if norm3(normal) <= 1e-12 {
        return axis;
    }
    let normal = normalize_or(normal, [0.0, 0.0, 1.0]);
    // radial = (profileCenter - axisPoint) projected ⟂ axis.
    let mut radial = sub3(profile_center, axis_point);
    let d = dot3(radial, axis);
    radial = [radial[0] - axis[0] * d, radial[1] - axis[1] * d, radial[2] - axis[2] * d];
    if norm3(radial) <= 1e-12 {
        return axis;
    }
    let c = cross3(axis, radial);
    if dot3(c, normal) < 0.0 {
        [-axis[0], -axis[1], -axis[2]]
    } else {
        axis
    }
}

/// The point on line `(line_point, line_dir)` closest to `point`.
pub(crate) fn closest_point_on_line(
    point: [f64; 3],
    line_point: [f64; 3],
    line_dir: [f64; 3],
) -> [f64; 3] {
    let dir = normalize_or(line_dir, [0.0, 1.0, 0.0]);
    let t = dot3(sub3(point, line_point), dir);
    [
        line_point[0] + dir[0] * t,
        line_point[1] + dir[1] * t,
        line_point[2] + dir[2] * t,
    ]
}

/// Clamp a degree value to `[-360, 360]`.
fn clamp_deg(v: f64) -> f64 {
    v.clamp(-360.0, 360.0)
}

/// Apply a feature's `inputParams.transform` (TRS, `rotationEuler` in DEGREES,
/// `M = T·R·S`) to a LOCAL point → WORLD. Mirrors composing that degree-based TRS
/// matrix and applying it to a point: `world = position + R·(scale ⊙ local)`, with `R` the exact
/// intrinsic XYZ Euler order matrix the kernel bake uses (`rotate_euler_xyz_f64`).
pub(crate) fn transform_point(transform: Option<&Value>, local: [f64; 3]) -> [f64; 3] {
    let position = read_vec3(transform, "position", [0.0, 0.0, 0.0]);
    let rotation_deg = read_vec3(transform, "rotationEuler", [0.0, 0.0, 0.0]);
    let scale = read_vec3(transform, "scale", [1.0, 1.0, 1.0]);
    let scaled = [local[0] * scale[0], local[1] * scale[1], local[2] * scale[2]];
    let euler = [
        rotation_deg[0].to_radians(),
        rotation_deg[1].to_radians(),
        rotation_deg[2].to_radians(),
    ];
    let rotated = rotate_euler_xyz_f64(scaled, euler);
    [
        rotated[0] + position[0],
        rotated[1] + position[1],
        rotated[2] + position[2],
    ]
}

/// Read a `[x, y, z]` from a `transform` sub-field (numbers only; a missing /
/// short array keeps the per-index default).
fn read_vec3(transform: Option<&Value>, key: &str, default: [f64; 3]) -> [f64; 3] {
    let array = transform.and_then(|t| t.get(key)).and_then(Value::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(Value::as_f64) {
                *slot = number;
            }
        }
    }
    out
}

/// Read `params[key]` as a finite number: a JSON number, else a plain numeric
/// string (e.g. `"12.5"`). Non-numeric / expression strings resolve to `0.0`
/// (the engine pre-resolves expressions before building, so this is only the
/// pure-geometry fallback). Mirrors the numeric input-param resolution fallback.
fn resolve_number(params: &Value, key: &str) -> f64 {
    match params.get(key) {
        Some(Value::Number(n)) => n.as_f64().filter(|v| v.is_finite()).unwrap_or(0.0),
        Some(Value::String(s)) => s.trim().parse::<f64>().ok().filter(|v| v.is_finite()).unwrap_or(0.0),
        _ => 0.0,
    }
}

// --- restyled leader geometry (matches the reference dimension-arrows image) --
//
// Each annotation draws a thick SILVER rod (a 3D tube) from the shared origin
// `point_a` out to `point_b`, an ORANGE cone arrowhead at `point_b`, and a
// single ORANGE origin sphere at the shared start point (deduped across the
// annotations that share it — a cube's three axis dims share one corner). The
// geometry is radially symmetric so it needs no camera orientation; it is fed to
// the `feature-dim-leaders` overlay group as flat triangle buffers. Colors are
// display sRGB written ~directly by the overlay shader (with a per-face shade for
// depth), so use hex/255 — no linear conversion.

/// Silver-grey rod shaft color (~0xccced1) — also the angle ARC tube.
const SHAFT_RGB: [f32; 3] = [0.80, 0.81, 0.82];
/// Orange cone + origin/handle-sphere color (#F5A623).
const ORANGE_RGB: [f32; 3] = [0.961, 0.651, 0.137];
/// Red — the angle gizmo's ZERO-reference (drawn DASHED) radial line.
const RED_RGB: [f32; 3] = [0.902, 0.157, 0.157];
/// Green — the angle gizmo's rotation-AXIS line.
const GREEN_RGB: [f32; 3] = [0.204, 0.808, 0.267];

/// Silver-rod shaft radius, CSS pixels (thick, reads as a 3D rod).
const SHAFT_RAD_PX: f64 = 2.2;
/// Arrowhead cone length, CSS pixels.
const CONE_LEN_PX: f64 = 16.0;
/// Arrowhead cone base radius, CSS pixels (fuller 3D cone).
const CONE_RAD_PX: f64 = 6.0;
/// Origin sphere radius, CSS pixels (medium, screen-constant). Shared with
/// `EngineState::dimension_origin_pick` so the click hit-radius matches the drawn
/// sphere exactly.
pub(crate) const ORIGIN_SPHERE_RAD_PX: f64 = 7.0;

/// The angle gizmo's ARC radius, CSS pixels (screen-constant — matching the previous
/// `FEATURE_ANGLE_RADIUS_PX`). Shared with the engine so the drawn arc, the chip
/// anchor (mid-sweep) and the drag hit-search all use the SAME radius.
pub const ANGLE_ARC_RAD_PX: f64 = 120.0;
/// The angle gizmo's ref/axis line radius, CSS pixels (thinner than the arc).
const ANGLE_RAY_RAD_PX: f64 = 1.6;
/// Degrees of sweep per arc tube segment (tessellation of the arc).
const ARC_DEG_PER_SEG: f64 = 4.0;
/// The RED zero-reference line's dash / gap length, CSS pixels.
const DASH_LEN_PX: f64 = 6.0;
const DASH_GAP_PX: f64 = 5.0;

const TUBE_SEGMENTS: usize = 8;
const CONE_SEGMENTS: usize = 16;
const SPHERE_RINGS: usize = 6;
const SPHERE_SECTORS: usize = 10;

/// Build the world-space leader geometry for a set of annotations as flat
/// triangle `(positions, colors)` buffers (9 position + 9 color floats per
/// triangle), ready to feed the `feature-dim-leaders` overlay group as `tris`.
/// Normals are omitted — the overlay parser computes a flat face normal per
/// triangle, and the shader's per-face shade gives the rods/cones/spheres their
/// 3D read. `world_per_pixel` keeps the rod/cone/sphere screen-constant.
pub fn leaders_buffers(
    annotations: &[FeatureDimAnnotation],
    world_per_pixel: f64,
) -> (Vec<f32>, Vec<f32>) {
    let mut tb = TriBuf::default();
    let shaft_rad = SHAFT_RAD_PX * world_per_pixel;
    let cone_len = CONE_LEN_PX * world_per_pixel;
    let cone_rad = CONE_RAD_PX * world_per_pixel;
    let sphere_rad = ORIGIN_SPHERE_RAD_PX * world_per_pixel;

    // Draw the shared origin sphere once per distinct start point.
    let mut origins: Vec<[f64; 3]> = Vec::new();
    let mut add_origin = |tb: &mut TriBuf, a: [f64; 3]| {
        if !origins.iter().any(|o| norm3(sub3(*o, a)) < 1e-6) {
            push_sphere(tb, a, sphere_rad, ORANGE_RGB);
            origins.push(a);
        }
    };

    for ann in annotations {
        match ann.kind {
            FeatureDimKind::Angular => {
                // The arc VERTEX gets the same orange origin sphere as a linear
                // dim's `point_a`, so it is a visible mode-toggle target (the arc's
                // sweep-END orange sphere is the angle DRAG handle, not a toggle).
                // `add_origin` dedups against a linear origin at the same world
                // point (a torus's `majorRadius` origin == this center), so no
                // doubled geometry there.
                add_origin(&mut tb, ann.center);
                push_angle_gizmo(&mut tb, ann, world_per_pixel);
            }
            FeatureDimKind::Linear => {
                let a = ann.point_a;
                let b = ann.point_b;
                let axis = sub3(b, a);
                let len = norm3(axis);
                add_origin(&mut tb, a);
                if len < 1e-9 {
                    continue;
                }
                let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
                // The cone occupies the far end; the rod runs from origin to it.
                let cl = cone_len.min(len * 0.9);
                let shaft_end = [b[0] - dir[0] * cl, b[1] - dir[1] * cl, b[2] - dir[2] * cl];
                push_tube(&mut tb, a, shaft_end, shaft_rad, SHAFT_RGB);
                push_cone(&mut tb, shaft_end, b, cone_rad, ORANGE_RGB);
            }
        }
    }
    (tb.positions, tb.colors)
}

/// Append a PLAIN leader line `a → b` (thin silver rod, NO arrowhead cone / origin
/// sphere — nothing that reads as grabbable) onto existing `(positions, colors)`
/// triangle buffers. The NON-dimensional assembly-constraint overlays (coincident /
/// parallel / …) draw their anchor-to-anchor leaders through this so the line
/// styling stays in this ONE home (same silver + screen-constant radius as the
/// dimension rods, slightly thinner because it carries no handle).
pub fn append_plain_leader(
    positions: &mut Vec<f32>,
    colors: &mut Vec<f32>,
    a: [f64; 3],
    b: [f64; 3],
    world_per_pixel: f64,
) {
    let mut tb = TriBuf {
        positions: std::mem::take(positions),
        colors: std::mem::take(colors),
    };
    push_tube(&mut tb, a, b, ANGLE_RAY_RAD_PX * world_per_pixel, SHAFT_RGB);
    *positions = tb.positions;
    *colors = tb.colors;
}

/// A flat triangle-soup accumulator (positions + per-vertex rgb colors).
#[derive(Default)]
struct TriBuf {
    positions: Vec<f32>,
    colors: Vec<f32>,
}

impl TriBuf {
    fn tri(&mut self, a: [f64; 3], b: [f64; 3], c: [f64; 3], rgb: [f32; 3]) {
        for p in [a, b, c] {
            self.positions
                .extend_from_slice(&[p[0] as f32, p[1] as f32, p[2] as f32]);
            self.colors.extend_from_slice(&rgb);
        }
    }
}

/// Push a solid 3D rod (open-ended tube) from `a` to `b` with world `radius`.
fn push_tube(tb: &mut TriBuf, a: [f64; 3], b: [f64; 3], radius: f64, rgb: [f32; 3]) {
    let axis = sub3(b, a);
    let len = norm3(axis);
    if len < 1e-9 || radius <= 0.0 {
        return;
    }
    let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
    let (u, v) = axis_basis(dir);
    let ring = |center: [f64; 3], k: usize| -> [f64; 3] {
        let ang = (k as f64 / TUBE_SEGMENTS as f64) * std::f64::consts::TAU;
        let (c, s) = (ang.cos() * radius, ang.sin() * radius);
        [
            center[0] + u[0] * c + v[0] * s,
            center[1] + u[1] * c + v[1] * s,
            center[2] + u[2] * c + v[2] * s,
        ]
    };
    for k in 0..TUBE_SEGMENTS {
        let a0 = ring(a, k);
        let a1 = ring(a, k + 1);
        let b0 = ring(b, k);
        let b1 = ring(b, k + 1);
        tb.tri(a0, b0, b1, rgb);
        tb.tri(a0, b1, a1, rgb);
    }
}

/// Push a filled arrowhead cone: apex at `tip`, base circle of world `radius`
/// centered at `base` (side facets + a base cap).
fn push_cone(tb: &mut TriBuf, base: [f64; 3], tip: [f64; 3], radius: f64, rgb: [f32; 3]) {
    let axis = sub3(tip, base);
    let len = norm3(axis);
    if len < 1e-9 || radius <= 0.0 {
        return;
    }
    let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
    let (u, v) = axis_basis(dir);
    let ring = |k: usize| -> [f64; 3] {
        let ang = (k as f64 / CONE_SEGMENTS as f64) * std::f64::consts::TAU;
        let (c, s) = (ang.cos() * radius, ang.sin() * radius);
        [
            base[0] + u[0] * c + v[0] * s,
            base[1] + u[1] * c + v[1] * s,
            base[2] + u[2] * c + v[2] * s,
        ]
    };
    let mut prev = ring(0);
    for k in 1..=CONE_SEGMENTS {
        let cur = ring(k);
        tb.tri(tip, prev, cur, rgb); // side facet
        tb.tri(base, cur, prev, rgb); // base cap
        prev = cur;
    }
}

/// Push a filled UV sphere of world `radius` at `center` (flat-shaded facets).
fn push_sphere(tb: &mut TriBuf, center: [f64; 3], radius: f64, rgb: [f32; 3]) {
    if radius <= 0.0 {
        return;
    }
    let point = |ring: usize, sector: usize| -> [f64; 3] {
        let lat = std::f64::consts::PI * (ring as f64 / SPHERE_RINGS as f64)
            - std::f64::consts::FRAC_PI_2;
        let lon = std::f64::consts::TAU * (sector as f64 / SPHERE_SECTORS as f64);
        [
            center[0] + lat.cos() * lon.cos() * radius,
            center[1] + lat.cos() * lon.sin() * radius,
            center[2] + lat.sin() * radius,
        ]
    };
    for r in 0..SPHERE_RINGS {
        for sct in 0..SPHERE_SECTORS {
            let p00 = point(r, sct);
            let p01 = point(r, sct + 1);
            let p10 = point(r + 1, sct);
            let p11 = point(r + 1, sct + 1);
            tb.tri(p00, p10, p11, rgb);
            tb.tri(p00, p11, p01, rgb);
        }
    }
}

/// Push the angle gizmo (image-9 target) for an ANGULAR annotation: a light-grey
/// ARC of screen-constant radius swept from `ref_dir` by `value` degrees about
/// `axis` at `center`, an ORANGE handle SPHERE at the sweep end with an ORANGE
/// CONE just past it along the arc tangent, a RED DASHED zero-reference line along
/// `ref_dir`, and a GREEN line along `axis`. Sizing is screen-constant via
/// `world_per_pixel` so the gizmo stays a fixed pixel size across zoom.
fn push_angle_gizmo(tb: &mut TriBuf, ann: &FeatureDimAnnotation, world_per_pixel: f64) {
    let center = ann.center;
    let axis = ann.axis;
    let start = ann.ref_dir;
    let radius = ANGLE_ARC_RAD_PX * world_per_pixel;
    let ray_rad = ANGLE_RAY_RAD_PX * world_per_pixel;
    let shaft_rad = SHAFT_RAD_PX * world_per_pixel;
    let cone_len = CONE_LEN_PX * world_per_pixel;
    let cone_rad = CONE_RAD_PX * world_per_pixel;
    let sphere_rad = ORIGIN_SPHERE_RAD_PX * world_per_pixel;
    if radius <= 1e-9 {
        return;
    }
    // A full 360° arc would close on itself; clamp the DRAWN sweep just under it
    // (matches the overlay's ±359.9 draw clamp) while the chip still shows the
    // real value.
    let value = ann.value.clamp(-359.9, 359.9);
    let value_rad = value.to_radians();

    // The arc: sample from 0 → value and connect consecutive points with grey
    // tube segments. The point at parameter `t` (radians) is
    // `center + rotate(start, axis, t) * radius`.
    let arc_point = |t: f64| -> [f64; 3] {
        let dir = rotate_about_axis(start, axis, t);
        [
            center[0] + dir[0] * radius,
            center[1] + dir[1] * radius,
            center[2] + dir[2] * radius,
        ]
    };
    let seg_count = ((value.abs() / ARC_DEG_PER_SEG).ceil() as usize).max(2);
    let mut prev = arc_point(0.0);
    for k in 1..=seg_count {
        let t = value_rad * (k as f64 / seg_count as f64);
        let cur = arc_point(t);
        push_tube(tb, prev, cur, shaft_rad, SHAFT_RGB);
        prev = cur;
    }

    // The sweep END: the orange handle sphere sits on the arc, the cone points
    // just past it along the arc tangent (the direction of increasing angle).
    let dir_end = rotate_about_axis(start, axis, value_rad);
    let end_pt = [
        center[0] + dir_end[0] * radius,
        center[1] + dir_end[1] * radius,
        center[2] + dir_end[2] * radius,
    ];
    push_sphere(tb, end_pt, sphere_rad, ORANGE_RGB);
    // Tangent = d/dt rotate = axis × dir_end, signed by the sweep direction.
    let sweep_sign = if value < 0.0 { -1.0 } else { 1.0 };
    let tangent = normalize_or(cross3(axis, dir_end), dir_end);
    let tangent = [tangent[0] * sweep_sign, tangent[1] * sweep_sign, tangent[2] * sweep_sign];
    let cone_tip = [
        end_pt[0] + tangent[0] * cone_len,
        end_pt[1] + tangent[1] * cone_len,
        end_pt[2] + tangent[2] * cone_len,
    ];
    push_cone(tb, end_pt, cone_tip, cone_rad, ORANGE_RGB);

    // RED DASHED zero-reference line from the center out along `ref_dir` to the
    // arc-start radius (short tube dashes with gaps).
    let ref_end = [
        center[0] + start[0] * radius,
        center[1] + start[1] * radius,
        center[2] + start[2] * radius,
    ];
    push_dashed(tb, center, ref_end, ray_rad, RED_RGB, world_per_pixel);

    // GREEN rotation-axis line through the center (a solid tube, both sides).
    let axis_len = radius * 0.7;
    let axis_a = [
        center[0] - axis[0] * axis_len,
        center[1] - axis[1] * axis_len,
        center[2] - axis[2] * axis_len,
    ];
    let axis_b = [
        center[0] + axis[0] * axis_len,
        center[1] + axis[1] * axis_len,
        center[2] + axis[2] * axis_len,
    ];
    push_tube(tb, axis_a, axis_b, ray_rad, GREEN_RGB);
}

/// Push a DASHED line `a → b` as a series of short solid tube segments (dash then
/// gap, in screen-constant CSS px). Used for the angle gizmo's red zero-reference.
fn push_dashed(
    tb: &mut TriBuf,
    a: [f64; 3],
    b: [f64; 3],
    radius: f64,
    rgb: [f32; 3],
    world_per_pixel: f64,
) {
    let axis = sub3(b, a);
    let len = norm3(axis);
    if len < 1e-9 {
        return;
    }
    let dir = [axis[0] / len, axis[1] / len, axis[2] / len];
    let dash = (DASH_LEN_PX * world_per_pixel).max(1e-6);
    let gap = (DASH_GAP_PX * world_per_pixel).max(1e-6);
    let mut s = 0.0;
    while s < len {
        let e = (s + dash).min(len);
        let p0 = [a[0] + dir[0] * s, a[1] + dir[1] * s, a[2] + dir[2] * s];
        let p1 = [a[0] + dir[0] * e, a[1] + dir[1] * e, a[2] + dir[2] * e];
        push_tube(tb, p0, p1, radius, rgb);
        s = e + gap;
    }
}

/// The world-space chip anchor for an ANGULAR annotation: the arc mid-sweep point
/// at the screen-constant radius (`center + rotate(ref_dir, axis, value/2) *
/// radius`) — i.e. `labelAnchor = vertex + bisector * radius`. Camera-dependent
/// (via `world_per_pixel`), so the engine computes it per frame.
pub fn angular_chip_anchor(ann: &FeatureDimAnnotation, world_per_pixel: f64) -> [f64; 3] {
    let radius = ANGLE_ARC_RAD_PX * world_per_pixel;
    let value = ann.value.clamp(-359.9, 359.9);
    let bisector = rotate_about_axis(ann.ref_dir, ann.axis, (value * 0.5).to_radians());
    [
        ann.center[0] + bisector[0] * radius,
        ann.center[1] + bisector[1] * radius,
        ann.center[2] + bisector[2] * radius,
    ]
}

/// Screen-px hit radius for grabbing a dimension arrowHEAD — the cone base plus a
/// little slack, so a click near the drawn arrowhead reliably grabs it. Shared by
/// `EngineState::dimension_arrow_pick`.
// Grab tolerance around a dimension arrowhead. Generous on purpose: egui only
// reports a DRAG once the pointer has already moved a few px past the press, so a
// tight radius makes the arrow feel un-grabbable. This gives a comfortable target.
pub(crate) const ARROW_HANDLE_HIT_RAD_PX: f64 = CONE_RAD_PX + 12.0;

/// The world-space arrowHEAD handle point of an annotation — the drag grab target
/// (`EngineState::dimension_arrow_pick`). LINEAR: the orange cone tip at
/// `point_b`. ANGULAR: the orange sweep-END handle sphere on the arc (`center +
/// rotate(ref_dir, axis, value°) * radius`, value clamped to the drawn ±359.9° so
/// the grab point matches the drawn handle). Camera-dependent for angular (via
/// `world_per_pixel`), so it is computed per frame.
pub(crate) fn arrow_handle_point(
    ann: &FeatureDimAnnotation,
    world_per_pixel: f64,
) -> [f64; 3] {
    match ann.kind {
        FeatureDimKind::Linear => ann.point_b,
        FeatureDimKind::Angular => {
            let radius = ANGLE_ARC_RAD_PX * world_per_pixel;
            let value = ann.value.clamp(-359.9, 359.9);
            let dir = rotate_about_axis(ann.ref_dir, ann.axis, value.to_radians());
            [
                ann.center[0] + dir[0] * radius,
                ann.center[1] + dir[1] * radius,
                ann.center[2] + dir[2] * radius,
            ]
        }
    }
}

// --- small vec3 helpers (self-contained; the leader geometry is pure) --------

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

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

/// Normalize `v`, or return `fallback` if `v` is ~zero-length.
fn normalize_or(v: [f64; 3], fallback: [f64; 3]) -> [f64; 3] {
    let n = norm3(v);
    if n < 1e-12 {
        fallback
    } else {
        [v[0] / n, v[1] / n, v[2] / n]
    }
}

/// A stable unit vector ⟂ `direction` (a port of the previous app's arbitrary-perpendicular helper).
fn arbitrary_perpendicular(direction: [f64; 3]) -> [f64; 3] {
    if norm3(direction) <= 1e-12 {
        return [0.0, 0.0, 1.0];
    }
    let seed = if dot3(direction, [0.0, 0.0, 1.0]).abs() < 0.9 {
        [0.0, 0.0, 1.0]
    } else {
        [0.0, 1.0, 0.0]
    };
    let mut perp = cross3(direction, seed);
    if norm3(perp) <= 1e-12 {
        perp = cross3(direction, [1.0, 0.0, 0.0]);
    }
    if norm3(perp) <= 1e-12 {
        [1.0, 0.0, 0.0]
    } else {
        normalize_or(perp, [1.0, 0.0, 0.0])
    }
}

/// Rotate `v` by `angle` radians about unit `axis` (Rodrigues). Shared with the
/// engine's angular drag/chip anchoring.
pub fn rotate_about_axis(v: [f64; 3], axis: [f64; 3], angle: f64) -> [f64; 3] {
    let axis = normalize_or(axis, [0.0, 1.0, 0.0]);
    let (s, c) = angle.sin_cos();
    let d = dot3(axis, v);
    let cr = cross3(axis, v);
    [
        v[0] * c + cr[0] * s + axis[0] * d * (1.0 - c),
        v[1] * c + cr[1] * s + axis[1] * d * (1.0 - c),
        v[2] * c + cr[2] * s + axis[2] * d * (1.0 - c),
    ]
}

fn norm3(v: [f64; 3]) -> f64 {
    (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]).sqrt()
}

fn 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],
    ]
}

/// A radially-symmetric perpendicular basis `(u, v)` for a unit `dir`.
fn axis_basis(dir: [f64; 3]) -> ([f64; 3], [f64; 3]) {
    let seed = if dir[0].abs() < 0.9 {
        [1.0, 0.0, 0.0]
    } else {
        [0.0, 1.0, 0.0]
    };
    let mut u = cross3(dir, seed);
    let un = norm3(u);
    if un < 1e-9 {
        u = [0.0, 1.0, 0.0];
    } else {
        u = [u[0] / un, u[1] / un, u[2] / un];
    }
    let v = cross3(dir, u);
    let vn = norm3(v).max(1e-9);
    (u, [v[0] / vn, v[1] / vn, v[2] / vn])
}

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

    fn ident_transform() -> Value {
        json!({
            "position": [0.0, 0.0, 0.0],
            "rotationEuler": [0.0, 0.0, 0.0],
            "scale": [1.0, 1.0, 1.0],
        })
    }

    fn dist(a: [f64; 3], b: [f64; 3]) -> f64 {
        norm3(sub3(a, b))
    }

    fn plane_refs(origin: [f64; 3], normal: [f64; 3], stub: f64) -> ResolvedRefs {
        ResolvedRefs {
            plane_origin: Some(origin),
            plane_normal: Some(normal),
            plane_dim_length: Some(stub),
            ..Default::default()
        }
    }

    // The plane offset dim runs from the un-offset base (origin − normal·offset)
    // to the current plane (origin), keyed `offset_distance` with the signed value.
    #[test]
    fn plane_offset_dim_runs_along_the_normal() {
        let params = json!({ "id": "Pl", "orientation": "XY", "offset_distance": 5.0 });
        let anns = build_annotations_with_refs(
            "P",
            &params,
            &plane_refs([0.0, 0.0, 5.0], [0.0, 0.0, 1.0], 1.0),
        );
        assert_eq!(anns.len(), 1);
        assert_eq!(anns[0].field_key, "offset_distance");
        assert_eq!(anns[0].value, 5.0);
        assert_eq!(anns[0].point_a, [0.0, 0.0, 0.0]); // base = origin − n·offset
        assert_eq!(anns[0].point_b, [0.0, 0.0, 5.0]); // handle = origin
    }

    // A NEGATIVE offset places the plane on the −normal side; the dim still runs
    // from the base to the current plane (the drag keeps the sign).
    #[test]
    fn plane_offset_dim_supports_negative() {
        let params = json!({ "id": "Pl", "orientation": "XY", "offset_distance": -4.0 });
        let anns = build_annotations_with_refs(
            "P",
            &params,
            &plane_refs([0.0, 0.0, -4.0], [0.0, 0.0, 1.0], 1.0),
        );
        assert_eq!(anns[0].value, -4.0);
        assert_eq!(anns[0].point_a, [0.0, 0.0, 0.0]);
        assert_eq!(anns[0].point_b, [0.0, 0.0, -4.0]);
    }

    // At offset ≈ 0 the leader would collapse (undraggable); a +normal stub keeps
    // it a real, draggable leader while the value stays 0.
    #[test]
    fn plane_offset_dim_at_zero_uses_a_draggable_stub() {
        let params = json!({ "id": "Pl", "orientation": "XY", "offset_distance": 0.0 });
        let anns = build_annotations_with_refs(
            "P",
            &params,
            &plane_refs([0.0, 0.0, 0.0], [0.0, 0.0, 1.0], 2.0),
        );
        assert_eq!(anns[0].value, 0.0);
        assert_eq!(anns[0].point_b, [0.0, 0.0, 2.0], "stub gives the leader a +normal direction");
        assert!(dist(anns[0].point_a, anns[0].point_b) > 1e-6, "non-degenerate → draggable");
    }

    // No resolved plane frame (unresolved / not yet run) → no dim, gracefully.
    #[test]
    fn plane_without_a_resolved_frame_has_no_dim() {
        let params = json!({ "id": "Pl", "orientation": "XY", "offset_distance": 5.0 });
        assert!(build_annotations_with_refs("P", &params, &ResolvedRefs::default()).is_empty());
    }

    #[test]
    fn cube_identity_gives_three_axis_dims() {
        let params = json!({
            "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.CU", &params);
        assert_eq!(anns.len(), 3);
        let keys: Vec<&str> = anns.iter().map(|a| a.field_key.as_str()).collect();
        assert_eq!(keys, ["sizeX", "sizeY", "sizeZ"]);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 10.0).abs() < 1e-9);
        assert!((dist(anns[1].point_a, anns[1].point_b) - 20.0).abs() < 1e-9);
        assert!((dist(anns[2].point_a, anns[2].point_b) - 30.0).abs() < 1e-9);
        // sizeX runs along +X from the origin corner.
        assert!((anns[0].point_a[0]).abs() < 1e-9);
        assert!((anns[0].point_b[0] - 10.0).abs() < 1e-9);
        assert!((anns[0].value - 10.0).abs() < 1e-9);
    }

    #[test]
    fn cube_translation_moves_the_dims() {
        let params = json!({
            "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0,
            "transform": {
                "position": [5.0, -3.0, 2.0],
                "rotationEuler": [0.0, 0.0, 0.0],
                "scale": [1.0, 1.0, 1.0],
            },
        });
        let anns = build_annotations("P.CU", &params);
        // The origin corner is translated; lengths are unchanged.
        assert!((anns[0].point_a[0] - 5.0).abs() < 1e-9);
        assert!((anns[0].point_a[1] + 3.0).abs() < 1e-9);
        assert!((anns[0].point_a[2] - 2.0).abs() < 1e-9);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 10.0).abs() < 1e-9);
    }

    #[test]
    fn cube_rotation_90_about_z_maps_x_axis_to_y() {
        let params = json!({
            "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0,
            "transform": {
                "position": [0.0, 0.0, 0.0],
                "rotationEuler": [0.0, 0.0, 90.0],
                "scale": [1.0, 1.0, 1.0],
            },
        });
        let anns = build_annotations("P.CU", &params);
        // Local +X (sizeX) rotates onto world +Y.
        let px = anns[0].point_b;
        assert!(px[0].abs() < 1e-6, "{px:?}");
        assert!((px[1] - 10.0).abs() < 1e-6, "{px:?}");
        assert!(px[2].abs() < 1e-6, "{px:?}");
        // Lengths preserved under rotation.
        assert!((dist(anns[1].point_a, anns[1].point_b) - 20.0).abs() < 1e-6);
    }

    #[test]
    fn cube_scale_scales_world_length() {
        let params = json!({
            "sizeX": 10.0, "sizeY": 20.0, "sizeZ": 30.0,
            "transform": {
                "position": [0.0, 0.0, 0.0],
                "rotationEuler": [0.0, 0.0, 0.0],
                "scale": [2.0, 1.0, 1.0],
            },
        });
        let anns = build_annotations("P.CU", &params);
        // World length is scaled by 2, but the reported param value is still 10.
        assert!((dist(anns[0].point_a, anns[0].point_b) - 20.0).abs() < 1e-9);
        assert!((anns[0].value - 10.0).abs() < 1e-9);
    }

    #[test]
    fn cylinder_gives_radius_and_height() {
        let params = json!({
            "radius": 4.0, "height": 12.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.CY", &params);
        assert_eq!(anns.len(), 2);
        assert_eq!(anns[0].field_key, "radius");
        assert_eq!(anns[1].field_key, "height");
        assert!((dist(anns[0].point_a, anns[0].point_b) - 4.0).abs() < 1e-9);
        assert!((dist(anns[1].point_a, anns[1].point_b) - 12.0).abs() < 1e-9);
        // Height runs along +Y, radius along +X.
        assert!((anns[0].point_b[0] - 4.0).abs() < 1e-9);
        assert!((anns[1].point_b[1] - 12.0).abs() < 1e-9);
    }

    #[test]
    fn cone_gives_three_dims() {
        let params = json!({
            "radiusBottom": 5.0, "radiusTop": 2.0, "height": 8.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.CO", &params);
        assert_eq!(anns.len(), 3);
        let keys: Vec<&str> = anns.iter().map(|a| a.field_key.as_str()).collect();
        assert_eq!(keys, ["radiusBottom", "radiusTop", "height"]);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 5.0).abs() < 1e-9);
        assert!((dist(anns[1].point_a, anns[1].point_b) - 2.0).abs() < 1e-9);
        assert!((dist(anns[2].point_a, anns[2].point_b) - 8.0).abs() < 1e-9);
        // The top radius dim is anchored at y = height.
        assert!((anns[1].point_a[1] - 8.0).abs() < 1e-9);
    }

    #[test]
    fn sphere_gives_one_radius_dim() {
        let params = json!({ "radius": 7.5, "transform": ident_transform() });
        let anns = build_annotations("P.S", &params);
        assert_eq!(anns.len(), 1);
        assert_eq!(anns[0].field_key, "radius");
        assert!((dist(anns[0].point_a, anns[0].point_b) - 7.5).abs() < 1e-9);
    }

    #[test]
    fn pyramid_gives_side_and_height_centered() {
        let params = json!({
            "baseSideLength": 6.0, "height": 10.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.PY", &params);
        assert_eq!(anns.len(), 2);
        assert_eq!(anns[0].field_key, "baseSideLength");
        assert_eq!(anns[1].field_key, "height");
        assert!((dist(anns[0].point_a, anns[0].point_b) - 6.0).abs() < 1e-9);
        assert!((dist(anns[1].point_a, anns[1].point_b) - 10.0).abs() < 1e-9);
        // Centered on the axis: base at y = -h/2, apex at y = +h/2.
        assert!((anns[1].point_a[1] + 5.0).abs() < 1e-9);
        assert!((anns[1].point_b[1] - 5.0).abs() < 1e-9);
    }

    #[test]
    fn unknown_type_gives_no_dims() {
        let params = json!({ "distance": 5.0 });
        assert!(build_annotations("EXTRUDE", &params).is_empty());
        assert!(build_annotations("BOOLEAN", &params).is_empty());
    }

    #[test]
    fn numeric_string_params_resolve() {
        let params = json!({
            "sizeX": "10", "sizeY": "20", "sizeZ": "30",
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.CU", &params);
        assert!((anns[0].value - 10.0).abs() < 1e-9);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 10.0).abs() < 1e-9);
    }

    #[test]
    fn leaders_buffers_emit_shaft_cone_and_origin_sphere_tris() {
        let ann = FeatureDimAnnotation::linear("sizeX", [0.0, 0.0, 0.0], [10.0, 0.0, 0.0], 10.0, "X");
        let (pos, col) = leaders_buffers(std::slice::from_ref(&ann), 0.1);
        // Triangle soup: 3 position + 3 color floats per vertex, and the count is
        // a whole number of triangles.
        assert!(!pos.is_empty(), "expected triangle geometry");
        assert_eq!(pos.len(), col.len(), "one rgb color per xyz position");
        assert_eq!(pos.len() % 9, 0, "whole triangles (3 verts * 3 floats)");
        // Both the silver shaft and the orange cone/sphere colors are present.
        let has = |rgb: [f32; 3]| {
            col.chunks_exact(3)
                .any(|c| (c[0] - rgb[0]).abs() < 1e-3 && (c[1] - rgb[1]).abs() < 1e-3 && (c[2] - rgb[2]).abs() < 1e-3)
        };
        assert!(has(SHAFT_RGB), "expected silver shaft tris");
        assert!(has(ORANGE_RGB), "expected orange cone/sphere tris");
    }

    #[test]
    fn cube_dims_share_one_origin_sphere() {
        // A cube's three axis dims all start at the same corner: the origin sphere
        // is deduped, so exactly one sphere's worth of extra tris appears vs a
        // single-annotation build sharing that origin.
        let anns = build_annotations(
            "P.CU",
            &json!({ "sizeX": 10.0, "sizeY": 10.0, "sizeZ": 10.0, "transform": ident_transform() }),
        );
        assert_eq!(anns.len(), 3);
        let origins: std::collections::BTreeSet<_> = anns
            .iter()
            .map(|a| (a.point_a[0] as i64, a.point_a[1] as i64, a.point_a[2] as i64))
            .collect();
        assert_eq!(origins.len(), 1, "cube dims share one origin corner");
        let (pos, _) = leaders_buffers(&anns, 0.1);
        assert!(!pos.is_empty());
    }

    // --- FD-2: torus / extrude / revolve + the angle gizmo --------------------

    fn color_present(col: &[f32], rgb: [f32; 3]) -> bool {
        col.chunks_exact(3).any(|c| {
            (c[0] - rgb[0]).abs() < 1e-3
                && (c[1] - rgb[1]).abs() < 1e-3
                && (c[2] - rgb[2]).abs() < 1e-3
        })
    }

    #[test]
    fn torus_emits_two_linear_and_one_angular() {
        let params = json!({
            "majorRadius": 5.0, "tubeRadius": 1.0, "arc": 90.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.T", &params);
        assert_eq!(anns.len(), 3);
        // majorRadius + tubeRadius are LINEAR; arc is ANGULAR.
        assert_eq!(anns[0].field_key, "majorRadius");
        assert_eq!(anns[0].kind, FeatureDimKind::Linear);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 5.0).abs() < 1e-9);
        assert_eq!(anns[1].field_key, "tubeRadius");
        assert_eq!(anns[1].kind, FeatureDimKind::Linear);
        assert!((dist(anns[1].point_a, anns[1].point_b) - 1.0).abs() < 1e-9);
        // tubeRadius is anchored at the tube centerline (majorRadius along +X).
        assert!((anns[1].point_a[0] - 5.0).abs() < 1e-9);
        // arc: angular about local +Y from the +X reference, value in degrees.
        let arc = &anns[2];
        assert_eq!(arc.field_key, "arc");
        assert_eq!(arc.kind, FeatureDimKind::Angular);
        assert!((arc.value - 90.0).abs() < 1e-9);
        assert!((arc.axis[1] - 1.0).abs() < 1e-6, "axis ≈ +Y: {:?}", arc.axis);
        assert!((arc.ref_dir[0] - 1.0).abs() < 1e-6, "ref ≈ +X: {:?}", arc.ref_dir);
    }

    #[test]
    fn torus_arc_clamped_to_360() {
        let params = json!({
            "majorRadius": 5.0, "tubeRadius": 1.0, "arc": 500.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.T", &params);
        assert!((anns[2].value - 360.0).abs() < 1e-9, "arc clamps to 360");
    }

    #[test]
    fn extrude_emits_linear_distance_along_normal() {
        let refs = ResolvedRefs {
            profile_center: Some([2.0, 0.0, 0.0]),
            profile_normal: Some([0.0, 0.0, 1.0]),
            ..Default::default()
        };
        let params = json!({ "distance": 10.0, "distanceBack": 3.0 });
        let anns = build_annotations_with_refs("E", &params, &refs);
        assert_eq!(anns.len(), 2);
        assert_eq!(anns[0].field_key, "distance");
        assert_eq!(anns[0].kind, FeatureDimKind::Linear);
        // The distance leader runs from the profile center along +normal (+Z) by 10.
        assert_eq!(anns[0].point_a, [2.0, 0.0, 0.0]);
        assert!((anns[0].point_b[2] - 10.0).abs() < 1e-9);
        assert!((dist(anns[0].point_a, anns[0].point_b) - 10.0).abs() < 1e-9);
        // The back leg runs along -normal by distanceBack.
        assert_eq!(anns[1].field_key, "distanceBack");
        assert!((anns[1].point_b[2] + 3.0).abs() < 1e-9);
    }

    #[test]
    fn revolve_emits_one_angular_about_axis() {
        // Axis = +Z through the origin; profile off +X. Expect one angular dim of
        // the given degrees, about +Z, zeroed on the radial (+X) to the profile.
        let refs = ResolvedRefs {
            profile_center: Some([5.0, 0.0, 0.0]),
            profile_normal: Some([0.0, 1.0, 0.0]),
            axis_point: Some([0.0, 0.0, 0.0]),
            axis_dir: Some([0.0, 0.0, 1.0]),
            ..Default::default()
        };
        let params = json!({ "angle": 234.0 });
        let anns = build_annotations_with_refs("R", &params, &refs);
        assert_eq!(anns.len(), 1);
        let a = &anns[0];
        assert_eq!(a.field_key, "angle");
        assert_eq!(a.kind, FeatureDimKind::Angular);
        assert!((a.value - 234.0).abs() < 1e-9);
        assert!((a.axis[2] - 1.0).abs() < 1e-6, "axis ≈ +Z: {:?}", a.axis);
        assert!((a.ref_dir[0] - 1.0).abs() < 1e-6, "ref ≈ +X: {:?}", a.ref_dir);
        // The vertex is the axis point nearest the profile (the origin here).
        assert!(norm3(a.center) < 1e-9, "vertex on axis: {:?}", a.center);
    }

    #[test]
    fn revolve_axis_orients_toward_profile_front() {
        // Flipping the profile normal flips which of the two axis directions the
        // oriented sweep uses (the `orient_revolve_axis` sign test).
        let base = ResolvedRefs {
            profile_center: Some([5.0, 0.0, 0.0]),
            profile_normal: Some([0.0, 1.0, 0.0]),
            axis_point: Some([0.0, 0.0, 0.0]),
            axis_dir: Some([0.0, 0.0, 1.0]),
            ..Default::default()
        };
        let flipped = ResolvedRefs {
            profile_normal: Some([0.0, -1.0, 0.0]),
            ..base.clone()
        };
        let params = json!({ "angle": 90.0 });
        let a = build_annotations_with_refs("R", &params, &base);
        let b = build_annotations_with_refs("R", &params, &flipped);
        assert!((a[0].axis[2] - 1.0).abs() < 1e-6);
        assert!((b[0].axis[2] + 1.0).abs() < 1e-6, "flipped normal → negated axis");
    }

    #[test]
    fn extrude_and_revolve_empty_without_resolved_refs() {
        let refs = ResolvedRefs::default();
        assert!(build_annotations_with_refs("E", &json!({ "distance": 5.0 }), &refs).is_empty());
        assert!(build_annotations_with_refs("R", &json!({ "angle": 90.0 }), &refs).is_empty());
    }

    #[test]
    fn angle_gizmo_emits_arc_cone_sphere_ref_and_axis_tris() {
        let params = json!({
            "majorRadius": 5.0, "tubeRadius": 1.0, "arc": 234.0,
            "transform": ident_transform(),
        });
        let anns = build_annotations("P.T", &params);
        let (pos, col) = leaders_buffers(&anns, 0.1);
        assert!(!pos.is_empty());
        assert_eq!(pos.len(), col.len());
        assert_eq!(pos.len() % 9, 0);
        // The angle gizmo contributes all four colors: grey arc + orange
        // cone/handle + red dashed reference + green axis.
        assert!(color_present(&col, SHAFT_RGB), "grey arc");
        assert!(color_present(&col, ORANGE_RGB), "orange cone/handle");
        assert!(color_present(&col, RED_RGB), "red dashed reference");
        assert!(color_present(&col, GREEN_RGB), "green axis");
    }

    #[test]
    fn angular_chip_anchor_sits_on_the_arc_mid_sweep() {
        // A 180° arc about +Z from +X: the mid-sweep bisector is +Y, so the chip
        // anchors at center + (+Y) * radius (radius = 120px * world_per_pixel).
        let ann = FeatureDimAnnotation::angular(
            "angle",
            [0.0, 0.0, 0.0],
            [0.0, 0.0, 1.0],
            [1.0, 0.0, 0.0],
            180.0,
            "A",
        );
        let wpp = 0.01;
        let anchor = angular_chip_anchor(&ann, wpp);
        let radius = ANGLE_ARC_RAD_PX * wpp;
        assert!((anchor[1] - radius).abs() < 1e-6, "mid-sweep ≈ +Y*radius: {anchor:?}");
        assert!(anchor[0].abs() < 1e-6 && anchor[2].abs() < 1e-6);
    }
}