brep_render/

constraint_overlays.rs

//! Assembly-constraint VIEWPORT overlays (build-spec §8.4) — the CONSTRAINT twin
//! of [`crate::feature_dimensions`].
//!
//! Pure builders: the kernel's `assembly_overlay_json` rows (per-constraint world
//! anchors / directions / status / measured value) + the `assembly_state_json`
//! constraint list (for `inputParams` — expression detection + element refs) fold
//! into [`ConstraintOverlay`] records, which bake into the SAME leader/arrow/arc
//! triangle buffers the feature-dimension gizmo draws (via
//! [`crate::feature_dimensions::leaders_buffers`] — nothing re-rolled, per the
//! UI-consistency directive):
//!
//! * **distance** → a LINEAR dimension annotation — the silver rod + orange
//!   cone arrow + orange origin sphere, GRABBABLE (drag edits
//!   `inputParams.distance`, commit auto-solves). Plane-based pairings draw the
//!   TRUE dimension perpendicular to the BASE face (the perpendicular-foot
//!   construction on [`build_distance_annotation`], matching the kernel's
//!   signed `d = (P_other − P_base)·n̂_base` convention); plane-less pairings
//!   keep the plain anchor-to-anchor leader.
//! * **angle** → an ANGULAR annotation (the screen-constant arc + orange sweep-end
//!   handle + red dashed zero reference + green axis), GRABBABLE (drag edits
//!   `inputParams.angle`).
//! * everything else (coincident / parallel / perpendicular / concentric /
//!   tangent / touch_align / fixed) → a plain anchor-to-anchor leader line +
//!   label anchor only — never a handle.
//!
//! Dragging is DISABLED for a distance/angle whose param is a non-numeric
//! EXPRESSION string (matches how feature dimensions treat expression-driven
//! params); the engine consults [`ConstraintOverlay::draggable`].
//!
//! The interactive state machine (hit regions, drag preview, the
//! `assembly_update_constraint_json` commit) lives in
//! `engine_state/assembly_overlay.rs`; this module stays camera-free and pure so
//! the geometry is unit-testable from canned JSON payloads.

use serde_json::Value;

use crate::feature_dimensions::{
    append_plain_leader, leaders_buffers, FeatureDimAnnotation,
};

/// Which overlay family a constraint renders as.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ConstraintOverlayKind {
    /// A grabbable linear dimension arrow pair (`distance`).
    Distance,
    /// A grabbable angle arc (`angle`).
    Angle,
    /// A non-interactive leader + label (every other type).
    Leader,
}

/// One constraint's overlay record: identity + status for the label, the
/// resolved world geometry, and (for the dimensional kinds) the annotation the
/// shared leader renderer draws + the drag machinery grabs.
#[derive(Clone, Debug)]
pub struct ConstraintOverlay {
    /// The constraint id (`DIST3`, `ANGL2`, …) — the mutation-ABI key.
    pub id: String,
    /// The constraint `type` string (`distance`, `coincident`, …).
    pub constraint_type: String,
    /// The solve status (`satisfied` / `adjusted` / `error` / …) — drives the
    /// label color via [`status_color`].
    pub status: String,
    /// The human status/solve message (label tooltip).
    pub message: String,
    /// The overlay family.
    pub kind: ConstraintOverlayKind,
    /// The resolved WORLD anchor points (one per selection; empty when the
    /// kernel could not resolve the selections — label-less, geometry-less row).
    pub anchors: Vec<[f64; 3]>,
    /// Distance/Angle: the dimension annotation (reusing the feature-dim shape so
    /// `leaders_buffers` renders it verbatim). `field_key` is the `inputParams`
    /// key the drag edits (`distance` / `angle`). `None` for `Leader` rows and
    /// for dimensional rows whose anchors did not resolve.
    pub annotation: Option<FeatureDimAnnotation>,
    /// The measured value the kernel evaluated (`value` in the overlay row), for
    /// the label suffix. `None` for non-dimensional rows.
    pub value: Option<f64>,
    /// The value's unit (`"mm"` / `"deg"`), empty when `value` is `None`.
    pub unit: String,
    /// Whether the dimensional handle may be DRAGGED: true only for
    /// Distance/Angle whose current param is numeric (or absent — a first-solve
    /// initialized target). A non-numeric expression string disables the drag.
    pub draggable: bool,
    /// The constraint's `inputParams` (from the state list) — the drag commit
    /// mutates a clone of this (so `elements` / flags ride along unchanged).
    pub input_params: Value,
    /// The referenced element names (`inputParams.elements`) — label hover
    /// highlights these through the existing emphasis machinery.
    pub elements: Vec<String>,
}

