@faicad/faijs 0.16.1 → 0.18.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 = '';
@@ -93,21 +102,30 @@ function mapEvolution(kernel, raw, resultHandle, inputFaceHashes, hashUpperBound
     // raw: {solid, evolution:{modified:{oldHandle:[newHandles]}, generated:{oldHandle:[new]}, deleted:[oldHandles]}}
     const parsed = JSON.parse(raw);
     const evo = parsed.evolution ?? { modified: {}, generated: {}, deleted: [] };
-    const modifiedKeys = new Set(Object.keys(evo.modified ?? {}).map(Number));
     const deletedKeys = new Set((evo.deleted ?? []).map(Number));
-    // 输入面 hash → 是否被改/删：通过该输入面在输入 hash 快照中的位置无法直接回溯句柄，
-    // 诚实映射：modified/deleted 用"发生变化的输入句柄数 == 输入面数"的对齐近似——
-    // v1 精确溯源依赖 per-shape hash 注册表（subShapeHashes 时登记 hash↔handle）。
+    // registry 登记的是 hash→handle（输入面）。下游 decodeEvolution/decodeHashEvolution 期望
+    // modified 为 OCCT 分段格式 [inHash, count, outHash1, outHash2, ...]（见 face-evolution.ts），
+    // 不是扁平 hash 列表——GOTCHA：曾误返回扁平列表，把 modified[1]（一个 hash ~1e9）当成
+    // count，导致 decodeHashEvolution 空转 17 亿次 push 抛 "Invalid array length"（2026-09-26 实证）。
+    // 故这里反向建 handle→hash 表，逐条目拼出 [inHash, outCount, ...outHashes]。
     const registry = hashRegistry.get(kernel);
+    const handleToHash = new Map();
+    if (registry)
+        for (const [h, handle] of registry)
+            handleToHash.set(handle, h);
     const modified = [];
     const deleted = [];
-    if (registry) {
-        for (const [hash, handle] of registry) {
-            if (modifiedKeys.has(handle))
-                modified.push(hash);
-            if (deletedKeys.has(handle))
-                deleted.push(hash);
-        }
+    for (const oldHandle of deletedKeys) {
+        const h = handleToHash.get(oldHandle);
+        if (h !== undefined)
+            deleted.push(h);
+    }
+    for (const [oldHandleStr, newHandles] of Object.entries(evo.modified ?? {})) {
+        const inHash = handleToHash.get(Number(oldHandleStr));
+        if (inHash === undefined)
+            continue;
+        const outHashes = newHandles.map((nh) => faceFingerprint(kernel, nh, hashUpperBound));
+        modified.push(inHash, outHashes.length, ...outHashes);
     }
     // generated：结果实体的新面 hash（数量按 generated 表展开）
     const generated = [];
@@ -128,9 +146,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,9 +192,45 @@ 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();
+    // GOTCHA（2026-09-26 非实体句柄修复）：brepkit 的 tessellateSolidGrouped / getSolidFaces
+    // 等 *Solid API 只吃 solid 句柄，传 face/wire/edge/compound 即抛
+    // "invalid solid handle: index N out of bounds"。而 brepkit **没有 shape-type 分类 API**
+    // （getFaceEdges(solid) 不抛错、会返回某一面的边，不能 try/catch 探测）。故 meshShape
+    // 必须靠这组「已知句柄集合」在执行前静态分发，而不是运行时探测：
+    //   knownFaces   → tessellateFace（JsMesh）
+    //   knownWires   → getWireEdges + tessellateEdge 逐边采样成线段
+    //   knownEdges   → tessellateEdge 直接采样成线段（wire.ts smooth 路径 interpolatePoints 返回 edge）
+    //   knownCompounds→ 逐子句柄按其类型 tessellate 后合并（sectionByPlane 面组 / importStep 多实体）
+    // 不在任何集合里的句柄一律按 solid 走 tessellateSolidGrouped（实体创建不入集合，天然落此路径）。
+    const knownWires = new Set();
+    const knownEdges = new Set();
+    // GOTCHA: getSolidFaces returns GLOBAL face indices (0..5, 6..11, ...) that collide
+    // with solid handles (per-type namespace). Enumerated sub-faces must NOT pollute
+    // knownFaces, else measuring a later solid whose handle number equals an old
+    // enumerated face gets mis-tessellated as a face. derivedFaces is consulted ONLY by
+    // getSubShapes edge/vertex drilling, never by meshShape/getBoundingBox.
+    const derivedFaces = new Set();
+    // 虚拟 compound 句柄计数器（非实体子句柄不进内核 makeCompound，见 makeCompound GOTCHA）。
+    const knownCompounds = new Map();
+    let virtualCompoundCounter = 0;
+    // GOTCHA（2026-09-26）：brepkit 句柄按**类型分命名空间**——solid/face/wire/edge 各自从 0 计数
+    // （实测 edge=wire=face=solid=0 可共存）。因此「某编号 N 在 knownFaces」与「某编号 N 是 solid」
+    // 并不互斥：新 solid 恰好复用了早先某 face 的编号时，knownFaces.has(N) 会把 solid 误判成 face
+    // （实测 box makeBox 返回 solid 2，撞 profile 早先的 face 2 → cloneShape 走 copyFace 崩溃）。
+    // 建 solid 时必须从 knownFaces/knownWires/knownEdges/derivedFaces 抹掉该编号，让默认 solid 路径生效。
+    // derivedFaces 也必须清：getSubShapes(solid,'edge') 会查 derivedFaces.has(s) 误走 getFaceEdges。
+    const markSolid = (h) => {
+        knownFaces.delete(h);
+        knownWires.delete(h);
+        knownEdges.delete(h);
+        knownCompounds.delete(h);
+        derivedFaces.delete(h);
+        return h;
+    };
     const readFallback = () => {
         try {
             return typeof kernel.meshFallbackCount === 'function' ? Number(kernel.meshFallbackCount()) : 0;
@@ -151,9 +241,174 @@ 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)));
+    };
+    /** 单个 face → BrepMeshResult（tessellateFace）。 */
+    const faceMesh = (f, deflection, angular) => {
+        const jm = kernel.tessellateFace(f, deflection, angular);
+        const positions = arr(jm.positions);
+        const normals = arr(jm.normals);
+        const indices = arr(jm.indices);
+        const triCount = jm.triangleCount > 0 ? jm.triangleCount : indices.length / 3;
+        return {
+            positions: new Float32Array(positions),
+            normals: new Float32Array(normals),
+            indices: new Uint32Array(indices),
+            vertexCount: positions.length / 3,
+            triangleCount: triCount,
+            faceGroups: new Int32Array([0, triCount, faceFingerprint(kernel, f, 1e9)]),
+            faceCount: 1,
+        };
+    };
+    /** 一组 edge 句柄 → 线段 mesh（positions 为采样点、indices 为端点对）。 */
+    // GOTCHA：tessellateEdge(edge, N) 返回扁平 [x,y,z,...] 采样点（NURBS 才采样 N 点，
+    // 直线边只回端点），不是三角网格；wire/curve 显示吃「端点对」索引（与 mesh 路径 wireMesh 同构）。
+    const edgesToLineMesh = (edgeHandles, deflection) => {
+        const positions = [];
+        const indices = [];
+        // 采样密度：按 deflection 粗采样即可（1D 线框显示，非精确几何）。
+        const nPts = Math.max(12, Math.round(4 / Math.max(deflection, 0.01)));
+        for (const e of edgeHandles) {
+            const pts = arr(kernel.tessellateEdge(e, nPts));
+            const base = positions.length / 3;
+            for (let i = 0; i < pts.length; i++)
+                positions.push(pts[i]);
+            const verts = pts.length / 3;
+            for (let i = 0; i < verts - 1; i++)
+                indices.push(base + i, base + i + 1);
+        }
+        return {
+            positions: new Float32Array(positions),
+            normals: new Float32Array(positions.length),
+            indices: new Uint32Array(indices),
+            vertexCount: positions.length / 3,
+            triangleCount: 0,
+            faceGroups: new Int32Array(0),
+            faceCount: 0,
+        };
+    };
+    /** wire → 线段 mesh（getWireEdges 取边集后逐边采样）。 */
+    const wireMesh = (wire, deflection) => {
+        const edges = arr(kernel.getWireEdges(wire));
+        return edgesToLineMesh(edges, deflection);
+    };
+    /** solid → BrepMeshResult（tessellateSolidGrouped，原 meshShape 实体路径抽出）。 */
+    const solidMesh = (solid, deflection, angular) => {
+        const raw = kernel.tessellateSolidGrouped(solid, deflection, angular);
+        const m = JSON.parse(raw);
+        // faceOffsets 形如 [start0, start1, ..., totalEnd]：以「索引数组单位」计的每面偏移（2026-09-19 实测），
+        // 除以 3 换算为 faijs 契约的三角形单位 [triStart, triCount, faceHash]
+        const fo = m.faceOffsets;
+        const faceCount = Math.max(0, fo.length - 1);
+        const faceHashes = [];
+        try {
+            const faces = arr(kernel.getSolidFaces(solid));
+            for (let i = 0; i < faceCount && i < faces.length; i++)
+                faceHashes.push(faceFingerprint(kernel, faces[i], 1e9));
+        }
+        catch { /* 非实体：faceHash 置 0 */ }
+        const faceGroups = new Int32Array(faceCount * 3);
+        for (let i = 0; i < faceCount; i++) {
+            faceGroups[i * 3] = fo[i] / 3;
+            faceGroups[i * 3 + 1] = (fo[i + 1] - fo[i]) / 3;
+            faceGroups[i * 3 + 2] = faceHashes[i] ?? 0;
+        }
+        return {
+            positions: new Float32Array(m.positions),
+            normals: new Float32Array(m.normals),
+            indices: new Uint32Array(m.indices),
+            vertexCount: m.positions.length / 3,
+            triangleCount: m.indices.length / 3,
+            faceGroups,
+            faceCount,
+        };
+    };
+    /** compound → 逐子句柄 tessellate 后合并（sectionByPlane 面组 / importStep 多实体）。 */
+    const compoundMesh = (children, deflection, angular) => {
+        const positions = [];
+        const normals = [];
+        const indices = [];
+        const faceGroups = [];
+        let triOffset = 0;
+        for (const c of children) {
+            let sub;
+            if (knownFaces.has(c)) {
+                sub = faceMesh(c, deflection, angular);
+            }
+            else if (knownWires.has(c)) {
+                sub = wireMesh(c, deflection);
+            }
+            else if (knownEdges.has(c)) {
+                sub = edgesToLineMesh([c], deflection);
+            }
+            else {
+                // 子句柄按 solid 处理（importStep 多实体 / makeCompound(solids)）。
+                sub = solidMesh(c, deflection, angular);
+            }
+            const vOffset = positions.length / 3;
+            for (let i = 0; i < sub.positions.length; i++)
+                positions.push(sub.positions[i]);
+            for (let i = 0; i < sub.normals.length; i++)
+                normals.push(sub.normals[i] ?? 0);
+            for (let i = 0; i < sub.indices.length; i++)
+                indices.push(sub.indices[i] + vOffset);
+            if (sub.faceGroups) {
+                for (let i = 0; i < sub.faceGroups.length; i += 3) {
+                    faceGroups.push((sub.faceGroups[i] ?? 0) + triOffset, sub.faceGroups[i + 1] ?? 0, sub.faceGroups[i + 2] ?? 0);
+                }
+            }
+            triOffset += sub.triangleCount;
+        }
+        return {
+            positions: new Float32Array(positions),
+            normals: new Float32Array(normals),
+            indices: new Uint32Array(indices),
+            vertexCount: positions.length / 3,
+            triangleCount: indices.length / 3,
+            faceGroups: new Int32Array(faceGroups),
+            faceCount: faceGroups.length / 3,
+        };
+    };
+    // ── 按句柄类型深拷贝（transform/copy 族分发用） ──
+    // GOTCHA：brepkit copySolid/copyFace/copyWire 三者入参严格对应 solid/face/wire 句柄，
+    // 传错即崩溃；transformSolid/transformFace/transformWire 均为「原地修改」void。
+    // place/translate 等会作用在 profile 产出的 face 上（sew 用例 place 两张 face），
+    // 故必须按 knownFaces/knownWires 分发，不能一律 copySolid。
+    const cloneShape = (shape) => {
+        if (knownFaces.has(shape)) {
+            const c = kernel.copyFace(shape);
+            knownFaces.add(c);
+            return c;
+        }
+        if (knownWires.has(shape)) {
+            const c = kernel.copyWire(shape);
+            knownWires.add(c);
+            return c;
+        }
+        return markSolid(kernel.copySolid(shape));
+    };
+    /** 深拷贝 + 原地仿射变换（matrix 已经 toKernelMatrix 归一为 16 元素 4×4）。 */
+    const cloneAndTransform = (shape, matrix16) => {
+        const c = cloneShape(shape);
+        const m = Float64Array.from(matrix16);
+        if (knownFaces.has(c))
+            kernel.transformFace(c, m);
+        else if (knownWires.has(c))
+            kernel.transformWire(c, m);
+        else
+            kernel.transformSolid(c, m);
+        return c;
+    };
     const api = {
         // ── 生命周期 ──
         release(_shape) { },
+        dispose(_shape) { },
         /** 内核级诊断：距上次读取的 mesh 布尔回退计数差（>0 = BREP 链已中断）。 */
         getMeshFallbackCount() {
             const now = readFallback();
@@ -162,49 +417,125 @@ export async function createBrepkitPrimitives() {
             return delta;
         },
         // ── 实体图元 ──
-        makeBox(dx, dy, dz) { return asHandle(kernel.makeBox(dx, dy, dz)); },
+        makeBox(dx, dy, dz) { return asHandle(markSolid(kernel.makeBox(dx, dy, dz))); },
         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)))));
