@faicad/faijs 0.29.5 → 0.31.1

package/dist/api/geom-types/vecOps.js

@@ -0,0 +1,202 @@
+/**
+ * Pure vector operations on Vec3 tuples.
+ *
+ * 第一方模块（2026-09-25 core-decouple Phase 1）：复制自 brepjs
+ * `src/core/vecOps.ts`（同源复制，签名不变）；import 来源改为 compat 面
+ * 第一方 `types.ts`。
+ */
+// ---------------------------------------------------------------------------
+// Arithmetic
+// ---------------------------------------------------------------------------
+/** Add two 3D vectors component-wise.
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns The component-wise sum `a + b`.
+ */
+export function vecAdd(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+/** Subtract vector `b` from vector `a` component-wise.
+ *
+ * @param a - Vector to subtract from.
+ * @param b - Vector to subtract.
+ * @returns The component-wise difference `a - b`.
+ */
+export function vecSub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+/** Multiply each component of a 3D vector by a scalar.
+ *
+ * @param v - Vector to scale.
+ * @param s - Scalar multiplier.
+ * @returns The scaled vector.
+ */
+export function vecScale(v, s) {
+    return [v[0] * s, v[1] * s, v[2] * s];
+}
+/** Negate all components of a 3D vector.
+ *
+ * @param v - Vector to negate.
+ * @returns The negated vector `-v`.
+ */
+export function vecNegate(v) {
+    return [-v[0], -v[1], -v[2]];
+}
+// ---------------------------------------------------------------------------
+// Products
+// ---------------------------------------------------------------------------
+/** Compute the dot product of two 3D vectors.
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns The scalar dot product `a · b`.
+ */
+export function vecDot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** Compute the cross product of two 3D vectors.
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns The cross product `a × b`.
+ */
+export function vecCross(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]];
+}
+// ---------------------------------------------------------------------------
+// Length / distance
+// ---------------------------------------------------------------------------
+/** Compute the Euclidean length of a 3D vector.
+ *
+ * @param v - Vector to measure.
+ * @returns The Euclidean length of `v`.
+ */
+export function vecLength(v) {
+    return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+}
+/** Compute the squared length of a 3D vector (avoids a sqrt).
+ *
+ * @param v - Vector to measure.
+ * @returns The squared Euclidean length of `v`.
+ */
+export function vecLengthSq(v) {
+    return v[0] * v[0] + v[1] * v[1] + v[2] * v[2];
+}
+/** Compute the Euclidean distance between two 3D points.
+ *
+ * @param a - First point.
+ * @param b - Second point.
+ * @returns The distance `|a - b|`.
+ */
+export function vecDistance(a, b) {
+    return vecLength(vecSub(a, b));
+}
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+/** Return a unit-length vector in the same direction, or `[0,0,0]` for near-zero input.
+ *
+ * @param v - Vector to normalize.
+ * @returns A unit-length vector in the same direction, or `[0,0,0]`.
+ */
+export function vecNormalize(v) {
+    const len = vecLength(v);
+    if (len < 1e-10)
+        return [0, 0, 0];
+    return [v[0] / len, v[1] / len, v[2] / len];
+}
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+/**
+ * Test whether two 3D vectors are approximately equal.
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @param tolerance - Per-component absolute tolerance.
+ * @returns True if the vectors are approximately equal.
+ * @default tolerance `1e-5`
+ */
+export function vecEquals(a, b, tolerance = 1e-5) {
+    return (Math.abs(a[0] - b[0]) < tolerance &&
+        Math.abs(a[1] - b[1]) < tolerance &&
+        Math.abs(a[2] - b[2]) < tolerance);
+}
+/**
+ * Test whether a 3D vector is approximately zero-length.
+ *
+ * @param v - Vector to test.
+ * @param tolerance - Length threshold below which the vector is considered zero.
+ * @returns True if the vector is approximately zero-length.
+ * @default tolerance `1e-10`
+ */
+export function vecIsZero(v, tolerance = 1e-10) {
+    return vecLengthSq(v) < tolerance * tolerance;
+}
+// ---------------------------------------------------------------------------
+// Geometry
+// ---------------------------------------------------------------------------
+/**
+ * Compute the unsigned angle between two 3D vectors in **radians**.
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns Angle in `[0, PI]`, or `0` if either vector is zero-length.
+ */
+export function vecAngle(a, b) {
+    const dot = vecDot(a, b);
+    const lenA = vecLength(a);
+    const lenB = vecLength(b);
+    if (lenA < 1e-10 || lenB < 1e-10)
+        return 0;
+    const cosAngle = Math.max(-1, Math.min(1, dot / (lenA * lenB)));
+    return Math.acos(cosAngle);
+}
+/** Project vector onto plane defined by its normal
+ *
+ * @param v - Vector to project.
+ * @param planeOrigin - A point on the plane.
+ * @param planeNormal - Plane normal (need not be unit length).
+ * @returns The projection of `v` onto the plane.
+ */
+export function vecProjectToPlane(v, planeOrigin, planeNormal) {
+    const relative = vecSub(v, planeOrigin);
+    const normalLen = vecLengthSq(planeNormal);
+    if (normalLen < 1e-20)
+        return v;
+    const projection = vecScale(planeNormal, vecDot(relative, planeNormal) / normalLen);
+    return vecSub(v, projection);
+}
+/** Rotate vector around an axis by angle (radians)
+ *
+ * @param v - Vector to rotate.
+ * @param axis - Rotation axis (need not be unit length).
+ * @param angleRad - Rotation angle in radians.
+ * @returns The rotated vector.
+ */
+export function vecRotate(v, axis, angleRad) {
+    const n = vecNormalize(axis);
+    const cos = Math.cos(angleRad);
+    const sin = Math.sin(angleRad);
+    const dot = vecDot(v, n);
+    const cross = vecCross(n, v);
+    return [
+        v[0] * cos + cross[0] * sin + n[0] * dot * (1 - cos),
+        v[1] * cos + cross[1] * sin + n[1] * dot * (1 - cos),
+        v[2] * cos + cross[2] * sin + n[2] * dot * (1 - cos),
+    ];
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+const round3 = (v) => Math.round(v * 1000) / 1000;
+/** Format a Vec3 as a human-readable string rounded to 3 decimal places.
+ *
+ * @param v - Vector to format.
+ * @returns A human-readable representation of `v`.
+ */
+export function vecRepr(v) {
+    return `x: ${round3(v[0])}, y: ${round3(v[1])}, z: ${round3(v[2])}`;
+}
+//# sourceMappingURL=vecOps.js.map

package/dist/api/geom-types/vecOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vecOps.js","sourceRoot":"","sources":["../../../src/api/geom-types/vecOps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure vector operations on Vec3 tuples.\n *\n * 第一方模块（2026-09-25 core-decouple Phase 1）：复制自 brepjs\n * `src/core/vecOps.ts`（同源复制，签名不变）；import 来源改为 compat 面\n * 第一方 `types.ts`。\n */\n\nimport type { Vec3 } from './types';\n\n// ---------------------------------------------------------------------------\n// Arithmetic\n// ---------------------------------------------------------------------------\n\n/** Add two 3D vectors component-wise.\n *\n * @param a - First vector.\n * @param b - Second vector.\n * @returns The component-wise sum `a + b`.\n */\nexport function vecAdd(a: Vec3, b: Vec3): Vec3 {\n  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];\n}\n\n/** Subtract vector `b` from vector `a` component-wise.\n *\n * @param a - Vector to subtract from.\n * @param b - Vector to subtract.\n * @returns The component-wise difference `a - b`.\n */\nexport function vecSub(a: Vec3, b: Vec3): Vec3 {\n  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];\n}\n\n/** Multiply each component of a 3D vector by a scalar.\n *\n * @param v - Vector to scale.\n * @param s - Scalar multiplier.\n * @returns The scaled vector.\n */\nexport function vecScale(v: Vec3, s: number): Vec3 {\n  return [v[0] * s, v[1] * s, v[2] * s];\n}\n\n/** Negate all components of a 3D vector.\n *\n * @param v - Vector to negate.\n * @returns The negated vector `-v`.\n */\nexport function vecNegate(v: Vec3): Vec3 {\n  return [-v[0], -v[1], -v[2]];\n}\n\n// ---------------------------------------------------------------------------\n// Products\n// ---------------------------------------------------------------------------\n\n/** Compute the dot product of two 3D vectors.\n *\n * @param a - First vector.\n * @param b - Second vector.\n * @returns The scalar dot product `a · b`.\n */\nexport function vecDot(a: Vec3, b: Vec3): number {\n  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];\n}\n\n/** Compute the cross product of two 3D vectors.\n *\n * @param a - First vector.\n * @param b - Second vector.\n * @returns The cross product `a × b`.\n */\nexport function vecCross(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// ---------------------------------------------------------------------------\n// Length / distance\n// ---------------------------------------------------------------------------\n\n/** Compute the Euclidean length of a 3D vector.\n *\n * @param v - Vector to measure.\n * @returns The Euclidean length of `v`.\n */\nexport function vecLength(v: Vec3): number {\n  return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);\n}\n\n/** Compute the squared length of a 3D vector (avoids a sqrt).\n *\n * @param v - Vector to measure.\n * @returns The squared Euclidean length of `v`.\n */\nexport function vecLengthSq(v: Vec3): number {\n  return v[0] * v[0] + v[1] * v[1] + v[2] * v[2];\n}\n\n/** Compute the Euclidean distance between two 3D points.\n *\n * @param a - First point.\n * @param b - Second point.\n * @returns The distance `|a - b|`.\n */\nexport function vecDistance(a: Vec3, b: Vec3): number {\n  return vecLength(vecSub(a, b));\n}\n\n// ---------------------------------------------------------------------------\n// Normalization\n// ---------------------------------------------------------------------------\n\n/** Return a unit-length vector in the same direction, or `[0,0,0]` for near-zero input.\n *\n * @param v - Vector to normalize.\n * @returns A unit-length vector in the same direction, or `[0,0,0]`.\n */\nexport function vecNormalize(v: Vec3): Vec3 {\n  const len = vecLength(v);\n  if (len < 1e-10) return [0, 0, 0];\n  return [v[0] / len, v[1] / len, v[2] / len];\n}\n\n// ---------------------------------------------------------------------------\n// Comparison\n// ---------------------------------------------------------------------------\n\n/**\n * Test whether two 3D vectors are approximately equal.\n *\n * @param a - First vector.\n * @param b - Second vector.\n * @param tolerance - Per-component absolute tolerance.\n * @returns True if the vectors are approximately equal.\n * @default tolerance `1e-5`\n */\nexport function vecEquals(a: Vec3, b: Vec3, tolerance = 1e-5): boolean {\n  return (\n    Math.abs(a[0] - b[0]) < tolerance &&\n    Math.abs(a[1] - b[1]) < tolerance &&\n    Math.abs(a[2] - b[2]) < tolerance\n  );\n}\n\n/**\n * Test whether a 3D vector is approximately zero-length.\n *\n * @param v - Vector to test.\n * @param tolerance - Length threshold below which the vector is considered zero.\n * @returns True if the vector is approximately zero-length.\n * @default tolerance `1e-10`\n */\nexport function vecIsZero(v: Vec3, tolerance = 1e-10): boolean {\n  return vecLengthSq(v) < tolerance * tolerance;\n}\n\n// ---------------------------------------------------------------------------\n// Geometry\n// ---------------------------------------------------------------------------\n\n/**\n * Compute the unsigned angle between two 3D vectors in **radians**.\n *\n * @param a - First vector.\n * @param b - Second vector.\n * @returns Angle in `[0, PI]`, or `0` if either vector is zero-length.\n */\nexport function vecAngle(a: Vec3, b: Vec3): number {\n  const dot = vecDot(a, b);\n  const lenA = vecLength(a);\n  const lenB = vecLength(b);\n  if (lenA < 1e-10 || lenB < 1e-10) return 0;\n  const cosAngle = Math.max(-1, Math.min(1, dot / (lenA * lenB)));\n  return Math.acos(cosAngle);\n}\n\n/** Project vector onto plane defined by its normal\n *\n * @param v - Vector to project.\n * @param planeOrigin - A point on the plane.\n * @param planeNormal - Plane normal (need not be unit length).\n * @returns The projection of `v` onto the plane.\n */\nexport function vecProjectToPlane(v: Vec3, planeOrigin: Vec3, planeNormal: Vec3): Vec3 {\n  const relative = vecSub(v, planeOrigin);\n  const normalLen = vecLengthSq(planeNormal);\n  if (normalLen < 1e-20) return v;\n  const projection = vecScale(planeNormal, vecDot(relative, planeNormal) / normalLen);\n  return vecSub(v, projection);\n}\n\n/** Rotate vector around an axis by angle (radians)\n *\n * @param v - Vector to rotate.\n * @param axis - Rotation axis (need not be unit length).\n * @param angleRad - Rotation angle in radians.\n * @returns The rotated vector.\n */\nexport function vecRotate(v: Vec3, axis: Vec3, angleRad: number): Vec3 {\n  const n = vecNormalize(axis);\n  const cos = Math.cos(angleRad);\n  const sin = Math.sin(angleRad);\n  const dot = vecDot(v, n);\n  const cross = vecCross(n, v);\n\n  return [\n    v[0] * cos + cross[0] * sin + n[0] * dot * (1 - cos),\n    v[1] * cos + cross[1] * sin + n[1] * dot * (1 - cos),\n    v[2] * cos + cross[2] * sin + n[2] * dot * (1 - cos),\n  ];\n}\n\n// ---------------------------------------------------------------------------\n// Formatting\n// ---------------------------------------------------------------------------\n\nconst round3 = (v: number): number => Math.round(v * 1000) / 1000;\n\n/** Format a Vec3 as a human-readable string rounded to 3 decimal places.\n *\n * @param v - Vector to format.\n * @returns A human-readable representation of `v`.\n */\nexport function vecRepr(v: Vec3): string {\n  return `x: ${round3(v[0])}, y: ${round3(v[1])}, z: ${round3(v[2])}`;\n}\n"]}

package/dist/api/geom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geom.d.ts","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAsDhD;;;;;;;;;;;;;IAaI;AACJ,wBAAgB,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,UAAU,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE1C;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAEvC"}
+{"version":3,"file":"geom.d.ts","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAuDhD;;;;;;;;;;;;;IAaI;AACJ,wBAAgB,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAE3E;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,UAAU,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAE1C;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;;;;;;;IAWI;AACJ,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAEvC"}

package/dist/api/geom.js

@@ -8,7 +8,8 @@
  *   优先 → anchor 几何反查（兜底）→ 报错
  * - bboxCenter/bboxMin/bboxMax：mesh 包围盒查询
  */
-import { cad } from '../mesh/index.js';
+// B3 correction (2026-10-06): no library-face cad aggregate — import the impl from its own module.
+import * as meshQuery from '../mesh/query.js';
 import { getBrepApi } from '../brep/handle-bridge.js';
 import { brepOf } from '../shape.js';
 /** 内部实现：faceNormal 专用——faceOrdinal+BREP 优先 → anchor 反查 → 报错（逻辑迁移自 resolveGeomRef）。 */
@@ -51,7 +52,7 @@ function geomQuery(of, anchor, faceOrdinal) {
     if (!anchor) {
         throw new Error('[GeomRef] faceNormal requires anchor or faceOrdinal');
     }
-    const face = cad.faceAt(of, { point: anchor });
+    const face = meshQuery.faceAt(of, { point: anchor });
     if (!face) {
         throw new Error(`[GeomRef] faceAt failed for anchor at ${anchor}`);
     }
@@ -87,7 +88,7 @@ export function faceNormal(of, anchor, ordinal) {
  * const c = cad.bboxCenter(part0)
   */
 export function bboxCenter(of) {
-    return cad.bboxCenter(of);
+    return meshQuery.bboxCenter(of);
 }
 /**
  * 查询几何包围盒最小角点。
@@ -102,7 +103,7 @@ export function bboxCenter(of) {
  * const mn = cad.bboxMin(part0)
   */
 export function bboxMin(of) {
-    return cad.boundingBox(of).min;
+    return meshQuery.boundingBox(of).min;
 }
 /**
  * 查询几何包围盒最大角点。
@@ -117,6 +118,6 @@ export function bboxMin(of) {
  * const mx = cad.bboxMax(part0)
   */
 export function bboxMax(of) {
-    return cad.boundingBox(of).max;
+    return meshQuery.boundingBox(of).max;
 }
 //# sourceMappingURL=geom.js.map

package/dist/api/geom.js.map

@@ -1 +1 @@
-{"version":3,"file":"geom.js","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api geom — $geom 查询函数族（有形签名）\n *\n *\n * `cad.<feature>(of, anchor?, ordinal?)`：\n * - of 是 Shape（编译产物 `ctx.<var>` 引用），非变量名\n * - faceNormal：faceOrdinal + brepOf(of) + kernel（拓扑引用）\n *   优先 → anchor 几何反查（兜底）→ 报错\n * - bboxCenter/bboxMin/bboxMax：mesh 包围盒查询\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { brepOf } from '../shape'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 内部实现：faceNormal 专用——faceOrdinal+BREP 优先 → anchor 反查 → 报错（逻辑迁移自 resolveGeomRef）。 */\nfunction geomQuery(\n  of: Shape,\n  anchor: Vec3 | undefined,\n  faceOrdinal: number | undefined,\n): Vec3 {\n  // 优先路径：faceOrdinal 拓扑引用（BREP 路径）\n  if (faceOrdinal !== undefined) {\n    const solid = brepOf(of) as BrepHandle | undefined\n    const kernel = getBrepApi()\n    if (solid && kernel) {\n      try {\n        const faces = kernel.getSubShapes(solid, 'face')\n        if (faceOrdinal < faces.length) {\n          const face = faces[faceOrdinal]\n          // 面法向：用 surfaceNormal 在 (0.5, 0.5) 处取\n          let normal: Vec3 = [0, 0, 1]\n          try {\n            const n = kernel.surfaceNormal(face, 0.5, 0.5)\n            normal = [n.x, n.y, n.z]\n          } catch {\n            // surfaceNormal 可能对某些面失败，用默认法向\n          }\n          kernel.release(face)\n          for (let i = 0; i < faces.length; i++) {\n            if (i !== faceOrdinal) kernel.release(faces[i])\n          }\n          return normal\n        }\n        // ordinal 越界 → 释放并降级到 anchor\n        for (const f of faces) kernel.release(f)\n      } catch {\n        // BREP 取面失败 → 降级到 anchor\n      }\n    }\n  }\n\n  // 兜底路径：anchor 几何反查\n  if (!anchor) {\n    throw new Error('[GeomRef] faceNormal requires anchor or faceOrdinal')\n  }\n  const face = cad.faceAt(of, { point: anchor })\n  if (!face) {\n    throw new Error(`[GeomRef] faceAt failed for anchor at ${anchor}`)\n  }\n  return face.normal\n}\n\n/**\n * 查询面上某点（锚点）的法向。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name faceNormal\n * @returns Vec3 面上锚点处的法向 [x,y,z]。\n * @param of - 目标几何（编译产物 ctx.<var> 引用）。type:Shape required:true\n * @param anchor - 锚点（几何反查兜底）。type:[x,y,z]\n * @param ordinal - 面序号（BREP 拓扑引用优先）。type:number\n * @example\n * const n = cad.faceNormal(part0, [0, 0, 5])\n  */\nexport function faceNormal(of: Shape, anchor?: Vec3, ordinal?: number): Vec3 {\n  return geomQuery(of, anchor, ordinal)\n}\n\n/**\n * 查询几何包围盒中心。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxCenter\n * @returns Vec3 包围盒中心 [x,y,z]。交互式可编辑（参数量引用）。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const c = cad.bboxCenter(part0)\n  */\nexport function bboxCenter(of: Shape): Vec3 {\n  return cad.bboxCenter(of)\n}\n\n/**\n * 查询几何包围盒最小角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMin\n * @returns Vec3 包围盒最小角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mn = cad.bboxMin(part0)\n  */\nexport function bboxMin(of: Shape): Vec3 {\n  return cad.boundingBox(of).min\n}\n\n/**\n * 查询几何包围盒最大角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMax\n * @returns Vec3 包围盒最大角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mx = cad.bboxMax(part0)\n  */\nexport function bboxMax(of: Shape): Vec3 {\n  return cad.boundingBox(of).max\n}\n"]}
+{"version":3,"file":"geom.js","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api geom — $geom 查询函数族（有形签名）\n *\n *\n * `cad.<feature>(of, anchor?, ordinal?)`：\n * - of 是 Shape（编译产物 `ctx.<var>` 引用），非变量名\n * - faceNormal：faceOrdinal + brepOf(of) + kernel（拓扑引用）\n *   优先 → anchor 几何反查（兜底）→ 报错\n * - bboxCenter/bboxMin/bboxMax：mesh 包围盒查询\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\n// B3 correction (2026-10-06): no library-face cad aggregate — import the impl from its own module.\nimport * as meshQuery from '../mesh/query'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { brepOf } from '../shape'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 内部实现：faceNormal 专用——faceOrdinal+BREP 优先 → anchor 反查 → 报错（逻辑迁移自 resolveGeomRef）。 */\nfunction geomQuery(\n  of: Shape,\n  anchor: Vec3 | undefined,\n  faceOrdinal: number | undefined,\n): Vec3 {\n  // 优先路径：faceOrdinal 拓扑引用（BREP 路径）\n  if (faceOrdinal !== undefined) {\n    const solid = brepOf(of) as BrepHandle | undefined\n    const kernel = getBrepApi()\n    if (solid && kernel) {\n      try {\n        const faces = kernel.getSubShapes(solid, 'face')\n        if (faceOrdinal < faces.length) {\n          const face = faces[faceOrdinal]\n          // 面法向：用 surfaceNormal 在 (0.5, 0.5) 处取\n          let normal: Vec3 = [0, 0, 1]\n          try {\n            const n = kernel.surfaceNormal(face, 0.5, 0.5)\n            normal = [n.x, n.y, n.z]\n          } catch {\n            // surfaceNormal 可能对某些面失败，用默认法向\n          }\n          kernel.release(face)\n          for (let i = 0; i < faces.length; i++) {\n            if (i !== faceOrdinal) kernel.release(faces[i])\n          }\n          return normal\n        }\n        // ordinal 越界 → 释放并降级到 anchor\n        for (const f of faces) kernel.release(f)\n      } catch {\n        // BREP 取面失败 → 降级到 anchor\n      }\n    }\n  }\n\n  // 兜底路径：anchor 几何反查\n  if (!anchor) {\n    throw new Error('[GeomRef] faceNormal requires anchor or faceOrdinal')\n  }\n  const face = meshQuery.faceAt(of, { point: anchor })\n  if (!face) {\n    throw new Error(`[GeomRef] faceAt failed for anchor at ${anchor}`)\n  }\n  return face.normal\n}\n\n/**\n * 查询面上某点（锚点）的法向。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name faceNormal\n * @returns Vec3 面上锚点处的法向 [x,y,z]。\n * @param of - 目标几何（编译产物 ctx.<var> 引用）。type:Shape required:true\n * @param anchor - 锚点（几何反查兜底）。type:[x,y,z]\n * @param ordinal - 面序号（BREP 拓扑引用优先）。type:number\n * @example\n * const n = cad.faceNormal(part0, [0, 0, 5])\n  */\nexport function faceNormal(of: Shape, anchor?: Vec3, ordinal?: number): Vec3 {\n  return geomQuery(of, anchor, ordinal)\n}\n\n/**\n * 查询几何包围盒中心。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxCenter\n * @returns Vec3 包围盒中心 [x,y,z]。交互式可编辑（参数量引用）。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const c = cad.bboxCenter(part0)\n  */\nexport function bboxCenter(of: Shape): Vec3 {\n  return meshQuery.bboxCenter(of)\n}\n\n/**\n * 查询几何包围盒最小角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMin\n * @returns Vec3 包围盒最小角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mn = cad.bboxMin(part0)\n  */\nexport function bboxMin(of: Shape): Vec3 {\n  return meshQuery.boundingBox(of).min\n}\n\n/**\n * 查询几何包围盒最大角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMax\n * @returns Vec3 包围盒最大角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mx = cad.bboxMax(part0)\n  */\nexport function bboxMax(of: Shape): Vec3 {\n  return meshQuery.boundingBox(of).max\n}\n"]}

package/dist/api/half-space.d.ts

@@ -0,0 +1,56 @@
+/**
+ * api halfSpace — 无限半空间实体（平台 op engines:['occt']）
+ *
+ * @platform occt — 实现直调 occt 原生 `halfSpace(origin, normal)`（occt-wasm 有，
+ * L1 契约 `brep/engine/primitives.ts` 无对应成员）⇒ 平台 op：defineOp 声明
+ * `engines: ['occt']`（D11）。守卫 ① 要求平台 import 自证身份（本头注）；调用方
+ * op 声明 `engines` 由守卫 ② 校验。
+ *
+ * 产物形态（实测，见 `test/api/occt-s3-capability-probes.test.ts` 的 A/B/C 三例）：
+ * 半空间是**无界实体**——它有有限的面（一张平面）+ 无界的「其余边界」，三角化
+ * 后**面载荷为空**（`positions.length === 0`），这是该几何的真值，不是失败。
+ * 它唯一的用途是**作无界布尔工具**：
+ *   `kernel.cut(makeBox(10,10,10), halfSpace({z:5},{z:1}))` → 体积 500、z ∈ [0,5]。
+ *
+ * 因此在脚本面它是「布尔工具发生器」：`cad.cut(part0, cad.halfSpace(...))`。
+ * 单独渲染它没有意义（空 mesh），单独导出 STEP 会得到无界体。
+ *
+ * 血缘：半空间没有面角色词汇（其面不来自任何输入面）⇒ `naming: unmodeled` + reason
+ * （方案 §4.2 表列此项）。
+ *
+ * 与既有 op 的边界（方案 §4.5 去重表）：`sectionByPlane` / `splitByPlane` 是**以平面
+ * 切割/求交**的中立 op；`halfSpace` 产**实体**、不作切割动作，二者不可互替——
+ * `halfSpace` 可喂给 `cut` / `common` / `split` 的任意工具位（包含 split 工具位）。
+ */
+import type { Shape } from '../mesh/types.js';
+type Vec3 = [number, number, number];
+/** `cad.halfSpace` 参数。 */
+export interface HalfSpaceParams {
+    /** 边界平面上的一点 `[x, y, z]`（mm）。半空间从该平面沿 `normal` 方向张开。 */
+    origin: Vec3;
+    /** 边界平面法向 `[x, y, z]`（不必单位化；零向量非法）。保留侧 = 法向所指一侧。 */
+    normal: Vec3;
+}
+/**
+ * 构造无限半空间实体（无界布尔工具）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name halfSpace
+ * @note 平台 op：仅 occt 引擎（原生 halfSpace，L1 契约无对应成员）。非 occt 引擎
+ *       执行前报错；brep_mock 不拦截。产物是**无界实体**：面载荷为空（无有限面可
+ *       离散），单独渲染无意义，用法是喂给布尔 op 作工具
+ *       （`cad.cut(part0, cad.halfSpace({ origin: [0,0,5], normal: [0,0,1] }))` 切出 z<=5 的一半）。
+ * @returns Shape 无限半空间实体（brep 句柄有效、mesh 为空）。
+ * @param params.origin - 边界平面上一点 [x,y,z]（mm）。type:Vec3 required:true
+ * @param params.normal - 边界平面法向 [x,y,z]（非零；保留侧 = 法向所指侧）。type:Vec3 required:true
+ * @example
+ * const half = cad.halfSpace({ origin: [0, 0, 5], normal: [0, 0, 1] })
+ * const lower = cad.cut(part0, half)
+ */
+export declare const halfSpace: ((params: HalfSpaceParams) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+export {};
+//# sourceMappingURL=half-space.d.ts.map

package/dist/api/half-space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"half-space.d.ts","sourceRoot":"","sources":["../../src/api/half-space.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEpC,0BAA0B;AAC1B,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,MAAM,EAAE,IAAI,CAAA;IACZ,oDAAoD;IACpD,MAAM,EAAE,IAAI,CAAA;CACb;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;;CAWpB,CAAA"}

package/dist/api/half-space.js

@@ -0,0 +1,82 @@
+/**
+ * api halfSpace — 无限半空间实体（平台 op engines:['occt']）
+ *
+ * @platform occt — 实现直调 occt 原生 `halfSpace(origin, normal)`（occt-wasm 有，
+ * L1 契约 `brep/engine/primitives.ts` 无对应成员）⇒ 平台 op：defineOp 声明
+ * `engines: ['occt']`（D11）。守卫 ① 要求平台 import 自证身份（本头注）；调用方
+ * op 声明 `engines` 由守卫 ② 校验。
+ *
+ * 产物形态（实测，见 `test/api/occt-s3-capability-probes.test.ts` 的 A/B/C 三例）：
+ * 半空间是**无界实体**——它有有限的面（一张平面）+ 无界的「其余边界」，三角化
+ * 后**面载荷为空**（`positions.length === 0`），这是该几何的真值，不是失败。
+ * 它唯一的用途是**作无界布尔工具**：
+ *   `kernel.cut(makeBox(10,10,10), halfSpace({z:5},{z:1}))` → 体积 500、z ∈ [0,5]。
+ *
+ * 因此在脚本面它是「布尔工具发生器」：`cad.cut(part0, cad.halfSpace(...))`。
+ * 单独渲染它没有意义（空 mesh），单独导出 STEP 会得到无界体。
+ *
+ * 血缘：半空间没有面角色词汇（其面不来自任何输入面）⇒ `naming: unmodeled` + reason
+ * （方案 §4.2 表列此项）。
+ *
+ * 与既有 op 的边界（方案 §4.5 去重表）：`sectionByPlane` / `splitByPlane` 是**以平面
+ * 切割/求交**的中立 op；`halfSpace` 产**实体**、不作切割动作，二者不可互替——
+ * `halfSpace` 可喂给 `cut` / `common` / `split` 的任意工具位（包含 split 工具位）。
+ */
+import { solidToShape } from '../brep/brep-ops.js';
+import { getBrepApi } from '../brep/handle-bridge.js';
+import { fromBrep } from '../shape.js';
+import { defineOp } from '../sdk.js';
+import { getOcctKernel } from '../occt-kernel/occtKernel.js';
+/** 元组 → BrepVec3 对象（同 sectionByPlane：L1/原生向量形参是 {x,y,z} 对象）。 */
+function toVec3(v, which) {
+    if (!Array.isArray(v) ||
+        v.length !== 3 ||
+        v.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        throw new Error(`E_HALF_SPACE_BAD_${which.toUpperCase()}: ${which} must be [x,y,z] finite numbers`);
+    }
+    if (which === 'normal' && v[0] === 0 && v[1] === 0 && v[2] === 0) {
+        throw new Error('E_HALF_SPACE_BAD_NORMAL: normal must be a non-zero vector (it defines the plane)');
+    }
+    return { x: v[0], y: v[1], z: v[2] };
+}
+/** BREP 路径：occt 原生 halfSpace → 无界实体（空 mesh）经 fromBrep 收养句柄。 */
+function halfSpaceBrep(params) {
+    const { origin, normal } = params ?? {};
+    const o = toVec3(origin, 'origin');
+    const n = toVec3(normal, 'normal');
+    const kernel = getBrepApi();
+    // 实测（探针 A）：无限半空间可被 `meshShape` 三角化，不抛错，产出空面载荷。
+    const handle = getOcctKernel().halfSpace(o, n);
+    return fromBrep(solidToShape(kernel, handle), { solid: handle });
+}
+/**
+ * 构造无限半空间实体（无界布尔工具）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name halfSpace
+ * @note 平台 op：仅 occt 引擎（原生 halfSpace，L1 契约无对应成员）。非 occt 引擎
+ *       执行前报错；brep_mock 不拦截。产物是**无界实体**：面载荷为空（无有限面可
+ *       离散），单独渲染无意义，用法是喂给布尔 op 作工具
+ *       （`cad.cut(part0, cad.halfSpace({ origin: [0,0,5], normal: [0,0,1] }))` 切出 z<=5 的一半）。
+ * @returns Shape 无限半空间实体（brep 句柄有效、mesh 为空）。
+ * @param params.origin - 边界平面上一点 [x,y,z]（mm）。type:Vec3 required:true
+ * @param params.normal - 边界平面法向 [x,y,z]（非零；保留侧 = 法向所指侧）。type:Vec3 required:true
+ * @example
+ * const half = cad.halfSpace({ origin: [0, 0, 5], normal: [0, 0, 1] })
+ * const lower = cad.cut(part0, half)
+ */
+export const halfSpace = defineOp({
+    name: 'halfSpace',
+    paramDims: { 'params.origin': 'length', 'params.normal': 'length' },
+    brep(params) {
+        return halfSpaceBrep(params);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'unbounded half-space has no source-derived face role vocabulary',
+    },
+});
+//# sourceMappingURL=half-space.js.map

package/dist/api/half-space.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"half-space.js","sourceRoot":"","sources":["../../src/api/half-space.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAYzD,gEAAgE;AAChE,SAAS,MAAM,CAAC,CAAO,EAAE,KAA0B;IACjD,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACjB,CAAC,CAAC,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC3D,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,iCAAiC,CAAC,CAAA;IACrG,CAAC;IACD,IAAI,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAA;IACrG,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACtC,CAAC;AAED,+DAA+D;AAC/D,SAAS,aAAa,CAAC,MAAuB;IAC5C,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAK,EAAsB,CAAA;IAC5D,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAClC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,+CAA+C;IAC/C,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAA0B,CAAA;IACvE,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAU,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,IAAI,EAAE,WAAW;IACjB,SAAS,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE;IACnE,IAAI,CAAC,MAAuB;QAC1B,OAAO,aAAa,CAAC,MAAM,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE;QACN,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,iEAAiE;KAC5D;CAChB,CAAC,CAAA","sourcesContent":["/**\n * api halfSpace — 无限半空间实体（平台 op engines:['occt']）\n *\n * @platform occt — 实现直调 occt 原生 `halfSpace(origin, normal)`（occt-wasm 有，\n * L1 契约 `brep/engine/primitives.ts` 无对应成员）⇒ 平台 op：defineOp 声明\n * `engines: ['occt']`（D11）。守卫 ① 要求平台 import 自证身份（本头注）；调用方\n * op 声明 `engines` 由守卫 ② 校验。\n *\n * 产物形态（实测，见 `test/api/occt-s3-capability-probes.test.ts` 的 A/B/C 三例）：\n * 半空间是**无界实体**——它有有限的面（一张平面）+ 无界的「其余边界」，三角化\n * 后**面载荷为空**（`positions.length === 0`），这是该几何的真值，不是失败。\n * 它唯一的用途是**作无界布尔工具**：\n *   `kernel.cut(makeBox(10,10,10), halfSpace({z:5},{z:1}))` → 体积 500、z ∈ [0,5]。\n *\n * 因此在脚本面它是「布尔工具发生器」：`cad.cut(part0, cad.halfSpace(...))`。\n * 单独渲染它没有意义（空 mesh），单独导出 STEP 会得到无界体。\n *\n * 血缘：半空间没有面角色词汇（其面不来自任何输入面）⇒ `naming: unmodeled` + reason\n * （方案 §4.2 表列此项）。\n *\n * 与既有 op 的边界（方案 §4.5 去重表）：`sectionByPlane` / `splitByPlane` 是**以平面\n * 切割/求交**的中立 op；`halfSpace` 产**实体**、不作切割动作，二者不可互替——\n * `halfSpace` 可喂给 `cut` / `common` / `split` 的任意工具位（包含 split 工具位）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle, BrepVec3 } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\ntype Vec3 = [number, number, number]\n\n/** `cad.halfSpace` 参数。 */\nexport interface HalfSpaceParams {\n  /** 边界平面上的一点 `[x, y, z]`（mm）。半空间从该平面沿 `normal` 方向张开。 */\n  origin: Vec3\n  /** 边界平面法向 `[x, y, z]`（不必单位化；零向量非法）。保留侧 = 法向所指一侧。 */\n  normal: Vec3\n}\n\n/** 元组 → BrepVec3 对象（同 sectionByPlane：L1/原生向量形参是 {x,y,z} 对象）。 */\nfunction toVec3(v: Vec3, which: 'origin' | 'normal'): BrepVec3 {\n  if (\n    !Array.isArray(v) ||\n    v.length !== 3 ||\n    v.some((n) => typeof n !== 'number' || !Number.isFinite(n))\n  ) {\n    throw new Error(`E_HALF_SPACE_BAD_${which.toUpperCase()}: ${which} must be [x,y,z] finite numbers`)\n  }\n  if (which === 'normal' && v[0] === 0 && v[1] === 0 && v[2] === 0) {\n    throw new Error('E_HALF_SPACE_BAD_NORMAL: normal must be a non-zero vector (it defines the plane)')\n  }\n  return { x: v[0], y: v[1], z: v[2] }\n}\n\n/** BREP 路径：occt 原生 halfSpace → 无界实体（空 mesh）经 fromBrep 收养句柄。 */\nfunction halfSpaceBrep(params: HalfSpaceParams): Shape {\n  const { origin, normal } = params ?? ({} as HalfSpaceParams)\n  const o = toVec3(origin, 'origin')\n  const n = toVec3(normal, 'normal')\n  const kernel = getBrepApi()\n  // 实测（探针 A）：无限半空间可被 `meshShape` 三角化，不抛错，产出空面载荷。\n  const handle = getOcctKernel().halfSpace(o, n) as unknown as BrepHandle\n  return fromBrep(solidToShape(kernel, handle), { solid: handle }) as Shape\n}\n\n/**\n * 构造无限半空间实体（无界布尔工具）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name halfSpace\n * @note 平台 op：仅 occt 引擎（原生 halfSpace，L1 契约无对应成员）。非 occt 引擎\n *       执行前报错；brep_mock 不拦截。产物是**无界实体**：面载荷为空（无有限面可\n *       离散），单独渲染无意义，用法是喂给布尔 op 作工具\n *       （`cad.cut(part0, cad.halfSpace({ origin: [0,0,5], normal: [0,0,1] }))` 切出 z<=5 的一半）。\n * @returns Shape 无限半空间实体（brep 句柄有效、mesh 为空）。\n * @param params.origin - 边界平面上一点 [x,y,z]（mm）。type:Vec3 required:true\n * @param params.normal - 边界平面法向 [x,y,z]（非零；保留侧 = 法向所指侧）。type:Vec3 required:true\n * @example\n * const half = cad.halfSpace({ origin: [0, 0, 5], normal: [0, 0, 1] })\n * const lower = cad.cut(part0, half)\n */\nexport const halfSpace = defineOp({\n  name: 'halfSpace',\n  paramDims: { 'params.origin': 'length', 'params.normal': 'length' },\n  brep(params: HalfSpaceParams) {\n    return halfSpaceBrep(params)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'unbounded half-space has no source-derived face role vocabulary',\n  } as Provenance,\n})\n"]}

package/dist/api/helix.d.ts

@@ -9,12 +9,14 @@
  *
  * 设计：
  * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。
- *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。
+ *   实现直连平台原生方法，能力由引擎身份本身界定（无第二个声明轴）。
  * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。
  * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3
  *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。
  */
 import type { Shape } from '../mesh/types.js';
+/** 螺旋手性：`'right'`（右手，逆时针上旋）或 `'left'`（左手，顺时针上旋）。 */
+export type HelixHanded = 'right' | 'left';
 /** `cad.helix` 参数。 */
 export interface HelixOptions {
     /** 螺旋半径（mm，>0）。 */
@@ -27,6 +29,11 @@ export interface HelixOptions {
     axis?: [number, number, number];
     /** 起点（默认原点）。 */
     origin?: [number, number, number];
+    /**
+     * 手性（默认 `'right'`）。同 pitch/height/radius 下左右旋互为镜像。
+     * `'right'` 走 `makeHelixWire`，`'left'` 走 `makeHelixWireHanded(..., true)`。
+     */
+    handed?: HelixHanded;
 }
 /**
  * 构造螺旋线（1D 曲线）。
@@ -35,15 +42,17 @@ export interface HelixOptions {
  * @async false
  * @qual ok
  * @name helix
- * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @note 平台 op：仅 occt 引擎（原生 makeHelixWire / makeHelixWireHanded）。非 occt 引擎执行前报错；brep_mock 不拦截。
  * @returns Shape 1D 螺旋线（kind:'curve'）。
  * @param options.radius - 螺旋半径（mm，>0）。type:number required:true
  * @param options.pitch - 螺距（mm，≠0）。type:number required:true
  * @param options.turns - 圈数（>0）。type:number required:true
  * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false
  * @param options.origin - 起点（默认原点）。type:Vec3 required:false
+ * @param options.handed - 手性：'right'（默认）或 'left'。type:HelixHanded required:false
  * @example
  * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })
+ * const lh = cad.helix({ radius: 5, pitch: 2, turns: 3, handed: 'left' })
  */
 export declare const helix: ((opts: HelixOptions) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

package/dist/api/helix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helix.d.ts","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,sBAAsB;AACtB,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc;IACd,KAAK,EAAE,MAAM,CAAA;IACb,yBAAyB;IACzB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,gBAAgB;IAChB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAuBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK;;CAMhB,CAAA"}
+{"version":3,"file":"helix.d.ts","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAA;AAE1C,sBAAsB;AACtB,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc;IACd,KAAK,EAAE,MAAM,CAAA;IACb,yBAAyB;IACzB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,gBAAgB;IAChB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK;;CAWhB,CAAA"}

package/dist/api/helix.js

@@ -9,7 +9,7 @@
  *
  * 设计：
  * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。
- *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。
+ *   实现直连平台原生方法，能力由引擎身份本身界定（无第二个声明轴）。
  * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。
  * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3
  *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。
@@ -19,7 +19,7 @@ import { getBrepApi } from '../brep/handle-bridge.js';
 import { fromBrepCurve } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { getOcctKernel } from '../occt-kernel/occtKernel.js';
-/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */
+/** BREP 路径：用 occt 原生 makeHelixWire / makeHelixWireHanded 构造螺旋线，登记 1D 句柄。 */
 function helixBrep(opts) {
     const { radius, pitch, turns } = opts;
     if (!(radius > 0))
@@ -28,12 +28,21 @@ function helixBrep(opts) {
         throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero');
     if (!(turns > 0))
         throw new Error('E_HELIX_BAD_TURNS: turns must be > 0');
+    const handed = opts.handed ?? 'right';
+    if (handed !== 'right' && handed !== 'left') {
+        throw new Error(`E_HELIX_BAD_HANDED: handed must be 'right' or 'left' (got '${String(handed)}')`);
+    }
     const axis = opts.axis ?? [0, 0, 1];
     const origin = opts.origin ?? [0, 0, 0];
     const height = pitch * turns;
     const kernel = getBrepApi();
     const occt = getOcctKernel();
-    const handle = occt.makeHelixWire({ x: origin[0], y: origin[1], z: origin[2] }, { x: axis[0], y: axis[1], z: axis[2] }, pitch, height, radius);
+    const o = { x: origin[0], y: origin[1], z: origin[2] };
+    const a = { x: axis[0], y: axis[1], z: axis[2] };
+    // 右手默认沿用 makeHelixWire（保持两个原生入口都可达）；左手走带手性的显式入口。
+    const handle = (handed === 'left'
+        ? occt.makeHelixWireHanded(o, a, pitch, height, radius, true)
+        : occt.makeHelixWire(o, a, pitch, height, radius));
     return fromBrepCurve(solidToShape(kernel, handle), { solid: handle });
 }
 /**
@@ -43,17 +52,24 @@ function helixBrep(opts) {
  * @async false
  * @qual ok
  * @name helix
- * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @note 平台 op：仅 occt 引擎（原生 makeHelixWire / makeHelixWireHanded）。非 occt 引擎执行前报错；brep_mock 不拦截。
  * @returns Shape 1D 螺旋线（kind:'curve'）。
  * @param options.radius - 螺旋半径（mm，>0）。type:number required:true
  * @param options.pitch - 螺距（mm，≠0）。type:number required:true
  * @param options.turns - 圈数（>0）。type:number required:true
  * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false
  * @param options.origin - 起点（默认原点）。type:Vec3 required:false
+ * @param options.handed - 手性：'right'（默认）或 'left'。type:HelixHanded required:false
  * @example
  * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })
+ * const lh = cad.helix({ radius: 5, pitch: 2, turns: 3, handed: 'left' })
  */
 export const helix = defineOp({
+    // name 必填：① 引擎门文案携带 op 名（`op 'helix' requires engine occt`，见
+    // test/api/sweep-loft.test.ts GOTCHA-3 对该形态的要求）；② occt op 覆盖率扫描器
+    // 的 op 全集只收 `export const X = defineOp({ name: '…' })`——缺 name 的 op
+    // 不可见，其直调的 occt 方法（makeHelixWireHanded）会被误判为「未接入」。
+    name: 'helix',
     brep(opts) {
         return helixBrep(opts);
     },

package/dist/api/helix.js.map

@@ -1 +1 @@
-{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAgBzD,sDAAsD;AACtD,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAC/B,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAC5C,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EACtC,KAAK,EACL,MAAM,EACN,MAAM,CACkB,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = occt.makeHelixWire(\n    { x: origin[0], y: origin[1], z: origin[2] },\n    { x: axis[0], y: axis[1], z: axis[2] },\n    pitch,\n    height,\n    radius,\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n */\nexport const helix = defineOp({\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}
+{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAwBzD,4EAA4E;AAC5E,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAA;IACrC,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,8DAA8D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnG,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACtD,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAChD,iDAAiD;IACjD,MAAM,MAAM,GAAG,CACb,MAAM,KAAK,MAAM;QACf,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAC3B,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,6DAA6D;IAC7D,iEAAiE;IACjE,oEAAoE;IACpE,mDAAmD;IACnD,IAAI,EAAE,OAAO;IACb,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   实现直连平台原生方法，能力由引擎身份本身界定（无第二个声明轴）。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** 螺旋手性：`'right'`（右手，逆时针上旋）或 `'left'`（左手，顺时针上旋）。 */\nexport type HelixHanded = 'right' | 'left'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n  /**\n   * 手性（默认 `'right'`）。同 pitch/height/radius 下左右旋互为镜像。\n   * `'right'` 走 `makeHelixWire`，`'left'` 走 `makeHelixWireHanded(..., true)`。\n   */\n  handed?: HelixHanded\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire / makeHelixWireHanded 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const handed = opts.handed ?? 'right'\n  if (handed !== 'right' && handed !== 'left') {\n    throw new Error(`E_HELIX_BAD_HANDED: handed must be 'right' or 'left' (got '${String(handed)}')`)\n  }\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const o = { x: origin[0], y: origin[1], z: origin[2] }\n  const a = { x: axis[0], y: axis[1], z: axis[2] }\n  // 右手默认沿用 makeHelixWire（保持两个原生入口都可达）；左手走带手性的显式入口。\n  const handle = (\n    handed === 'left'\n      ? occt.makeHelixWireHanded(o, a, pitch, height, radius, true)\n      : occt.makeHelixWire(o, a, pitch, height, radius)\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire / makeHelixWireHanded）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @param options.handed - 手性：'right'（默认）或 'left'。type:HelixHanded required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n * const lh = cad.helix({ radius: 5, pitch: 2, turns: 3, handed: 'left' })\n */\nexport const helix = defineOp({\n  // name 必填：① 引擎门文案携带 op 名（`op 'helix' requires engine occt`，见\n  // test/api/sweep-loft.test.ts GOTCHA-3 对该形态的要求）；② occt op 覆盖率扫描器\n  // 的 op 全集只收 `export const X = defineOp({ name: '…' })`——缺 name 的 op\n  // 不可见，其直调的 occt 方法（makeHelixWireHanded）会被误判为「未接入」。\n  name: 'helix',\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}