@faicad/faijs 0.13.0

package/dist/brep/face-evolution.js

@@ -0,0 +1,408 @@
+/**
+ * 面演化（face evolution）工具：hash 映射 ↔ ordinal 映射转换
+ *
+ * See docs/api-contract.md §11 (topology contract) for face evolution context.
+ *
+ * occt-wasm 的 *WithHistory API 返回 BrepEvolutionData，其中 modified/generated
+ * 用面 hash（内存指针哈希）编码。本模块将其解码为 ordinal 映射（面枚举序号），
+ * 可安全持久化进 faijs 文本。
+ *
+ * 核心原理（分析文档 §4.4）：
+ * getSubShapes(shape,'face')[i] ↔ subShapeHashes(shape,'face',B)[i] 一一对应
+ * 因此可以把 hash 映射无损转换为 ordinal 映射。
+ */
+/** hash 上界（与 occt-wasm kernel.cpp 一致：`% 2147483647`） */
+export const HASH_UPPER_BOUND = 2147483647;
+/**
+ * Collect the hash list of all faces of a shape (via subShapeHashes; efficient, no handles allocated).
+ * @param kernel - the OCCT kernel.
+ * @param shape - the shape whose face hashes to collect.
+ * @returns the array of face hashes.
+ */
+export function getFaceHashes(kernel, shape) {
+    return Array.from(kernel.subShapeHashes(shape, 'face', HASH_UPPER_BOUND));
+}
+/**
+ * Collect the union of face hashes of two shapes (for WithHistory calls of binary boolean operations).
+ *
+ * Analysis doc §4.2: fuse/cut/intersect must pass subShapeHashes(A) ∪ subShapeHashes(B)
+ * to track both inputs' face evolution.
+ * @param kernel - the OCCT kernel.
+ * @param shapeA - the first input shape.
+ * @param shapeB - the second input shape.
+ * @returns the union of the two shapes' face hashes.
+ */
+export function getUnionFaceHashes(kernel, shapeA, shapeB) {
+    const hashesA = getFaceHashes(kernel, shapeA);
+    const hashesB = getFaceHashes(kernel, shapeB);
+    return [...new Set([...hashesA, ...hashesB])];
+}
+/**
+ * 解码 BrepEvolutionData 的 modified 数组为 ordinal 映射。
+ *
+ * modified 分段编码格式：[inputHash, count, outHash1, outHash2, ...] × N
+ *
+ * @param kernel      the OCCT kernel.
+ * @param evo         the BrepEvolutionData (from a *WithHistory API).
+ * @param inputShape  the input shape (for the input face hash → ordinal mapping).
+ * @param resultShape the result shape (for the output face hash → ordinal mapping).
+ * @returns the FaceEvolution: inOrdinal → outOrdinal[].
+ */
+export function decodeEvolution(kernel, evo, inputShape, resultShape) {
+    const inputHashes = getFaceHashes(kernel, inputShape);
+    const resultHashes = getFaceHashes(kernel, resultShape);
+    // 构建 hash → ordinal 查找表
+    const resultHashToOrdinal = new Map();
+    for (let i = 0; i < resultHashes.length; i++) {
+        resultHashToOrdinal.set(resultHashes[i], i);
+    }
+    const inputHashToOrdinal = new Map();
+    for (let i = 0; i < inputHashes.length; i++) {
+        inputHashToOrdinal.set(inputHashes[i], i);
+    }
+    // 解码 modified 数组
+    const evolution = new Map();
+    const modified = evo.modified;
+    let idx = 0;
+    while (idx < modified.length) {
+        const inHash = modified[idx];
+        const count = modified[idx + 1];
+        const outOrdinals = [];
+        for (let j = 0; j < count; j++) {
+            const outHash = modified[idx + 2 + j];
+            const outOrdinal = resultHashToOrdinal.get(outHash);
+            if (outOrdinal !== undefined) {
+                outOrdinals.push(outOrdinal);
+            }
+        }
+        const inOrdinal = inputHashToOrdinal.get(inHash);
+        if (inOrdinal !== undefined) {
+            evolution.set(inOrdinal, outOrdinals);
+        }
+        idx += 2 + count;
+    }
+    return evolution;
+}
+/**
+ * 把 BrepEvolutionData 解码为 hash 键演化（§2.4）。
+ *
+ * modified 分段编码格式：[inHash, count, outHash1, ...] × N —— 本身就是
+ * hash→hash[] 的 1→多映射，直接按同一格式解出 hash 键版本，不需要
+ * getSubShapes 逐句柄 hashCode，也不分配任何句柄。
+ *
+ * generated 刻意不进 role 传播（§1.3 事实：occt 系 generated hash 指向中间形、
+ * 对布尔实测 0 个存活），生成面改由 DerivedFaceTopoRef 以 lineage 命名。
+ *
+ * @param evo - the BrepEvolutionData (from a *WithHistory API).
+ * @returns the hash-keyed evolution.
+ */
+export function decodeHashEvolution(evo) {
+    const modified = new Map();
+    const m = evo.modified;
+    let idx = 0;
+    while (idx < m.length) {
+        const inHash = m[idx];
+        const count = m[idx + 1];
+        const outHashes = [];
+        for (let j = 0; j < count; j++) {
+            outHashes.push(m[idx + 2 + j]);
+        }
+        modified.set(inHash, outHashes);
+        idx += 2 + count;
+    }
+    return { modified, deleted: new Set(evo.deleted) };
+}
+/**
+ * 把一次双输入布尔（cut/fuse/intersect）的打包演化按「inHash 属于 A 还是 B」
+ * 拆成 A、B 两张 hash 演化（§3.4 布尔合流，faijs 对 brepjs 的必要扩展）。
+ *
+ * 现有 *WithHistoryBrep 包装只用 getUnionFaceHashes 传入 A∪B 两边 hash、且只对
+ * 基体 a 解码序号演化。本函数对同一份 evo 零额外内核调用：用 subShapeHashes(a)
+ * / subShapeHashes(b) 两个集合判定每个 inHash 的归属，各自传播各自的 role 表。
+ *
+ * @param evo     - the BrepEvolutionData (from a binary boolean *WithHistory API).
+ * @param hashesA - the face hashes of input A (target), via subShapeHashes.
+ * @param hashesB - the face hashes of input B (tool), via subShapeHashes.
+ * @returns the A/B split hash evolutions (faces from neither input are dropped).
+ */
+export function splitHashEvolutionByOrigin(evo, hashesA, hashesB) {
+    const raw = decodeHashEvolution(evo);
+    const setA = new Set(hashesA);
+    const setB = new Set(hashesB);
+    const aModified = new Map();
+    const bModified = new Map();
+    for (const [inHash, outs] of raw.modified) {
+        if (setA.has(inHash))
+            aModified.set(inHash, [...outs]);
+        else if (setB.has(inHash))
+            bModified.set(inHash, [...outs]);
+    }
+    const aDeleted = new Set();
+    const bDeleted = new Set();
+    for (const h of raw.deleted) {
+        if (setA.has(h))
+            aDeleted.add(h);
+        else if (setB.has(h))
+            bDeleted.add(h);
+    }
+    return { a: { modified: aModified, deleted: aDeleted }, b: { modified: bModified, deleted: bDeleted } };
+}
+/**
+ * 构造 hash 键恒等演化（§2.4：变换类 translate/rotate/scale/copy 用）。
+ *
+ * 刚体变换/深拷贝不改变面数量与顺序：输入第 i 面 hash → 输出第 i 面 hash，
+ * 用 subShapeHashes 两端对齐合成 hash 恒等（避免调用 *WithHistory 的签名兼容问题）。
+ *
+ * @param kernel       - the OCCT kernel.
+ * @param inputShape   - the input shape.
+ * @param resultShape  - the transformed/copied output shape.
+ * @returns the hash identity evolution (modified: in[i] → [out[i]]).
+ */
+export function identityHashEvolution(kernel, inputShape, resultShape) {
+    const inputHashes = getFaceHashes(kernel, inputShape);
+    const resultHashes = getFaceHashes(kernel, resultShape);
+    const count = Math.min(inputHashes.length, resultHashes.length);
+    const modified = new Map();
+    for (let i = 0; i < count; i++) {
+        modified.set(inputHashes[i], [resultHashes[i]]);
+    }
+    return { modified, deleted: new Set() };
+}
+/**
+ * 双输入布尔 + roleTable 合流组合封装（§3.4，stdlib boolean 链式调用用）。
+ *
+ * 一次 *WithHistory 内核调用同时产出：
+ * - result：结果实体
+ * - faceEvolution：序号键演化（进 faceEvolutionCache，服务选择器/可视化）
+ * - roleTable：A/B 两侧 role 表各自传播后合并（进 roleTableCache，服务命名）
+ *
+ * 缝面（generated）刻意不进 role 传播（§1.3/R2：generated hash 指向中间形、
+ * 实测 0 存活），以本次语句 LHS 为 outPart 新 origin 的位置名由调用方决定。
+ *
+ * @param kernel  - the OCCT kernel.
+ * @param op      - the boolean operation ('fuse' | 'cut' | 'intersect').
+ * @param a       - the target shape.
+ * @param b       - the tool shape.
+ * @param tableA  - the target's role table.
+ * @param tableB  - the tool's role table.
+ * @param outPart - the boolean statement's LHS variable name (new origin for seam faces).
+ * @returns the result handle, ordinal evolution and merged role table.
+ */
+export function booleanWithRoleTable(kernel, op, a, b, tableA, tableB, outPart) {
+    const inputHashes = getUnionFaceHashes(kernel, a, b);
+    let evo;
+    if (op === 'fuse')
+        evo = kernel.fuseWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    else if (op === 'cut')
+        evo = kernel.cutWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    else
+        evo = kernel.intersectWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    const faceEvolution = decodeEvolution(kernel, evo, a, evo.result);
+    // A/B 拆流 → 各自传播 → 合表（§3.4）
+    const hashesA = getFaceHashes(kernel, a);
+    const hashesB = getFaceHashes(kernel, b);
+    const { a: evoA, b: evoB } = splitHashEvolutionByOrigin(evo, hashesA, hashesB);
+    const merged = mergeRoleTablesLocal(tableA, evoA, tableB, evoB, outPart);
+    return { result: evo.result, faceEvolution, roleTable: merged };
+}
+/** 合表（避免 naming/roles 循环依赖：本文件不 import naming，用结构等价实现）。 */
+function mergeRoleTablesLocal(tableA, evoA, tableB, evoB, outPart) {
+    const result = new Map();
+    for (const [origin, roles] of tableA) {
+        result.set(origin, propagateOriginRoles(roles, evoA));
+    }
+    for (const [origin, roles] of tableB) {
+        const existing = result.get(origin);
+        const advanced = propagateOriginRoles(roles, evoB);
+        if (existing) {
+            const merged = new Map();
+            for (const [role, hs] of existing)
+                merged.set(role, [...hs]);
+            for (const [role, hs] of advanced) {
+                const prev = merged.get(role);
+                merged.set(role, prev ? [...new Set([...prev, ...hs])] : [...hs]);
+            }
+            result.set(origin, merged);
+        }
+        else {
+            result.set(origin, advanced);
+        }
+    }
+    // 缝面位置名：调用方决定是否补（generated 不可靠，默认不补）
+    void outPart;
+    return result;
+}
+/** 单 origin 传播（结构等价于 naming/roles.propagateRoles，避免循环依赖）。 */
+function propagateOriginRoles(roles, evolution) {
+    const updated = new Map();
+    for (const [role, hashes] of roles) {
+        const successors = [];
+        for (const hash of hashes) {
+            if (evolution.deleted.has(hash))
+                continue;
+            const modified = evolution.modified.get(hash);
+            const targets = modified !== undefined && modified.length > 0 ? modified : [hash];
+            for (const h of targets)
+                if (!successors.includes(h))
+                    successors.push(h);
+        }
+        if (successors.length > 0)
+            updated.set(role, successors);
+    }
+    return updated;
+}
+/**
+ * Decode a BrepEvolutionData deleted array into the ordinal list of deleted faces.
+ * @param kernel     - the OCCT kernel.
+ * @param evo        - the BrepEvolutionData (from a *WithHistory API).
+ * @param inputShape - the input shape (for the hash → ordinal mapping).
+ * @returns the array of deleted face ordinals.
+ */
+export function decodeDeleted(kernel, evo, inputShape) {
+    const inputHashes = getFaceHashes(kernel, inputShape);
+    const inputHashToOrdinal = new Map();
+    for (let i = 0; i < inputHashes.length; i++) {
+        inputHashToOrdinal.set(inputHashes[i], i);
+    }
+    const deletedOrdinals = [];
+    for (const hash of evo.deleted) {
+        const ordinal = inputHashToOrdinal.get(hash);
+        if (ordinal !== undefined) {
+            deletedOrdinals.push(ordinal);
+        }
+    }
+    return deletedOrdinals;
+}
+// ─── WithHistory 封装函数 ───
+/**
+ * cutWithHistory 封装：执行切割并返回结果 + 面演化映射。
+ *
+ * @param kernel OCCT 内核
+ * @param a 基体
+ * @param b 工具（从基体中减去）
+ * @returns { result: 结果 BrepHandle, faceEvolution: 面演化映射 }
+ */
+export function cutWithHistoryBrep(kernel, a, b) {
+    const inputHashes = getUnionFaceHashes(kernel, a, b);
+    const evo = kernel.cutWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    const faceEvolution = decodeEvolution(kernel, evo, a, evo.result);
+    return { result: evo.result, faceEvolution };
+}
+/**
+ * fuseWithHistory wrapper: performs the fuse and returns the result plus the face evolution mapping.
+ * @param kernel - the OCCT kernel.
+ * @param a - the base shape.
+ * @param b - the tool shape to fuse into the base.
+ * @returns the result BrepHandle plus the face evolution mapping.
+ */
+export function fuseWithHistoryBrep(kernel, a, b) {
+    const inputHashes = getUnionFaceHashes(kernel, a, b);
+    const evo = kernel.fuseWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    const faceEvolution = decodeEvolution(kernel, evo, a, evo.result);
+    return { result: evo.result, faceEvolution };
+}
+/**
+ * intersectWithHistory wrapper: performs the intersection and returns the result plus the face evolution mapping.
+ * @param kernel - the OCCT kernel.
+ * @param a - the first input shape.
+ * @param b - the second input shape.
+ * @returns the result BrepHandle plus the face evolution mapping.
+ */
+export function intersectWithHistoryBrep(kernel, a, b) {
+    const inputHashes = getUnionFaceHashes(kernel, a, b);
+    const evo = kernel.intersectWithHistory(a, b, inputHashes, HASH_UPPER_BOUND);
+    const faceEvolution = decodeEvolution(kernel, evo, a, evo.result);
+    return { result: evo.result, faceEvolution };
+}
+// ─── 变换操作面演化 ───
+/**
+ * 构造恒等面演化映射（用于 translate/rotate/scale 等不改变拓扑的操作）。
+ *
+ * 变换操作不改变面的数量和顺序，每个面 ordinal i → [i]。
+ * 避免调用 *WithHistory API（rotate/scale 的 WithHistory 签名与现有 Euler/Vec3 参数不兼容）。
+ *
+ * @param kernel OCCT 内核
+ * @param shape 输入形状（用于获取面数量）
+ * @returns 恒等 FaceEvolution
+ */
+export function identityEvolution(kernel, shape) {
+    const faceCount = getFaceHashes(kernel, shape).length;
+    const evolution = new Map();
+    for (let i = 0; i < faceCount; i++) {
+        evolution.set(i, [i]);
+    }
+    return evolution;
+}
+// ─── directEdit WithHistory 封装（fillet / chamfer：单输入） ───
+/**
+ * 单输入 directEdit（fillet/chamfer）+ roleTable 传播封装。
+ *
+ * 与 `booleanWithRoleTable`（双输入）对应：单输入只有一张输入 role 表，
+ * 一次 `*WithHistory` 内核调用产出结果 + 面演化，沿 hash 演化推进所有 origin。
+ *
+ * generated 刻意不进 role 传播（§1.3 事实：generated hash 指向中间形，
+ * 实测 0 存活），过渡面的命名由 DerivedFaceTopoRef 在 M2 处理。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param op              - the directEdit operation ('fillet' | 'chamfer').
+ * @param solid          - the input solid (single input, unlike boolean's a/b).
+ * @param edgeHandles     - the resolved Edge handles to fillet/chamfer.
+ * @param radius          - the fillet radius or chamfer distance (uniform only).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name (for new origin allocation).
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export function directEditWithRoleTable(kernel, op, solid, edgeHandles, radius, inputRoleTable, outPart) {
+    const inputHashes = getFaceHashes(kernel, solid);
+    let evo;
+    if (op === 'fillet') {
+        evo = kernel.filletWithHistory(solid, edgeHandles, radius, inputHashes, HASH_UPPER_BOUND);
+    }
+    else {
+        evo = kernel.chamferWithHistory(solid, edgeHandles, radius, inputHashes, HASH_UPPER_BOUND);
+    }
+    const faceEvolution = decodeEvolution(kernel, evo, solid, evo.result);
+    const hashEvo = decodeHashEvolution(evo);
+    const roleTable = propagateAllOriginsLocal(inputRoleTable, hashEvo);
+    // outPart used for new-origin allocation in M2 (derived faces); M1 does not
+    // generate positional roles for transition faces.
+    void outPart;
+    return { result: evo.result, faceEvolution, roleTable };
+}
+/**
+ * 单输入 directEdit 的便捷别名：fillet。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param solid          - the input solid.
+ * @param edgeHandles     - the resolved Edge handles.
+ * @param radius          - the fillet radius (uniform).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name.
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export function filletWithRoleTable(kernel, solid, edgeHandles, radius, inputRoleTable, outPart) {
+    return directEditWithRoleTable(kernel, 'fillet', solid, edgeHandles, radius, inputRoleTable, outPart);
+}
+/**
+ * 单输入 directEdit 的便捷别名：chamfer。
+ *
+ * @param kernel          - the OCCT kernel.
+ * @param solid          - the input solid.
+ * @param edgeHandles     - the resolved Edge handles.
+ * @param distance        - the chamfer distance (uniform).
+ * @param inputRoleTable  - the input's role table.
+ * @param outPart         - the statement's LHS variable name.
+ * @returns the result handle, ordinal evolution and propagated role table.
+ */
+export function chamferWithRoleTable(kernel, solid, edgeHandles, distance, inputRoleTable, outPart) {
+    return directEditWithRoleTable(kernel, 'chamfer', solid, edgeHandles, distance, inputRoleTable, outPart);
+}
+/** 单输入 roleTable 传播（结构等价于 naming/roles.propagateAllOrigins，避免循环依赖）。 */
+function propagateAllOriginsLocal(roles, evolution) {
+    const result = new Map();
+    for (const [origin, originRoles] of roles) {
+        result.set(origin, propagateOriginRoles(originRoles, evolution));
+    }
+    return result;
+}
+//# sourceMappingURL=face-evolution.js.map