+            const h = markSolid(kernel.makeBox(dx, dy, dz));
+            // ⚠️ 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'); },
+        makeCylinder(radius, height) { return asHandle(markSolid(kernel.makeCylinder(radius, height))); },
+        makeSphere(radius) { return asHandle(markSolid(kernel.makeSphere(radius, 32))); },
+        makeCone(r1, r2, height) { return asHandle(markSolid(kernel.makeCone(r1, r2, height))); },
+        makeRectangle(width, height) {
+            const f = kernel.makeRectangle(width, height);
+            knownFaces.add(f);
+            return asHandle(f);
+        },
+        makeEllipsoid(rx, ry, rz) { return asHandle(markSolid(kernel.makeEllipsoid(rx, ry, rz))); },
+        makeTorus(majorRadius, minorRadius) { return asHandle(markSolid(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(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)));
+        },
+        sew(shapesList, tolerance) {
+            return asHandle(kernel.sewFaces(Uint32Array.from(shapesList.map(asNum)), tolerance ?? 1e-6));
+        },
+        sewAndSolidify(faces, _tolerance) {
+            // brepkit 的 makeSolid 即「缝合并固化成实体」（sewFaces + 建 solid）。
+            return asHandle(markSolid(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)))));
-        },
-        // ── 倒角与圆角 ──
+        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))))); },
+        common(a, b) {
+            // brepkit 无 `common` 原生名；交集语义由 `intersect` 承担（method-map: dialect）。
+            return asHandle(markSolid(trackFallback(kernel.intersect(asNum(a), asNum(b)))));
+        },
+        intersect(a, b) { return asHandle(trackFallback(kernel.intersect(asNum(a), asNum(b)))); },
+        fuseAll(shapesList) {
+            return asHandle(markSolid(trackFallback(kernel.fuseAll(Int32Array.from(shapesList.map(asNum))))));
+        },
+        sectionByPlane(shape, point, normal) {
+            // brepkit 原生 section(solid, plane) 返回剖面 face 句柄组（§3.6-2 新中立名）。
+            // GOTCHA：brepkit section 返回的是 **face** 句柄（不是 edge/wire），必须登记进 knownFaces，
+            // 否则 op 层 makeCompound(这些 face) 后送 meshShape 会按 solid 路径崩溃。
+            const s = asNum(shape);
+            const faces = arr(kernel.section(s, point.x, point.y, point.z, normal.x, normal.y, normal.z));
+            for (const f of faces)
+                knownFaces.add(f);
+            return faces.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;
+            markSolid(a);
+            markSolid(b);
+            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 实证）。
@@ -212,39 +543,40 @@ export async function createBrepkitPrimitives() {
         // brepkit transformSolid 吃 4×4 行主序 16 元素。所有 transformSolid 调用一律经
         // toKernelMatrix 归一（下方唯一转换点），禁止直出 16 元素旁路。
         translate(shape, dx, dy, dz) {
-            const c = kernel.copySolid(asNum(shape));
-            kernel.transformSolid(c, toKernelMatrix(translationMatrix(dx, dy, dz)));
-            return asHandle(c);
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(translationMatrix(dx, dy, dz))));
         },
         scale(shape, center, factor) {
-            const c = kernel.copySolid(asNum(shape));
-            kernel.transformSolid(c, toKernelMatrix(scaleMatrix(center, factor)));
-            return asHandle(c);
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(scaleMatrix(center, factor))));
         },
         transform(shape, matrix) {
-            const c = kernel.copySolid(asNum(shape));
-            kernel.transformSolid(c, toKernelMatrix(matrix));
-            return asHandle(c);
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
         },
         located(shape, matrix) {
-            const c = kernel.copySolid(asNum(shape));
-            kernel.transformSolid(c, toKernelMatrix(matrix));
-            return asHandle(c);
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
+        },
+        locate(shape, matrix) {
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
         },
         generalTransform(shape, matrix) {
-            const c = kernel.copySolid(asNum(shape));
-            kernel.transformSolid(c, toKernelMatrix(matrix));
-            return asHandle(c);
+            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
         },
