@faicad/faijs 0.16.1 → 0.17.0

package/dist/brepkit-kernel/brepkitKernel.js

@@ -1,19 +1,32 @@
 /**
- * brepkit-kernel/brepkitKernel — brepkit 内核 → faijs BrepEngineApi 适配器（v1 白名单）
+ * brepkit-kernel/brepkitKernel — brepkit 内核 → faijs BrepEngineApi 适配器
+ *
+ * Phase 4（docs/plans/2026-09-24-brep-engine-api-narrowing-native-access.md）：
+ * 本文件是 L1 契约 `BrepEngineApi` 的 **brepkit 显式对象字面量实现**——与 occt 侧
+ * `occt-primitives.ts` 同构：逐方法接线、方言在适配器内消化、零 `unsupported()` 桩。
+ *
+ * 契约面收窄后 L1 只含 occt/brepkit 双方**语义可对齐**的方法（唯一真源：
+ * `api/surface/engine-method-map.json` 的 aligned/dialect 条目）。brepkit 独有
+ * 能力（chamfer2d/chamferV2/filletV2/sketch* 族、serializeSolid、meshBoolean、
+ * minkowskiSum …）与单方语义（loft、平面 section/split 之外的 splitter 语义…）
+ * 都不在本对象里——平台代码经原生面 `getBrepkitKernel()`（D3）访问。
  *
  * 设计要点（对应 3d_editor 项目的 weapp-voice-ai-modeling 设计计划 §5）：
  * - 句柄：brepkit u32 句柄与 faijs BrepHandle(number) 同构，直通零转换；
  * - 拓扑红线：meshShape 用 tessellateSolidGrouped 输出 faceGroups，与三角化几何同源；
  * - 面溯源：布尔/倒角走 *WithEvolution，映射为 BrepEvolutionData（hash 编码）；
  * - 链纪律：kernel.meshFallbackCount 计数差 > 0 → getMeshFallbackCount 暴露给宿主，
- *   由宿主标记 BREP 链中断（不在此层静默处理）；
- * - v1 白名单之外的方法：显式抛错（报错好于掩盖，禁止空实现假成功）。
+ *   由宿主标记 BREP 链中断（不在此层静默处理）。
  */
 import { initBrepkitWasm } from './brepkitWasm.js';
 // ── 句柄桥接：brepkit number 句柄 ↔ BrepHandle（零运行时成本，与 occt 适配器同构） ──
 const asHandle = (n) => n;
 const asNum = (h) => h;
 const arr = (x) => Array.from(x);