impl ConstraintOverlay {
    /// The `inputParams` key a drag on this overlay edits (`distance` / `angle`).
    pub fn field_key(&self) -> Option<&'static str> {
        match self.kind {
            ConstraintOverlayKind::Distance => Some("distance"),
            ConstraintOverlayKind::Angle => Some("angle"),
            ConstraintOverlayKind::Leader => None,
        }
    }

    /// The world-space label anchor: a dimensional annotation's chip anchor (the
    /// leader midpoint, or the angle arc's mid-sweep at the screen-constant
    /// radius — camera-dependent via `world_per_pixel`); a leader row's anchor
    /// midpoint (or its single anchor). `None` when nothing resolved.
    pub fn label_anchor(&self, world_per_pixel: f64) -> Option<[f64; 3]> {
        if let Some(annotation) = &self.annotation {
            return Some(match self.kind {
                ConstraintOverlayKind::Angle => {
                    crate::feature_dimensions::angular_chip_anchor(annotation, world_per_pixel)
                }
                _ => annotation.midpoint(),
            });
        }
        match self.anchors.len() {
            0 => None,
            1 => Some(self.anchors[0]),
            _ => {
                let a = self.anchors[0];
                let b = self.anchors[1];
                Some([(a[0] + b[0]) * 0.5, (a[1] + b[1]) * 0.5, (a[2] + b[2]) * 0.5])
            }
        }
    }

    /// The label chip text: `{id} {value}{unit}` for dimensional rows
    /// (`DIST3 5.25 mm`, `ANGL2 90°`), bare `{id}` otherwise.
    pub fn label_text(&self) -> String {
        match self.value {
            Some(value) => {
                let n = format!("{value:.2}");
                let n = n.trim_end_matches('0').trim_end_matches('.');
                if self.unit == "deg" {
                    format!("{} {}\u{00b0}", self.id, n)
                } else if self.unit.is_empty() {
                    format!("{} {}", self.id, n)
                } else {
                    format!("{} {} {}", self.id, n, self.unit)
                }
            }
            None => self.id.clone(),
        }
    }
}

// ---------------------------------------------------------------------------
// Status → color
// ---------------------------------------------------------------------------

/// The requirements-doc §5 status → color vocabulary as display-sRGB `[r,g,b]`
/// (0..1, hex/255 like the leader palette — the overlay shader writes ~directly).
///
/// Overlay-shader color (0..1 floats) for a constraint status — a thin view
/// over the ONE canonical map in [`crate::assembly_status`] (the panel's row
/// labels and the tree rollup consume the same table; unified at Wave-3
/// integration so the vocabulary can never drift).
pub fn status_color(status: &str) -> [f32; 3] {
    let [r, g, b] = crate::assembly_status::status_color_rgb(status);
    [r as f32 / 255.0, g as f32 / 255.0, b as f32 / 255.0]
}

// ---------------------------------------------------------------------------
// Builder
// ---------------------------------------------------------------------------

/// Build the overlay records from the kernel payloads: `overlay_rows` is the
/// parsed `assembly_overlay_json` array; `state_constraints` is the parsed
/// `assembly_state_json`'s `constraints` array (may be `Null` — the builder then
/// has no `inputParams`, so dimensional rows fall back to draggable-with-empty
/// params). Rows without resolved anchors yield status-only records (no
/// geometry, no label anchor); a `fixed` constraint's single anchor yields a
/// label anchor but no leader.
pub fn build_constraint_overlays(
    overlay_rows: &Value,
    state_constraints: &Value,
) -> Vec<ConstraintOverlay> {
    let Some(rows) = overlay_rows.as_array() else {
        return Vec::new();
    };
    rows.iter()
        .filter_map(|row| build_row(row, state_constraints))
        .collect()
}