-        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 拆成数组。
+        copy(shape) { return asHandle(cloneShape(asNum(shape))); },
+        copyShape(shape) { return asHandle(cloneShape(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 测试用整圆）。
@@ -256,62 +588,145 @@ export async function createBrepkitPrimitives() {
         },
         // ── 曲线构造 ──
         makeLineEdge(start, end) {
-            return asHandle(kernel.makeLineEdge(start.x, start.y, start.z, end.x, end.y, end.z));
+            const e = kernel.makeLineEdge(start.x, start.y, start.z, end.x, end.y, end.z);
+            knownEdges.add(e);
+            return asHandle(e);
+        },
+        makeArcEdge(start, mid, end) {
+            // 方言消化：occt 吃 3 点；brepkit makeCircleArc3d 吃 (start,end,center,axis)。
+            const { center, axis } = circumcircle(start, mid, end);
+            const e = 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);
+            knownEdges.add(e);
+            return asHandle(e);
+        },
+        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];
+            const e = kernel.makeNurbsEdge(first.x, first.y, first.z, last.x, last.y, last.z, degree, knots, flattenPoints(controlPoints), weights);
+            knownEdges.add(e);
+            return asHandle(e);
+        },
+        makeCircleEdge(center, normal, radius) {
+            const e = kernel.makeCircleEdge(center.x, center.y, center.z, normal.x, normal.y, normal.z, radius);
+            knownEdges.add(e);
+            return asHandle(e);
         },
