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`).
//! * **center** → two plain leaders drawn BY ROLE from the row's `groups`
//!   (the kernel mapper's inferred `[width pair, tab]` element-index groups):
//!   the width span between its two faces, and a leader from that span's
//!   midpoint (which lies on the mid-plane) to the tab's anchor centroid; the
//!   label sits at the width midpoint. Pick order never shapes the drawing.
//! * 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 type's icon glyph (`brep_kernel::ConstraintTypeDef::icon`) — what
    /// the viewport chip shows in place of the id. Empty for an unknown type,
    /// in which case the chip falls back to the id.
    pub icon: 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]>,
    /// The element ROLE groups a multi-element type inferred (`groups` on the
    /// overlay row): index groups into `anchors`, role order — center's
    /// `[width pair, tab]`. Empty for the pairing types, whose two anchors ARE
    /// the drawing.
    pub groups: Vec<Vec<usize>>,
    /// 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 role-grouped row's
    /// first-group centroid (center: the width span's midpoint, on the
    /// mid-plane); 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(),
            });
        }
        if let Some((span, _)) = self.role_leaders() {
            return Some(co_mid(span.0, span.1));
        }
        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 role-drawn leaders of a grouped row (center): the WIDTH span
    /// between the first group's two anchors, and the leader from that span's
    /// midpoint to the second group's anchor centroid. `None` unless the row
    /// carries two groups whose indexes all resolve to anchors (a pairing row,
    /// or a stale `groups` against a shorter anchor list, draws the plain
    /// leader instead).
    fn role_leaders(&self) -> Option<(([f64; 3], [f64; 3]), ([f64; 3], [f64; 3]))> {
        let [width, tab] = self.groups.as_slice() else {
            return None;
        };
        let [w0, w1] = width.as_slice() else {
            return None;
        };
        let (a, b) = (*self.anchors.get(*w0)?, *self.anchors.get(*w1)?);
        if tab.is_empty() {
            return None;
        }
        let mut centroid = [0.0f64; 3];
        for &index in tab {
            let p = self.anchors.get(index)?;
            for k in 0..3 {
                centroid[k] += p[k] / tab.len() as f64;
            }
        }
        Some(((a, b), (co_mid(a, b), centroid)))
    }

    /// The label chip text: the type's icon, then `{value}{unit}` for
    /// dimensional rows (`⟺ 5.25 mm`, `∠ 90°`); the bare icon otherwise. The
    /// id no longer rides in the chip — the app's chip hover names it — so a
    /// crowded assembly reads by picture, not by `DIST3`/`COIN9` codes. A row
    /// whose type has no icon keeps the id in the icon's place.
    pub fn label_text(&self) -> String {
        let lead = if self.icon.is_empty() { self.id.as_str() } else { self.icon.as_str() };
        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!("{lead} {n}\u{00b0}")
                } else if self.unit.is_empty() {
                    format!("{lead} {n}")
                } else {
                    format!("{lead} {n} {}", self.unit)
                }
            }
            None => lead.to_string(),
        }
    }
}

// ---------------------------------------------------------------------------
// 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 icon = brep_kernel::constraint_type(&constraint_type)
        .map(|def| def.icon.to_string())
        .unwrap_or_default();
    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 groups = read_groups(row.get("groups"));
    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,
        icon,
        status,
        message,
        kind,
        anchors,
        groups,
        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 {
            continue;
        }
        if let Some((span, tab)) = overlay.role_leaders() {
            // Role-drawn (center): the width span, then mid-plane → tab.
            append_plain_leader(&mut positions, &mut colors, span.0, span.1, world_per_pixel);
            append_plain_leader(&mut positions, &mut colors, tab.0, tab.1, world_per_pixel);
        } else if 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()
}

/// The row's role `groups` (index groups into `anchors`); empty when absent.
fn read_groups(value: Option<&Value>) -> Vec<Vec<usize>> {
    value
        .and_then(Value::as_array)
        .map(|groups| {
            groups
                .iter()
                .map(|group| {
                    group
                        .as_array()
                        .map(|list| {
                            list.iter()
                                .filter_map(Value::as_u64)
                                .map(|index| index as usize)
                                .collect()
                        })
                        .unwrap_or_default()
                })
                .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_mid(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
    [(a[0] + b[0]) * 0.5, (a[1] + b[1]) * 0.5, (a[2] + b[2]) * 0.5]
}

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(), "\u{27FA} 8 mm", "icon, not id, leads the chip");
        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(), "\u{27FA} -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(), "\u{2220} 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(), "\u{2261}", "a leader row's chip is the bare icon");
        assert_eq!(overlays[2].icon, "\u{2261}");

        // 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");
    }

    /// A center row draws BY ROLE: the width span between the two width
    /// anchors and a leader from its midpoint to the tab centroid, with the
    /// label on the width midpoint — whatever order the picks arrived in. A
    /// grouped row whose indexes do not fit the anchors falls back to the
    /// plain first-two leader rather than panicking.
    #[test]
    fn center_rows_draw_the_width_span_and_the_tab_leader_by_role() {
        // Picked tab-first: anchors[0] is the tab, the width is [2, 1].
        let rows = json!([
            { "id": "CNTR1", "type": "center", "status": "satisfied", "message": "",
              "anchors": [[6.0, 1.0, 0.0], [4.0, 0.0, 0.0], [0.0, 0.0, 0.0]],
              "directions": [[1.0, 0.0, 0.0], [1.0, 0.0, 0.0], [-1.0, 0.0, 0.0]],
              "geoms": ["plane", "plane", "plane"],
              "groups": [[2, 1], [0]] },
            // Four picks: the tab centroid is the midpoint of its two anchors.
            { "id": "CNTR2", "type": "center", "status": "satisfied", "message": "",
              "anchors": [[0.0, 0.0, 0.0], [0.0, 3.0, 0.0], [5.0, 1.0, 0.0], [5.0, 2.0, 0.0]],
              "directions": [null, null, null, null],
              "geoms": ["plane", "plane", "plane", "plane"],
              "groups": [[0, 1], [2, 3]] },
            // Stale groups (an index past the anchors) → the plain leader.
            { "id": "CNTR3", "type": "center", "status": "adjusted", "message": "",
              "anchors": [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0]],
              "directions": [null, null],
              "groups": [[0, 5], [1]] },
        ]);
        let overlays = build_constraint_overlays(&rows, &Value::Null);
        assert_eq!(overlays.len(), 3);
        assert!(overlays.iter().all(|o| o.kind == ConstraintOverlayKind::Leader && !o.draggable));
        assert_eq!(overlays[0].groups, vec![vec![2, 1], vec![0]]);
        // Label on the WIDTH midpoint (x=2), not the first-two-anchors midpoint (x=5).
        assert_eq!(overlays[0].label_anchor(0.1), Some([2.0, 0.0, 0.0]));
        let (span, tab) = overlays[0].role_leaders().expect("role leaders");
        assert_eq!(span, ([0.0, 0.0, 0.0], [4.0, 0.0, 0.0]));
        assert_eq!(tab, ([2.0, 0.0, 0.0], [6.0, 1.0, 0.0]));
        assert_eq!(overlays[0].label_text(), "\u{25EB}", "a center chip is the bare icon");
        let (_, tab2) = overlays[1].role_leaders().expect("role leaders");
        assert_eq!(tab2, ([0.0, 1.5, 0.0], [5.0, 1.5, 0.0]));
        assert!(overlays[2].role_leaders().is_none(), "stale groups draw nothing by role");
        assert_eq!(overlays[2].label_anchor(0.1), Some([1.0, 0.0, 0.0]));

        // Buffers: the role-drawn row emits TWO tubes' worth of triangles — more
        // than a plain one-leader row of the same anchor count.
        let (pos_center, col_center) = constraint_overlay_buffers(&overlays[..1], 0.1);
        let (pos_plain, _) = constraint_overlay_buffers(&overlays[2..], 0.1);
        assert_eq!(pos_center.len(), col_center.len());
        assert_eq!(pos_center.len() % 9, 0);
        assert!(!pos_plain.is_empty());
        assert_eq!(pos_center.len(), 2 * pos_plain.len(), "two leaders vs one");
    }

    #[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");
    }
}