@faicad/faijs 0.13.0

package/dist/api/assembly/solvers/linalg.js

@@ -0,0 +1,217 @@
+/**
+ * api/assembly/solvers/linalg — 自实现向量数学与线性求解（P1，裁定 4）
+ *
+ * 规模极小（≤30 阶对称正定），优先 Cholesky（比 Gauss-Jordan 更稳且快），
+ * 退化时回落 Gauss-Jordan 带部分主元。vendored 的 `ikFns.solveLinear` 是模块私有、
+ * 不可 import（裁定 4），故在此自实现，vendored 只读约定不变。
+ *
+ * 模块零外部依赖；所有函数纯数值。
+ */
+/**
+ * Component-wise vector sum `a + b`.
+ * @param a - left operand.
+ * @param b - right operand.
+ * @returns the sum vector.
+ */
+export function vadd(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+/**
+ * Component-wise vector difference `a - b`.
+ * @param a - left operand.
+ * @param b - right operand.
+ * @returns the difference vector.
+ */
+export function vsub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+/**
+ * Dot product `⟨a, b⟩`.
+ * @param a - left operand.
+ * @param b - right operand.
+ * @returns the dot product.
+ */
+export function vdot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/**
+ * Cross product `a × b`.
+ * @param a - left operand.
+ * @param b - right operand.
+ * @returns the cross-product vector.
+ */
+export function vcross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+/**
+ * Scalar multiple `a * s`.
+ * @param a - the vector.
+ * @param s - the scalar factor.
+ * @returns the scaled vector.
+ */
+export function vscale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+/**
+ * Euclidean norm `‖a‖`.
+ * @param a - the vector.
+ * @returns the norm.
+ */
+export function vnorm(a) {
+    return Math.hypot(a[0], a[1], a[2]);
+}
+/**
+ * 原地归一化（零向量安全：返回 [0,0,0]）。
+ * @param a - the vector to normalize (not mutated).
+ * @returns the unit vector along `a`, or `[0, 0, 0]` for a near-zero vector.
+ */
+export function vnormalize(a) {
+    const l = vnorm(a);
+    return l < 1e-15 ? [0, 0, 0] : [a[0] / l, a[1] / l, a[2] / l];
+}
+/**
+ * Sum of squared components `‖a‖²`.
+ * @param a - the vector.
+ * @returns the sum of squares.
+ */
+export function vsumsqr(a) {
+    return a[0] * a[0] + a[1] * a[1] + a[2] * a[2];
+}
+/**
+ * AᵀA（n×m 矩阵 → n×n 对称）与 Aᵀb。矩阵按行主序扁平存于 `A`（len = rows*cols）。
+ * @param a - row-major `rows × cols` matrix A (flat array, length rows*cols).
+ * @param rows - number of rows of A.
+ * @param cols - number of columns of A.
+ * @returns the `cols × cols` symmetric matrix AᵀA (row-major, flat).
+ */
+export function ata(a, rows, cols) {
+    const out = new Array(cols * cols).fill(0);
+    for (let i = 0; i < cols; i++) {
+        for (let j = 0; j < cols; j++) {
+            let s = 0;
+            for (let k = 0; k < rows; k++)
+                s += a[k * cols + i] * a[k * cols + j];
+            out[i * cols + j] = s;
+        }
+    }
+    return out;
+}
+/**
+ * Aᵀb for the row-major `rows × cols` matrix `a` and length-`rows` vector `b`.
+ * @param a - row-major `rows × cols` matrix A (flat array, length rows*cols).
+ * @param b - right-hand-side vector of length rows.
+ * @param rows - number of rows of A.
+ * @param cols - number of columns of A.
+ * @returns the length-`cols` vector Aᵀb.
+ */
+export function atb(a, b, rows, cols) {
+    const out = new Array(cols).fill(0);
+    for (let j = 0; j < cols; j++) {
+        let s = 0;
+        for (let k = 0; k < rows; k++)
+            s += a[k * cols + j] * b[k];
+        out[j] = s;
+    }
+    return out;
+}
+/**
+ * 解 (M + λI) x = b，M 为 n×n 对称正定（此处 M = JᵀJ）。
+ * 先尝试 Cholesky(M + λI)；若非正定，逐步放大 λ 重试；最终回落带部分主元 Gauss-Jordan。
+ *
+ * @param m - row-major `n × n` symmetric positive-definite matrix M (flat array).
+ * @param b - right-hand-side vector of length n.
+ * @param n - system dimension.
+ * @param lambda - initial damping coefficient (progressively amplified on retry).
+ * @returns 解向量 x，或退化时 null。
+ */
+export function solveDampedNormal(m, b, n, lambda) {
+    // 尝试多级 λ（LM 阻尼放大）
+    const lambdas = [lambda, lambda * 4, lambda * 16, lambda * 64, lambda * 256, lambda * 1024];
+    for (const lam of lambdas) {
+        const md = m.slice();
+        for (let i = 0; i < n; i++)
+            md[i * n + i] += lam;
+        const x = choleskySolve(md, b, n);
+        if (x)
+            return x;
+    }
+    return gaussJordanSolve(m, b, n, lambda);
+}
+/** Cholesky（A = L Lᵀ）解对称正定系统；失败返回 null。 */
+function choleskySolve(a, b, n) {
+    const L = new Array(n * n).fill(0);
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j <= i; j++) {
+            let s = a[i * n + j];
+            for (let k = 0; k < j; k++)
+                s -= L[i * n + k] * L[j * n + k];
+            if (i === j) {
+                if (s <= 0)
+                    return null; // 非正定
+                L[i * n + i] = Math.sqrt(s);
+            }
+            else {
+                L[i * n + j] = s / L[j * n + j];
+            }
+        }
+    }
+    // 前代 L y = b
+    const y = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+        let s = b[i];
+        for (let k = 0; k < i; k++)
+            s -= L[i * n + k] * y[k];
+        y[i] = s / L[i * n + i];
+    }
+    // 回代 Lᵀ x = y
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        let s = y[i];
+        for (let k = i + 1; k < n; k++)
+            s -= L[k * n + i] * x[k];
+        x[i] = s / L[i * n + i];
+    }
+    return x;
+}
+/** 带部分主元 Gauss-Jordan，附加 λI 阻尼保证可解性。 */
+function gaussJordanSolve(a, b, n, lambda) {
+    const m = a.slice();
+    for (let i = 0; i < n; i++)
+        m[i * n + i] += lambda;
+    const x = new Array(n).fill(0);
+    const aug = new Array(n).fill(0).map((_, i) => [...m.slice(i * n, i * n + n), b[i]]);
+    for (let col = 0; col < n; col++) {
+        let piv = col;
+        let best = Math.abs(aug[col][col]);
+        for (let r = col + 1; r < n; r++) {
+            const v = Math.abs(aug[r][col]);
+            if (v > best) {
+                best = v;
+                piv = r;
+            }
+        }
+        if (best < 1e-15)
+            return null;
+        if (piv !== col) {
+            const tmp = aug[piv];
+            aug[piv] = aug[col];
+            aug[col] = tmp;
+        }
+        const d = aug[col][col];
+        for (let j = col; j <= n; j++)
+            aug[col][j] /= d;
+        for (let r = 0; r < n; r++) {
+            if (r === col)
+                continue;
+            const f = aug[r][col];
+            if (f === 0)
+                continue;
+            for (let j = col; j <= n; j++)
+                aug[r][j] -= f * aug[col][j];
+        }
+    }
+    for (let i = 0; i < n; i++)
+        x[i] = aug[i][n];
+    return x;
+}
+//# sourceMappingURL=linalg.js.map