+/** 适配器内部的显式失败（替代旧 unsupported 桩：能力缺失一律在静态判定拦截，不在实现体里伪装）。 */
+function fail(detail) {
+    throw new Error(`[brepkit-kernel] ${detail}`);
+}
 /**
  * brepkit 几何查询返回值归一为 number[]。
  *
@@ -64,10 +77,6 @@ function toNumArray(v) {
     }
     return [];
 }
-/** v1 白名单外的方法统一抛错（携带适配器上下文与 v1 范围说明）。 */
-function unsupported(name) {
-    throw new Error(`[brepkit-kernel] BrepEngineApi.${name} 不在 brepkit 适配器 v1 白名单内（能力表见设计文档 §5.2）。该操作请在 OCCT 链执行，或等待适配器扩展。`);
-}
 /** 面稳定指纹：解析曲面参数 + 面积 → FNV-1a → 取模上界（跨操作可追溯，与句柄无关）。 */
 function faceFingerprint(kernel, face, upperBound) {
     let params = '';
@@ -128,9 +137,45 @@ function mapEvolution(kernel, raw, resultHandle, inputFaceHashes, hashUpperBound
 }
 /** per-kernel 的 hash↔handle 登记表（fuseWithHistory 溯源对齐用）。 */
 const hashRegistry = new WeakMap();
+/** 三点外接圆（makeArcEdge 方言消化：occt 吃 3 点，brepkit 吃圆心+轴）。 */
+function circumcircle(a, b, c) {
+    const abx = b.x - a.x, aby = b.y - a.y, abz = b.z - a.z;
+    const acx = c.x - a.x, acy = c.y - a.y, acz = c.z - a.z;
+    const nx = aby * acz - abz * acy;
+    const ny = abz * acx - abx * acz;
+    const nz = abx * acy - aby * acx;
+    const n2 = nx * nx + ny * ny + nz * nz;
+    if (n2 < 1e-18)
+        fail('makeArcEdge: 3 points are collinear (no circumscribed circle)');
+    const ab2 = abx * abx + aby * aby + abz * abz;
+    const ac2 = acx * acx + acy * acy + acz * acz;
+    // center = a + ( ac2·(ab×n) + ab2·(n×ac) ) / (2·n²)
+    const abxnx = aby * nz - abz * ny, abxny = abz * nx - abx * nz, abxnz = abx * ny - aby * nx;
+    const nxacx = ny * acz - nz * acy, nxacy = nz * acx - nx * acz, nxacz = nx * acy - ny * acx;
+    const denom = 2 * n2;
+    const len = Math.sqrt(n2);
+    return {
+        center: {
+            x: a.x + (ac2 * abxnx + ab2 * nxacx) / denom,
+            y: a.y + (ac2 * abxny + ab2 * nxacy) / denom,
+            z: a.z + (ac2 * abxnz + ab2 * nxacz) / denom,
+        },
+        axis: { x: nx / len, y: ny / len, z: nz / len },
+    };
+}
+/** BrepVec3[] → 扁平 Float64Array（brepkit 坐标数组方言）。 */
+function flattenPoints(points) {
+    const out = new Float64Array(points.length * 3);
+    for (let i = 0; i < points.length; i++) {
+        out[i * 3] = points[i].x;
+        out[i * 3 + 1] = points[i].y;
+        out[i * 3 + 2] = points[i].z;
+    }
+    return out;
+}
 /**
- * 创建 brepkit BrepEngineApi 实现（v1 白名单）。
- * 与 occt 的 initOcctWasm 同位：返回满足引擎契约的原语集合。
+ * 创建 brepkit BrepEngineApi 实现（L1 契约显式对象字面量）。
+ * 与 occt 的 createOcctPrimitives 同位：返回满足引擎契约的原语集合。
  * @returns a promise resolving to the BrepEngineApi implementation plus brepkit-specific
  * diagnostics (`getMeshFallbackCount`).
  */
@@ -138,8 +183,9 @@ export async function createBrepkitPrimitives() {
     const kernel = await initBrepkitWasm();
     liveKernel = kernel;
     let lastFallbackCount = 0;
-    // 已知面句柄集合：getSubShapes(shape,'face') 返回的面在此登记；
-    // getSubShapes(handle,'edge'/'vertex') 据此分发到 face 级或 solid 级 API。
+    // 已知面句柄集合：getSubShapes(shape,'face') / makeRectangle / makeFace / buildTriFace
+    // 返回的面在此登记；extrude/revolveVec 的 face 输入断言、getSubShapes 的
+    // edge/vertex 分发都据此判定（brepkit 无 shape-type 分类 API，见下方注释）。
     const knownFaces = new Set();
     const readFallback = () => {
         try {
@@ -151,9 +197,18 @@ export async function createBrepkitPrimitives() {
     };
     /** 布尔类操作后登记回退计数差（§5.4：宿主每步读取，>0 即链中断）。 */
     const trackFallback = (r) => { lastFallbackCount = readFallback(); return r; };
+    const faceCenterOfMass = (face) => {
+        // brepkit 无 per-face 质心 API；用 UV 域中点在曲面上求值作为面中心近似
+        // （与 OCCT 路径的「面中心用于命名/拾取锚点」语义一致，不追求精确质心）。
+        const d = toNumArray(kernel.getSurfaceDomain(asNum(face)));
+        const u = ((d[0] ?? 0) + (d[1] ?? 1)) / 2;
+        const v = ((d[2] ?? 0) + (d[3] ?? 1)) / 2;
+        return vec3Of(toNumArray(kernel.evaluateSurface(asNum(face), u, v)));
+    };
     const api = {
         // ── 生命周期 ──
         release(_shape) { },
+        dispose(_shape) { },
         /** 内核级诊断：距上次读取的 mesh 布尔回退计数差（>0 = BREP 链已中断）。 */
         getMeshFallbackCount() {
             const now = readFallback();
@@ -166,45 +221,113 @@ export async function createBrepkitPrimitives() {
         makeBoxFromCorners(corner1, corner2) {
             const dx = Math.abs(corner2.x - corner1.x), dy = Math.abs(corner2.y - corner1.y), dz = Math.abs(corner2.z - corner1.z);
             const h = kernel.makeBox(dx, dy, dz);
-            return asHandle(kernel.transformSolid(h, toKernelMatrix(translationMatrix(Math.min(corner1.x, corner2.x), Math.min(corner1.y, corner2.y), Math.min(corner1.z, corner2.z)))));
+            // ⚠️ transformSolid 是「原地修改、返回 undefined」——makeBox 的句柄本身即新实体，
+            // 直接原地变换后返回 h；若写 `asHandle(transformSolid(...))` 会拿到 undefined 句柄
+            // （2026-09-25 实证：导致 splitBrep 基于半空间盒的 common/cut 全部失效）。
+            kernel.transformSolid(h, toKernelMatrix(translationMatrix(Math.min(corner1.x, corner2.x), Math.min(corner1.y, corner2.y), Math.min(corner1.z, corner2.z))));
+            return asHandle(h);
         },
         makeCylinder(radius, height) { return asHandle(kernel.makeCylinder(radius, height)); },
         makeSphere(radius) { return asHandle(kernel.makeSphere(radius, 32)); },
         makeCone(r1, r2, height) { return asHandle(kernel.makeCone(r1, r2, height)); },
-        makeRectangle(_width, _height) { return unsupported('makeRectangle'); },
+        makeRectangle(width, height) {
+            const f = kernel.makeRectangle(width, height);
+            knownFaces.add(f);
+            return asHandle(f);
+        },
+        makeEllipsoid(rx, ry, rz) { return asHandle(kernel.makeEllipsoid(rx, ry, rz)); },
+        makeTorus(majorRadius, minorRadius) { return asHandle(kernel.makeTorus(majorRadius, minorRadius, 64)); },
+        makeVertex(x, y, z) { return asHandle(kernel.makeVertex(x, y, z)); },
         // ── 造型运算 ──
-        extrude(_shape, _dx, _dy, _dz) { return unsupported('extrude'); }, // ⚠️ wasm extrude(face, dir, distance) 语义不同 → 保持 unsupported
-        loft(_wires, _isSolid, _ruled) { return unsupported('loft'); },
+        extrude(shape, dx, dy, dz) {
+            // 方言归一（§3.6-1）：L1 口径是挤出向量；brepkit 原生吃 (face, dir, distance)。
+            const s = asNum(shape);
+            if (!knownFaces.has(s)) {
+                fail('extrude requires a face input (plan §3.6-1); got a handle that is not a known face');
+            }
+            const len = Math.hypot(dx, dy, dz);
+            if (len === 0)
+                fail('extrude: zero-length extrusion vector');
+            return asHandle(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(kernel.revolve(s, center.x, center.y, center.z, direction.x, direction.y, direction.z, angleDeg));
+        },
+        sew(shapesList, tolerance) {
+            return asHandle(kernel.sewFaces(Uint32Array.from(shapesList.map(asNum)), tolerance ?? 1e-6));
+        },
+        sewAndSolidify(faces, _tolerance) {
+            // brepkit 的 makeSolid 即「缝合并固化成实体」（sewFaces + 建 solid）。
+            return asHandle(kernel.makeSolid(Uint32Array.from(faces.map(asNum))));
+        },
+        shell(solid, facesToRemove, thickness, _tolerance) {
+            // brepkit 参数序 (solid, thickness, open_faces)；tolerance 内核固定。
+            return asHandle(kernel.shell(asNum(solid), thickness, Uint32Array.from(facesToRemove.map(asNum))));
+        },
+        hullFromPoints(points, _tolerance) {
+            return asHandle(kernel.convexHull(flattenPoints(points)));
+        },
         // ── 布尔与分割 ──
         fuse(a, b) { return asHandle(trackFallback(kernel.fuse(asNum(a), asNum(b)))); },
         cut(a, b) { return asHandle(trackFallback(kernel.cut(asNum(a), asNum(b)))); },
-        common(a, b) { return asHandle(trackFallback(kernel.common(asNum(a), asNum(b)))); },
-        intersect(a, b) { return asHandle(trackFallback(kernel.common(asNum(a), asNum(b)))); },
-        section(_a, _b) { return unsupported('section'); }, // ⚠️ wasm section(solid+平面) 语义不同 → 保持 unsupported
-        fuseAll(shapes) {
-            return asHandle(trackFallback(kernel.fuseAll(Int32Array.from(shapes.map(asNum)))));
+        common(a, b) {
+            // brepkit 无 `common` 原生名；交集语义由 `intersect` 承担（method-map: dialect）。
+            return asHandle(trackFallback(kernel.intersect(asNum(a), asNum(b))));
+        },
+        intersect(a, b) { return asHandle(trackFallback(kernel.intersect(asNum(a), asNum(b)))); },
+        fuseAll(shapesList) {
+            return asHandle(trackFallback(kernel.fuseAll(Int32Array.from(shapesList.map(asNum)))));
+        },
+        sectionByPlane(shape, point, normal) {
+            // brepkit 原生 section(solid, plane) 返回剖面 face 句柄组（§3.6-2 新中立名）。
+            return arr(kernel.section(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z)).map(asHandle);
+        },
+        splitByPlane(shape, point, normal) {
+            const parts = arr(kernel.split(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z));
+            if (parts.length !== 2) {
+                fail(`splitByPlane: expected 2 solids, got ${parts.length}`);
+            }
+            // 法向正侧 = positive（§3.7）：按质心在平面法向的投影分类。
+            const originDot = point.x * normal.x + point.y * normal.y + point.z * normal.z;
+            const side = (h) => {
+                const c = toNumArray(kernel.centerOfMass(h, 0.05));
+                return (c[0] ?? 0) * normal.x + (c[1] ?? 0) * normal.y + (c[2] ?? 0) * normal.z - originDot;
+            };
+            const [a, b] = parts;
+            return side(a) >= side(b)
+                ? { positive: asHandle(a), negative: asHandle(b) }
+                : { positive: asHandle(b), negative: asHandle(a) };
         },
-        // ── 倒角与圆角 ──
+        // ── 倒角与圆角（Q7：只对齐等距 + 距角两种粒度）──
         chamfer(solid, edges, distance) {
-            return asHandle(trackFallback(kernel.chamfer(asNum(solid), Int32Array.from(edges.map(asNum)), distance)));
+            return asHandle(trackFallback(kernel.chamfer(asNum(solid), Uint32Array.from(edges.map(asNum)), distance)));
         },
         chamferDistAngle(solid, edges, distance, angleDeg) {
-            return asHandle(trackFallback(kernel.chamferDistanceAngle(asNum(solid), Int32Array.from(edges.map(asNum)), distance, angleDeg)));
+            // 方言映射：L1 chamferDistAngle ↔ brepkit chamferDistanceAngle。
+            // ⚠️ 单位方言：L1 口径是**度**（`AddDA(distance, angleDeg, E, F)`），brepkit 内核吃**弧度**
+            // （2026-09-25 实证：传 45 抛 "angle must be less than π/2"；传 π/4 正常倒角）。
+            const angleRad = (angleDeg * Math.PI) / 180;
+            return asHandle(trackFallback(kernel.chamferDistanceAngle(asNum(solid), Uint32Array.from(edges.map(asNum)), distance, angleRad)));
         },
         fillet(solid, edges, radius) {
-            return asHandle(trackFallback(kernel.fillet(asNum(solid), Int32Array.from(edges.map(asNum)), radius)));
+            return asHandle(trackFallback(kernel.fillet(asNum(solid), Uint32Array.from(edges.map(asNum)), radius)));
         },
         filletVariable(solid, edge, startRadius, endRadius) {
-            return asHandle(trackFallback(kernel.filletVariable(asNum(solid), asNum(edge), startRadius, endRadius)));
+            // 方言映射：L1 filletVariable(solid, edge, startRadius, endRadius)（单边变半径）
+            // ↔ brepkit filletVariable(solid, json) 吃**序列** `[{edge, radius1, radius2}, ...]`。
+            // ⚠️ 直接传 4 个位置参数会触发 wasm memory out of bounds（2026-09-25 实证）。
+            const spec = JSON.stringify([{ edge: asNum(edge), radius1: startRadius, radius2: endRadius }]);
+            return asHandle(trackFallback(kernel.filletVariable(asNum(solid), spec)));
         },
         filletWithHistory(solid, edges, radius, inputFaceHashes, hashUpperBound) {
             const raw = kernel.filletWithEvolution(asNum(solid), Int32Array.from(edges.map(asNum)), radius);
             return mapEvolution(kernel, raw, JSON.parse(raw).solid, inputFaceHashes, hashUpperBound);
         },
-        chamferWithHistory(_solid, _edges, _distance, _inputFaceHashes, _hashUpperBound) {
-            // brepkit 无 chamferWithEvolution → 等距倒角演化不支持，诚实报错（能力表 evolution 仅覆盖 fuse/cut/fillet）
-            return unsupported('chamferWithHistory');
-        },
         // ── 变换 ──
         // ⚠️ brepkit 的 transformSolid 是「原地修改、返回 undefined」——必须先 copySolid
         // 复制出新句柄再变换，否则会篡改调用方手里的原实体（单测 2026-09-19 实证）。
@@ -231,20 +354,33 @@ export async function createBrepkitPrimitives() {
             kernel.transformSolid(c, toKernelMatrix(matrix));
             return asHandle(c);
         },
+        locate(shape, matrix) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.transformSolid(c, toKernelMatrix(matrix));
+            return asHandle(c);
+        },
         generalTransform(shape, matrix) {
             const c = kernel.copySolid(asNum(shape));
             kernel.transformSolid(c, toKernelMatrix(matrix));
             return asHandle(c);
         },
         copy(shape) { return asHandle(kernel.copySolid(asNum(shape))); },
-        // ── 阵列（Phase 2：brepkit wasm 已导出 linearPattern/circularPattern/gridPattern） ──
-        // brepkit wasm 的 pattern 内核函数都返回 compound（含全部副本，README「Returns a
-        // compound handle containing all copies」实证）→ 经 getCompoundSolids 拆成数组。
+        copyShape(shape) { return asHandle(kernel.copySolid(asNum(shape))); },
+        composeTransform(m1, m2) {
+            // 方言：L1 是 3×4 行主序 12 元素；brepkit composeTransforms 吃/回 4×4 16 元素。
+            const r = kernel.composeTransforms(Float64Array.from(toKernelMatrix(m1)), Float64Array.from(toKernelMatrix(m2)));
+            return Array.from(r).slice(0, 12);
+        },
+        mirror(shape, point, normal) {
+            return asHandle(kernel.mirror(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z));
+        },
+        // ── 阵列 ──
+        // brepkit wasm 的 pattern 内核函数都返回 compound（含全部副本）→ 经 getCompoundSolids 拆成数组。
         linearPattern(shape, direction, spacing, count) {
             const compound = kernel.linearPattern(asNum(shape), direction.x, direction.y, direction.z, spacing, count);
             return arr(kernel.getCompoundSolids(compound)).map(asHandle);
         },
-        circularPattern(shape, center, axis, angleStep, count) {
+        circularPattern(shape, _center, axis, _angleStep, count) {
             // ⚠️ brepkit wasm circularPattern(solid, ax, ay, az, count) 无 center/angle 参数：
             // 固定整圆均分（每份 360°/count）。fullAngle=360 时与 vendored/occt 语义一致；
             // 其它角度跨度无法表达（语义限制记录于此，parity 测试用整圆）。
@@ -258,23 +394,50 @@ export async function createBrepkitPrimitives() {
         makeLineEdge(start, end) {
             return asHandle(kernel.makeLineEdge(start.x, start.y, start.z, end.x, end.y, end.z));
         },
-        makeArcEdge(_start, _mid, _end) { return unsupported('makeArcEdge'); },
-        makeBezierEdge(_controlPoints) { return unsupported('makeBezierEdge'); },
+        makeArcEdge(start, mid, end) {
+            // 方言消化：occt 吃 3 点；brepkit makeCircleArc3d 吃 (start,end,center,axis)。
+            const { center, axis } = circumcircle(start, mid, end);
+            return asHandle(kernel.makeCircleArc3d(start.x, start.y, start.z, end.x, end.y, end.z, center.x, center.y, center.z, axis.x, axis.y, axis.z));
+        },
+        makeBezierEdge(controlPoints) {
+            // 方言消化：L1 吃控制点（Bezier）；brepkit 原生 makeNurbsEdge 吃
+            // (start,end,degree,knots,control_points,weights)。Bezier = degree n-1 的
+            // clamped NURBS，knots = [0]×n + [1]×n，weights 全 1。
+            const n = controlPoints.length;
+            if (n < 2)
+                fail('makeBezierEdge: need at least 2 control points');
+            const degree = n - 1;
+            const knots = new Float64Array(2 * n);
+            for (let i = n; i < 2 * n; i++)
+                knots[i] = 1;
+            const weights = new Float64Array(n).fill(1);
+            const first = controlPoints[0];
+            const last = controlPoints[n - 1];
+            return asHandle(kernel.makeNurbsEdge(first.x, first.y, first.z, last.x, last.y, last.z, degree, knots, flattenPoints(controlPoints), weights));
+        },
+        makeCircleEdge(center, normal, radius) {
+            return asHandle(kernel.makeCircleEdge(center.x, center.y, center.z, normal.x, normal.y, normal.z, radius));
+        },
         // ── 拓扑构造 ──
         makeWire(edges) {
             return asHandle(kernel.makeWire(Int32Array.from(edges.map(asNum)), false));
         },
-        makeFace(wire) { return asHandle(kernel.makeFaceFromWire(asNum(wire))); },
-        makeCompound(shapes) {
-            return asHandle(kernel.makeCompound(Int32Array.from(shapes.map(asNum))));
+        makeFace(wire) {
+            const f = kernel.makeFaceFromWire(asNum(wire));
+            knownFaces.add(f);
+            return asHandle(f);
         },
-        sewAndSolidify(faces, tolerance) {
-            return asHandle(kernel.sewFaces(Int32Array.from(faces.map(asNum)), tolerance ?? 1e-6));
+        makeCompound(shapesList) {
+            return asHandle(kernel.makeCompound(Int32Array.from(shapesList.map(asNum))));
         },
-        buildTriFace(_a, _b, _c) { return unsupported('buildTriFace'); },
         addHolesInFace(face, holeWires) {
             return asHandle(kernel.addHolesToFace(asNum(face), Int32Array.from(holeWires.map(asNum))));
         },
+        buildTriFace(a, b, c) {
+            const f = kernel.makePolygon(flattenPoints([a, b, c]));
+            knownFaces.add(f);
+            return asHandle(f);
+        },
         // ── 三角化（BREP→mesh 唯一出口） ──
         meshShape(shape, options) {
             const deflection = options?.linearDeflection ?? 0.1;
@@ -369,23 +532,13 @@ export async function createBrepkitPrimitives() {
                 }
             }
             else {
-                return unsupported(`getSubShapes(${type})`);
+                fail(`getSubShapes(${type}): unsupported sub-shape type`);
             }
             return list.map(asHandle);
         },
-        queryBatch(shapes) {
-            return shapes.map(h => {
-                try {
-                    return { area: Number(kernel.faceArea(asNum(h))) };
-                }
-                catch {
-                    return { area: 0 };
-                }
-            });
-        },
         subShapeHashes(shape, type, hashUpperBound) {
             if (type !== 'face')
-                return unsupported(`subShapeHashes(${type})`);
+                fail(`subShapeHashes(${type}): only 'face' is supported by brepkit`);
             const faces = arr(kernel.getSolidFaces(asNum(shape)));
             const hashes = faces.map(f => faceFingerprint(kernel, f, hashUpperBound));
             // 登记 hash↔handle（fuseWithHistory 溯源对齐依赖此表）
@@ -406,6 +559,16 @@ export async function createBrepkitPrimitives() {
                 return false;
             }
         },
+        shapeType(shape) {
+            try {
+                const s = arr(kernel.getSolidFaces(asNum(shape)));
+                const f = arr(kernel.getFaces(asNum(shape)));
+                return s.length > 0 ? 'SOLID' : f.length > 0 ? 'FACE' : 'COMPOUND';
+            }
+            catch {
+                return 'COMPOUND';
+            }
+        },
         shapeOrientation(shape) {
             try {
                 return String(kernel.getShapeOrientation(asNum(shape)));
@@ -414,6 +577,16 @@ export async function createBrepkitPrimitives() {
                 return 'forward';
             }
         },
+        edgeToFaceMap(shape) {
+            // brepkit 返回 JSON 字符串 {"edgeId":[faceId,...]}；L1 契约是 unknown（调用方自解析）。
+            return kernel.edgeToFaceMap(asNum(shape));
+        },
+        adjacentFaces(shape, face) {
+            return arr(kernel.adjacentFaces(asNum(shape), asNum(face))).map(asHandle);
+        },
+        sharedEdges(a, b) {
+            return arr(kernel.sharedEdges(asNum(a), asNum(b))).map(asHandle);
+        },
         // ── 几何求值 ──
         curveType(edge) { return String(kernel.getEdgeCurveType(asNum(edge))); },
         curvePointAtParam(edge, param) {
@@ -472,12 +645,7 @@ export async function createBrepkitPrimitives() {
             const d = toNumArray(kernel.getSurfaceDomain(asNum(face)));
             return { uMin: d[0] ?? 0, uMax: d[1] ?? 1, vMin: d[2] ?? 0, vMax: d[3] ?? 1 };
         },
-        getSurfaceCenterOfMass(face) {
-            // brepkit 无 per-face 质心 API；用 UV 域中点在曲面上求值作为面中心近似
-            // （与 OCCT 路径的「面中心用于命名/拾取锚点」语义一致，不追求精确质心）。
-            const b = this.uvBounds(face);
-            return this.pointOnSurface(face, (b.uMin + b.uMax) / 2, (b.vMin + b.vMax) / 2);
-        },
+        surfaceCenterOfMass: faceCenterOfMass,
         getFaceCylinderData(face) {
             try {
                 const p = JSON.parse(kernel.getAnalyticSurfaceParams(asNum(face)));
@@ -496,6 +664,25 @@ export async function createBrepkitPrimitives() {
             catch { /* 非 Nurbs 边 */ }
             return null;
         },
+        interpolatePoints(points, degree) {
+            return asHandle(kernel.interpolatePoints(flattenPoints(points), degree));
+        },
+        defeature(shape, faces) {
+            return asHandle(kernel.defeature(asNum(shape), Uint32Array.from(faces.map(asNum))));
+        },
+        draft(shape, faces, pull, neutral, angleDeg) {
+            return asHandle(kernel.draft(asNum(shape), Uint32Array.from(faces.map(asNum)), pull.x, pull.y, pull.z, neutral.x, neutral.y, neutral.z, angleDeg));
+        },
+        removeHolesFromFace(face) {
+            return asHandle(kernel.removeHolesFromFace(asNum(face)));
+        },
+        reverseShape(shape) {
+            return asHandle(kernel.reverseShape(asNum(shape)));
+        },
+        projectEdges(shape, origin, direction, xAxis, hiddenLines, deflection) {
+            // brepkit 返回 JSON 字符串 {"visible":[[x,y,…]],"hidden":[[…]]}；L1 契约是 unknown。
+            return kernel.projectEdges(asNum(shape), origin.x, origin.y, origin.z, direction.x, direction.y, direction.z, xAxis.x, xAxis.y, xAxis.z, hiddenLines, deflection);
+        },
         // ── 测量 ──
         getBoundingBox(shape, _useTriangulation) {
             const b = kernel.boundingBox(asNum(shape));
@@ -506,29 +693,88 @@ export async function createBrepkitPrimitives() {
             // centerOfMass 返回 Float64Array [x,y,z]（非 JSON 字符串）
             return vec3Of(toNumArray(kernel.centerOfMass(asNum(shape), 0.05)));
         },
+        getSurfaceArea(shape) {
+            // 方言映射：L1 getSurfaceArea ↔ brepkit surfaceArea(solid, deflection)。
+            return Number(kernel.surfaceArea(asNum(shape), 0.05));
+        },
+        getLength(shape) {
+            // 方言映射：L1 getLength ↔ brepkit edgeLength(edge) / wireLength(wire)。
+            // wire 与 edge 的入参差异在适配器内判别（D6）：edgeLength 只吃 edge 句柄，
+            // 对 wire 会抛错；据此分发，两条路径都失败时如实抛出（不静默返回 0）。
+            const s = asNum(shape);
+            try {
+                kernel.getEdgeCurveType(s);
+                return Number(kernel.edgeLength(s));
+            }
+            catch {
+                return Number(kernel.wireLength(s));
+            }
+        },
         // ── 校验与修复 ──
-        isValid(_shape) { return unsupported('isValid'); },
-        unifySameDomain(shape) { return shape; /* brepkit 无对应 API；恒等返回（不丢句柄） */ },
-        healSolid(shape, _tolerance) { return asHandle(kernel.healSolid(asNum(shape))); },
-        fixShape(shape) { return asHandle(kernel.healSolid(asNum(shape))); },
-        fixFaceOrientations(shape) { return asHandle(kernel.fixFaceOrientations(asNum(shape))); },
-        removeDegenerateEdges(_shape) { return unsupported('removeDegenerateEdges'); },
+        // ⚠️ brepkit 的修复类内核函数全部是「**原地修改入参实体 + 返回修复计数**」，不是返回新句柄：
+        //   healSolid(solid)             → 修复的问题数
+        //   fixFaceOrientations(solid)   → 修复的面数
+        //   unifyFaces(solid)            → 合并删除的面数
+        //   removeDegenerateEdges(s,tol) → 删除的边数
+        //   repairSolid(solid)           → 修复后剩余错误数
+        // 直接 `asHandle(kernel.healSolid(...))` 会把计数（常见为 0）当成句柄，得到无效实体
+        // （2026-09-25 实证）。正确适配：先 copySolid 保护调用方原实体，再原地修复副本，返回副本句柄。
+        isValid(shape) {
+            // brepkit validateSolid 返回错误数（0 = 有效）。
+            return Number(kernel.validateSolid(asNum(shape))) === 0;
+        },
+        unifySameDomain(shape) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.unifyFaces(c);
+            return asHandle(c);
+        },
+        healSolid(shape, _tolerance) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.healSolid(c);
+            return asHandle(c);
+        },
+        fixShape(shape) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.healSolid(c);
+            return asHandle(c);
+        },
+        fixFaceOrientations(shape) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.fixFaceOrientations(c);
+            return asHandle(c);
+        },
+        removeDegenerateEdges(shape, tolerance) {
+            const c = kernel.copySolid(asNum(shape));
+            kernel.removeDegenerateEdges(c, tolerance ?? 1e-6);
+            return asHandle(c);
+        },
         // ── IO ──
         importStep(data) {
-            const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
-            return asHandle(kernel.importStep(text));
+            // ⚠️ brepkit importStep 吃 **Uint8Array**（不是字符串），返回 **Uint32Array**（文件内可含多个 solid）。
+            // L1 契约是单 BrepHandle：0 个 → fail；1 个 → 直通；多个 → 合成 compound（2026-09-25 实证）。
+            const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+            const solids = arr(kernel.importStep(bytes));
+            if (solids.length === 0)
+                fail('importStep: kernel returned no solid');
+            return asHandle(solids.length === 1 ? solids[0] : kernel.makeCompound(Uint32Array.from(solids)));
         },
         exportStep(shape) {
             // brepkit exportStep 返回 UTF-8 字节（Uint8Array），需解码为 STEP 文本（2026-09-19 实测）
             const bytes = kernel.exportStep(asNum(shape));
             return typeof bytes === 'string' ? bytes : new TextDecoder().decode(bytes);
         },
-        importStl(_data) { return unsupported('importStl'); },
+        importStl(data) {
+            const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+            return asHandle(kernel.importStl(bytes));
+        },
         fromBREP(data) {
-            const bytes = Uint8Array.from(atobPolyfill(data));
-            return asHandle(kernel.deserializeSolid(bytes));
+            // ⚠️ brepkit fromBREP 吃字符串（STEP 文本或 toBREP/toBrepJson 输出，内核自动判别），
+            // 与 serializeSolid/deserializeSolid 的**二进制 arena** 是两套机制。
+            // 旧实现误用 `deserializeSolid(atob(data))`：base64 解码破坏了 STEP 文本 → 往返必失败
+            // （2026-09-25 实证：fromBREP(STEP)、fromBREP(toBREP)、fromBREP(toBrepJson) 均成功）。
+            return asHandle(kernel.fromBREP(data));
         },
-        // ── 面演化（可选能力槽） ──
+        // ── 面演化（L1 三员 + filletWithHistory，双方都有对齐实现） ──
         cutWithHistory(a, b, inputFaceHashes, hashUpperBound) {
             const raw = kernel.cutWithEvolution(asNum(a), asNum(b));
             return mapEvolution(kernel, raw, JSON.parse(raw).solid, inputFaceHashes, hashUpperBound);
@@ -537,73 +783,10 @@ export async function createBrepkitPrimitives() {
             const raw = kernel.fuseWithEvolution(asNum(a), asNum(b));
             return mapEvolution(kernel, raw, JSON.parse(raw).solid, inputFaceHashes, hashUpperBound);
         },
-        intersectWithHistory(_a, _b, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('intersectWithHistory');
-        },
-        // Phase 0.1 补齐的 7 个：brepkit 适配器 v1 未实现 —— 如实抛错，不伪造。
-        // ⚠️ 这些桩**不能**被当作"已实现"来探测：`typeof api.xWithHistory === 'function'`
-        // 恒为真。Phase 0.2 起适配器的 `evolution` 是逐核函数**名单**
-        // （`adapters/brepkit.ts` = ['fuse','cut','fillet']），名单才是唯一真相来源；
-        // 声明多写一项 = 让该 op 静默通过静态判定后死在这些桩上（红线违规）。
-        translateWithHistory(_shape, _dx, _dy, _dz, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('translateWithHistory');
-        },
-        rotateWithHistory(_shape, _axis, _angleRad, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('rotateWithHistory');
-        },
-        mirrorWithHistory(_shape, _point, _normal, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('mirrorWithHistory');
-        },
-        scaleWithHistory(_shape, _center, _factor, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('scaleWithHistory');
-        },
-        shellWithHistory(_solid, _faces, _thickness, _tolerance, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('shellWithHistory');
-        },
-        offsetWithHistory(_solid, _distance, _tolerance, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('offsetWithHistory');
-        },
-        thickenWithHistory(_shape, _thickness, _tolerance, _inputFaceHashes, _hashUpperBound) {
-            return unsupported('thickenWithHistory');
+        intersectWithHistory(a, b, inputFaceHashes, hashUpperBound) {
+            const raw = kernel.intersectWithEvolution(asNum(a), asNum(b));
+            return mapEvolution(kernel, raw, JSON.parse(raw).solid, inputFaceHashes, hashUpperBound);
         },
-        // ── XCAF 装配（v1 关闭） ──
-        createXCAFDocument() { return unsupported('createXCAFDocument'); },
-        importXCAFFromSTEP(_stepData) { return unsupported('importXCAFFromSTEP'); },
-        // ── Phase 3 登记方法（capability-map 64 方法收口）：真实现 3 个（wasm 有对应导出，
-        //   命名映射），其余如实 unsupported——能力表不声明，静态判定拦截 ──
-        boundingBox(shape) { return kernel.getBoundingBox(asNum(shape)); },
-        surfaceCenterOfMass(face) { return kernel.getSurfaceCenterOfMass(asNum(face)); },
-        dispose(_shape) { },
-        shapeType(_shape) { return unsupported('shapeType'); },
-        isNull(_shape) { return unsupported('isNull'); },
-        iterShapes(_shape) { return unsupported('iterShapes'); },
-        locate(_shape, _matrix) { return unsupported('locate'); },
-        copyShape(_shape) { return unsupported('copyShape'); },
-        downcast(_shape, _targetType) { return unsupported('downcast'); },
-        composeTransform(_m1, _m2) { return unsupported('composeTransform'); },
-        buildExtrusionLaw(_profile, _length, _endFactor) { return unsupported('buildExtrusionLaw'); },
-        buildEdgeOnSurface(_curve, _surface) { return unsupported('buildEdgeOnSurface'); },
-        healFace(_shape, _tolerance) { return unsupported('healFace'); },
-        healWire(_shape, _tolerance) { return unsupported('healWire'); },
-        fixSelfIntersection(_wire) { return unsupported('fixSelfIntersection'); },
-        hullFromPoints(_points, _tolerance) { return unsupported('hullFromPoints'); },
-        loftAdvanced(_wires, _options) { return unsupported('loftAdvanced'); },
-        makeEllipsoid(rx, ry, rz) { return asHandle(kernel.makeEllipsoid(rx, ry, rz)); }, // Phase 3: wasm 同签名真实现（brepkit-wasm.d.ts:1354）
-        makeFaceOnSurface(_face, _wire) { return unsupported('makeFaceOnSurface'); },
-        makeTorus(majorRadius, minorRadius) { return asHandle(kernel.makeTorus(majorRadius, minorRadius, 64)); }, // Phase 3: wasm 真实现（segments 固定 64，BrepEngineApi 不暴露）
-        makeVertex(x, y, z) { return asHandle(kernel.makeVertex(x, y, z)); }, // Phase 3: wasm 同签名真实现
-        makeWireFromMixed(_items) { return unsupported('makeWireFromMixed'); },
-        mirror(shape, point, normal) { return asHandle(kernel.mirror(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z)); }, // Phase 3: wasm 真实现
-        revolveVec(_shape, _center, _direction, _angleDeg) { return unsupported('revolveVec'); },
-        sew(_shapes, _tolerance) { return unsupported('sew'); },
-        shell(solid, facesToRemove, thickness, _tolerance) { return asHandle(kernel.shell(asNum(solid), thickness, Uint32Array.from(facesToRemove.map(asNum)))); }, // Phase 3: wasm 真实现（tolerance 忽略）
-        simplePipe(_profile, _spine) { return unsupported('simplePipe'); },
-        simplify(_shape) { return unsupported('simplify'); },
-        split(_shape, _tools) { return unsupported('split'); }, // ⚠️ wasm split 是平面分割（solid+平面参数），与 BrepEngineApi 工具实体分割语义不匹配 → 保持 unsupported
-        sweepPipeShell(_profile, _spine, _freenet, _smooth) { return unsupported('sweepPipeShell'); },
-        generalTransformNonOrthogonal(_shape, _matrix) { return unsupported('generalTransformNonOrthogonal'); },
-        generalTransformWithHistory(_shape, _matrix, _inputFaceHashes, _hashUpperBound) { return unsupported('generalTransformWithHistory'); },
-        applyComposedTransformWithHistory(_shape, _matrix, _inputFaceHashes, _hashUpperBound) { return unsupported('applyComposedTransformWithHistory'); },
     };
     return api;
 }
@@ -647,14 +830,23 @@ function vec3Of(p) {
         return { x: p[0], y: p[1], z: p[2] };
     return { x: Number(p.x), y: Number(p.y), z: Number(p.z) };
 }
-/** base64 解码（node 与浏览器通用，避免直接依赖 Buffer）。 */
-function atobPolyfill(s) {
-    if (typeof atob === 'function')
-        return atob(s);
-    return Buffer.from(s, 'base64').toString('binary');
-}
-/** 释放内核单例（测试收尾用；宿主常驻不需调用）。 */
+/** 已初始化的 brepkit 内核单例（createBrepkitPrimitives 时赋值）。 */
 let liveKernel = null;
+/**
+ * 原生 brepkit 内核面（D3）：平台特定代码访问 brepkit 独有能力的唯一入口
+ * （chamfer2d/chamferV2/filletV2/sketch* 族、serializeSolid、meshBoolean 等）。
+ *
+ * ⚠️ 这是**平台特定**出口——import 本函数即声明「这段代码只跑在 brepkit 引擎下」。
+ * 可移植代码请用 `getBrepApi()`（L1 契约面）。
+ *
+ * @returns the live brepkit wasm kernel singleton.
+ */
+export function getBrepkitKernel() {
+    if (!liveKernel) {
+        throw new Error('[brepkit-kernel] kernel not initialized: call createBrepkitPrimitives() first');
+    }
+    return liveKernel;
+}
 /** 释放内核单例（测试收尾用；宿主常驻不需调用）。 */
 export function disposeBrepkit() {
     try {