-        makeArcEdge(_start, _mid, _end) { return unsupported('makeArcEdge'); },
-        makeBezierEdge(_controlPoints) { return unsupported('makeBezierEdge'); },
         // ── 拓扑构造 ──
         makeWire(edges) {
-            return asHandle(kernel.makeWire(Int32Array.from(edges.map(asNum)), false));
+            const w = kernel.makeWire(Int32Array.from(edges.map(asNum)), false);
+            knownWires.add(w);
+            return asHandle(w);
         },
-        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) {
+            const kids = arr(shapesList.map(asNum));
+            // GOTCHA（2026-09-26）：brepkit makeCompound 只接受 **solid** 句柄——把 face/wire
+            // （sectionByPlane 截面面组）塞进去即抛 "invalid solid handle"。非实体子句柄时
+            // 不调内核，改用高段虚拟句柄（0x80000000+），仅靠 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 = 0x80000000 + virtualCompoundCounter;
+                knownCompounds.set(v, kids);
+                return asHandle(v);
+            }
+            const c = kernel.makeCompound(Int32Array.from(kids));
+            knownCompounds.set(c, kids);
+            return asHandle(c);
         },
-        buildTriFace(_a, _b, _c) { return unsupported('buildTriFace'); },
         addHolesInFace(face, holeWires) {
-            return asHandle(kernel.addHolesToFace(asNum(face), Int32Array.from(holeWires.map(asNum))));
+            // addHolesToFace 返回**新 face 句柄**（同曲面 + 内孔 wire），必须登记进 knownFaces，
+            // 否则 profile(op) 带孔面送 meshShape 会落到 solid 路径崩溃。
+            const f = kernel.addHolesToFace(asNum(face), Int32Array.from(holeWires.map(asNum)));
+            knownFaces.add(f);
+            return asHandle(f);
+        },
+        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;
             const angular = options?.angularDeflection ?? 0.5;