package/dist/api/assembly/solvers/linalg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linalg.js","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/linalg.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solvers/linalg — 自实现向量数学与线性求解（P1，裁定 4）\n *\n * 规模极小（≤30 阶对称正定），优先 Cholesky（比 Gauss-Jordan 更稳且快），\n * 退化时回落 Gauss-Jordan 带部分主元。vendored 的 `ikFns.solveLinear` 是模块私有、\n * 不可 import（裁定 4），故在此自实现，vendored 只读约定不变。\n *\n * 模块零外部依赖；所有函数纯数值。\n */\n\nexport type Vec3 = [number, number, number]\n\n/**\n * Component-wise vector sum `a + b`.\n * @param a - left operand.\n * @param b - right operand.\n * @returns the sum vector.\n */\nexport function vadd(a: Vec3, b: Vec3): Vec3 {\n  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]]\n}\n/**\n * Component-wise vector difference `a - b`.\n * @param a - left operand.\n * @param b - right operand.\n * @returns the difference vector.\n */\nexport function vsub(a: Vec3, b: Vec3): Vec3 {\n  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]\n}\n/**\n * Dot product `⟨a, b⟩`.\n * @param a - left operand.\n * @param b - right operand.\n * @returns the dot product.\n */\nexport function vdot(a: Vec3, b: Vec3): number {\n  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]\n}\n/**\n * Cross product `a × b`.\n * @param a - left operand.\n * @param b - right operand.\n * @returns the cross-product vector.\n */\nexport function vcross(a: Vec3, b: Vec3): Vec3 {\n  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]\n}\n/**\n * Scalar multiple `a * s`.\n * @param a - the vector.\n * @param s - the scalar factor.\n * @returns the scaled vector.\n */\nexport function vscale(a: Vec3, s: number): Vec3 {\n  return [a[0] * s, a[1] * s, a[2] * s]\n}\n/**\n * Euclidean norm `‖a‖`.\n * @param a - the vector.\n * @returns the norm.\n */\nexport function vnorm(a: Vec3): number {\n  return Math.hypot(a[0], a[1], a[2])\n}\n/**\n * 原地归一化（零向量安全：返回 [0,0,0]）。\n * @param a - the vector to normalize (not mutated).\n * @returns the unit vector along `a`, or `[0, 0, 0]` for a near-zero vector.\n */\nexport function vnormalize(a: Vec3): Vec3 {\n  const l = vnorm(a)\n  return l < 1e-15 ? [0, 0, 0] : [a[0] / l, a[1] / l, a[2] / l]\n}\n/**\n * Sum of squared components `‖a‖²`.\n * @param a - the vector.\n * @returns the sum of squares.\n */\nexport function vsumsqr(a: Vec3): number {\n  return a[0] * a[0] + a[1] * a[1] + a[2] * a[2]\n}\n\n/**\n * AᵀA（n×m 矩阵 → n×n 对称）与 Aᵀb。矩阵按行主序扁平存于 `A`（len = rows*cols）。\n * @param a - row-major `rows × cols` matrix A (flat array, length rows*cols).\n * @param rows - number of rows of A.\n * @param cols - number of columns of A.\n * @returns the `cols × cols` symmetric matrix AᵀA (row-major, flat).\n */\nexport function ata(a: number[], rows: number, cols: number): number[] {\n  const out = new Array(cols * cols).fill(0)\n  for (let i = 0; i < cols; i++) {\n    for (let j = 0; j < cols; j++) {\n      let s = 0\n      for (let k = 0; k < rows; k++) s += a[k * cols + i] * a[k * cols + j]\n      out[i * cols + j] = s\n    }\n  }\n  return out\n}\n/**\n * Aᵀb for the row-major `rows × cols` matrix `a` and length-`rows` vector `b`.\n * @param a - row-major `rows × cols` matrix A (flat array, length rows*cols).\n * @param b - right-hand-side vector of length rows.\n * @param rows - number of rows of A.\n * @param cols - number of columns of A.\n * @returns the length-`cols` vector Aᵀb.\n */\nexport function atb(a: number[], b: number[], rows: number, cols: number): number[] {\n  const out = new Array(cols).fill(0)\n  for (let j = 0; j < cols; j++) {\n    let s = 0\n    for (let k = 0; k < rows; k++) s += a[k * cols + j] * b[k]\n    out[j] = s\n  }\n  return out\n}\n\n/**\n * 解 (M + λI) x = b，M 为 n×n 对称正定（此处 M = JᵀJ）。\n * 先尝试 Cholesky(M + λI)；若非正定，逐步放大 λ 重试；最终回落带部分主元 Gauss-Jordan。\n *\n * @param m - row-major `n × n` symmetric positive-definite matrix M (flat array).\n * @param b - right-hand-side vector of length n.\n * @param n - system dimension.\n * @param lambda - initial damping coefficient (progressively amplified on retry).\n * @returns 解向量 x，或退化时 null。\n */\nexport function solveDampedNormal(\n  m: number[],\n  b: number[],\n  n: number,\n  lambda: number,\n): number[] | null {\n  // 尝试多级 λ（LM 阻尼放大）\n  const lambdas = [lambda, lambda * 4, lambda * 16, lambda * 64, lambda * 256, lambda * 1024]\n  for (const lam of lambdas) {\n    const md = m.slice()\n    for (let i = 0; i < n; i++) md[i * n + i] += lam\n    const x = choleskySolve(md, b, n)\n    if (x) return x\n  }\n  return gaussJordanSolve(m, b, n, lambda)\n}\n\n/** Cholesky（A = L Lᵀ）解对称正定系统；失败返回 null。 */\nfunction choleskySolve(a: number[], b: number[], n: number): number[] | null {\n  const L = new Array(n * n).fill(0)\n  for (let i = 0; i < n; i++) {\n    for (let j = 0; j <= i; j++) {\n      let s = a[i * n + j]\n      for (let k = 0; k < j; k++) s -= L[i * n + k] * L[j * n + k]\n      if (i === j) {\n        if (s <= 0) return null // 非正定\n        L[i * n + i] = Math.sqrt(s)\n      } else {\n        L[i * n + j] = s / L[j * n + j]\n      }\n    }\n  }\n  // 前代 L y = b\n  const y = new Array(n).fill(0)\n  for (let i = 0; i < n; i++) {\n    let s = b[i]\n    for (let k = 0; k < i; k++) s -= L[i * n + k] * y[k]\n    y[i] = s / L[i * n + i]\n  }\n  // 回代 Lᵀ x = y\n  const x = new Array(n).fill(0)\n  for (let i = n - 1; i >= 0; i--) {\n    let s = y[i]\n    for (let k = i + 1; k < n; k++) s -= L[k * n + i] * x[k]\n    x[i] = s / L[i * n + i]\n  }\n  return x\n}\n\n/** 带部分主元 Gauss-Jordan，附加 λI 阻尼保证可解性。 */\nfunction gaussJordanSolve(a: number[], b: number[], n: number, lambda: number): number[] | null {\n  const m = a.slice()\n  for (let i = 0; i < n; i++) m[i * n + i] += lambda\n  const x = new Array(n).fill(0)\n  const aug = new Array(n).fill(0).map((_, i) => [...m.slice(i * n, i * n + n), b[i]])\n  for (let col = 0; col < n; col++) {\n    let piv = col\n    let best = Math.abs(aug[col][col])\n    for (let r = col + 1; r < n; r++) {\n      const v = Math.abs(aug[r][col])\n      if (v > best) {\n        best = v\n        piv = r\n      }\n    }\n    if (best < 1e-15) return null\n    if (piv !== col) {\n      const tmp = aug[piv]\n      aug[piv] = aug[col]\n      aug[col] = tmp\n    }\n    const d = aug[col][col]\n    for (let j = col; j <= n; j++) aug[col][j] /= d\n    for (let r = 0; r < n; r++) {\n      if (r === col) continue\n      const f = aug[r][col]\n      if (f === 0) continue\n      for (let j = col; j <= n; j++) aug[r][j] -= f * aug[col][j]\n    }\n  }\n  for (let i = 0; i < n; i++) x[i] = aug[i][n]\n  return x\n}\n"]}

package/dist/api/assembly/solvers/pose-from-delta.d.ts

@@ -0,0 +1,43 @@
+/**
+ * api/assembly/solvers/pose-from-delta — 模长参数化旋转（P1，对齐 B2 / solver.py:309-328）
+ *
+ * 复刻 CadQuery `solver.py` 的旋转参数化：旋转用 3 维 ΔR=(a,b,c)（模长参数化），
+ * 不直接用四元数。与 CQ 逐字一致：
+ *
+ *   m = a²+b²+c²
+ *   u = 2R/(1+m)            // 虚部
+ *   s = (1-m)/(1+m)         // 实部
+ *   Rotate(v,R) = 2⟨u,v⟩u + (s²−⟨u,u⟩)v + 2s(u×v)
+ *
+ * 该公式对 (s,u) 单位四元数即标准旋转（s²+⟨u,u⟩=1 ⇒ s²−⟨u,u⟩ = 1−2⟨u,u⟩）。
+ * 初值 R=(1e-2,1e-2,1e-2)（B3）。
+ */
+import type { Vec3 } from './linalg.js';
+/**
+ * 由 ΔR=(a,b,c) 计算四元数分量（实部 s、虚部 u）。
+ * @param a - first magnitude-parameterized rotation component.
+ * @param b - second magnitude-parameterized rotation component.
+ * @param c - third magnitude-parameterized rotation component.
+ * @returns the quaternion parts: scalar part `s` and imaginary part `u` (Vec3).
+ */
+export declare function quatPartsFromR(a: number, b: number, c: number): {
+    s: number;
+    u: Vec3;
+};
+/**
+ * 用 ΔR 旋转向量 v（CQ `Rotate`，逐字实现）。
+ * @param v - 待旋转向量（本地系）。
+ * @param r - ΔR=(a,b,c)。
+ * @returns 旋转后的向量。
+ */
+export declare function rotateByR(v: Vec3, r: Vec3): Vec3;
+/**
+ * 由 ΔR 生成 brepjs 序四元数 [w,x,y,z]（即 CQ 的 (s,u)）。
+ * 供 `poseToAssemblyTransform` 的 SolverPose.rotation 使用。
+ * @param a - first magnitude-parameterized rotation component.
+ * @param b - second magnitude-parameterized rotation component.
+ * @param c - third magnitude-parameterized rotation component.
+ * @returns the quaternion as `[w, x, y, z]` (brepjs order).
+ */
+export declare function quatFromR(a: number, b: number, c: number): [number, number, number, number];
+//# sourceMappingURL=pose-from-delta.d.ts.map

package/dist/api/assembly/solvers/pose-from-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pose-from-delta.d.ts","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/pose-from-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAGpC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,IAAI,CAAA;CAAE,CAOtF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,CAUhD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAI3F"}

package/dist/api/assembly/solvers/pose-from-delta.js

@@ -0,0 +1,61 @@
+/**
+ * api/assembly/solvers/pose-from-delta — 模长参数化旋转（P1，对齐 B2 / solver.py:309-328）
+ *
+ * 复刻 CadQuery `solver.py` 的旋转参数化：旋转用 3 维 ΔR=(a,b,c)（模长参数化），
+ * 不直接用四元数。与 CQ 逐字一致：
+ *
+ *   m = a²+b²+c²
+ *   u = 2R/(1+m)            // 虚部
+ *   s = (1-m)/(1+m)         // 实部
+ *   Rotate(v,R) = 2⟨u,v⟩u + (s²−⟨u,u⟩)v + 2s(u×v)
+ *
+ * 该公式对 (s,u) 单位四元数即标准旋转（s²+⟨u,u⟩=1 ⇒ s²−⟨u,u⟩ = 1−2⟨u,u⟩）。
+ * 初值 R=(1e-2,1e-2,1e-2)（B3）。
+ */
+import { vcross, vdot } from './linalg.js';
+/**
+ * 由 ΔR=(a,b,c) 计算四元数分量（实部 s、虚部 u）。
+ * @param a - first magnitude-parameterized rotation component.
+ * @param b - second magnitude-parameterized rotation component.
+ * @param c - third magnitude-parameterized rotation component.
+ * @returns the quaternion parts: scalar part `s` and imaginary part `u` (Vec3).
+ */
+export function quatPartsFromR(a, b, c) {
+    const m = a * a + b * b + c * c;
+    const denom = 1 + m;
+    return {
+        s: (1 - m) / denom,
+        u: [2 * a / denom, 2 * b / denom, 2 * c / denom],
+    };
+}
+/**
+ * 用 ΔR 旋转向量 v（CQ `Rotate`，逐字实现）。
+ * @param v - 待旋转向量（本地系）。
+ * @param r - ΔR=(a,b,c)。
+ * @returns 旋转后的向量。
+ */
+export function rotateByR(v, r) {
+    const { s, u } = quatPartsFromR(r[0], r[1], r[2]);
+    const uv = vdot(u, v);
+    const uu = vdot(u, u);
+    const cross = vcross(u, v);
+    return [
+        2 * uv * u[0] + (s * s - uu) * v[0] + 2 * s * cross[0],
+        2 * uv * u[1] + (s * s - uu) * v[1] + 2 * s * cross[1],
+        2 * uv * u[2] + (s * s - uu) * v[2] + 2 * s * cross[2],
+    ];
+}
+/**
+ * 由 ΔR 生成 brepjs 序四元数 [w,x,y,z]（即 CQ 的 (s,u)）。
+ * 供 `poseToAssemblyTransform` 的 SolverPose.rotation 使用。
+ * @param a - first magnitude-parameterized rotation component.
+ * @param b - second magnitude-parameterized rotation component.
+ * @param c - third magnitude-parameterized rotation component.
+ * @returns the quaternion as `[w, x, y, z]` (brepjs order).
+ */
+export function quatFromR(a, b, c) {
+    const m = a * a + b * b + c * c;
+    const denom = 1 + m;
+    return [(1 - m) / denom, 2 * a / denom, 2 * b / denom, 2 * c / denom];
+}
+//# sourceMappingURL=pose-from-delta.js.map

package/dist/api/assembly/solvers/pose-from-delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pose-from-delta.js","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/pose-from-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IAC5D,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC/B,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAA;IACnB,OAAO;QACL,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK;QAClB,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;KACjD,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,CAAO,EAAE,CAAO;IACxC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACjD,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACrB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC1B,OAAO;QACL,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;QACtD,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;QACtD,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;KACvD,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS;IACvD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC/B,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAA;IACnB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;AACvE,CAAC","sourcesContent":["/**\n * api/assembly/solvers/pose-from-delta — 模长参数化旋转（P1，对齐 B2 / solver.py:309-328）\n *\n * 复刻 CadQuery `solver.py` 的旋转参数化：旋转用 3 维 ΔR=(a,b,c)（模长参数化），\n * 不直接用四元数。与 CQ 逐字一致：\n *\n *   m = a²+b²+c²\n *   u = 2R/(1+m)            // 虚部\n *   s = (1-m)/(1+m)         // 实部\n *   Rotate(v,R) = 2⟨u,v⟩u + (s²−⟨u,u⟩)v + 2s(u×v)\n *\n * 该公式对 (s,u) 单位四元数即标准旋转（s²+⟨u,u⟩=1 ⇒ s²−⟨u,u⟩ = 1−2⟨u,u⟩）。\n * 初值 R=(1e-2,1e-2,1e-2)（B3）。\n */\n\nimport type { Vec3 } from './linalg'\nimport { vcross, vdot } from './linalg'\n\n/**\n * 由 ΔR=(a,b,c) 计算四元数分量（实部 s、虚部 u）。\n * @param a - first magnitude-parameterized rotation component.\n * @param b - second magnitude-parameterized rotation component.\n * @param c - third magnitude-parameterized rotation component.\n * @returns the quaternion parts: scalar part `s` and imaginary part `u` (Vec3).\n */\nexport function quatPartsFromR(a: number, b: number, c: number): { s: number; u: Vec3 } {\n  const m = a * a + b * b + c * c\n  const denom = 1 + m\n  return {\n    s: (1 - m) / denom,\n    u: [2 * a / denom, 2 * b / denom, 2 * c / denom],\n  }\n}\n\n/**\n * 用 ΔR 旋转向量 v（CQ `Rotate`，逐字实现）。\n * @param v - 待旋转向量（本地系）。\n * @param r - ΔR=(a,b,c)。\n * @returns 旋转后的向量。\n */\nexport function rotateByR(v: Vec3, r: Vec3): Vec3 {\n  const { s, u } = quatPartsFromR(r[0], r[1], r[2])\n  const uv = vdot(u, v)\n  const uu = vdot(u, u)\n  const cross = vcross(u, v)\n  return [\n    2 * uv * u[0] + (s * s - uu) * v[0] + 2 * s * cross[0],\n    2 * uv * u[1] + (s * s - uu) * v[1] + 2 * s * cross[1],\n    2 * uv * u[2] + (s * s - uu) * v[2] + 2 * s * cross[2],\n  ]\n}\n\n/**\n * 由 ΔR 生成 brepjs 序四元数 [w,x,y,z]（即 CQ 的 (s,u)）。\n * 供 `poseToAssemblyTransform` 的 SolverPose.rotation 使用。\n * @param a - first magnitude-parameterized rotation component.\n * @param b - second magnitude-parameterized rotation component.\n * @param c - third magnitude-parameterized rotation component.\n * @returns the quaternion as `[w, x, y, z]` (brepjs order).\n */\nexport function quatFromR(a: number, b: number, c: number): [number, number, number, number] {\n  const m = a * a + b * b + c * c\n  const denom = 1 + m\n  return [(1 - m) / denom, 2 * a / denom, 2 * b / denom, 2 * c / denom]\n}\n"]}

package/dist/api/assembly/solvers/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * api/assembly/solvers/types — 纯 TS global 求解器的类型与契约（P1）
+ *
+ * 设计依据：`docs/plans/2026-09-08-assembly-dual-solver.md`（B1–B10、裁定 1–6）
+ * 与 `docs/plans/2026-09-17-assembly-global-solver-plan.md`。
+ *
+ * 本模块是 pure-type / 轻量数据层，不依赖任何 vendored 或运行时单例，
+ * 供 solve.ts、global-solver.ts、compound.ts 共享。
+ */
+import type { AssemblyTransform } from '../../../runtime-state.js';
+/** 求解风格：'chain'（vendored brepjs 解析链式，默认）/ 'global'（CadQuery 兼容全局最小二乘）。 */
+export type SolverStyle = 'chain' | 'global';
+/**
+ * 求解选项（P1）：透传自 `cad.assembly({ solver })` / `AssemblyBehavior.solver`。
+ * `name` 用于 B4 锚定（assembly.py:465 `name == self.name` 锁定）→ 从 behavior.name 注入。
+ */
+export interface SolveOptions {
+    /** 默认 'chain'，向后零兼容。 */
+    solver?: SolverStyle;
+    /** 装配名（B4 锚定用；cq-compat 的 buildAssembly 注入）。 */
+    name?: string;
+}
+/**
+ * global 求解器内部的本地系标记（local-frame marker）。
+ *
+ * 与 CQ solver.py 的 marker 同义：
+ * - point：装配实体的局部坐标点；
+ * - axis：轴上一点 + 单位方向（边/圆柱面法线）；
+ * - plane：面中心 + 单位法向（face_mate / align / angle 用）。
+ *
+ * 所有坐标取自成员 Shape 的本地系（faijs Shape 不携带 placement → 本地系 == 建模系）。
+ */
+export type GlobalMarker = {
+    type: 'point';
+    p: [number, number, number];
+} | {
+    type: 'axis';
+    origin: [number, number, number];
+    dir: [number, number, number];
+} | {
+    type: 'plane';
+    center: [number, number, number];
+    normal: [number, number, number];
+};
+/** global 求解结果（与 `AssemblySolveResult` 对齐的字段集，但新增 residuals）。 */
+export interface GlobalSolveResult {
+    /** 每个被定位成员一条终态变换（pivot 恒 [0,0,0]；恒等位姿不输出）。 */
+    transforms: AssemblyTransform[];
+    /** 恒 0（数值求解不做 DOF 分析，保留字段避免 undefined）。 */
+    dof: number;
+    /** LM 终止即 true（无论残差大小；裁定 4.6）。 */
+    converged: boolean;
+    /** 仅约束类型无法映射为代价时填充。 */
+    unsupported: string[];
+    /** 逐约束最终残差（诊断，满足「绝不静默」）。 */
+    residuals: number[];
+    /** 残差超阈值（>1e-6·scale）的约束逐条写入（折中可见）。 */
+    warnings?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/assembly/solvers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE/D,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE5C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAEzF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAA;IACX,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAA;IAClB,uBAAuB;IACvB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB"}

package/dist/api/assembly/solvers/types.js

@@ -0,0 +1,11 @@
+/**
+ * api/assembly/solvers/types — 纯 TS global 求解器的类型与契约（P1）
+ *
+ * 设计依据：`docs/plans/2026-09-08-assembly-dual-solver.md`（B1–B10、裁定 1–6）
+ * 与 `docs/plans/2026-09-17-assembly-global-solver-plan.md`。
+ *
+ * 本模块是 pure-type / 轻量数据层，不依赖任何 vendored 或运行时单例，
+ * 供 solve.ts、global-solver.ts、compound.ts 共享。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/assembly/solvers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * api/assembly/solvers/types — 纯 TS global 求解器的类型与契约（P1）\n *\n * 设计依据：`docs/plans/2026-09-08-assembly-dual-solver.md`（B1–B10、裁定 1–6）\n * 与 `docs/plans/2026-09-17-assembly-global-solver-plan.md`。\n *\n * 本模块是 pure-type / 轻量数据层，不依赖任何 vendored 或运行时单例，\n * 供 solve.ts、global-solver.ts、compound.ts 共享。\n */\n\nimport type { AssemblyTransform } from '../../../runtime-state'\n\n/** 求解风格：'chain'（vendored brepjs 解析链式，默认）/ 'global'（CadQuery 兼容全局最小二乘）。 */\nexport type SolverStyle = 'chain' | 'global'\n\n/**\n * 求解选项（P1）：透传自 `cad.assembly({ solver })` / `AssemblyBehavior.solver`。\n * `name` 用于 B4 锚定（assembly.py:465 `name == self.name` 锁定）→ 从 behavior.name 注入。\n */\nexport interface SolveOptions {\n  /** 默认 'chain'，向后零兼容。 */\n  solver?: SolverStyle\n  /** 装配名（B4 锚定用；cq-compat 的 buildAssembly 注入）。 */\n  name?: string\n}\n\n/**\n * global 求解器内部的本地系标记（local-frame marker）。\n *\n * 与 CQ solver.py 的 marker 同义：\n * - point：装配实体的局部坐标点；\n * - axis：轴上一点 + 单位方向（边/圆柱面法线）；\n * - plane：面中心 + 单位法向（face_mate / align / angle 用）。\n *\n * 所有坐标取自成员 Shape 的本地系（faijs Shape 不携带 placement → 本地系 == 建模系）。\n */\nexport type GlobalMarker =\n  | { type: 'point'; p: [number, number, number] }\n  | { type: 'axis'; origin: [number, number, number]; dir: [number, number, number] }\n  | { type: 'plane'; center: [number, number, number]; normal: [number, number, number] }\n\n/** global 求解结果（与 `AssemblySolveResult` 对齐的字段集，但新增 residuals）。 */\nexport interface GlobalSolveResult {\n  /** 每个被定位成员一条终态变换（pivot 恒 [0,0,0]；恒等位姿不输出）。 */\n  transforms: AssemblyTransform[]\n  /** 恒 0（数值求解不做 DOF 分析，保留字段避免 undefined）。 */\n  dof: number\n  /** LM 终止即 true（无论残差大小；裁定 4.6）。 */\n  converged: boolean\n  /** 仅约束类型无法映射为代价时填充。 */\n  unsupported: string[]\n  /** 逐约束最终残差（诊断，满足「绝不静默」）。 */\n  residuals: number[]\n  /** 残差超阈值（>1e-6·scale）的约束逐条写入（折中可见）。 */\n  warnings?: string[]\n}\n\n"]}

package/dist/api/assembly/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * api/assembly/types — 装配约束的 faijs 侧类型（P1，方案 §5.2/§5.3）
+ *
+ * 设计约束（方案 §5.1）：
+ * - C1 可序列化：约束参数全部 JSON 安全，写进 .fai.js 文本、跨重放指认同一实体。
+ * - C4 a 是参考（reference）、b 是从动（dependent）：移动 b 去贴合 a。
+ * - C6 派生值不入库：约束对象不存 transform。
+ *
+ * 本模块是纯类型层：只依赖 naming 的 TopoRef 类型，不依赖 compound（避免循环）。
+ * FaceMateConstraint（遗留形态）也在此定义，compound.ts re-export 保持既有导出面。
+ */
+import type { PartName } from '../../identity.js';
+import type { FaceTopoRef, EdgeTopoRef } from '../../topology/naming/index.js';
+/** 3D 向量（mm）。 */
+export type AssemblyVec3 = [number, number, number];
+/**
+ * 面引用：`{ topoRef }`（首选，宿主拾取生成，跨重放稳定）或
+ * 旧快照 `{ surfaceType?, center, normal }`（兼容已持久化的历史脚本 / 手写调试）。
+ */
+export type FaceRef = {
+    topoRef: FaceTopoRef;
+} | {
+    surfaceType?: string;
+    center: AssemblyVec3;
+    normal: AssemblyVec3;
+};
+/**
+ * 边引用：`{ topoRef }`（直边 → 轴；圆边 → 轴线）或轴快照 `{ axis }`。
+ */
+export type EdgeRef = {
+    topoRef: EdgeTopoRef;
+} | {
+    axis: {
+        origin: AssemblyVec3;
+        direction: AssemblyVec3;
+    };
+};
+/**
+ * 装配实体引用（§5.2）：
+ * - 面：平面 → plane 实体；圆柱/回转面 → axis 实体（需 hint.axis）；
+ * - 边：直边/圆边 → axis 实体；
+ * - 点：局部坐标 → point 实体；
+ * - faceIndex：面序号简写（1 起，手写友好但跨拓扑变更不稳定，仅调试）。
+ */
+export type EntityRef = {
+    part: PartName;
+    face: FaceRef;
+} | {
+    part: PartName;
+    edge: EdgeRef;
+} | {
+    part: PartName;
+    point: AssemblyVec3;
+} | {
+    part: PartName;
+    faceIndex: number;
+};
+/** 面对面贴合：法向反向 + 面中心重合（遗留 face_mate 的新名；求解降级为 concentric + 轴编码）。 */
+export interface MateConstraint {
+    type: 'mate';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 同向对齐：法向同向 + 面中心重合（mate 的不翻转变体）。 */
+export interface AlignConstraint {
+    type: 'align';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 共面/共点/共线（brepjs 原生 coincident；保留面内 2 个平移 DOF）。 */
+export interface CoincidentConstraint {
+    type: 'coincident';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 轴重合（孔轴配合 / 插入；要求两侧都是轴实体）。 */
+export interface ConcentricConstraint {
+    type: 'concentric';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 定距（mm）。 */
+export interface DistanceConstraint {
+    type: 'distance';
+    value: number;
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 夹角（deg，plane-plane）。 */
+export interface AngleConstraint {
+    type: 'angle';
+    value: number;
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 平行（angle 0° 的语法糖）。 */
+export interface ParallelConstraint {
+    type: 'parallel';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 垂直（angle 90° 的语法糖）。 */
+export interface PerpendicularConstraint {
+    type: 'perpendicular';
+    a: EntityRef;
+    b: EntityRef;
+}
+/** 锚定该部件（地基）。 */
+export interface FixedConstraint {
+    type: 'fixed';
+    part: PartName;
+}
+/** 新形态约束的并集。 */
+export type StructuralConstraint = MateConstraint | AlignConstraint | CoincidentConstraint | ConcentricConstraint | DistanceConstraint | AngleConstraint | ParallelConstraint | PerpendicularConstraint | FixedConstraint;
+/**
+ * 装配约束的一个面：`{ topoRef: FaceTopoRef }`（§6.2 新形态，执行期解析几何）或
+ * 旧快照 `{ surfaceType, center, normal }`（兼容已持久化的历史脚本）。
+ */
+export type FaceMateFace = {
+    topoRef: FaceTopoRef;
+} | {
+    surfaceType?: string;
+    center: AssemblyVec3;
+    normal: AssemblyVec3;
+};
+/** A face-mate constraint aligning two faces so the moving face mates against the fixed face. */
+export interface FaceMateConstraint {
+    type: 'face_mate';
+    fixedPartName: PartName;
+    movingPartName: PartName;
+    fixedFace: FaceMateFace;
+    movingFace: FaceMateFace;
+}
+/** `cad.assembly({ constraints })` 接受的全部约束形态（遗留 + 新增）。 */
+export type AssemblyConstraint = FaceMateConstraint | StructuralConstraint;
+//# sourceMappingURL=types.d.ts.map

package/dist/api/assembly/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/types.ts"],"names":[],"mappings":"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"}

package/dist/api/assembly/types.js

@@ -0,0 +1,13 @@
+/**
+ * api/assembly/types — 装配约束的 faijs 侧类型（P1，方案 §5.2/§5.3）
+ *
+ * 设计约束（方案 §5.1）：
+ * - C1 可序列化：约束参数全部 JSON 安全，写进 .fai.js 文本、跨重放指认同一实体。
+ * - C4 a 是参考（reference）、b 是从动（dependent）：移动 b 去贴合 a。
+ * - C6 派生值不入库：约束对象不存 transform。
+ *
+ * 本模块是纯类型层：只依赖 naming 的 TopoRef 类型，不依赖 compound（避免循环）。
+ * FaceMateConstraint（遗留形态）也在此定义，compound.ts re-export 保持既有导出面。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/assembly/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/assembly/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG","sourcesContent":["/**\n * api/assembly/types — 装配约束的 faijs 侧类型（P1，方案 §5.2/§5.3）\n *\n * 设计约束（方案 §5.1）：\n * - C1 可序列化：约束参数全部 JSON 安全，写进 .fai.js 文本、跨重放指认同一实体。\n * - C4 a 是参考（reference）、b 是从动（dependent）：移动 b 去贴合 a。\n * - C6 派生值不入库：约束对象不存 transform。\n *\n * 本模块是纯类型层：只依赖 naming 的 TopoRef 类型，不依赖 compound（避免循环）。\n * FaceMateConstraint（遗留形态）也在此定义，compound.ts re-export 保持既有导出面。\n */\n\nimport type { PartName } from '../../identity'\nimport type { FaceTopoRef, EdgeTopoRef } from '../../topology/naming'\n\n/** 3D 向量（mm）。 */\nexport type AssemblyVec3 = [number, number, number]\n\n// ── 实体引用 EntityRef（§5.2）──\n\n/**\n * 面引用：`{ topoRef }`（首选，宿主拾取生成，跨重放稳定）或\n * 旧快照 `{ surfaceType?, center, normal }`（兼容已持久化的历史脚本 / 手写调试）。\n */\nexport type FaceRef =\n  | { topoRef: FaceTopoRef }\n  | { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 }\n\n/**\n * 边引用：`{ topoRef }`（直边 → 轴；圆边 → 轴线）或轴快照 `{ axis }`。\n */\nexport type EdgeRef =\n  | { topoRef: EdgeTopoRef }\n  | { axis: { origin: AssemblyVec3; direction: AssemblyVec3 } }\n\n/**\n * 装配实体引用（§5.2）：\n * - 面：平面 → plane 实体；圆柱/回转面 → axis 实体（需 hint.axis）；\n * - 边：直边/圆边 → axis 实体；\n * - 点：局部坐标 → point 实体；\n * - faceIndex：面序号简写（1 起，手写友好但跨拓扑变更不稳定，仅调试）。\n */\nexport type EntityRef =\n  | { part: PartName; face: FaceRef }\n  | { part: PartName; edge: EdgeRef }\n  | { part: PartName; point: AssemblyVec3 }\n  | { part: PartName; faceIndex: number }\n\n// ── 约束类型（§5.3 总表）──\n\n/** 面对面贴合：法向反向 + 面中心重合（遗留 face_mate 的新名；求解降级为 concentric + 轴编码）。 */\nexport interface MateConstraint {\n  type: 'mate'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 同向对齐：法向同向 + 面中心重合（mate 的不翻转变体）。 */\nexport interface AlignConstraint {\n  type: 'align'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 共面/共点/共线（brepjs 原生 coincident；保留面内 2 个平移 DOF）。 */\nexport interface CoincidentConstraint {\n  type: 'coincident'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 轴重合（孔轴配合 / 插入；要求两侧都是轴实体）。 */\nexport interface ConcentricConstraint {\n  type: 'concentric'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 定距（mm）。 */\nexport interface DistanceConstraint {\n  type: 'distance'\n  value: number\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 夹角（deg，plane-plane）。 */\nexport interface AngleConstraint {\n  type: 'angle'\n  value: number\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 平行（angle 0° 的语法糖）。 */\nexport interface ParallelConstraint {\n  type: 'parallel'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 垂直（angle 90° 的语法糖）。 */\nexport interface PerpendicularConstraint {\n  type: 'perpendicular'\n  a: EntityRef\n  b: EntityRef\n}\n\n/** 锚定该部件（地基）。 */\nexport interface FixedConstraint {\n  type: 'fixed'\n  part: PartName\n}\n\n/** 新形态约束的并集。 */\nexport type StructuralConstraint =\n  | MateConstraint\n  | AlignConstraint\n  | CoincidentConstraint\n  | ConcentricConstraint\n  | DistanceConstraint\n  | AngleConstraint\n  | ParallelConstraint\n  | PerpendicularConstraint\n  | FixedConstraint\n\n// ── 遗留形态（§2.1，规范化时改写为 mate）──\n\n/**\n * 装配约束的一个面：`{ topoRef: FaceTopoRef }`（§6.2 新形态，执行期解析几何）或\n * 旧快照 `{ surfaceType, center, normal }`（兼容已持久化的历史脚本）。\n */\nexport type FaceMateFace = { topoRef: FaceTopoRef } | {\n  surfaceType?: string\n  center: AssemblyVec3\n  normal: AssemblyVec3\n}\n\n/** A face-mate constraint aligning two faces so the moving face mates against the fixed face. */\nexport interface FaceMateConstraint {\n  type: 'face_mate'\n  fixedPartName: PartName\n  movingPartName: PartName\n  fixedFace: FaceMateFace\n  movingFace: FaceMateFace\n}\n\n/** `cad.assembly({ constraints })` 接受的全部约束形态（遗留 + 新增）。 */\nexport type AssemblyConstraint = FaceMateConstraint | StructuralConstraint\n"]}