@faicad/faijs 0.33.1 → 0.35.2

package/dist/sketch/project.js

@@ -0,0 +1,656 @@
+/**
+ * project — single-point conversion between the canonical sketch model and the
+ * two downstream projection dialects (§4.5).
+ *
+ *   canonical  ⇄  FCStd (`fcstd-types`, integer ConstraintType + PointPos)
+ *   canonical  ⇄  CadQuery (tag + string constraint names, 0..1 positions)
+ *
+ * One implementation, two projections: the FCStd side feeds the planegcs solve
+ * pipeline; the CadQuery side feeds `cq-compat-sketch`. Constraints with no
+ * counterpart in a target dialect raise an explicit `E_SKETCHC_*` — never a
+ * silent downgrade.
+ */
+import { PointPos, GeoId, CONSTRAINT_NAMES, ConstraintType } from './fcstd-types.js';
+import { evalBSpline } from './bspline.js';
+/** Projection error with a stable `E_SKETCHC_*` code. */
+export class SketchProjectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'SketchProjectionError';
+    }
+}
+// ── at / Ref resolution ──
+/**
+ * Map a canonical `At` to an FCStd `PointPos`. Throws `E_SKETCHC_UNMAPPED` when there is no counterpart.
+ *
+ * @param at - the canonical position.
+ * @returns the FCStd `PointPos` integer.
+ */
+export function atToFreeCad(at) {
+    if (at === undefined)
+        return PointPos.none;
+    if (at === 'start')
+        return PointPos.start;
+    if (at === 'end')
+        return PointPos.end;
+    if (at === 'center')
+        return PointPos.mid;
+    if (at === 'mid') {
+        throw new SketchProjectionError('E_SKETCHC_UNMAPPED', 'at "mid" (arc/line midpoint) has no FCStd PointPos');
+    }
+    if (typeof at === 'number') {
+        if (at === 0)
+            return PointPos.start;
+        if (at === 1)
+            return PointPos.end;
+        throw new SketchProjectionError('E_SKETCHC_UNMAPPED', `parametric at ${at} has no FCStd PointPos`);
+    }
+    throw new SketchProjectionError('E_SKETCHC_UNMAPPED', `unsupported at ${String(at)}`);
+}
+/**
+ * Map an FCStd `PointPos` to a canonical `At` (`mid` FCStd means the centre).
+ *
+ * @param pos - the FCStd `PointPos` integer.
+ * @returns the canonical position, or `undefined` for `none`.
+ */
+export function atFromFreeCad(pos) {
+    switch (pos) {
+        case PointPos.none: return undefined;
+        case PointPos.start: return 'start';
+        case PointPos.end: return 'end';
+        case PointPos.mid: return 'center';
+        default: return undefined;
+    }
+}
+/**
+ * Map a canonical `At` to a CadQuery 0..1 parameter (`null` = the arc-centre `None` argument).
+ *
+ * @param at - the canonical position.
+ * @returns the CadQuery 0..1 parameter, or `null` for centre.
+ */
+export function atToCadQuery(at) {
+    if (at === undefined)
+        return null;
+    if (at === 'start')
+        return 0;
+    if (at === 'end')
+        return 1;
+    if (at === 'mid')
+        return 0.5;
+    if (at === 'center')
+        return null;
+    return at;
+}
+/**
+ * Map a CadQuery 0..1 parameter to a canonical `At`.
+ *
+ * @param v - the CadQuery parameter, or `null`/`undefined` for centre.
+ * @returns the canonical position, or `undefined` for `null`/`undefined`.
+ */
+export function atFromCadQuery(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    if (v === 0)
+        return 'start';
+    if (v === 1)
+        return 'end';
+    if (v === 0.5)
+        return 'mid';
+    return v;
+}
+/**
+ * Build the tag → index lookup for a geometry list in one pass.
+ *
+ * @param geoms - canonical geometry list.
+ * @returns tag → geometry index.
+ */
+export function buildTagIndex(geoms) {
+    const index = new Map();
+    geoms.forEach((g, i) => {
+        if (g.tag !== undefined)
+            index.set(g.tag, i);
+    });
+    return index;
+}
+/**
+ * Resolve a canonical `Ref` to an FCStd `(geoId, pos)` pair.
+ *
+ * @param ref - the canonical reference (tag or index + at).
+ * @param tagIndex - tag → index map (from {@link buildTagIndex}).
+ * @param geoms - the geometry array (for bounds checking of index refs).
+ * @returns the FCStd `(geoId, pos)` pair.
+ * @throws SketchProjectionError `E_SKETCHC_BAD_REF` for unknown tag or out-of-range index.
+ */
+export function refToFreeCad(ref, tagIndex, geoms) {
+    let geoId;
+    if ('tag' in ref) {
+        const found = tagIndex.get(ref.tag);
+        if (found === undefined) {
+            throw new SketchProjectionError('E_SKETCHC_BAD_REF', `unknown tag "${ref.tag}"`);
+        }
+        geoId = found;
+    }
+    else if (ref.index === -1 || ref.index === -2) {
+        // AXIS ANCHORS (IRON RULE patch, 2026-10-04): canonical Refs may carry the
+        // X axis (-1) / Y axis (-2) verbatim so FCStd axis refs round-trip through
+        // canonical. The planegcs backend resolves them (`pt()`: -1 → root point,
+        // -2 → VAxis point); anything else negative stays invalid.
+        geoId = ref.index;
+    }
+    else if (ref.index <= -3 && ref.index > -2000) {
+        // EXTERNAL ANCHORS (IRON RULE patch, 2026-10-04): canonical Refs may carry
+        // the external-geometry geoId verbatim; the emitted `cad.sketch` carries
+        // the resolved fixed polylines as its `external` param and the backend
+        // (`pt()` + `externalLines`) resolves every ref statically.
+        geoId = ref.index;
+    }
+    else {
+        if (!Number.isInteger(ref.index) || ref.index < 0 || ref.index >= geoms.length) {
+            throw new SketchProjectionError('E_SKETCHC_BAD_REF', `index ${ref.index} out of range [0, ${geoms.length})`);
+        }
+        geoId = ref.index;
+    }
+    return { geoId, pos: atToFreeCad(ref.at) };
+}
+// ── geometry projection ──
+/**
+ * Spread the `construction` flag when present so reference geometry round-trips
+ * through the FCStd projection (canonical ⇄ FCStd). Returns an empty object when
+ * the flag is absent, so spreading is a no-op for ordinary geometry.
+ */
+function con(g) {
+    return g.construction ? { construction: true } : {};
+}
+/**
+ * Project canonical geometry to the FCStd shape consumed by the solver.
+ *
+ * @param geoms - canonical geometry.
+ * @returns FCStd geometry records (same order/index).
+ * @throws SketchProjectionError `E_SKETCHC_UNSUPPORTED_GEOM` for reserved kinds.
+ */
+export function toFreeCadGeoms(geoms) {
+    return geoms.map((g, index) => {
+        switch (g.kind) {
+            case 'line':
+                return { kind: 'line', index, x1: g.x1, y1: g.y1, z1: 0, x2: g.x2, y2: g.y2, z2: 0, ...con(g) };
+            case 'circle':
+                return { kind: 'circle', index, cx: g.cx, cy: g.cy, cz: 0, radius: g.r, ...con(g) };
+            case 'arc': {
+                // Pass the canonical signed span (a0, a1) through unchanged. planegcs builds
+                // the arc from the pinned start/end endpoints *and* the signed start/end
+                // angles, so a CW arc (a1 < a0) is drawn as the short clockwise arc.
+                // Normalising a1 into a CCW span would instead produce the long arc through
+                // those same endpoints. Arc orientation is carried back to the caller via
+                // solveSketch (input ccw preserved), not recovered here.
+                const a0 = g.a0;
+                const a1 = g.a1;
+                return {
+                    kind: 'arc', index, cx: g.cx, cy: g.cy, cz: 0, radius: g.r,
+                    startAngle: a0, endAngle: a1,
+                    x1: g.cx + g.r * Math.cos(a0), y1: g.cy + g.r * Math.sin(a0), z1: 0,
+                    x2: g.cx + g.r * Math.cos(a1), y2: g.cy + g.r * Math.sin(a1), z2: 0,
+                    ...con(g),
+                };
+            }
+            case 'point':
+                // Reopened 2026-09-28: planegcs-backend pushes standalone points and
+                // pulls them back; contour extraction skips them (no profile use).
+                return { kind: 'point', index, x: g.x, y: g.y, z: 0, ...con(g) };
+            case 'bspline': {
+                // Reopened 2026-09-29 (fcstd-port A2): the entry used to reject this
+                // with E_SKETCHC_UNSUPPORTED_GEOM even though the whole downstream
+                // chain already consumed it — planegcs-backend.ts:233 pushes the exact
+                // endpoints as a line proxy (so coincident/dimension constraints on the
+                // curve ends still solve), planegcs-backend.ts:700 pulls them back,
+                // contour.ts:57 de Boor-samples the interior, and verify.ts:30 anchors
+                // on the endpoints. Rejecting here was entry-schema narrowness, not a
+                // solver capability gap.
+                //
+                // Endpoints are evaluated at the clamped domain ends rather than read
+                // off poles[0]/poles[last]: a periodic or non-clamped knot vector has
+                // poles that are NOT on the curve, and evalBSpline already clamps its
+                // argument into [knots[degree], knots[n]] (bspline.ts:39-40).
+                const d = { poles: g.poles, knots: g.knots, degree: g.degree, periodic: g.periodic ?? false };
+                const lo = d.knots[d.degree] ?? 0;
+                const hi = d.knots[d.knots.length - d.degree - 1] ?? lo;
+                const s = d.poles.length > 0 ? evalBSpline(d, lo) : { x: 0, y: 0 };
+                const e = d.poles.length > 0 ? evalBSpline(d, hi) : { x: 0, y: 0 };
+                return {
+                    kind: 'bspline', index,
+                    poles: g.poles, knots: g.knots, degree: g.degree, periodic: d.periodic,
+                    x1: s.x, y1: s.y, z1: 0, x2: e.x, y2: e.y, z2: 0,
+                    ...con(g),
+                };
+            }
+            case 'ellipse': {
+                // rx/ry ARE the major/minor radii (fromFreeCadGeoms maps them back
+                // positionally), `angle` is the major-axis rotation in radians — the
+                // same unit contour.ts and planegcs consume for angleXU.
+                const major = g.rx;
+                const minor = g.ry;
+                const angleXU = g.angle ?? 0;
+                // first focus pair (computed, mirroring FreeCAD's stored foci)
+                const c = Math.sqrt(Math.max(major * major - minor * minor, 0));
+                const ca = Math.cos(angleXU);
+                const sa = Math.sin(angleXU);
+                return {
+                    kind: 'ellipse', index,
+                    cx: g.cx, cy: g.cy, cz: 0,
+                    majorRadius: major, minorRadius: minor, angleXU,
+                    fx1: g.cx - c * ca, fy1: g.cy - c * sa,
+                    fx2: g.cx + c * ca, fy2: g.cy + c * sa,
+                    ...con(g),
+                };
+            }
+        }
+    });
+}
+/**
+ * Project FCStd geometry back to the canonical model (reserved kinds are reported).
+ *
+ * @param geoms - FCStd geometry records from the solver.
+ * @returns canonical geometry (same order/index).
+ */
+export function fromFreeCadGeoms(geoms) {
+    return geoms.map((g) => {
+        switch (g.kind) {
+            case 'line':
+                return { kind: 'line', x1: g.x1, y1: g.y1, x2: g.x2, y2: g.y2, ...con(g) };
+            case 'circle':
+                return { kind: 'circle', cx: g.cx, cy: g.cy, r: g.radius, ...con(g) };
+            case 'arc': {
+                const ccw = normalizeArcCcw(g.startAngle, g.endAngle);
+                return { kind: 'arc', cx: g.cx, cy: g.cy, r: g.radius, a0: g.startAngle, a1: g.endAngle, ccw, ...con(g) };
+            }
+            case 'point':
+                return { kind: 'point', x: g.x, y: g.y, ...con(g) };
+            case 'ellipse':
+                return { kind: 'ellipse', cx: g.cx, cy: g.cy, rx: g.majorRadius, ry: g.minorRadius, angle: g.angleXU, ...con(g) };
+            case 'bspline':
+                return { kind: 'bspline', poles: g.poles, knots: g.knots, degree: g.degree, periodic: g.periodic, ...con(g) };
+        }
+    });
+}
+/** True when the arc span is counter-clockwise as stored. */
+function normalizeArcCcw(startAngle, endAngle) {
+    let sweep = endAngle - startAngle;
+    while (sweep <= 0)
+        sweep += 2 * Math.PI;
+    while (sweep > 2 * Math.PI)
+        sweep -= 2 * Math.PI;
+    return sweep > 0;
+}
+function mapConstraint(c, tagIndex, geoms) {
+    const ref = (r) => refToFreeCad(r, tagIndex, geoms);
+    switch (c.kind) {
+        case 'fixed':
+            // FCStd has no explicit fixed constraint — the implicit fixed frame
+            // (RtPnt + H/V axes) absorbs the rigid-body DoF (§4.5).
+            return 'noop';
+        case 'coincident':
+            return { type: ConstraintType.Coincident, refs: [ref(c.a), ref(c.b)] };
+        case 'horizontal':
+            return { type: ConstraintType.Horizontal, refs: [ref(c.of)] };
+        case 'vertical':
+            return { type: ConstraintType.Vertical, refs: [ref(c.of)] };
+        case 'parallel':
+            return { type: ConstraintType.Parallel, refs: [ref(c.a), ref(c.b)] };
+        case 'perpendicular':
+            return { type: ConstraintType.Perpendicular, refs: [ref(c.a), ref(c.b)] };
+        case 'tangent':
+            return { type: ConstraintType.Tangent, refs: [ref(c.a), ref(c.b)] };
+        case 'distance':
+            return { type: ConstraintType.Distance, refs: [ref(c.a), ref(c.b)], value: c.value };
+        case 'distanceX':
+            return { type: ConstraintType.DistanceX, refs: [ref(c.a), ref(c.b)], value: c.value };
+        case 'distanceY':
+            return { type: ConstraintType.DistanceY, refs: [ref(c.a), ref(c.b)], value: c.value };
+        case 'length': {
+            // Length is expressed as a point-to-point Distance over the element ends.
+            const base = ref(c.of);
+            const start = { geoId: base.geoId, pos: PointPos.start };
+            const end = { geoId: base.geoId, pos: PointPos.end };
+            return { type: ConstraintType.Distance, refs: [start, end], value: c.value };
+        }
+        case 'angle':
+            return { type: ConstraintType.Angle, refs: [ref(c.a), ref(c.b)], value: c.value };
+        case 'orientation':
+            // Reverse of the 1-ref Angle projection: emit a single-reference FCStd
+            // Angle (absolute line orientation, radians). The planegcs backend lowers a
+            // 1-ref Angle to `p2p_angle` on the line's own endpoints.
+            return { type: ConstraintType.Angle, refs: [ref(c.of)], value: Math.atan2(c.dir[1], c.dir[0]) };
+        case 'radius':
+            return { type: ConstraintType.Radius, refs: [ref(c.of)], value: c.value };
+        case 'diameter':
+            return { type: ConstraintType.Diameter, refs: [ref(c.of)], value: c.value };
+        case 'arcAngle':
+            throw new SketchProjectionError('E_SKETCHC_UNMAPPED', 'constraint "arcAngle" has no FCStd counterpart');
+        case 'equal':
+            return { type: ConstraintType.Equal, refs: [ref(c.a), ref(c.b)] };
+        case 'pointOnObject':
+            return { type: ConstraintType.PointOnObject, refs: [ref(c.p), ref(c.on)] };
+        case 'symmetric':
+            return { type: ConstraintType.Symmetric, refs: [ref(c.p1), ref(c.p2), ref(c.about)] };
+    }
+}
+/**
+ * Project canonical constraints to the FCStd shape the solver consumes.
+ *
+ * @param constraints - canonical constraints.
+ * @param geoms - canonical geometry (for tag/index resolution).
+ * @returns FCStd constraints plus the no-op (`fixed`) indices.
+ */
+export function toFreeCadConstraints(constraints, geoms) {
+    const tagIndex = buildTagIndex(geoms);
+    const out = [];
+    const noops = [];
+    constraints.forEach((c, index) => {
+        const mapped = mapConstraint(c, tagIndex, geoms);
+        if (mapped === 'noop') {
+            noops.push(index);
+            return;
+        }
+        out.push({ index, type: mapped.type, refs: mapped.refs, value: mapped.value ?? 0, isDriving: true, name: '' });
+    });
+    return { constraints: out, noops };
+}
+/**
+ * Minimum number of refs each FCStd constraint type must carry before
+ * {@link fromFreeCadConstraints} can express it.
+ *
+ * GOTCHA (2026-09-28, `Bathroom_cabinet_sink.FCStd` Sketch259): FreeCAD stores
+ * an implicit axis/origin as GeoUndef, so a "vertical distance from the X axis"
+ * arrives as a **1-ref** `DistanceY`. `two()`/`ref()` then dereferenced the
+ * absent second ref and threw `Cannot read properties of undefined (reading
+ * 'pos')`, which the converter reports as `solver-throw` and which failed
+ * 436/900 corpus files. Only types the projection switch actually handles are
+ * listed here: anything absent (InternalAlignment, Block, Weight …) keeps
+ * flowing to the `default:` branch and is still reported as `unsupported-type`.
+ */
+const REFS_REQUIRED = {
+    [ConstraintType.Horizontal]: 1,
+    [ConstraintType.Vertical]: 1,
+    [ConstraintType.Distance]: 1, // 1-ref Distance is a length (see the case below)
+    [ConstraintType.Angle]: 1, // the case below flags a 1-ref Angle as ambiguous
+    [ConstraintType.Radius]: 1,
+    [ConstraintType.Diameter]: 1,
+    [ConstraintType.Coincident]: 2,
+    [ConstraintType.Parallel]: 2,
+    [ConstraintType.Tangent]: 2,
+    [ConstraintType.DistanceX]: 1,
+    [ConstraintType.DistanceY]: 1,
+    [ConstraintType.Perpendicular]: 2,
+    [ConstraintType.Equal]: 2,
+    [ConstraintType.PointOnObject]: 2,
+    [ConstraintType.Symmetric]: 3,
+};
+/**
+ * Project FCStd sketch constraints back to the canonical model — the reverse of
+ * {@link toFreeCadConstraints} / `mapConstraint`. This is the bridge the fcstd
+ * converter uses to emit `cad.sketch({ geoms, constraints })` from a parsed
+ * `Sketcher::SketchObject` (2026-09-28 plan A1).
+ *
+ * Mapping notes / GOTCHAs (validated against `mapConstraint` + the planegcs
+ * backend):
+ * - `length` is stored FCStd-side as a point-to-point Distance over the line's
+ *   own start/end — a 1-ref Distance projects back to `length` (GOTCHA: a
+ *   genuine 2-ref Distance between two distinct points is NOT a length).
+ * - `fixed` has no FCStd counterpart (the implicit frame absorbs it), so it can
+ *   never appear in FCStd input — nothing to project back.
+ * - Angle values pass through UNCHANGED in both directions: FreeCAD serializes
+ *   Angle constraint `Value` in radians in the XML, and the planegcs backend
+ *   forwards it verbatim. Consumers wanting canonical degrees must convert at
+ *   the boundary that knows the file unit (GOTCHA 2026-09-28: forward
+ *   projection also passes through, so roundtrips are unit-consistent).
+ * - Constraints referencing the axes (geoId -1/-2) or external geometry
+ *   (geoId <= -3) have no canonical Ref (canonical refs are own-geometry
+ *   indices only) — reported in `unmapped` with reason
+ *   `external-or-axis-ref` instead of being silently dropped.
+ * - `isDriving === false` (reference/driven) constraints carry no solve
+ *   information — reported with reason `reference-driven`.
+ * - A constraint with fewer refs than its type requires (e.g. a 1-ref
+ *   `DistanceY`, which FreeCAD writes when the axis is implicit) is reported
+ *   with reason `ambiguous-refs`; see `REFS_REQUIRED`. This projection never
+ *   throws on such input.
+ *
+ * @param cons - FCStd constraints (e.g. from `parseSketchObject`).
+ * @param _geoms - unused; kept for signature symmetry with the projection pipeline.
+ * @returns canonical constraints plus the unmapped ledger.
+ */
+export function fromFreeCadConstraints(cons, _geoms) {
+    const ref = (r) => {
+        const at = atFromFreeCad(r.pos);
+        return (at === undefined ? { index: r.geoId } : { index: r.geoId, at });
+    };
+    const constraints = [];
+    const unmapped = [];
+    const pushUnmapped = (index, type, reason) => {
+        unmapped.push({ index, type, typeName: CONSTRAINT_NAMES[type] ?? `type#${type}`, reason });
+    };
+    cons.forEach((c, index) => {
+        if (!c.isDriving) {
+            // Reference/driven constraint carries no solve information — canonical has
+            // no field for it. Drop it silently instead of reporting a gap.
+            return;
+        }
+        // External geometry refs (geoId <= -3, down to just above GeoUndef) ride
+        // into canonical as negative Ref indices verbatim — the converter resolves
+        // the referenced external geometry to fixed polylines at convert time and
+        // the emitted `cad.sketch` carries them as its `external` param, so the
+        // planegcs backend (`pt()` + `externalLines`) resolves every ref
+        // statically (IRON RULE patch, 2026-10-04: no run-time attempt — a ref the
+        // converter could NOT resolve never enters sketchInputs).
+        // GOTCHA (2026-10-04, taperedballnose): old-format constraint triples pad
+        // unused slots with GeoUndef = -2000 (sketch-parse.ts skips them when
+        // building externalGeoIds for the same reason) — a real axis/external ref
+        // never reaches -2000. The old `geoId < 0` blanket check here used to
+        // reject ~every constraint in such files (20 of 21 in the sample) as
+        // `external-or-axis-ref`, mass-gapping otherwise-clean sketches.
+        // Ref-count guard (see REFS_REQUIRED) — runs BEFORE any ref dereference so
+        // an under-specified constraint is recorded rather than thrown out of the
+        // whole projection. Types the switch does not handle (InternalAlignment,
+        // Block, Weight …) are absent from the map and stay on the `default:` path,
+        // so they keep reporting `unsupported-type`.
+        const required = REFS_REQUIRED[c.type];
+        if (required !== undefined && c.refs.length < required) {
+            pushUnmapped(index, c.type, 'ambiguous-refs');
+            return;
+        }
+        const two = () => [ref(c.refs[0]), ref(c.refs[1])];
+        switch (c.type) {
+            case ConstraintType.Coincident: {
+                const [a, b] = two();
+                constraints.push({ kind: 'coincident', a, b });
+                break;
+            }
+            case ConstraintType.Horizontal:
+                // GOTCHA (IRON RULE patch, 2026-10-04, Chair Sketch255): FreeCAD's
+                // Horizontal has a TWO-POINT form (refs[1] may be an external point):
+                // "these two points are level". The canonical `horizontal` kind only
+                // takes one line ref — projecting the 2-ref form to it SILENTLY DROPPED
+                // the second point and changed the constraint set (solver DoF mismatch
+                // → E_SKETCHC_CONFLICTING at run time). Static equivalent instead:
+                // two points level ⟺ distanceY(a, b, 0).
+                if (c.refs.length >= 2 && c.refs[1].pos !== PointPos.none && c.refs[1].geoId !== c.refs[0].geoId) {
+                    constraints.push({ kind: 'distanceY', a: ref(c.refs[0]), b: ref(c.refs[1]), value: 0 });
+                }
+                else {
+                    constraints.push({ kind: 'horizontal', of: ref(c.refs[0]) });
+                }
+                break;
+            case ConstraintType.Vertical:
+                // symmetric case to Horizontal: two points aligned ⟺ distanceX(a, b, 0)
+                if (c.refs.length >= 2 && c.refs[1].pos !== PointPos.none && c.refs[1].geoId !== c.refs[0].geoId) {
+                    constraints.push({ kind: 'distanceX', a: ref(c.refs[0]), b: ref(c.refs[1]), value: 0 });
+                }
+                else {
+                    constraints.push({ kind: 'vertical', of: ref(c.refs[0]) });
+                }
+                break;
+            case ConstraintType.Parallel: {
+                const [a, b] = two();
+                constraints.push({ kind: 'parallel', a, b });
+                break;
+            }
+            case ConstraintType.Perpendicular: {
+                const [a, b] = two();
+                constraints.push({ kind: 'perpendicular', a, b });
+                break;
+            }
+            case ConstraintType.Tangent: {
+                const [a, b] = two();
+                constraints.push({ kind: 'tangent', a, b });
+                break;
+            }
+            case ConstraintType.Distance:
+                if (c.refs.length >= 2 &&
+                    // GOTCHA: mapConstraint encodes canonical `length` as a Distance over
+                    // the SAME geometry's start/end points — a same-geoId start/end pair
+                    // is a length, not a genuine point-to-point distance.
+                    !(c.refs[0].geoId === c.refs[1].geoId && c.refs[0].pos === PointPos.start && c.refs[1].pos === PointPos.end)) {
+                    const [a, b] = two();
+                    constraints.push({ kind: 'distance', a, b, value: c.value });
+                }
+                else {
+                    // point-to-point Distance over one element's own ends = length
+                    // (canonical `length` refs the whole element, no `at`)
+                    constraints.push({ kind: 'length', of: { index: c.refs[0].geoId }, value: c.value });
+                }
+                break;
+            case ConstraintType.DistanceX: {
+                if (c.refs.length >= 2) {
+                    const [a, b] = two();
+                    constraints.push({ kind: 'distanceX', a, b, value: c.value });
+                }
+                else {
+                    // 1-ref DistanceX = absolute X coordinate of the point/line w.r.t. the
+                    // Y-axis (VAxis, geoId -2). The planegcs backend special-cases an
+                    // axis-edge second ref as `coordinate_x` (absolute, not a difference),
+                    // matching FreeCAD's single-reference DistanceX semantics.
+                    constraints.push({ kind: 'distanceX', a: ref(c.refs[0]), b: { index: GeoId.VAxis }, value: c.value });
+                }
+                break;
+            }
+            case ConstraintType.DistanceY: {
+                if (c.refs.length >= 2) {
+                    const [a, b] = two();
+                    constraints.push({ kind: 'distanceY', a, b, value: c.value });
+                }
+                else {
+                    // 1-ref DistanceY = absolute Y coordinate w.r.t. the X-axis (HAxis=-1).
+                    constraints.push({ kind: 'distanceY', a: ref(c.refs[0]), b: { index: GeoId.HAxis }, value: c.value });
+                }
+                break;
+            }
+            case ConstraintType.Angle:
+                if (c.refs.length >= 2) {
+                    const [a, b] = two();
+                    constraints.push({ kind: 'angle', a, b, value: c.value });
+                }
+                else {
+                    // 1-ref Angle = absolute orientation of a single line w.r.t. the X-axis.
+                    // Canonical models this as `orientation` (dir = [cos, sin]); the
+                    // planegcs backend lowers a 1-ref FCStd Angle to `p2p_angle` on the
+                    // line's own endpoints, and `mapConstraint` re-emits it as a 1-ref
+                    // Angle on the reverse path.
+                    constraints.push({ kind: 'orientation', of: ref(c.refs[0]), dir: [Math.cos(c.value), Math.sin(c.value)] });
+                }
+                break;
+            case ConstraintType.Radius:
+                constraints.push({ kind: 'radius', of: ref(c.refs[0]), value: c.value });
+                break;
+            case ConstraintType.Diameter:
+                constraints.push({ kind: 'diameter', of: ref(c.refs[0]), value: c.value });
+                break;
+            case ConstraintType.Equal: {
+                const [a, b] = two();
+                constraints.push({ kind: 'equal', a, b });
+                break;
+            }
+            case ConstraintType.PointOnObject:
+                constraints.push({ kind: 'pointOnObject', p: ref(c.refs[0]), on: ref(c.refs[1]) });
+                break;
+            case ConstraintType.Symmetric:
+                constraints.push({
+                    kind: 'symmetric',
+                    p1: ref(c.refs[0]),
+                    p2: ref(c.refs[1]),
+                    about: ref(c.refs[2]),
+                });
+                break;
+            case ConstraintType.Weight:
+                // Weight is a solver soft-penalty hint, not a geometric constraint —
+                // canonical has no field for it. Drop it (no gap, no constraint).
+                break;
+            case ConstraintType.Block: {
+                // Block freezes its referenced geometry. Canonical `fixed` is the closest
+                // existing kind; `mapConstraint` lowers `fixed` to a no-op because the
+                // implicit fixed frame already pins the rigid body.
+                for (const r of c.refs)
+                    constraints.push({ kind: 'fixed', of: ref(r) });
+                break;
+            }
+            default:
+                // InternalAlignment / SnellsLaw / Group / Text / …
+                pushUnmapped(index, c.type, 'unsupported-type');
+        }
+    });
+    return { constraints, unmapped };
+}
+// ── CadQuery projection (constraint type names) ──
+/** CadQuery constraint names for the canonical kinds it supports (the other 8). */
+export const CONSTRAINT_KIND_TO_CADQUERY = {
+    fixed: 'FixedPoint',
+    coincident: 'Coincident',
+    angle: 'Angle',
+    length: 'Length',
+    distance: 'Distance',
+    radius: 'Radius',
+    orientation: 'Orientation',
+    arcAngle: 'ArcAngle',
+};
+/**
+ * CadQuery constraint name → canonical kind.
+ *
+ * Beyond the one-name-per-kind reverse of {@link CONSTRAINT_KIND_TO_CADQUERY},
+ * CadQuery spells the fixed constraint **two** ways — `Fixed` (whole entity) and
+ * `FixedPoint` (a point) — and both mean canonical `fixed` here. The forward
+ * direction emits `FixedPoint`; the reverse direction must accept either, or a
+ * caller that reads upstream CadQuery scripts (`s.constrain(f, "Fixed")`) gets
+ * `E_SKETCHC_UNSUPPORTED_CONSTRAINT` on a name upstream accepts.
+ */
+export const CADQUERY_TO_CONSTRAINT_KIND = {
+    ...Object.fromEntries(Object.entries(CONSTRAINT_KIND_TO_CADQUERY).map(([kind, name]) => [name, kind])),
+    Fixed: 'fixed',
+};
+/**
+ * Map a canonical constraint kind to its CadQuery name.
+ *
+ * @param kind - canonical constraint kind.
+ * @returns the CadQuery constraint name.
+ * @throws SketchProjectionError `E_SKETCHC_UNSUPPORTED_BY_CQ` when CQ has no counterpart.
+ */
+export function constraintKindToCadQuery(kind) {
+    const name = CONSTRAINT_KIND_TO_CADQUERY[kind];
+    if (!name) {
+        throw new SketchProjectionError('E_SKETCHC_UNSUPPORTED_BY_CQ', `constraint "${kind}" is not supported by CadQuery`);
+    }
+    return name;
+}
+/**
+ * Map a CadQuery constraint name to its canonical kind.
+ *
+ * @param name - CadQuery constraint name.
+ * @returns the canonical kind.
+ * @throws SketchProjectionError `E_SKETCHC_UNSUPPORTED_CONSTRAINT` for unknown names.
+ */
+export function constraintKindFromCadQuery(name) {
+    const kind = CADQUERY_TO_CONSTRAINT_KIND[name];
+    if (!kind) {
+        throw new SketchProjectionError('E_SKETCHC_UNSUPPORTED_CONSTRAINT', `unknown CadQuery constraint "${name}"`);
+    }
+    return kind;
+}
+//# sourceMappingURL=project.js.map