@faicad/faijs 0.33.1 → 0.35.2

package/dist/brepkit-kernel/brepkitKernel.js

@@ -9,7 +9,7 @@
  * `api/surface/engine-method-map.json` 的 aligned/dialect 条目）。brepkit 独有
  * 能力（chamfer2d/chamferV2/filletV2/sketch* 族、serializeSolid、meshBoolean、
  * minkowskiSum …）与单方语义（loft、平面 section/split 之外的 splitter 语义…）
- * 都不在本对象里——平台代码经原生面 `getBrepkitKernel()`（D3）访问。
+ * 都不在本对象里——平台代码经原生面 `getBrepKitKernel()`（D3）访问。
  *
  * 设计要点（对应 3d_editor 项目的 weapp-voice-ai-modeling 设计计划 §5）：
  * - 句柄：brepkit u32 句柄与 faijs BrepHandle(number) 同构，直通零转换；
@@ -68,6 +68,19 @@ const withKind = (kind, n) => {
     }
 };
 const arr = (x) => Array.from(x);
+/**
+ * L1 向量形参的静态校验：`BrepVec3 = {x,y,z}` **对象**，不是元组、更不是布尔。
+ *
+ * 包侧旧口径（`loft(wires, isSolid?, ruled?)` 之类）会把标量/布尔塞进向量位，进内核
+ * 后只剩一句无指向的 wasm 报错（实测 `cannot normalize zero vector`）。编译期管不住的
+ * 调用点（跨包 `as unknown as` 注入）在此静态判一次，给可指路的错误。
+ */
+const isBrepVec3 = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return typeof o.x === 'number' && typeof o.y === 'number' && typeof o.z === 'number';
+};
 /** 适配器内部的显式失败（替代旧 unsupported 桩：能力缺失一律在静态判定拦截，不在实现体里伪装）。 */
 function fail(detail) {
     throw new Error(`[brepkit-kernel] ${detail}`);
@@ -331,6 +344,12 @@ export async function createBrepkitPrimitives() {
     const derivedFaces = new Set();
     // 虚拟 compound 句柄计数器（非实体子句柄不进内核 makeCompound，见 makeCompound GOTCHA）。
     const knownCompounds = new Map();
+    // 虚拟 compound 句柄 → 真内核 compound 句柄（exportStep 等 IO 需要真句柄；几何分发全走虚拟句柄）。
+    // 2026-10-13：brepkit 句柄按**类型分命名空间**（同文件 356 行 GOTCHA），compound 命名空间从 0 计数，
+    // 与 solid 命名空间**重号**（实测 5 成员 solid [0..4] 的 compound 句柄 = 0）——knownCompounds 以
+    // 内核句柄为 key 会在「查询同号的另一 solid」时误判成 compound（textToSolid 'Hello' translate 后
+    // 只剩 1 成员即此：copySolid(0) 被当成员 solid 复制）。故 compound 一律用 0x20000000+ 虚拟句柄。
+    const kernelCompoundHandles = new Map();
     let virtualCompoundCounter = 0;
     // GOTCHA（2026-09-26）：brepkit 句柄按**类型分命名空间**——solid/face/wire/edge 各自从 0 计数
     // （实测 edge=wire=face=solid=0 可共存）。因此「某编号 N 在 knownFaces」与「某编号 N 是 solid」
@@ -554,8 +573,41 @@ export async function createBrepkitPrimitives() {
         }
         return markSolid(kernel.copySolid(shape));
     };
-    /** 深拷贝 + 原地仿射变换（matrix 已经 toKernelMatrix 归一为 16 元素 4×4）。 */
+    /** 成员句柄数组 → compound（solid-only 内核直通；face/wire/edge 混合走虚拟句柄）。
+     *  makeCompound 适配器与 cloneAndTransform 的 compound 分支共用（同一分发逻辑一份）。
+     *
+     *  GOTCHA（2026-10-13）：**所有** compound 一律返回虚拟句柄（0x20000000+）——brepkit
+     *  的 compound 句柄与 solid 句柄**分命名空间且可重号**（见 356 行 GOTCHA：实测成员
+     *  [0..4] 的 compound 内核句柄 = 0），knownCompounds 若以内核句柄为 key，查询同号的
+     *  另一 solid 时会误判成 compound（'Hello' translate 后只剩 1 成员的根因）。真内核
+     *  compound 句柄仅保留在 kernelCompoundHandles，供 exportStep 等 IO 使用。 */
+    const compoundOf = (kids) => {
+        virtualCompoundCounter++;
+        const v = 0x20000000 + virtualCompoundCounter;
+        const hasNonSolid = kids.some((k) => knownFaces.has(k) || knownWires.has(k) || knownEdges.has(k) || knownCompounds.has(k));
+        if (!hasNonSolid) {
+            const c = kernel.makeCompound(Int32Array.from(kids));
+            kernelCompoundHandles.set(v, c);
+        }
+        knownCompounds.set(v, kids);
+        return v;
+    };
+    /**
+     * 深拷贝 + 原地仿射变换（matrix 已经 toKernelMatrix 归一为 16 元素 4×4）。
+     *
+     * compound 分支（2026-10-13 修复）：brepkit 的 copySolid/transformSolid 只吃
+     * **solid** 句柄——整体传 compound 会静默丢成员（实测 textToSolid 的 'Hello'
+     * 5 成员 compound 经 translate 居中后只剩 1 个，真机 3D 文字只剩最后一个字符）。
+     * 必须逐成员深拷贝 + 变换后再 compoundOf 重组。
+     */
     const cloneAndTransform = (shape, matrix16, kind = KIND_SOLID) => {
+        const kids = knownCompounds.get(shape);
+        if (kids) {
+            // kids 是裸句柄号（无类型标签，kindOf 恒 0）；子成员类型由 cloneShape 的
+            // knownFaces/knownWires 集合兜底分发（集合 key 即裸号），故递归传默认 kind。
+            const t = kids.map((k) => cloneAndTransform(k, matrix16));
+            return compoundOf(t);
+        }
         const c = cloneShape(shape, kind);
         const m = Float64Array.from(matrix16);
         if (kind === KIND_FACE || knownFaces.has(c))
@@ -707,12 +759,12 @@ export async function createBrepkitPrimitives() {
             return asHandle(markSolid(kernel.extrude(s, dx / len, dy / len, dz / len, len)));
         },
         revolveVec(shape, center, direction, angleDeg) {
-            // 方言归一：brepkit revolve 只吃 face（与 extrude 同族断言）。
-            const s = asNum(shape);
-            if (!knownFaces.has(s)) {
-                fail('revolveVec requires a face input; got a handle that is not a known face');
-            }
-            return asHandle(markSolid(kernel.revolve(s, center.x, center.y, center.z, direction.x, direction.y, direction.z, angleDeg)));
+            // 方言归一（与 sweep / loft 同款）：brepkit 原生 revolve 只吃 face，而 L1 调用方
+            // 传的是**闭合轮廓 wire**（如 faijs-fasteners 的 revolveProfile 直传 wire）；
+            // occt 侧原生 revolve 两者都吃。方言在适配器消化：wire → makeFaceFromWire 升面，
+            // 升面失败（开口 wire）由内核报错，不在适配器预判（与 sweep 同一纪律）。
+            const faceNum = profileFaceOf(shape, 'revolveVec');
+            return asHandle(markSolid(kernel.revolve(faceNum, center.x, center.y, center.z, direction.x, direction.y, direction.z, angleDeg)));
         },
         sweep(profile, spine) {
             // L1 中立 sweep：occt 侧走 sweepPipeShell；brepkit 只吃 (face, 路径 edge)
@@ -730,19 +782,21 @@ export async function createBrepkitPrimitives() {
             }
             // ① 各截面 → face。
             const faces = sections.map((s) => profileFaceOf(s, 'loft'));
-            // ② brepkit loft 要求各截面**顶点数一致**。内核自己也会抛，但报错不含「哪几个
-            //    截面、差多少」——执行前静态判一次，给出可指路的错误；不静默降级、不换引擎
-            //    （方案 §5②，红线：静态可判的输入约束必须在执行前报错）。
-            const counts = faces.map((f) => arr(kernel.getFaceVertices(f)).length);
-            const ref = counts[0];
-            if (counts.some((c) => c !== ref)) {
-                fail('E_LOFT_SECTION_MISMATCH: brepkit loft requires every section to have the same ' +
-                    `vertex count, got [${counts.join(', ')}] — use cad.loftAdvanced (occt) for ` +
-                    'sections with different vertex counts');
-            }
+            // ② 顶点数不一致的截面（如圆 → 方）直接放行：brepkit 内核
+            //    （operations/loft.rs）会把所有截面重采样到最大顶点数再蒙皮，
+            //    wasm 绑定层无额外校验。不再执行前拦截（原 E_LOFT_SECTION_MISMATCH
+            //    门禁已移除，2026-10-14）。
             const farr = Uint32Array.from(faces);
             // ③ 选项映射：endPoint → loftWithOptions；ruled=false → loftSmooth。
             if (endPoint !== undefined) {
+                // 契约守卫：L1 的第三参是 `endPoint: BrepVec3`，而包侧旧口径是
+                // `loft(wires, isSolid?, ruled?)`（faijs-gears `kernel/gears.ts` 的
+                // `loft(wires, false, false)` 即如此）。布尔量落进 endPoint 位后会一路进内核，
+                // 只得到一句无指向的 wasm 报错（实测 `cannot normalize zero vector`）——
+                // 静态可判的输入约束必须在执行前显式失败（方案 §5② 红线），不进内核猜。
+                if (!isBrepVec3(endPoint)) {
+                    fail(`E_LOFT_BAD_ENDPOINT: loft endPoint must be a BrepVec3 ({x,y,z}), got ${JSON.stringify(endPoint)}`);
+                }
                 return asHandle(markSolid(kernel.loftWithOptions(farr, JSON.stringify({ ruled, endPoint: [endPoint.x, endPoint.y, endPoint.z] }))));
             }
             return asHandle(markSolid(ruled ? kernel.loft(farr) : kernel.loftSmooth(farr)));
@@ -761,6 +815,38 @@ export async function createBrepkitPrimitives() {
         hullFromPoints(points, _tolerance) {
             return asHandle(markSolid(kernel.convexHull(flattenPoints(points))));
         },
+        // ── 样条面 / 体构造补缺（2026-10-13 进 L1）──
+        bsplineSurface(points, rows, cols) {
+            // §7 决策点 1 选**插值**（interpolateSurface）：L1 语义锚是 occt 的过点
+            // GeomAPI_PointsToBSplineSurface。不用 approximateSurfaceLspia——那是逼近，语义不同。
+            // 阶数：brepkit 要求 degree < 该方向点数，缺省 3 并夹紧（点少时降阶，不崩）。
+            const degU = Math.max(1, Math.min(3, rows - 1));
+            const degV = Math.max(1, Math.min(3, cols - 1));
+            if (points.length !== rows * cols) {
+                fail(`bsplineSurface: expected ${rows * cols} points (${rows}×${cols}), got ${points.length}`);
+            }
+            const f = kernel.interpolateSurface(flattenPoints(points), rows, cols, degU, degV);
+            knownFaces.add(f);
+            return asFace(f);
+        },
+        makeSolid(shell) {
+            const n = asNum(shell);
+            // 方言归一：brepkit 的 revolve / extrude / loft 已直接产出实体（markSolid 登记），
+            // 而 occt 的 revolve 产 shell、须 MakeSolid 固化。中立调用方统一写成
+            // `makeSolid(revolve(...))`（faijs-fasteners 的 revolveProfile 即如此），故此处对
+            // **已是实体**的输入幂等返回——不是吞错：非 shell 的输入仍交给内核报错。
+            if (knownSolids.has(n))
+                return shell;
+            return asHandle(markSolid(kernel.solidFromShell(n)));
+        },
+        thicken(shape, thickness, tolerance) {
+            // brepkit 原生 thicken 只有 (face, thickness)，**无 tolerance 参数** ——
+            // 传非零容差即显式失败，不静默丢弃（与 sweep/loft 的显式失败同一纪律）。
+            if (tolerance !== undefined && tolerance !== 0) {
+                fail(`thicken: brepkit has no tolerance parameter (got ${tolerance}); pass 0 or omit it`);
+            }
+            return asHandle(markSolid(kernel.thicken(asNum(shape), thickness)));
+        },
         // ── 布尔与分割 ──
         fuse(a, b) { return asHandle(markSolid(trackFallback(kernel.fuse(asNum(a), asNum(b))))); },
         cut(a, b) { return asHandle(markSolid(trackFallback(kernel.cut(asNum(a), asNum(b))))); },
@@ -859,6 +945,11 @@ export async function createBrepkitPrimitives() {
         mirror(shape, point, normal) {
             return withKind(kindOf(shape), kernel.mirror(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z));
         },
+        rotate(shape, axis, angleRad) {
+            // brepkit 无 rotate 原语 → 适配器组 Rodrigues 3×4 矩阵后走既有 cloneAndTransform
+            // （toKernelMatrix 仍是唯一方言转换点；与 translate/scale 同一条路径）。
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(rotationMatrix(axis.point, axis.direction, angleRad)), kindOf(shape)));
+        },
         // ── 阵列 ──
         // brepkit wasm 的 pattern 内核函数都返回 compound（含全部副本）→ 经 getCompoundSolids 拆成数组。
         linearPattern(shape, direction, spacing, count) {
@@ -937,6 +1028,90 @@ export async function createBrepkitPrimitives() {
             knownEdges.add(e);
             return asEdge(e);
         },
+        makeCircleArc(center, normal, radius, startAngle, endAngle) {
+            // 方言消化：L1 吃 (圆心, 法向, 半径, 起止角)；brepkit makeCircleArc3d 吃
+            // (start, end, center, axis)。先在法向的垂直平面里建正交基 (u,v)，
+            // 起点/终点由角度算，axis 取归一化法向（右手：θ 增大绕 axis 逆时针）。
+            const len = Math.hypot(normal.x, normal.y, normal.z);
+            if (!(len > 0))
+                fail('makeCircleArc: normal must be a non-zero vector');
+            const n = { x: normal.x / len, y: normal.y / len, z: normal.z / len };
+            let u;
+            const ax = Math.abs(n.x);
+            const ay = Math.abs(n.y);
+            const az = Math.abs(n.z);
+            if (ax <= ay && ax <= az)
+                u = { x: 0, y: -n.z, z: n.y };
+            else if (ay <= az)
+                u = { x: -n.z, y: 0, z: n.x };
+            else
+                u = { x: n.y, y: -n.x, z: 0 };
+            const ul = Math.hypot(u.x, u.y, u.z);
+            u = { x: u.x / ul, y: u.y / ul, z: u.z / ul };
+            const v = {
+                x: n.y * u.z - n.z * u.y,
+                y: n.z * u.x - n.x * u.z,
+                z: n.x * u.y - n.y * u.x,
+            };
+            const at = (ang) => {
+                const cs = Math.cos(ang) * radius;
+                const sn = Math.sin(ang) * radius;
+                return {
+                    x: center.x + u.x * cs + v.x * sn,
+                    y: center.y + u.y * cs + v.y * sn,
+                    z: center.z + u.z * cs + v.z * sn,
+                };
+            };
+            const start = at(startAngle);
+            const end = at(endAngle);
+            const e = kernel.makeCircleArc3d(start.x, start.y, start.z, end.x, end.y, end.z, center.x, center.y, center.z, n.x, n.y, n.z);
+            knownEdges.add(e);
+            return asEdge(e);
+        },
+        makeHelixWire(origin, axis, pitch, height, radius, leftHanded) {
+            // 左手显式失败：brepkit 无带手性螺旋原语，而采样拟合补镜像属「静默换算法」
+            // （同 pitch/height/radius 下左右旋互为镜像，报错比悄悄换构造更安全）。
+            // 这是**形参级**缺口：右手在 brepkit 上仍然可用，故 op 侧不声明 engines:['occt']
+            // ——声明了会把右手一并拒掉。缺口在实现体内显式报错（同 extrude 拒绝非 face 输入）。
+            if (leftHanded) {
+                fail('makeHelixWire: left-handed helix requires the occt engine ' +
+                    '(brepkit has no handed helix primitive; no mirror fallback by design)');
+            }
+            // §7 决策点 2 选 (a)：解析螺旋采样 → interpolatePoints 造 NURBS edge → makeWire。
+            // brepkit 的 helicalSweep 是**扫掠成体**，不能用于 1D wire。
+            // 偏差 = 采样弦高（近似，非解析），由 helix 一致性测试钉 band。
+            const pts = sampleHelixPoints(origin, axis, pitch, height, radius);
+            const degree = Math.min(3, pts.length - 1);
+            const e = kernel.interpolatePoints(flattenPoints(pts), degree);
+            knownEdges.add(e);
+            const w = kernel.makeWire(Int32Array.from([e]), false);
+            knownWires.add(w);
+            return asWire(w);
+        },
+        approximatePoints(points, tolerance) {
+            // 方言消化：L1 吃 (点列, 容差)；brepkit approximateCurveLspia 还要
+            // degree / num_control_points / max_iterations —— 由适配器给缺省
+            // （degree 3 夹紧、numCps 取点数、迭代 100），容差直接落 tolerance。
+            const n = points.length;
+            if (n < 2)
+                fail(`approximatePoints: need at least 2 points, got ${n}`);
+            const degree = Math.max(1, Math.min(3, n - 1));
+            const e = kernel.approximateCurveLspia(flattenPoints(points), degree, n, tolerance ?? 1e-2, 100);
+            knownEdges.add(e);
+            return asEdge(e);
+        },
+        interpolatePointsWithTangents(points, _startTangent, _endTangent) {
+            // ⚠️ 退化实现（§7 决策点 3 选 (a)）：brepkit 无「带端点切向约束的插值」原语，
+            // 这里退化为普通 interpolatePoints（degree 3）—— **两端切向被丢弃**，端点
+            // 斜率与 occt 的 GeomAPI_Interpolate(scale=True) 不同。这是有记录的近似
+            // （HAND_MAP note + 偏差 band 双钉），不是静默降级。
+            const n = points.length;
+            if (n < 2)
+                fail(`interpolatePointsWithTangents: need at least 2 points, got ${n}`);
+            const e = kernel.interpolatePoints(flattenPoints(points), Math.min(3, n - 1));
+            knownEdges.add(e);
+            return asEdge(e);
+        },
         // ── 拓扑构造 ──
         makeWire(edges) {
             const w = kernel.makeWire(Int32Array.from(edges.map(asNum)), false);
@@ -952,18 +1127,13 @@ export async function createBrepkitPrimitives() {
             const kids = arr(shapesList.map(asNum));
             // GOTCHA（2026-09-26）：brepkit makeCompound 只接受 **solid** 句柄——把 face/wire
             // （sectionByPlane 截面面组）塞进去即抛 "invalid solid handle"。非实体子句柄时
-            // 不调内核，改用高段虚拟句柄（0x20000000+，避开类型标签 bit26..28），仅靠 knownCompounds 表分发
-            // meshShape/wireframe/getSubShapes/getBoundingBox，不触达内核。
-            const hasNonSolid = kids.some((k) => knownFaces.has(k) || knownWires.has(k) || knownEdges.has(k) || knownCompounds.has(k));
-            if (hasNonSolid) {
-                virtualCompoundCounter++;
-                const v = 0x20000000 + virtualCompoundCounter;
-                knownCompounds.set(v, kids);
-                return asHandle(v);
-            }
-            const c = kernel.makeCompound(Int32Array.from(kids));
-            knownCompounds.set(c, kids);
-            return asHandle(c);
+            // 不调内核；且 compound 与 solid 分命名空间会**重号**（2026-10-13 实测成员 [0..4]
+            // 的 compound 内核句柄 = 0），真句柄进 knownCompounds 会让同号 solid 查询误判。
+            // 故**一律**走高段虚拟句柄（0x20000000+），仅靠 knownCompounds 表分发
+            // meshShape/wireframe/getSubShapes/getBoundingBox，不触达内核；真内核句柄由
+            // compoundOf 保留在 kernelCompoundHandles 供 exportStep 映射。分发逻辑与
+            // cloneAndTransform 的 compound 分支共用 compoundOf（一份实现）。
+            return asHandle(compoundOf(kids));
         },
         addHolesInFace(face, holeWires) {
             // addHolesToFace 返回**新 face 句柄**（同曲面 + 内孔 wire），必须登记进 knownFaces，
@@ -977,6 +1147,13 @@ export async function createBrepkitPrimitives() {
             knownFaces.add(f);
             return asFace(f);
         },
+        makeNonPlanarFace(wire) {
+            // brepkit 的 makeFaceFromWire 不区分平面/非平面（与 makeFace 同一原生），
+            // 但 L1 保留独立中立名：occt 侧 makeFace 是平面路径，语义不同。
+            const f = kernel.makeFaceFromWire(asNum(wire));
+            knownFaces.add(f);
+            return asFace(f);
+        },
         // ── 三角化（BREP→mesh 唯一出口） ──
         meshShape(shape, options) {
             const deflection = options?.linearDeflection ?? DEFAULT_LINEAR_DEFLECTION.as(mm);
@@ -1270,6 +1447,9 @@ export async function createBrepkitPrimitives() {
                 return false;
             }
         },
+        subShapeCount(shape, type) {
+            return api.getSubShapes(shape, type).length;
+        },
         shapeType(shape) {
             try {
                 const s = arr(kernel.getSolidFaces(asNum(shape)));
@@ -1502,7 +1682,15 @@ export async function createBrepkitPrimitives() {
         },
         getSurfaceArea(shape) {
             // 方言映射：L1 getSurfaceArea ↔ brepkit surfaceArea(solid, deflection)。
-            return Number(kernel.surfaceArea(asNum(shape), 0.05));
+            // ⚠️ brepkit 的 surfaceArea **只吃 solid**（传 face 报 `invalid solid handle:
+            // index 0 is out of bounds`），而 L1 的语义锚（occt getSurfaceArea）也吃 face
+            // —— gears / fasteners 大量对面调 getSurfaceArea。故 face 走 brepkit 原生
+            // faceArea（同名不同参，属方言消化，不是静默降级）。
+            const n = asNum(shape);
+            // faceArea(face, deflection) —— deflection 与 surfaceArea 同一口径（0.05）。
+            if (resolveKind(shape, n) === KIND_FACE)
+                return Number(kernel.faceArea(n, 0.05));
+            return Number(kernel.surfaceArea(n, 0.05));
         },
         getLength(shape) {
             // 唯一 edge 弧长之和（与 occt 适配器同口径，D5）。
@@ -1561,14 +1749,23 @@ export async function createBrepkitPrimitives() {
             const solids = arr(kernel.importStep(bytes));
             if (solids.length === 0)
                 fail('importStep: kernel returned no solid');
-            const c = solids.length === 1 ? solids[0] : kernel.makeCompound(Uint32Array.from(solids));
+            // 多实体 → compoundOf（虚拟句柄）：compound 与 solid 分命名空间会重号，真句柄
+            // 登记 knownCompounds 会在查询同号 solid 时误判（2026-10-13 修复，同 makeCompound）。
+            // ⚠️ 每个成员 solid 必须先 markSolid：否则 buildCompoundTopologyRuntime 枚举成员面
+            // （面号进 derivedFaces）后再 getSubShapes(member,'edge')，isFaceLike 会因成员号撞
+            // 面号且不在 knownSolids 而误判 → getFaceEdges 只回一个面的 4 条边（faceCount=0，
+            // edgeNaming.faces=null），真机选成员2 的边倒角报「no adjacent-face lineage」。
             if (solids.length > 1)
-                knownCompounds.set(c, solids);
-            return asHandle(markSolid(c));
+                return asHandle(compoundOf(markSolids(solids)));
+            return asHandle(markSolid(solids[0]));
         },
         exportStep(shape) {
+            // 虚拟 compound（0x20000000+）需映射回真内核句柄——compound 与 solid 分命名空间，
+            // 内核 exportStep 不认虚拟句柄（2026-10-13 compoundOf 虚拟化后补映射）。
+            const s = asNum(shape);
+            const real = kernelCompoundHandles.get(s) ?? s;
             // brepkit exportStep 返回 UTF-8 字节（Uint8Array），需解码为 STEP 文本（2026-09-19 实测）
-            const bytes = kernel.exportStep(asNum(shape));
+            const bytes = kernel.exportStep(real);
             return typeof bytes === 'string' ? bytes : new TextDecoder().decode(bytes);
         },
         importStl(data) {
@@ -1634,6 +1831,88 @@ function translationMatrix(dx, dy, dz) {
         0, 0, 1, dz,
     ];
 }
+/**
+ * 3×4 行主序旋转矩阵（绕**任意轴** axis={point,direction} 转 angleRad，右手）。
+ *
+ * 与 `engine-compat/harness.ts` 的 rotate 测试桩同算法（Rodrigues），保证 brepkit
+ * 侧与 occt 侧 `rotate` 可对照：
+ *   R = I·cosθ + (d⊗d)(1−cosθ) + [d]×·sinθ ，平移 t = P − R·P（轴上的点不动）。
+ */
+function rotationMatrix(point, direction, angleRad) {
+    const len = Math.hypot(direction.x, direction.y, direction.z);
+    if (!(len > 0))
+        fail('rotate: axis direction must be a non-zero vector');
+    const d = { x: direction.x / len, y: direction.y / len, z: direction.z / len };
+    const c = Math.cos(angleRad);
+    const s = Math.sin(angleRad);
+    const t = 1 - c;
+    const r00 = c + d.x * d.x * t;
+    const r01 = d.x * d.y * t - d.z * s;
+    const r02 = d.x * d.z * t + d.y * s;
+    const r10 = d.x * d.y * t + d.z * s;
+    const r11 = c + d.y * d.y * t;
+    const r12 = d.y * d.z * t - d.x * s;
+    const r20 = d.x * d.z * t - d.y * s;
+    const r21 = d.y * d.z * t + d.x * s;
+    const r22 = c + d.z * d.z * t;
+    return [
+        r00, r01, r02, point.x - (r00 * point.x + r01 * point.y + r02 * point.z),
+        r10, r11, r12, point.y - (r10 * point.x + r11 * point.y + r12 * point.z),
+        r20, r21, r22, point.z - (r20 * point.x + r21 * point.y + r22 * point.z),
+    ];
+}
+/**
+ * 右手圆柱螺旋线采样点（解析式，供 brepkit 侧 makeHelixWire 拟合用）。
+ *
+ * 参数化：θ ∈ [0, 2π·turns]，turns = height / pitch；
+ *   P(θ) = origin + u·r·cosθ + v·r·sinθ + â·(pitch·θ / 2π)
+ * 其中 (u, v, â) 是右手正交基，â = axis/|axis|。θ 到终点时沿轴推进量恰为 height。
+ *
+ * 段数按圈数取（每圈 `SEGMENTS_PER_TURN` 段，下限 8 段）—— 采样弦高即偏差来源，
+ * 由 helix 一致性测试钉 band。
+ */
+function sampleHelixPoints(origin, axis, pitch, height, radius, segmentsPerTurn = 36) {
+    const len = Math.hypot(axis.x, axis.y, axis.z);
+    if (!(len > 0))
+        fail('makeHelixWire: axis must be a non-zero vector');
+    if (!(pitch !== 0))
+        fail('makeHelixWire: pitch must be non-zero');
+    const a = { x: axis.x / len, y: axis.y / len, z: axis.z / len };
+    // 与 makePlanarFaceTool（occt 侧）同一取轴策略：取分量绝对值最小的坐标构造正交基，
+    // 避免 axis 轴对齐时退化。
+    const ax = Math.abs(a.x);
+    const ay = Math.abs(a.y);
+    const az = Math.abs(a.z);
+    let u;
+    if (ax <= ay && ax <= az)
+        u = { x: 0, y: -a.z, z: a.y };
+    else if (ay <= az)
+        u = { x: -a.z, y: 0, z: a.x };
+    else
+        u = { x: a.y, y: -a.x, z: 0 };
+    const ul = Math.hypot(u.x, u.y, u.z);
+    u = { x: u.x / ul, y: u.y / ul, z: u.z / ul };
+    const v = {
+        x: a.y * u.z - a.z * u.y,
+        y: a.z * u.x - a.x * u.z,
+        z: a.x * u.y - a.y * u.x,
+    };
+    const turns = height / pitch;
+    const total = Math.max(8, Math.ceil(Math.abs(turns) * segmentsPerTurn));
+    const out = [];
+    for (let i = 0; i <= total; i++) {
+        const th = (2 * Math.PI * turns * i) / total;
+        const cs = Math.cos(th);
+        const sn = Math.sin(th);
+        const axial = (pitch * th) / (2 * Math.PI);
+        out.push({
+            x: origin.x + (u.x * cs + v.x * sn) * radius + a.x * axial,
+            y: origin.y + (u.y * cs + v.y * sn) * radius + a.y * axial,
+            z: origin.z + (u.z * cs + v.z * sn) * radius + a.z * axial,
+        });
+    }
+    return out;
+}
 /** 3×4 行主序缩放矩阵（绕 center 缩放；faijs 接口方言，12 元素）。 */
 function scaleMatrix(center, factor) {
     return [
@@ -1679,7 +1958,7 @@ let memoizedKernel = null;
  *
  * @returns the live brepkit wasm kernel singleton.
  */
-export function getBrepkitKernel() {
+export function getBrepKitKernel() {
     if (!liveKernel) {
         throw new Error('[brepkit-kernel] kernel not initialized: call createBrepkitPrimitives() first');
     }