fn build_row(row: &Value, state_constraints: &Value) -> Option<ConstraintOverlay> {
    let id = row.get("id")?.as_str()?.to_string();
    let constraint_type = row
        .get("type")
        .and_then(Value::as_str)
        .unwrap_or("")
        .to_string();
    let status = row
        .get("status")
        .and_then(Value::as_str)
        .unwrap_or("")
        .to_string();
    let message = row
        .get("message")
        .and_then(Value::as_str)
        .unwrap_or("")
        .to_string();
    let anchors = read_points(row.get("anchors"));
    let directions = read_dirs(row.get("directions"));
    let geoms = read_strings(row.get("geoms"));
    let value = row.get("value").and_then(Value::as_f64);
    let unit = row
        .get("unit")
        .and_then(Value::as_str)
        .unwrap_or("")
        .to_string();

    // The matching state entry's inputParams (expression check + elements).
    let input_params = state_constraints
        .as_array()
        .and_then(|list| {
            list.iter().find(|entry| {
                entry
                    .get("inputParams")
                    .and_then(|p| p.get("id"))
                    .and_then(Value::as_str)
                    == Some(id.as_str())
            })
        })
        .and_then(|entry| entry.get("inputParams"))
        .cloned()
        .unwrap_or_else(|| Value::Object(serde_json::Map::new()));
    let elements = input_params
        .get("elements")
        .and_then(Value::as_array)
        .map(|list| {
            list.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .unwrap_or_default();

    let kind = match constraint_type.as_str() {
        "distance" => ConstraintOverlayKind::Distance,
        "angle" => ConstraintOverlayKind::Angle,
        _ => ConstraintOverlayKind::Leader,
    };

    // Dragging: only the dimensional kinds, and only while the param is NOT a
    // non-numeric expression string (absent / number / plain numeric string are
    // all draggable — matching the feature-dimension expression rule).
    let draggable = match kind {
        ConstraintOverlayKind::Leader => false,
        ConstraintOverlayKind::Distance => param_allows_drag(&input_params, "distance"),
        ConstraintOverlayKind::Angle => param_allows_drag(&input_params, "angle"),
    };

    let annotation = match kind {
        ConstraintOverlayKind::Distance => {
            build_distance_annotation(&anchors, &directions, &geoms, value)
        }
        ConstraintOverlayKind::Angle => build_angle_annotation(&anchors, &directions, value),
        ConstraintOverlayKind::Leader => None,
    };

    Some(ConstraintOverlay {
        id,
        constraint_type,
        status,
        message,
        kind,
        anchors,
        annotation,
        value: match kind {
            ConstraintOverlayKind::Leader => None,
            _ => value,
        },
        unit,
        draggable,
        input_params,
        elements,
    })
}

/// Whether `params[key]` permits a value drag: absent (first-solve initialized),
/// a JSON number, or a PLAIN numeric string — but NOT a non-numeric expression
/// string (`"a + b"`), which stays authoritative and disables the handle.
fn param_allows_drag(params: &Value, key: &str) -> bool {
    match params.get(key) {
        None | Some(Value::Null) => true,
        Some(Value::Number(_)) => true,
        Some(Value::String(text)) => text.trim().parse::<f64>().is_ok(),
        _ => false,
    }
}

/// The distance constraint's LINEAR annotation.
///
/// PLANE-BASED pairings (at least one element is tagged `"plane"` in the row's
/// `geoms` — the BASE face, element 0 preferred, matching the kernel mapper's
/// base choice) draw the TRUE dimension: the other element's anchor `P` is
/// projected onto the base plane along its outward normal `n̂` — the
/// perpendicular foot `F = P − s·n̂` with `s = (P − Q)·n̂` the SIGNED offset —
/// and the arrow runs `F → P`. That segment is normal to the base face by
/// construction and its length `|s|` IS the constrained distance, so the arrow
/// shows the kernel's signed `d = (P_other − P_base)·n̂_base` convention
/// verbatim (a negative `s` points behind the face). The base normal rides in
/// the annotation's (linear-unused) `axis` field so the drag can measure
/// signed offsets along it — including through the face into negatives, and
/// even when `s = 0` collapses the segment to a point.
///
/// Plane-less pairings (lines/points — no side to be on) keep the plain
/// `anchors[0] → anchors[1]` leader with the unsigned measured value and a
/// zero `axis`. `None` unless both anchors resolved.
fn build_distance_annotation(
    anchors: &[[f64; 3]],
    directions: &[Option<[f64; 3]>],
    geoms: &[String],
    value: Option<f64>,
) -> Option<FeatureDimAnnotation> {
    if anchors.len() < 2 {
        return None;
    }
    // The base plane: the first element tagged "plane" with a usable normal.
    let base = (0..2).find(|&i| {
        geoms.get(i).map(String::as_str) == Some("plane")
            && directions
                .get(i)
                .copied()
                .flatten()
                .is_some_and(|n| co_norm(n) > 1e-9)
    });
    if let Some(base) = base {
        let n = directions[base].expect("base index checked above");
        let len = co_norm(n);
        let n = [n[0] / len, n[1] / len, n[2] / len];
        let q = anchors[base];
        let p = anchors[1 - base];
        let s = co_dot(co_sub(p, q), n);
        let foot = [p[0] - n[0] * s, p[1] - n[1] * s, p[2] - n[2] * s];
        // The kernel's measured `value` equals `s` for both plane arms (same
        // formula over the same anchors); prefer it for label consistency.
        let mut annotation =
            FeatureDimAnnotation::linear("distance", foot, p, value.unwrap_or(s), "D");
        annotation.axis = n;
        return Some(annotation);
    }
    let a = anchors[0];
    let b = anchors[1];
    let value = value.unwrap_or_else(|| co_norm(co_sub(b, a)));
    Some(FeatureDimAnnotation::linear("distance", a, b, value, "D"))
}

/// The angle constraint's ANGULAR annotation. Geometry: the arc sweeps from
/// direction `d0` toward `d1` about `axis = normalize(d0 × d1)` — the axis that
/// makes rotating `d0` by the measured interior angle land exactly on `d1` — and
/// is centered at the closest-approach midpoint of the two carrier lines
/// (`anchors[i] + t·dᵢ`), the natural angle vertex; parallel/degenerate carriers
/// fall back to the anchor midpoint, and a parallel/antiparallel pair (the 0°/
/// 180° satisfied states — `d0 × d1 ≈ 0`) falls back to an arbitrary
/// perpendicular axis via the `angular` ctor, which still renders and keeps the
/// drag well-defined once the value moves off zero. `None` unless both anchors
/// AND both directions resolved.
fn build_angle_annotation(
    anchors: &[[f64; 3]],
    directions: &[Option<[f64; 3]>],
    value: Option<f64>,
) -> Option<FeatureDimAnnotation> {
    if anchors.len() < 2 || directions.len() < 2 {
        return None;
    }
    let d0 = directions[0]?;
    let d1 = directions[1]?;
    let axis = co_cross(d0, d1);
    let center = carrier_closest_midpoint(anchors[0], d0, anchors[1], d1);
    let value = value.unwrap_or(0.0).clamp(-360.0, 360.0);
    Some(FeatureDimAnnotation::angular(
        "angle", center, axis, d0, value, "A",
    ))
}

/// The midpoint of the closest-approach segment between carrier lines
/// `a + t·da` and `b + s·db`; the anchor midpoint when (near) parallel.
fn carrier_closest_midpoint(a: [f64; 3], da: [f64; 3], b: [f64; 3], db: [f64; 3]) -> [f64; 3] {
    let mid = |p: [f64; 3], q: [f64; 3]| {
        [(p[0] + q[0]) * 0.5, (p[1] + q[1]) * 0.5, (p[2] + q[2]) * 0.5]
    };
    let da_n = co_norm(da);
    let db_n = co_norm(db);
    if da_n < 1e-9 || db_n < 1e-9 {
        return mid(a, b);
    }
    let u = [da[0] / da_n, da[1] / da_n, da[2] / da_n];
    let v = [db[0] / db_n, db[1] / db_n, db[2] / db_n];
    let w0 = co_sub(a, b);
    let b_uv = co_dot(u, v);
    let denom = 1.0 - b_uv * b_uv;
    if denom.abs() < 1e-9 {
        return mid(a, b); // parallel carriers — no unique vertex
    }
    let d = co_dot(u, w0);
    let e = co_dot(v, w0);
    let t = (b_uv * e - d) / denom;
    let s = (e - b_uv * d) / denom;
    let p = [a[0] + u[0] * t, a[1] + u[1] * t, a[2] + u[2] * t];
    let q = [b[0] + v[0] * s, b[1] + v[1] * s, b[2] + v[2] * s];
    mid(p, q)
}

// ---------------------------------------------------------------------------
// Buffers
// ---------------------------------------------------------------------------

/// Bake the whole overlay set into flat world-space triangle `(positions,
/// colors)` buffers (the `tris` shape the overlay group consumes): the
/// dimensional annotations through [`leaders_buffers`] (identical arrow/arc
/// styling), the non-dimensional rows as plain silver leaders
/// ([`append_plain_leader`]). Rows without geometry contribute nothing.
pub fn constraint_overlay_buffers(
    overlays: &[ConstraintOverlay],
    world_per_pixel: f64,
) -> (Vec<f32>, Vec<f32>) {
    let annotations: Vec<FeatureDimAnnotation> = overlays
        .iter()
        .filter_map(|overlay| overlay.annotation.clone())
        .collect();
    let (mut positions, mut colors) = leaders_buffers(&annotations, world_per_pixel);
    for overlay in overlays {
        if overlay.kind == ConstraintOverlayKind::Leader && overlay.anchors.len() >= 2 {
            append_plain_leader(
                &mut positions,
                &mut colors,
                overlay.anchors[0],
                overlay.anchors[1],
                world_per_pixel,
            );
        }
    }
    (positions, colors)
}

// ---------------------------------------------------------------------------
// JSON + vec helpers (self-contained; `co_` prefixed like the fd_ family)
// ---------------------------------------------------------------------------

fn read_points(value: Option<&Value>) -> Vec<[f64; 3]> {
    value
        .and_then(Value::as_array)
        .map(|list| list.iter().filter_map(read_point3).collect())
        .unwrap_or_default()
}

/// Directions align index-wise with anchors; a JSON `null` (a point-like
/// selection has no direction) stays `None`.
fn read_dirs(value: Option<&Value>) -> Vec<Option<[f64; 3]>> {
    value
        .and_then(Value::as_array)
        .map(|list| list.iter().map(read_point3).collect())
        .unwrap_or_default()
}

/// The row's per-element `geoms` tags (aligned index-wise with anchors);
/// empty when absent — a distance row then has no identifiable base plane and
/// falls back to the plain anchor-to-anchor leader.
fn read_strings(value: Option<&Value>) -> Vec<String> {
    value
        .and_then(Value::as_array)
        .map(|list| {
            list.iter()
                .map(|v| v.as_str().unwrap_or("").to_string())
                .collect()
        })
        .unwrap_or_default()
}

fn read_point3(value: &Value) -> Option<[f64; 3]> {
    let list = value.as_array()?;
    Some([
        list.first()?.as_f64()?,
        list.get(1)?.as_f64()?,
        list.get(2)?.as_f64()?,
    ])
}

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

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

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

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

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

    /// A one-entry `assembly_state_json`-shaped constraint list (the builder
    /// matches entries by `inputParams.id` only, so `type` is informational).
    fn state_with(params: Value) -> Value {
        json!([{ "type": "constraint", "inputParams": params, "persistentData": {},
                 "enabled": true, "open": false }])
    }

    #[test]
    fn distance_row_builds_a_grabbable_linear_annotation() {
        let rows = json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[0.0, 0.0, 0.0], [8.0, 0.0, 0.0]],
            "directions": [[1.0, 0.0, 0.0], [-1.0, 0.0, 0.0]],
            "value": 8.0, "unit": "mm", "target": 8.0,
        }]);
        let state = state_with(json!({
            "id": "DIST1", "elements": ["ACOMP1:Part_PX", "ACOMP2:Part_NX"], "distance": 8.0
        }));
        // Without state constraints the row still builds (params default empty).
        assert_eq!(build_constraint_overlays(&rows, &Value::Null).len(), 1);
        let overlays = build_constraint_overlays(&rows, &state);
        assert_eq!(overlays.len(), 1);
        let o = &overlays[0];
        assert_eq!(o.kind, ConstraintOverlayKind::Distance);
        assert!(o.draggable, "numeric distance param is draggable");
        assert_eq!(o.field_key(), Some("distance"));
        assert_eq!(o.elements, ["ACOMP1:Part_PX", "ACOMP2:Part_NX"]);
        let ann = o.annotation.as_ref().expect("linear annotation");
        assert_eq!(ann.kind, FeatureDimKind::Linear);
        assert_eq!(ann.point_a, [0.0, 0.0, 0.0]);
        assert_eq!(ann.point_b, [8.0, 0.0, 0.0]);
        assert!((ann.value - 8.0).abs() < 1e-12);
        // Label: id + value + unit; anchored at the leader midpoint.
        assert_eq!(o.label_text(), "DIST1 8 mm");
        assert_eq!(o.label_anchor(0.1), Some([4.0, 0.0, 0.0]));
    }

    #[test]
    fn plane_based_distance_draws_the_perpendicular_foot_arrow() {
        // Base face: a plane TILTED off every axis (n̂ = [1,1,1]/√3) anchored
        // at Q; the other anchor P sits obliquely off the plane — the naive
        // Q→P chord is NOT normal to the face. The arrow must instead run
        // foot → P along n̂ with length |s|, s = (P−Q)·n̂ (the constraint's
        // signed value), and stash n̂ in `axis` for the signed drag.
        let n = 1.0 / 3.0_f64.sqrt();
        let q = [1.0, 2.0, 3.0];
        let p = [4.0, 1.0, 5.0];
        let s = 4.0 / 3.0_f64.sqrt(); // (P−Q)·n̂ = (3 − 1 + 2)/√3
        let rows = json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [q, p],
            "directions": [[n, n, n], null],
            "geoms": ["plane", "point"],
            "value": s, "unit": "mm",
        }]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        let ann = overlays[0].annotation.as_ref().expect("linear annotation");
        // Tip = the other element's anchor; base normal stashed for the drag.
        assert_eq!(ann.point_b, p);
        for i in 0..3 {
            assert!((ann.axis[i] - n).abs() < 1e-12, "axis = n̂: {:?}", ann.axis);
        }
        // The segment is exactly s·n̂ — perpendicular to the base face, length
        // == the constrained distance, pointing to P's (positive) side.
        let d = co_sub(ann.point_b, ann.point_a);
        assert!(co_norm(co_cross(d, ann.axis)) < 1e-9, "arrow ∥ base normal: {d:?}");
        assert!((co_dot(d, ann.axis) - s).abs() < 1e-12, "signed length == s");
        assert!((co_norm(d) - s.abs()).abs() < 1e-12, "world length == |s|");
        // The foot lies IN the base plane (through Q, normal n̂).
        assert!(co_dot(co_sub(ann.point_a, q), ann.axis).abs() < 1e-12, "foot on the plane");
        assert!((ann.value - s).abs() < 1e-12, "value = the kernel's signed measure");
    }

    #[test]
    fn plane_second_and_negative_offsets_flip_the_arrow_behind_the_face() {
        // The plane may be the SECOND element (a point/vertex picked first):
        // it is still the base. P sits BEHIND the face (s = −4 along +Z), so
        // the arrow points opposite the normal and the label goes negative.
        let rows = json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[2.0, 3.0, 1.0], [0.0, 0.0, 5.0]],
            "directions": [null, [0.0, 0.0, 1.0]],
            "geoms": ["point", "plane"],
            "value": -4.0, "unit": "mm",
        }]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        let o = &overlays[0];
        let ann = o.annotation.as_ref().expect("linear annotation");
        assert_eq!(ann.point_a, [2.0, 3.0, 5.0], "foot above P, in the plane z=5");
        assert_eq!(ann.point_b, [2.0, 3.0, 1.0], "tip at the point anchor, behind the face");
        assert_eq!(ann.axis, [0.0, 0.0, 1.0]);
        assert!((ann.value + 4.0).abs() < 1e-12, "signed value: {}", ann.value);
        assert_eq!(o.label_text(), "DIST1 -4 mm");
        // A plane-LESS row (line/point pairing) keeps the plain anchor-to-anchor
        // leader and a zero axis (magnitude drag domain).
        let rows = json!([{
            "id": "DIST2", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[0.0, 0.0, 0.0], [8.0, 0.0, 0.0]],
            "directions": [[0.0, 1.0, 0.0], [0.0, 1.0, 0.0]],
            "geoms": ["line", "line"],
            "value": 8.0, "unit": "mm",
        }]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        let ann = overlays[0].annotation.as_ref().expect("linear annotation");
        assert_eq!(ann.point_a, [0.0, 0.0, 0.0]);
        assert_eq!(ann.point_b, [8.0, 0.0, 0.0]);
        assert_eq!(ann.axis, [0.0; 3], "no base plane → no signed-drag axis");
    }

    #[test]
    fn expression_distance_param_disables_the_drag() {
        let rows = json!([{
            "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
            "anchors": [[0.0, 0.0, 0.0], [8.0, 0.0, 0.0]],
            "directions": [null, null],
            "value": 8.0, "unit": "mm",
        }]);
        let state = state_with(json!({ "id": "DIST1", "elements": [], "distance": "gap * 2" }));
        let overlays = build_constraint_overlays(&rows, &state);
        assert!(!overlays[0].draggable, "expression param must disable dragging");
        // The graphics still render — only the handle is inert.
        assert!(overlays[0].annotation.is_some());
        // A PLAIN-NUMERIC string param stays draggable (matches the feature-dim
        // literal rule), as does an ABSENT param (first-solve initialized).
        let state = state_with(json!({ "id": "DIST1", "elements": [], "distance": "8.0" }));
        assert!(build_constraint_overlays(&rows, &state)[0].draggable);
        let state = state_with(json!({ "id": "DIST1", "elements": [] }));
        assert!(build_constraint_overlays(&rows, &state)[0].draggable);
    }

    #[test]
    fn angle_row_maps_directions_onto_the_arc_annotation() {
        // Two carriers meeting at the origin: d0 = +X at (5,0,0), d1 = +Y at
        // (0,5,0); measured 90°. The arc must sweep from +X about +Z (d0×d1) so
        // rotating ref_dir by the value lands on d1, centered at the carrier
        // intersection (the origin).
        let rows = json!([{
            "id": "ANGL2", "type": "angle", "status": "adjusted", "message": "",
            "anchors": [[5.0, 0.0, 0.0], [0.0, 5.0, 0.0]],
            "directions": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
            "value": 90.0, "unit": "deg",
        }]);
        let state = state_with(json!({ "id": "ANGL2", "elements": [], "angle": 90.0 }));
        let overlays = build_constraint_overlays(&rows, &state);
        let o = &overlays[0];
        assert_eq!(o.kind, ConstraintOverlayKind::Angle);
        assert!(o.draggable);
        assert_eq!(o.field_key(), Some("angle"));
        let ann = o.annotation.as_ref().expect("angular annotation");
        assert_eq!(ann.kind, FeatureDimKind::Angular);
        assert!((ann.value - 90.0).abs() < 1e-9);
        assert!((ann.axis[2] - 1.0).abs() < 1e-9, "axis = d0×d1 = +Z: {:?}", ann.axis);
        assert!((ann.ref_dir[0] - 1.0).abs() < 1e-9, "ref = d0 = +X: {:?}", ann.ref_dir);
        assert!(co_norm(ann.center) < 1e-9, "vertex at the carrier intersection: {:?}", ann.center);
        // Rotating the reference by the value lands on d1 — the arc end points at
        // the second carrier.
        let end = crate::feature_dimensions::rotate_about_axis(
            ann.ref_dir,
            ann.axis,
            ann.value.to_radians(),
        );
        assert!((end[1] - 1.0).abs() < 1e-9, "arc end ≈ d1: {end:?}");
        assert_eq!(o.label_text(), "ANGL2 90\u{00b0}");
    }

    #[test]
    fn non_dimensional_rows_get_leaders_only_and_degenerate_rows_get_nothing() {
        let rows = json!([
            // parallel: full anchors → a leader, never a handle.
            { "id": "PARA3", "type": "parallel", "status": "satisfied", "message": "",
              "anchors": [[0.0, 0.0, 0.0], [0.0, 4.0, 0.0]],
              "directions": [[0.0, 0.0, 1.0], [0.0, 0.0, 1.0]] },
            // fixed: ONE anchor → label anchor only, no leader.
            { "id": "FIXD1", "type": "fixed", "status": "satisfied", "message": "",
              "anchors": [[1.0, 2.0, 3.0]], "directions": [null] },
            // unresolved selections: status-only row (no anchors key at all).
            { "id": "COIN9", "type": "coincident", "status": "invalid-selection",
              "message": "unknown element" },
        ]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        assert_eq!(overlays.len(), 3);
        assert!(overlays.iter().all(|o| o.kind == ConstraintOverlayKind::Leader));
        assert!(overlays.iter().all(|o| !o.draggable && o.annotation.is_none()));
        assert_eq!(overlays[0].label_anchor(0.1), Some([0.0, 2.0, 0.0]));
        assert_eq!(overlays[1].label_anchor(0.1), Some([1.0, 2.0, 3.0]));
        assert_eq!(overlays[2].label_anchor(0.1), None, "no anchors → no label anchor");
        assert_eq!(overlays[2].label_text(), "COIN9");

        // Buffers: only the two-anchor parallel row contributes leader tris; the
        // single-anchor + unresolved rows add nothing (and nothing panics).
        let (pos, col) = constraint_overlay_buffers(&overlays, 0.1);
        assert!(!pos.is_empty(), "parallel leader emits tris");
        assert_eq!(pos.len(), col.len());
        assert_eq!(pos.len() % 9, 0, "whole triangles");
        let only_first: Vec<ConstraintOverlay> = overlays[1..].to_vec();
        let (pos2, _) = constraint_overlay_buffers(&only_first, 0.1);
        assert!(pos2.is_empty(), "one-anchor + unresolved rows draw no leaders");
    }

    #[test]
    fn dimensional_rows_bake_through_the_shared_leader_renderer() {
        let rows = json!([
            { "id": "DIST1", "type": "distance", "status": "satisfied", "message": "",
              "anchors": [[0.0, 0.0, 0.0], [10.0, 0.0, 0.0]],
              "directions": [null, null], "value": 10.0, "unit": "mm" },
            { "id": "ANGL2", "type": "angle", "status": "blocked", "message": "",
              "anchors": [[5.0, 0.0, 0.0], [0.0, 5.0, 0.0]],
              "directions": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
              "value": 90.0, "unit": "deg" },
        ]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        let (pos, col) = constraint_overlay_buffers(&overlays, 0.1);
        assert!(!pos.is_empty());
        assert_eq!(pos.len(), col.len());
        assert_eq!(pos.len() % 9, 0);
        // The shared feature-dim palette is present: silver shaft + orange handle
        // (linear leader + arc), red dashed zero reference + green axis (arc).
        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([0.80, 0.81, 0.82]), "silver shaft/arc tris");
        assert!(has([0.961, 0.651, 0.137]), "orange cone/handle tris");
        assert!(has([0.902, 0.157, 0.157]), "red zero-reference tris");
        assert!(has([0.204, 0.808, 0.267]), "green axis tris");
    }

    #[test]
    fn status_colors_follow_the_requirements_vocabulary() {
        let hex = |rgb: [f32; 3]| -> u32 {
            (((rgb[0] * 255.0).round() as u32) << 16)
                | (((rgb[1] * 255.0).round() as u32) << 8)
                | ((rgb[2] * 255.0).round() as u32)
        };
        assert_eq!(hex(status_color("satisfied")), 0x30d158);
        assert_eq!(hex(status_color("disabled")), 0x8e8e93);
        assert_eq!(hex(status_color("adjusted")), 0xffd60a);
        assert_eq!(hex(status_color("blocked")), 0xff3b30);
        assert_eq!(hex(status_color("error")), 0xff3b30);
        assert_eq!(hex(status_color("something-new")), 0xffd60a, "default is amber");
    }
}