package/dist/brep/face-evolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-evolution.js","sourceRoot":"","sources":["../../src/brep/face-evolution.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 面演化（face evolution）工具：hash 映射 ↔ ordinal 映射转换\n *\n * See docs/api-contract.md §11 (topology contract) for face evolution context.\n *\n * occt-wasm 的 *WithHistory API 返回 BrepEvolutionData，其中 modified/generated\n * 用面 hash（内存指针哈希）编码。本模块将其解码为 ordinal 映射（面枚举序号），\n * 可安全持久化进 faijs 文本。\n *\n * 核心原理（分析文档 §4.4）：\n * getSubShapes(shape,'face')[i] ↔ subShapeHashes(shape,'face',B)[i] 一一对应\n * 因此可以把 hash 映射无损转换为 ordinal 映射。\n */\n\nimport type { BrepHandle, BrepEvolutionData } from './engine/types'\nimport type { BrepEngineApi } from './engine/primitives'\n\n/** hash 上界（与 occt-wasm kernel.cpp 一致：`% 2147483647`） */\nexport const HASH_UPPER_BOUND = 2147483647\n\n/**\n * 面演化映射：输入面 ordinal → 输出面 ordinal 列表\n *\n * - 1→1：面被修改但未被切割（如面带孔仍是单面）\n * - 1→N：面被切割成多个面\n * - 不在 map 中：面未被修改或被删除\n */\nexport type FaceEvolution = Map<number, number[]>\n\n/**\n * Collect the hash list of all faces of a shape (via subShapeHashes; efficient, no handles allocated).\n * @param kernel - the OCCT kernel.\n * @param shape - the shape whose face hashes to collect.\n * @returns the array of face hashes.\n */\nexport function getFaceHashes(kernel: BrepEngineApi, shape: BrepHandle): number[] {\n  return Array.from(kernel.subShapeHashes(shape, 'face', HASH_UPPER_BOUND))\n}\n\n/**\n * Collect the union of face hashes of two shapes (for WithHistory calls of binary boolean operations).\n *\n * Analysis doc §4.2: fuse/cut/intersect must pass subShapeHashes(A) ∪ subShapeHashes(B)\n * to track both inputs' face evolution.\n * @param kernel - the OCCT kernel.\n * @param shapeA - the first input shape.\n * @param shapeB - the second input shape.\n * @returns the union of the two shapes' face hashes.\n */\nexport function getUnionFaceHashes(\n  kernel: BrepEngineApi,\n  shapeA: BrepHandle,\n  shapeB: BrepHandle,\n): number[] {\n  const hashesA = getFaceHashes(kernel, shapeA)\n  const hashesB = getFaceHashes(kernel, shapeB)\n  return [...new Set([...hashesA, ...hashesB])]\n}\n\n/**\n * 解码 BrepEvolutionData 的 modified 数组为 ordinal 映射。\n *\n * modified 分段编码格式：[inputHash, count, outHash1, outHash2, ...] × N\n *\n * @param kernel      the OCCT kernel.\n * @param evo         the BrepEvolutionData (from a *WithHistory API).\n * @param inputShape  the input shape (for the input face hash → ordinal mapping).\n * @param resultShape the result shape (for the output face hash → ordinal mapping).\n * @returns the FaceEvolution: inOrdinal → outOrdinal[].\n */\nexport function decodeEvolution(\n  kernel: BrepEngineApi,\n  evo: BrepEvolutionData,\n  inputShape: BrepHandle,\n  resultShape: BrepHandle,\n): FaceEvolution {\n  const inputHashes = getFaceHashes(kernel, inputShape)\n  const resultHashes = getFaceHashes(kernel, resultShape)\n\n  // 构建 hash → ordinal 查找表\n  const resultHashToOrdinal = new Map<number, number>()\n  for (let i = 0; i < resultHashes.length; i++) {\n    resultHashToOrdinal.set(resultHashes[i], i)\n  }\n  const inputHashToOrdinal = new Map<number, number>()\n  for (let i = 0; i < inputHashes.length; i++) {\n    inputHashToOrdinal.set(inputHashes[i], i)\n  }\n\n  // 解码 modified 数组\n  const evolution: FaceEvolution = new Map()\n  const modified = evo.modified\n  let idx = 0\n  while (idx < modified.length) {\n    const inHash = modified[idx]\n    const count = modified[idx + 1]\n    const outOrdinals: number[] = []\n    for (let j = 0; j < count; j++) {\n      const outHash = modified[idx + 2 + j]\n      const outOrdinal = resultHashToOrdinal.get(outHash)\n      if (outOrdinal !== undefined) {\n        outOrdinals.push(outOrdinal)\n      }\n    }\n    const inOrdinal = inputHashToOrdinal.get(inHash)\n    if (inOrdinal !== undefined) {\n      evolution.set(inOrdinal, outOrdinals)\n    }\n    idx += 2 + count\n  }\n\n  return evolution\n}\n\n\n/**\n * Hash 键面演化：输入面 hash → 输出面 hash 列表（1→多分裂时多个）。\n *\n * 与序号键 FaceEvolution 并列、同源（同一次 *WithHistory 打包结果解出），\n * 一个供 role 传播（hash 键）、一个供选择器/文本（序号键），零额外 wasm 调用。\n */\nexport interface HashEvolution {\n  /** 输入面 hash → 输出面 hash 列表（1→多分裂时多个）。 */\n  readonly modified: ReadonlyMap<number, readonly number[]>\n  /** 输入面中已不存在的面 hash。 */\n  readonly deleted: ReadonlySet<number>\n}\n\n/**\n * 把 BrepEvolutionData 解码为 hash 键演化（§2.4）。\n *\n * modified 分段编码格式：[inHash, count, outHash1, ...] × N —— 本身就是\n * hash→hash[] 的 1→多映射，直接按同一格式解出 hash 键版本，不需要\n * getSubShapes 逐句柄 hashCode，也不分配任何句柄。\n *\n * generated 刻意不进 role 传播（§1.3 事实：occt 系 generated hash 指向中间形、\n * 对布尔实测 0 个存活），生成面改由 DerivedFaceTopoRef 以 lineage 命名。\n *\n * @param evo - the BrepEvolutionData (from a *WithHistory API).\n * @returns the hash-keyed evolution.\n */\nexport function decodeHashEvolution(evo: BrepEvolutionData): HashEvolution {\n  const modified = new Map<number, number[]>()\n  const m = evo.modified\n  let idx = 0\n  while (idx < m.length) {\n    const inHash = m[idx]\n    const count = m[idx + 1]\n    const outHashes: number[] = []\n    for (let j = 0; j < count; j++) {\n      outHashes.push(m[idx + 2 + j])\n    }\n    modified.set(inHash, outHashes)\n    idx += 2 + count\n  }\n  return { modified, deleted: new Set(evo.deleted) }\n}\n\n/**\n * 把一次双输入布尔（cut/fuse/intersect）的打包演化按「inHash 属于 A 还是 B」\n * 拆成 A、B 两张 hash 演化（§3.4 布尔合流，faijs 对 brepjs 的必要扩展）。\n *\n * 现有 *WithHistoryBrep 包装只用 getUnionFaceHashes 传入 A∪B 两边 hash、且只对\n * 基体 a 解码序号演化。本函数对同一份 evo 零额外内核调用：用 subShapeHashes(a)\n * / subShapeHashes(b) 两个集合判定每个 inHash 的归属，各自传播各自的 role 表。\n *\n * @param evo     - the BrepEvolutionData (from a binary boolean *WithHistory API).\n * @param hashesA - the face hashes of input A (target), via subShapeHashes.\n * @param hashesB - the face hashes of input B (tool), via subShapeHashes.\n * @returns the A/B split hash evolutions (faces from neither input are dropped).\n */\nexport function splitHashEvolutionByOrigin(\n  evo: BrepEvolutionData,\n  hashesA: readonly number[],\n  hashesB: readonly number[],\n): { a: HashEvolution; b: HashEvolution } {\n  const raw = decodeHashEvolution(evo)\n  const setA = new Set(hashesA)\n  const setB = new Set(hashesB)\n\n  const aModified = new Map<number, number[]>()\n  const bModified = new Map<number, number[]>()\n  for (const [inHash, outs] of raw.modified) {\n    if (setA.has(inHash)) aModified.set(inHash, [...outs])\n    else if (setB.has(inHash)) bModified.set(inHash, [...outs])\n  }\n\n  const aDeleted = new Set<number>()\n  const bDeleted = new Set<number>()\n  for (const h of raw.deleted) {\n    if (setA.has(h)) aDeleted.add(h)\n    else if (setB.has(h)) bDeleted.add(h)\n  }\n\n  return { a: { modified: aModified, deleted: aDeleted }, b: { modified: bModified, deleted: bDeleted } }\n}\n\n/**\n * 构造 hash 键恒等演化（§2.4：变换类 translate/rotate/scale/copy 用）。\n *\n * 刚体变换/深拷贝不改变面数量与顺序：输入第 i 面 hash → 输出第 i 面 hash，\n * 用 subShapeHashes 两端对齐合成 hash 恒等（避免调用 *WithHistory 的签名兼容问题）。\n *\n * @param kernel       - the OCCT kernel.\n * @param inputShape   - the input shape.\n * @param resultShape  - the transformed/copied output shape.\n * @returns the hash identity evolution (modified: in[i] → [out[i]]).\n */\nexport function identityHashEvolution(\n  kernel: BrepEngineApi,\n  inputShape: BrepHandle,\n  resultShape: BrepHandle,\n): HashEvolution {\n  const inputHashes = getFaceHashes(kernel, inputShape)\n  const resultHashes = getFaceHashes(kernel, resultShape)\n  const count = Math.min(inputHashes.length, resultHashes.length)\n  const modified = new Map<number, number[]>()\n  for (let i = 0; i < count; i++) {\n    modified.set(inputHashes[i], [resultHashes[i]])\n  }\n  return { modified, deleted: new Set() }\n}\n\n/**\n * 双输入布尔 + roleTable 合流组合封装（§3.4，stdlib boolean 链式调用用）。\n *\n * 一次 *WithHistory 内核调用同时产出：\n * - result：结果实体\n * - faceEvolution：序号键演化（进 faceEvolutionCache，服务选择器/可视化）\n * - roleTable：A/B 两侧 role 表各自传播后合并（进 roleTableCache，服务命名）\n *\n * 缝面（generated）刻意不进 role 传播（§1.3/R2：generated hash 指向中间形、\n * 实测 0 存活），以本次语句 LHS 为 outPart 新 origin 的位置名由调用方决定。\n *\n * @param kernel  - the OCCT kernel.\n * @param op      - the boolean operation ('fuse' | 'cut' | 'intersect').\n * @param a       - the target shape.\n * @param b       - the tool shape.\n * @param tableA  - the target's role table.\n * @param tableB  - the tool's role table.\n * @param outPart - the boolean statement's LHS variable name (new origin for seam faces).\n * @returns the result handle, ordinal evolution and merged role table.\n */\nexport function booleanWithRoleTable(\n  kernel: BrepEngineApi,\n  op: 'fuse' | 'cut' | 'intersect',\n  a: BrepHandle,\n  b: BrepHandle,\n  tableA: ReadonlyMap<unknown, unknown>,\n  tableB: ReadonlyMap<unknown, unknown>,\n  outPart: string,\n): { result: BrepHandle; faceEvolution: FaceEvolution; roleTable: ReadonlyMap<unknown, unknown> } {\n  const inputHashes = getUnionFaceHashes(kernel, a, b)\n  let evo: BrepEvolutionData\n  if (op === 'fuse') evo = kernel.fuseWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n  else if (op === 'cut') evo = kernel.cutWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n  else evo = kernel.intersectWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n\n  const faceEvolution = decodeEvolution(kernel, evo, a, evo.result)\n\n  // A/B 拆流 → 各自传播 → 合表（§3.4）\n  const hashesA = getFaceHashes(kernel, a)\n  const hashesB = getFaceHashes(kernel, b)\n  const { a: evoA, b: evoB } = splitHashEvolutionByOrigin(evo, hashesA, hashesB)\n  const merged = mergeRoleTablesLocal(tableA, evoA, tableB, evoB, outPart)\n\n  return { result: evo.result, faceEvolution, roleTable: merged }\n}\n\n/** 合表（避免 naming/roles 循环依赖：本文件不 import naming，用结构等价实现）。 */\nfunction mergeRoleTablesLocal(\n  tableA: ReadonlyMap<unknown, unknown>,\n  evoA: HashEvolution,\n  tableB: ReadonlyMap<unknown, unknown>,\n  evoB: HashEvolution,\n  outPart: string,\n): ReadonlyMap<unknown, unknown> {\n  const result = new Map<unknown, unknown>()\n  for (const [origin, roles] of tableA) {\n    result.set(origin, propagateOriginRoles(roles as ReadonlyMap<string, readonly number[]>, evoA))\n  }\n  for (const [origin, roles] of tableB) {\n    const existing = result.get(origin) as ReadonlyMap<string, readonly number[]> | undefined\n    const advanced = propagateOriginRoles(roles as ReadonlyMap<string, readonly number[]>, evoB)\n    if (existing) {\n      const merged = new Map<string, number[]>()\n      for (const [role, hs] of existing) merged.set(role, [...hs])\n      for (const [role, hs] of advanced) {\n        const prev = merged.get(role)\n        merged.set(role, prev ? [...new Set([...prev, ...hs])] : [...hs])\n      }\n      result.set(origin, merged)\n    } else {\n      result.set(origin, advanced)\n    }\n  }\n  // 缝面位置名：调用方决定是否补（generated 不可靠，默认不补）\n  void outPart\n  return result\n}\n\n/** 单 origin 传播（结构等价于 naming/roles.propagateRoles，避免循环依赖）。 */\nfunction propagateOriginRoles(\n  roles: ReadonlyMap<string, readonly number[]>,\n  evolution: HashEvolution,\n): ReadonlyMap<string, readonly number[]> {\n  const updated = new Map<string, number[]>()\n  for (const [role, hashes] of roles) {\n    const successors: number[] = []\n    for (const hash of hashes) {\n      if (evolution.deleted.has(hash)) continue\n      const modified = evolution.modified.get(hash)\n      const targets = modified !== undefined && modified.length > 0 ? modified : [hash]\n      for (const h of targets) if (!successors.includes(h)) successors.push(h)\n    }\n    if (successors.length > 0) updated.set(role, successors)\n  }\n  return updated\n}\n\n/**\n * Decode a BrepEvolutionData deleted array into the ordinal list of deleted faces.\n * @param kernel     - the OCCT kernel.\n * @param evo        - the BrepEvolutionData (from a *WithHistory API).\n * @param inputShape - the input shape (for the hash → ordinal mapping).\n * @returns the array of deleted face ordinals.\n */\nexport function decodeDeleted(\n  kernel: BrepEngineApi,\n  evo: BrepEvolutionData,\n  inputShape: BrepHandle,\n): number[] {\n  const inputHashes = getFaceHashes(kernel, inputShape)\n  const inputHashToOrdinal = new Map<number, number>()\n  for (let i = 0; i < inputHashes.length; i++) {\n    inputHashToOrdinal.set(inputHashes[i], i)\n  }\n\n  const deletedOrdinals: number[] = []\n  for (const hash of evo.deleted) {\n    const ordinal = inputHashToOrdinal.get(hash)\n    if (ordinal !== undefined) {\n      deletedOrdinals.push(ordinal)\n    }\n  }\n  return deletedOrdinals\n}\n\n// ─── WithHistory 封装函数 ───\n\n/**\n * cutWithHistory 封装：执行切割并返回结果 + 面演化映射。\n *\n * @param kernel OCCT 内核\n * @param a 基体\n * @param b 工具（从基体中减去）\n * @returns { result: 结果 BrepHandle, faceEvolution: 面演化映射 }\n */\nexport function cutWithHistoryBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): { result: BrepHandle; faceEvolution: FaceEvolution } {\n  const inputHashes = getUnionFaceHashes(kernel, a, b)\n  const evo = kernel.cutWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n  const faceEvolution = decodeEvolution(kernel, evo, a, evo.result)\n  return { result: evo.result, faceEvolution }\n}\n\n/**\n * fuseWithHistory wrapper: performs the fuse and returns the result plus the face evolution mapping.\n * @param kernel - the OCCT kernel.\n * @param a - the base shape.\n * @param b - the tool shape to fuse into the base.\n * @returns the result BrepHandle plus the face evolution mapping.\n */\nexport function fuseWithHistoryBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): { result: BrepHandle; faceEvolution: FaceEvolution } {\n  const inputHashes = getUnionFaceHashes(kernel, a, b)\n  const evo = kernel.fuseWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n  const faceEvolution = decodeEvolution(kernel, evo, a, evo.result)\n  return { result: evo.result, faceEvolution }\n}\n\n/**\n * intersectWithHistory wrapper: performs the intersection and returns the result plus the face evolution mapping.\n * @param kernel - the OCCT kernel.\n * @param a - the first input shape.\n * @param b - the second input shape.\n * @returns the result BrepHandle plus the face evolution mapping.\n */\nexport function intersectWithHistoryBrep(\n  kernel: BrepEngineApi,\n  a: BrepHandle,\n  b: BrepHandle,\n): { result: BrepHandle; faceEvolution: FaceEvolution } {\n  const inputHashes = getUnionFaceHashes(kernel, a, b)\n  const evo = kernel.intersectWithHistory(a, b, inputHashes, HASH_UPPER_BOUND)\n  const faceEvolution = decodeEvolution(kernel, evo, a, evo.result)\n  return { result: evo.result, faceEvolution }\n}\n\n// ─── 变换操作面演化 ───\n\n/**\n * 构造恒等面演化映射（用于 translate/rotate/scale 等不改变拓扑的操作）。\n *\n * 变换操作不改变面的数量和顺序，每个面 ordinal i → [i]。\n * 避免调用 *WithHistory API（rotate/scale 的 WithHistory 签名与现有 Euler/Vec3 参数不兼容）。\n *\n * @param kernel OCCT 内核\n * @param shape 输入形状（用于获取面数量）\n * @returns 恒等 FaceEvolution\n */\nexport function identityEvolution(\n  kernel: BrepEngineApi,\n  shape: BrepHandle,\n): FaceEvolution {\n  const faceCount = getFaceHashes(kernel, shape).length\n  const evolution: FaceEvolution = new Map()\n  for (let i = 0; i < faceCount; i++) {\n    evolution.set(i, [i])\n  }\n  return evolution\n}\n\n// ─── directEdit WithHistory 封装（fillet / chamfer：单输入） ───\n\n/**\n * 单输入 directEdit（fillet/chamfer）+ roleTable 传播封装。\n *\n * 与 `booleanWithRoleTable`（双输入）对应：单输入只有一张输入 role 表，\n * 一次 `*WithHistory` 内核调用产出结果 + 面演化，沿 hash 演化推进所有 origin。\n *\n * generated 刻意不进 role 传播（§1.3 事实：generated hash 指向中间形，\n * 实测 0 存活），过渡面的命名由 DerivedFaceTopoRef 在 M2 处理。\n *\n * @param kernel          - the OCCT kernel.\n * @param op              - the directEdit operation ('fillet' | 'chamfer').\n * @param solid          - the input solid (single input, unlike boolean's a/b).\n * @param edgeHandles     - the resolved Edge handles to fillet/chamfer.\n * @param radius          - the fillet radius or chamfer distance (uniform only).\n * @param inputRoleTable  - the input's role table.\n * @param outPart         - the statement's LHS variable name (for new origin allocation).\n * @returns the result handle, ordinal evolution and propagated role table.\n */\nexport function directEditWithRoleTable(\n  kernel: BrepEngineApi,\n  op: 'fillet' | 'chamfer',\n  solid: BrepHandle,\n  edgeHandles: BrepHandle[],\n  radius: number,\n  inputRoleTable: ReadonlyMap<unknown, unknown>,\n  outPart: string,\n): { result: BrepHandle; faceEvolution: FaceEvolution; roleTable: ReadonlyMap<unknown, unknown> } {\n  const inputHashes = getFaceHashes(kernel, solid)\n  let evo: BrepEvolutionData\n  if (op === 'fillet') {\n    evo = kernel.filletWithHistory(solid, edgeHandles, radius, inputHashes, HASH_UPPER_BOUND)\n  } else {\n    evo = kernel.chamferWithHistory(solid, edgeHandles, radius, inputHashes, HASH_UPPER_BOUND)\n  }\n\n  const faceEvolution = decodeEvolution(kernel, evo, solid, evo.result)\n  const hashEvo = decodeHashEvolution(evo)\n  const roleTable = propagateAllOriginsLocal(inputRoleTable, hashEvo)\n\n  // outPart used for new-origin allocation in M2 (derived faces); M1 does not\n  // generate positional roles for transition faces.\n  void outPart\n\n  return { result: evo.result, faceEvolution, roleTable }\n}\n\n/**\n * 单输入 directEdit 的便捷别名：fillet。\n *\n * @param kernel          - the OCCT kernel.\n * @param solid          - the input solid.\n * @param edgeHandles     - the resolved Edge handles.\n * @param radius          - the fillet radius (uniform).\n * @param inputRoleTable  - the input's role table.\n * @param outPart         - the statement's LHS variable name.\n * @returns the result handle, ordinal evolution and propagated role table.\n */\nexport function filletWithRoleTable(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  edgeHandles: BrepHandle[],\n  radius: number,\n  inputRoleTable: ReadonlyMap<unknown, unknown>,\n  outPart: string,\n): { result: BrepHandle; faceEvolution: FaceEvolution; roleTable: ReadonlyMap<unknown, unknown> } {\n  return directEditWithRoleTable(kernel, 'fillet', solid, edgeHandles, radius, inputRoleTable, outPart)\n}\n\n/**\n * 单输入 directEdit 的便捷别名：chamfer。\n *\n * @param kernel          - the OCCT kernel.\n * @param solid          - the input solid.\n * @param edgeHandles     - the resolved Edge handles.\n * @param distance        - the chamfer distance (uniform).\n * @param inputRoleTable  - the input's role table.\n * @param outPart         - the statement's LHS variable name.\n * @returns the result handle, ordinal evolution and propagated role table.\n */\nexport function chamferWithRoleTable(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  edgeHandles: BrepHandle[],\n  distance: number,\n  inputRoleTable: ReadonlyMap<unknown, unknown>,\n  outPart: string,\n): { result: BrepHandle; faceEvolution: FaceEvolution; roleTable: ReadonlyMap<unknown, unknown> } {\n  return directEditWithRoleTable(kernel, 'chamfer', solid, edgeHandles, distance, inputRoleTable, outPart)\n}\n\n/** 单输入 roleTable 传播（结构等价于 naming/roles.propagateAllOrigins，避免循环依赖）。 */\nfunction propagateAllOriginsLocal(\n  roles: ReadonlyMap<unknown, unknown>,\n  evolution: HashEvolution,\n): ReadonlyMap<unknown, unknown> {\n  const result = new Map<unknown, unknown>()\n  for (const [origin, originRoles] of roles) {\n    result.set(origin, propagateOriginRoles(originRoles as ReadonlyMap<string, readonly number[]>, evolution))\n  }\n  return result\n}\n"]}

package/dist/brep/handle-bridge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * handle-bridge — OCCT 句柄 → faijs Shape 的 SDK 桥接（B1）
+ *
+ *
+ * 第三方库要造 BREP 产物，需要"OCCT handle → mesh"。`src/brep/brep-ops.ts:17`
+ * 有 `import * as THREE from 'three'`，SDK 绝不能 import 它（会把 three 拉进
+ * SDK bundle，违反 `src/sdk.test.ts` 的零 heavy 依赖守卫）。本文件在**新建的
+ * 零依赖模块**中实现，直接调运行时注入的 `kernel.meshShape`。
+ *
+ * 依赖约束（硬性）：只允许 import `runtime-state`、`stdlib/shape`、type-only
+ * `mesh/types`——任何新增依赖必须保持 dist/sdk.js 零 heavy 依赖守卫通过。
+ */
+import type { Shape } from '../mesh/types.js';
+import { fromBrep } from '../shape.js';
+/**
+ * Get the OCCT kernel instance faijs is currently using.
+ * @returns the current OCCT kernel.
+ * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.
+ */
+export declare function getKernel(): unknown;
+/**
+ * Options controlling how a handle is tessellated.
+ */
+export interface MeshHandleOptions {
+    /** linear deflection (mm), default 0.1 — matches the built-in ops (src/brep/brep-ops.ts:27). */
+    linearDeflection?: number;
+    /** angular segment count, default 32 — angularDeflection = 2π / segments. */
+    segments?: number;
+}
+/**
+ * OCC 句柄身份契约判别（单一真源）。
+ *
+ * occt-wasm 的 `handle()` 工厂（vendored occtWasm helpers.ts:25）构造的句柄对象
+ * 统一携带 `__occtWasm: true`。本叶子是 faijs 侧唯一允许的判据：
+ * define-op 的 `wrapBrepOne` 用它区分"几何句柄"与"纯数据记录"，本文件
+ * `fromHandle`/`meshHandle` 入口用它做形态断言。禁止在其他文件硬编码
+ * `'__occtWasm' in v` 字符串直查——句柄/数据判定的任何新消费点都必须引用本叶子。
+ * @param v - 待判别的值。
+ * @returns `true` 当且仅当 `v` 是携带 `__occtWasm: true` 标记的句柄对象。
+ */
+export declare function isOcctHandle(v: unknown): boolean;
+/**
+ * Tessellate an OCCT handle into a Shape (without registering a BREP slot).
+ * @param handle - the OCCT solid handle to tessellate (numeric id or `__occtWasm`-tagged object).
+ * @param opts - optional tessellation options.
+ * @returns the tessellated Shape.
+ */
+export declare function meshHandle(handle: unknown, opts?: MeshHandleOptions): Shape;
+/**
+ * Default path (recommended): tessellate + register the BREP slot in one step.
+ * Equivalent to meshHandle(h) + fromBrep(sh, { solid: h }).
+ * Library authors only fall back to the meshHandle + fromBrep combination when
+ * they need custom tessellation precision.
+ * @param handle - the OCCT solid handle to bridge (numeric id or `__occtWasm`-tagged object).
+ * @param opts - optional tessellation options.
+ * @returns the registered Shape, as returned by fromBrep.
+ */
+export declare function fromHandle(handle: unknown, opts?: MeshHandleOptions): ReturnType<typeof fromBrep>;
+//# sourceMappingURL=handle-bridge.d.ts.map

package/dist/brep/handle-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-bridge.d.ts","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAUnC;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAMnC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhD;AAyBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAW3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAGjG"}

package/dist/brep/handle-bridge.js

@@ -0,0 +1,91 @@
+/**
+ * handle-bridge — OCCT 句柄 → faijs Shape 的 SDK 桥接（B1）
+ *
+ *
+ * 第三方库要造 BREP 产物，需要"OCCT handle → mesh"。`src/brep/brep-ops.ts:17`
+ * 有 `import * as THREE from 'three'`，SDK 绝不能 import 它（会把 three 拉进
+ * SDK bundle，违反 `src/sdk.test.ts` 的零 heavy 依赖守卫）。本文件在**新建的
+ * 零依赖模块**中实现，直接调运行时注入的 `kernel.meshShape`。
+ *
+ * 依赖约束（硬性）：只允许 import `runtime-state`、`stdlib/shape`、type-only
+ * `mesh/types`——任何新增依赖必须保持 dist/sdk.js 零 heavy 依赖守卫通过。
+ */
+import { getBackends } from '../runtime-state.js';
+import { fromBrep } from '../shape.js';
+/**
+ * Get the OCCT kernel instance faijs is currently using.
+ * @returns the current OCCT kernel.
+ * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.
+ */
+export function getKernel() {
+    const kernel = getBackends().kernel.brep;
+    if (!kernel) {
+        throw new Error('[faijs/bridge] OCCT kernel not available: BREP operations require an initialized kernel');
+    }
+    return kernel;
+}
+/**
+ * OCC 句柄身份契约判别（单一真源）。
+ *
+ * occt-wasm 的 `handle()` 工厂（vendored occtWasm helpers.ts:25）构造的句柄对象
+ * 统一携带 `__occtWasm: true`。本叶子是 faijs 侧唯一允许的判据：
+ * define-op 的 `wrapBrepOne` 用它区分"几何句柄"与"纯数据记录"，本文件
+ * `fromHandle`/`meshHandle` 入口用它做形态断言。禁止在其他文件硬编码
+ * `'__occtWasm' in v` 字符串直查——句柄/数据判定的任何新消费点都必须引用本叶子。
+ * @param v - 待判别的值。
+ * @returns `true` 当且仅当 `v` 是携带 `__occtWasm: true` 标记的句柄对象。
+ */
+export function isOcctHandle(v) {
+    return typeof v === 'object' && v !== null && v.__occtWasm === true;
+}
+/** 合法句柄输入：branded numeric id（occt-wasm 的 `ShapeHandle` 运行时形态）或
+ *  `__occtWasm` 标记对象（`handle()` 工厂产物）。 */
+function isHandleLike(v) {
+    return typeof v === 'number' || isOcctHandle(v);
+}
+/**
+ * 入口形态断言：拒绝把纯数据记录当句柄三角化。
+ * 纯数据记录（无 `__occtWasm` 标记的 plain object，如 sheetmetal part 数据）
+ * 必须在 SDK 边界被显式拒绝（E_BAD_HANDLE），而不是在 kernel 深处以
+ * `OcctError: meshShape: Invalid shape ID 0` 崩溃——define-op 的 wrapBrepOne
+ * 已在第一道透传过滤，本断言是第二道防线（防未来未带标记的新句柄形态漏网）。
+ */
+function requireHandle(handle, caller) {
+    if (!isHandleLike(handle)) {
+        throw new Error(`[faijs/bridge] ${caller}: E_BAD_HANDLE: expected an OCCT handle (numeric id or ` +
+            `__occtWasm-tagged object); got ${handle === null ? 'null' : typeof handle}. ` +
+            `Plain data records must not be tessellated as handles.`);
+    }
+}
+/**
+ * Tessellate an OCCT handle into a Shape (without registering a BREP slot).
+ * @param handle - the OCCT solid handle to tessellate (numeric id or `__occtWasm`-tagged object).
+ * @param opts - optional tessellation options.
+ * @returns the tessellated Shape.
+ */
+export function meshHandle(handle, opts) {
+    requireHandle(handle, 'meshHandle');
+    const kernel = getKernel();
+    const mesh = kernel.meshShape(handle, {
+        linearDeflection: opts?.linearDeflection ?? 0.1,
+        angularDeflection: (2 * Math.PI) / Math.max(3, opts?.segments ?? 32),
+    });
+    return {
+        positions: new Float32Array(mesh.positions),
+        indices: new Uint32Array(mesh.indices),
+    };
+}
+/**
+ * Default path (recommended): tessellate + register the BREP slot in one step.
+ * Equivalent to meshHandle(h) + fromBrep(sh, { solid: h }).
+ * Library authors only fall back to the meshHandle + fromBrep combination when
+ * they need custom tessellation precision.
+ * @param handle - the OCCT solid handle to bridge (numeric id or `__occtWasm`-tagged object).
+ * @param opts - optional tessellation options.
+ * @returns the registered Shape, as returned by fromBrep.
+ */
+export function fromHandle(handle, opts) {
+    requireHandle(handle, 'fromHandle');
+    return fromBrep(meshHandle(handle, opts), { solid: handle });
+}
+//# sourceMappingURL=handle-bridge.js.map

package/dist/brep/handle-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-bridge.js","sourceRoot":"","sources":["../../src/brep/handle-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAUnC;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAA;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAA;IAC5G,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAA8B,CAAC,UAAU,KAAK,IAAI,CAAA;AACnG,CAAC;AAED;0CAC0C;AAC1C,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,MAAe,EAAE,MAAc;IACpD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,kBAAkB,MAAM,yDAAyD;YAC/E,kCAAkC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,IAAI;YAC9E,wDAAwD,CAC3D,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,SAAS,EAAoB,CAAA;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE;QACpC,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,IAAI,GAAG;QAC/C,iBAAiB,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC;KACrE,CAAC,CAAA;IACF,OAAO;QACL,SAAS,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,SAA8B,CAAC;QAChE,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,OAA4B,CAAC;KAC5D,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,IAAwB;IAClE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAC9D,CAAC","sourcesContent":["/**\n * handle-bridge — OCCT 句柄 → faijs Shape 的 SDK 桥接（B1）\n *\n *\n * 第三方库要造 BREP 产物，需要\"OCCT handle → mesh\"。`src/brep/brep-ops.ts:17`\n * 有 `import * as THREE from 'three'`，SDK 绝不能 import 它（会把 three 拉进\n * SDK bundle，违反 `src/sdk.test.ts` 的零 heavy 依赖守卫）。本文件在**新建的\n * 零依赖模块**中实现，直接调运行时注入的 `kernel.meshShape`。\n *\n * 依赖约束（硬性）：只允许 import `runtime-state`、`stdlib/shape`、type-only\n * `mesh/types`——任何新增依赖必须保持 dist/sdk.js 零 heavy 依赖守卫通过。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends } from '../runtime-state'\nimport { fromBrep } from '../shape'\n\n/** 结构化内核接口（不 import occt-wasm，只做结构匹配，避免 heavy 依赖） */\ninterface MeshableKernel {\n  meshShape(\n    handle: unknown,\n    opts: { linearDeflection: number; angularDeflection: number },\n  ): { positions: ArrayLike<number>; indices: ArrayLike<number> }\n}\n\n/**\n * Get the OCCT kernel instance faijs is currently using.\n * @returns the current OCCT kernel.\n * @throws when the kernel is not ready (mesh mode or uninitialized) — never silently returns null.\n */\nexport function getKernel(): unknown {\n  const kernel = getBackends().kernel.brep\n  if (!kernel) {\n    throw new Error('[faijs/bridge] OCCT kernel not available: BREP operations require an initialized kernel')\n  }\n  return kernel\n}\n\n/**\n * Options controlling how a handle is tessellated.\n */\nexport interface MeshHandleOptions {\n  /** linear deflection (mm), default 0.1 — matches the built-in ops (src/brep/brep-ops.ts:27). */\n  linearDeflection?: number\n  /** angular segment count, default 32 — angularDeflection = 2π / segments. */\n  segments?: number\n}\n\n/**\n * OCC 句柄身份契约判别（单一真源）。\n *\n * occt-wasm 的 `handle()` 工厂（vendored occtWasm helpers.ts:25）构造的句柄对象\n * 统一携带 `__occtWasm: true`。本叶子是 faijs 侧唯一允许的判据：\n * define-op 的 `wrapBrepOne` 用它区分\"几何句柄\"与\"纯数据记录\"，本文件\n * `fromHandle`/`meshHandle` 入口用它做形态断言。禁止在其他文件硬编码\n * `'__occtWasm' in v` 字符串直查——句柄/数据判定的任何新消费点都必须引用本叶子。\n * @param v - 待判别的值。\n * @returns `true` 当且仅当 `v` 是携带 `__occtWasm: true` 标记的句柄对象。\n */\nexport function isOcctHandle(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && (v as { __occtWasm?: unknown }).__occtWasm === true\n}\n\n/** 合法句柄输入：branded numeric id（occt-wasm 的 `ShapeHandle` 运行时形态）或\n *  `__occtWasm` 标记对象（`handle()` 工厂产物）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'number' || isOcctHandle(v)\n}\n\n/**\n * 入口形态断言：拒绝把纯数据记录当句柄三角化。\n * 纯数据记录（无 `__occtWasm` 标记的 plain object，如 sheetmetal part 数据）\n * 必须在 SDK 边界被显式拒绝（E_BAD_HANDLE），而不是在 kernel 深处以\n * `OcctError: meshShape: Invalid shape ID 0` 崩溃——define-op 的 wrapBrepOne\n * 已在第一道透传过滤，本断言是第二道防线（防未来未带标记的新句柄形态漏网）。\n */\nfunction requireHandle(handle: unknown, caller: string): void {\n  if (!isHandleLike(handle)) {\n    throw new Error(\n      `[faijs/bridge] ${caller}: E_BAD_HANDLE: expected an OCCT handle (numeric id or ` +\n        `__occtWasm-tagged object); got ${handle === null ? 'null' : typeof handle}. ` +\n        `Plain data records must not be tessellated as handles.`,\n    )\n  }\n}\n\n/**\n * Tessellate an OCCT handle into a Shape (without registering a BREP slot).\n * @param handle - the OCCT solid handle to tessellate (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the tessellated Shape.\n */\nexport function meshHandle(handle: unknown, opts?: MeshHandleOptions): Shape {\n  requireHandle(handle, 'meshHandle')\n  const kernel = getKernel() as MeshableKernel\n  const mesh = kernel.meshShape(handle, {\n    linearDeflection: opts?.linearDeflection ?? 0.1,\n    angularDeflection: (2 * Math.PI) / Math.max(3, opts?.segments ?? 32),\n  })\n  return {\n    positions: new Float32Array(mesh.positions as ArrayLike<number>),\n    indices: new Uint32Array(mesh.indices as ArrayLike<number>),\n  }\n}\n\n/**\n * Default path (recommended): tessellate + register the BREP slot in one step.\n * Equivalent to meshHandle(h) + fromBrep(sh, { solid: h }).\n * Library authors only fall back to the meshHandle + fromBrep combination when\n * they need custom tessellation precision.\n * @param handle - the OCCT solid handle to bridge (numeric id or `__occtWasm`-tagged object).\n * @param opts - optional tessellation options.\n * @returns the registered Shape, as returned by fromBrep.\n */\nexport function fromHandle(handle: unknown, opts?: MeshHandleOptions): ReturnType<typeof fromBrep> {\n  requireHandle(handle, 'fromHandle')\n  return fromBrep(meshHandle(handle, opts), { solid: handle })\n}\n"]}