-            const raw = kernel.tessellateSolidGrouped(asNum(shape), deflection, angular);
-            const m = JSON.parse(raw);
-            // faceOffsets 形如 [start0, start1, ..., totalEnd]：以「索引数组单位」计的每面偏移（2026-09-19 实测），
-            // 除以 3 换算为 faijs 契约的三角形单位 [triStart, triCount, faceHash]
-            const fo = m.faceOffsets;
-            const faceCount = Math.max(0, fo.length - 1);
-            const faceHashes = [];
-            try {
-                const faces = arr(kernel.getSolidFaces(asNum(shape)));
-                for (let i = 0; i < faceCount && i < faces.length; i++)
-                    faceHashes.push(faceFingerprint(kernel, faces[i], 1e9));
-            }
-            catch { /* 非实体：faceHash 置 0 */ }
-            const faceGroups = new Int32Array(faceCount * 3);
-            for (let i = 0; i < faceCount; i++) {
-                faceGroups[i * 3] = fo[i] / 3;
-                faceGroups[i * 3 + 1] = (fo[i + 1] - fo[i]) / 3;
-                faceGroups[i * 3 + 2] = faceHashes[i] ?? 0;
-            }
-            return {
-                positions: new Float32Array(m.positions),
-                normals: new Float32Array(m.normals),
-                indices: new Uint32Array(m.indices),
-                vertexCount: m.positions.length / 3,
-                triangleCount: m.indices.length / 3,
-                faceGroups,
-                faceCount,
-            };
+            const s = asNum(shape);
+            // 非实体句柄按已知集合静态分发（见文件头 GOTCHA：brepkit 无 shape-type 分类 API）。
+            // 顺序：face → wire → edge → compound → solid。实体创建不入任何集合，天然落 solid 路径。
+            if (knownFaces.has(s))
+                return faceMesh(s, deflection, angular);
+            if (knownWires.has(s))
+                return wireMesh(s, deflection);
+            if (knownEdges.has(s))
+                return edgesToLineMesh([s], deflection);
+            const compoundChildren = knownCompounds.get(s);
+            if (compoundChildren)
+                return compoundMesh(compoundChildren, deflection, angular);
+            // solid（或未登记句柄）：走原 tessellateSolidGrouped 路径。
+            return solidMesh(s, deflection, angular);
         },
         wireframe(shape, deflection) {
             const d = deflection ?? 0.1;
+            const s = asNum(shape);
+            // GOTCHA：meshEdgesAll 是 solid-only API——buildTopologyFromMesh 会对 face/wire/edge
+            // 产物调 wireframe(...)，传入非实体句柄即抛 "invalid solid handle"。按已知集合分发：
+            // face -> getFaceEdges；wire -> getWireEdges；edge -> [self]；否则 solid 走 meshEdgesAll。
+            let edgeHandles = null;
+            if (knownFaces.has(s))
+                edgeHandles = arr(kernel.getFaceEdges(s));
+            else if (knownWires.has(s))
+                edgeHandles = arr(kernel.getWireEdges(s));
+            else if (knownEdges.has(s))
+                edgeHandles = [s];
+            else if (knownCompounds.has(s)) {
+                // compound（sectionByPlane 面组）：逐子面收集边。
+                edgeHandles = [];
+                for (const k of knownCompounds.get(s)) {
+                    if (knownFaces.has(k))
+                        edgeHandles.push(...arr(kernel.getFaceEdges(k)));
+                    else if (knownWires.has(k))
+                        edgeHandles.push(...arr(kernel.getWireEdges(k)));
+                    else if (knownEdges.has(k))
+                        edgeHandles.push(k);
+                }
+            }
+            if (edgeHandles) {
+                const nPts = Math.max(12, Math.round(4 / Math.max(d, 0.01)));
+                const positions = [];
+                const offsets = [0];
+                for (const e of edgeHandles) {
+                    const pts = arr(kernel.tessellateEdge(e, nPts));
+                    for (const p of pts)
+                        positions.push(p);
+                    offsets.push(positions.length / 3);
+                }
+                const edgeGroups = new Int32Array(edgeHandles.length * 3);
+                for (let i = 0; i < edgeHandles.length; i++) {
+                    edgeGroups[i * 3] = offsets[i] ?? 0;
+                    edgeGroups[i * 3 + 1] = (offsets[i + 1] ?? positions.length / 3) - (offsets[i] ?? 0);
+                    edgeGroups[i * 3 + 2] = i;
+                }
+                return { points: new Float32Array(positions), edgeGroups, pointCount: positions.length / 3, edgeCount: edgeHandles.length };
+            }
+            // solid（或未登记句柄）：走原 meshEdgesAll 路径。
             // JsEdgeLines：edgeCount/offsets/positions 均为属性（offsets/positions 为 TypedArray，2026-09-19 实测）
-            const me = kernel.meshEdgesAll(asNum(shape), d, 0.5);
+            const me = kernel.meshEdgesAll(s, d, 0.5);
             const edgeCount = Number(me.edgeCount);
             const offsets = arr(me.offsets);
             const positions = arr(me.positions);
@@ -334,9 +749,52 @@ export async function createBrepkitPrimitives() {
         // edge/vertex 查询时按句柄是否在 knownFaces 里分发到 face 级或 solid 级 API。
         getSubShapes(shape, type) {
             const s = asNum(shape);
+            // GOTCHA（2026-09-26 非实体句柄修复）：buildTopologyFromMesh 会对**面产物**
+            // 调 getSubShapes(face,'face')。brepkit 的 getSolidFaces/getShellFaces 是 solid-only，
+            // 对面句柄一个抛 "invalid solid handle"、catch 里再抛 "invalid shell handle"——
+            // 两跳都不被捕获即崩溃。brepkit 无 shape-type 分类 API，必须靠已知集合先分发：
+            // 输入本身就是 knownFaces 里的一张面时，'face' 返回 [s]，edge/vertex 走 face 级 API。
+            if (knownFaces.has(s)) {
+                if (type === 'face')
+                    return [asHandle(s)];
+                if (type === 'edge') {
+                    const es = arr(kernel.getFaceEdges(s));
+                    es.forEach((e) => knownEdges.add(e));
+                    return es.map(asHandle);
+                }
+                if (type === 'vertex')
+                    return arr(kernel.getFaceVertices(s)).map(asHandle);
+                return [];
+            }
+            if (knownWires.has(s)) {
+                if (type === 'edge') {
+                    const es = arr(kernel.getWireEdges(s));
+                    es.forEach((e) => knownEdges.add(e));
+                    return es.map(asHandle);
+                }
+                return [];
+            }
+            if (knownEdges.has(s)) {
+                // input is itself an edge (wire.ts smooth path: interpolatePoints returns edge)
+                if (type === 'edge')
+                    return [asHandle(s)];
+                return [];
+            }
+            const compKids = knownCompounds.get(s);
+            if (compKids) {
+                // compound（sectionByPlane 面组 / makeCompound 多实体 / importStep 多实体）：
+                // 'face' 返回子面，'solid' 返回子实体，其余空。
+                if (type === 'face')
+                    return compKids.filter((k) => knownFaces.has(k)).map(asHandle);
+                if (type === 'solid')
+                    return compKids.filter((k) => !knownFaces.has(k) && !knownWires.has(k) && !knownEdges.has(k)).map(asHandle);
+                return [];
+            }
             let list;
+            const isFaceLike = knownFaces.has(s) || derivedFaces.has(s);
             if (type === 'face') {
-                // 输入可能是 solid 或 shell
+                // 输入可能是 solid 或 shell。枚举到的子面登记到 derivedFaces（不进 knownFaces，
+                // 避免与 solid 句柄撞号——见 derivedFaces 注释）。
                 try {
                     list = arr(kernel.getSolidFaces(s));
                 }
@@ -344,15 +802,15 @@ export async function createBrepkitPrimitives() {
                     list = arr(kernel.getShellFaces?.(s) ?? []);
                 }
                 for (const f of list)
-                    knownFaces.add(f);
+                    derivedFaces.add(f);
             }
             else if (type === 'edge') {
-                list = knownFaces.has(s)
+                list = isFaceLike
                     ? arr(kernel.getFaceEdges(s))
                     : arr(kernel.getSolidEdges(s));
             }
             else if (type === 'vertex') {
-                list = knownFaces.has(s)
+                list = isFaceLike
                     ? arr(kernel.getFaceVertices(s))
                     : arr(kernel.getSolidVertices(s));
             }
@@ -369,24 +827,27 @@ 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})`);
-            const faces = arr(kernel.getSolidFaces(asNum(shape)));
+                fail(`subShapeHashes(${type}): only 'face' is supported by brepkit`);
+            const s = asNum(shape);
+            // GOTCHA：buildTopologyFromMesh 会对面产物调 subShapeHashes(face,'face')；
+            // getSolidFaces 是 solid-only，对面句柄崩溃。输入本身是已知面时，哈希即其自身指纹。
+            if (knownFaces.has(s))
+                return [faceFingerprint(kernel, s, hashUpperBound)];
+            // wire/edge 无面；compound（sectionByPlane 面组）的子句柄即面。
+            if (knownWires.has(s) || knownEdges.has(s))
+                return [];
+            const compKids = knownCompounds.get(s);
+            if (compKids) {
+                const faces = compKids.filter((k) => knownFaces.has(k));
+                return faces.map((f) => faceFingerprint(kernel, f, hashUpperBound));
+            }
+            const faces = arr(kernel.getSolidFaces(s));
             const hashes = faces.map(f => faceFingerprint(kernel, f, hashUpperBound));
             // 登记 hash↔handle（fuseWithHistory 溯源对齐依赖此表）
             const reg = hashRegistry.get(kernel) ?? new Map();
@@ -406,6 +867,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 +885,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 +953,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,39 +972,181 @@ export async function createBrepkitPrimitives() {
             catch { /* 非 Nurbs 边 */ }
             return null;
         },
+        interpolatePoints(points, degree) {
+            // GOTCHA：interpolatePoints 返回 **edge** 句柄（不是 wire）——wire.ts smooth 路径把它
+            // 直接当 wire 送 solidToShape。登记进 knownEdges，meshShape 才能走 tessellateEdge 路径。
+            const e = kernel.interpolatePoints(flattenPoints(points), degree);
+            knownEdges.add(e);
+            return asHandle(e);
+        },
+        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) {
+            // removeHolesFromFace 返回**新 face 句柄**（去掉内孔的同曲面 face），必须登记进 knownFaces。
+            const f = kernel.removeHolesFromFace(asNum(face));
+            knownFaces.add(f);
+            return asHandle(f);
+        },
+        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));
-            return { xmin: b[0], ymin: b[1], zmin: b[2], xmax: b[3], ymax: b[4], zmax: b[5] };
+            const s = asNum(shape);
+            const bboxFromPoints = (pts) => {
+                let xmin = Infinity, ymin = Infinity, zmin = Infinity, xmax = -Infinity, ymax = -Infinity, zmax = -Infinity;
+                for (let i = 0; i + 2 < pts.length; i += 3) {
+                    xmin = Math.min(xmin, pts[i]);
+                    ymin = Math.min(ymin, pts[i + 1]);
+                    zmin = Math.min(zmin, pts[i + 2]);
+                    xmax = Math.max(xmax, pts[i]);
+                    ymax = Math.max(ymax, pts[i + 1]);
+                    zmax = Math.max(zmax, pts[i + 2]);
+                }
+                if (!Number.isFinite(xmin)) {
+                    xmin = ymin = zmin = 0;
+                    xmax = ymax = zmax = 0;
+                }
+                return { xmin, ymin, zmin, xmax, ymax, zmax };
+            };
+            const solidBbox = (h) => {
+                const b = kernel.boundingBox(h);
+                return { xmin: b[0], ymin: b[1], zmin: b[2], xmax: b[3], ymax: b[4], zmax: b[5] };
+            };
+            const kids = knownCompounds.get(s);
+            if (kids) {
+                let xmin = Infinity, ymin = Infinity, zmin = Infinity, xmax = -Infinity, ymax = -Infinity, zmax = -Infinity;
+                for (const k of kids) {
+                    try {
+                        let b;
+                        if (knownFaces.has(k))
+                            b = bboxFromPoints(arr(kernel.tessellateFace(k, 0.1, 1).positions));
+                        else if (knownWires.has(k))
+                            b = bboxFromPoints(arr(kernel.getWireEdges(k)).flatMap((e) => arr(kernel.tessellateEdge(e, 16))));
+                        else if (knownEdges.has(k))
+                            b = bboxFromPoints(arr(kernel.tessellateEdge(k, 16)));
+                        else
+                            b = solidBbox(k);
+                        xmin = Math.min(xmin, b.xmin);
+                        ymin = Math.min(ymin, b.ymin);
+                        zmin = Math.min(zmin, b.zmin);
+                        xmax = Math.max(xmax, b.xmax);
+                        ymax = Math.max(ymax, b.ymax);
+                        zmax = Math.max(zmax, b.zmax);
+                    }
+                    catch { /* 子项 bbox 查询失败忽略 */ }
+                }
+                if (!Number.isFinite(xmin)) {
+                    xmin = ymin = zmin = 0;
+                    xmax = ymax = zmax = 0;
+                }
+                return { xmin, ymin, zmin, xmax, ymax, zmax };
+            }
+            // GOTCHA：kernel.boundingBox 是 solid-only。face/wire/edge 句柄必须走 tessellation 采样，
+            // 否则 measure() 对 wire/profile 调 getBoundingBox 即崩 "invalid solid handle"。
+            if (knownFaces.has(s))
+                return bboxFromPoints(arr(kernel.tessellateFace(s, 0.1, 1).positions));
+            if (knownWires.has(s))
+                return bboxFromPoints(arr(kernel.getWireEdges(s)).flatMap((e) => arr(kernel.tessellateEdge(e, 16))));
+            if (knownEdges.has(s))
+                return bboxFromPoints(arr(kernel.tessellateEdge(s, 16)));
+            return solidBbox(s);
         },
         getVolume(shape) { return Number(kernel.volume(asNum(shape), 0.05)); },
         getCenterOfMass(shape) {
             // 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 +1155,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 +1202,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 {