@faicad/faijs 0.22.2 → 0.29.3

package/dist/api/boolean.js

@@ -1,5 +1,5 @@
 /**
- * stdlib boolean — 布尔库函数（union/subtract/intersect，多输入）
+ * api boolean — 布尔库函数（union/subtract/intersect，多输入）
  *
  *
  * dispatchPath 静态判定 brep/mesh，BREP 路径用 *WithHistory 收集面演化。
@@ -12,9 +12,10 @@ import { solidToShape } from '../brep/brep-ops.js';
 import { booleanWithRoleTable, } from '../brep/face-evolution.js';
 import { getCurrentStmt, getBackends, keepHidden, nameOf } from '../runtime-state.js';
 import { getBrepApi } from '../brep/handle-bridge.js';
-import { fromBrep, brepOf, inputRoleTable } from '../shape.js';
+import { fromBrep, brepOf, hasMeshSolid, inputRoleTable } from '../shape.js';
 import { reconcileBrepInputs } from './reconcile.js';
 import { OpError } from './internal/result-unwrap.js';
+import { meshKernelFailure, meshSolidEntry, meshSolidProduct } from './internal/mesh-solid-op.js';
 import { defineOp } from '../sdk.js';
 import { engineCapabilitySet } from '../cad-runtime/backend-dispatch.js';
 // ── 共享内部实现 ──
@@ -44,7 +45,7 @@ function booleanBrep(inputs, operation) {
         const offenders = inputs
             .map((s, i) => (inputSolids[i] ? undefined : nameOf(s) ?? `input[${i}]`))
             .filter((x) => x !== undefined);
-        throw new OpError(`boolean/${operation}`, 'E_BREP_UNSUPPORTED', `[stdlib/boolean] ${operation}: input is not on the BREP chain (no OCCT handle) — ` +
+        throw new OpError(`boolean/${operation}`, 'E_BREP_UNSUPPORTED', `[api/boolean] ${operation}: input is not on the BREP chain (no OCCT handle) — ` +
             `non-solid geometry (wire/face/shell) cannot take part in a boolean. offenders: ${offenders.join(', ')}`);
     }
     let resultSolid;
@@ -52,17 +53,42 @@ function booleanBrep(inputs, operation) {
     let roleTable;
     // 链式布尔：每步 target（累积结果）与下一个 tool 合流
     const op = operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect';
+    // F 组（2026-10-03，FAULHABER/Beam-coupling 语料）：import_brep 资产可能是
+    // wire/face（ShapeBinder 冻结几何）——它们带 OCCT handle、能通过上面的
+    // 「无 handle」守卫，但 OCCT 的 BOP 只接受 solid：fuse(wire, solid) 直接
+    // "operation failed"（内核直测实证，PartShape5/PartShape6/PartShape93 均
+    // wire/face、vol=0）。C3c-1 已实证 0 体积线框成员对 compound invariants
+    // 零影响 ⇒ union 的语义是 solid 合流，非 solid 输入如实跳过（keepHidden
+    // 语义不变）；全非 solid 才抛错。cut/intersect 语义不变（工具/交域必须 solid）。
+    const NON_SOLID = new Set(['wire', 'face', 'shell', 'vertex', 'edge']);
+    const inputTypes = inputSolids.map((h) => {
+        try {
+            return h ? kernel.shapeType(h) : 'solid';
+        }
+        catch {
+            return 'solid';
+        }
+    });
+    // compound/compsolid 可能含 solid，是合法 fuse 输入——只跳过确定的非 solid 类型。
+    const boolIdx = operation === 'union'
+        ? inputTypes.map((t, i) => (NON_SOLID.has(t) ? -1 : i)).filter((i) => i >= 0)
+        : inputs.map((_, i) => i);
+    if (operation === 'union' && boolIdx.length === 0) {
+        throw new OpError(`boolean/${operation}`, 'E_BREP_UNSUPPORTED', `[api/boolean] ${operation}: no solid input — wire/face/shell geometry cannot fuse (types: ${inputTypes.join(', ')})`);
+    }
     // 静态定轨：当前引擎是否声明了本 op 的面演化核函数（读的是同一声明源 dispatchPath 用的
     // 能力集，不是运行时探测）。fuse/cut 因 gate 保证此处恒 true；intersect 在 occt true、
     // brepkit/mock false（后者走 L1 裸 `kernel[op]`，该方法是 BrepEngineApi 必需成员，必存在）。
     const historyCap = op === 'fuse' ? 'fuseWithHistory' : op === 'cut' ? 'cutWithHistory' : 'intersectWithHistory';
     const useHistory = engineCapabilitySet(getBackends().config.brepCapabilities).has(historyCap);
-    // 首个输入作为 target 起点
-    resultSolid = inputSolids[0];
+    // 首个 solid 输入作为 target 起点（F 组：可能不是 inputs[0] —— wire/face
+    // 资产常排在前面作为 profile/binder）。
+    resultSolid = inputSolids[boolIdx[0]];
     roleTable = useHistory
-        ? inputRoleTable(inputs[0])
+        ? inputRoleTable(inputs[boolIdx[0]])
         : undefined;
-    for (let i = 1; i < inputSolids.length; i++) {
+    for (let bi = 1; bi < boolIdx.length; bi++) {
+        const i = boolIdx[bi];
         const prev = resultSolid;
         const tool = inputSolids[i];
         if (useHistory) {
@@ -77,9 +103,39 @@ function booleanBrep(inputs, operation) {
                 r = booleanWithRoleTable(kernel, op, prev, tool, prevTable ?? new Map(), toolTable ?? new Map(), outStmt);
             }
             catch (cause) {
-                const msg = cause instanceof Error ? cause.message : String(cause);
-                throw new OpError(`boolean/${operation}`, 'E_OP_FAILED', `[stdlib/boolean] ${operation}: kernel ${op} failed for inputs ` +
-                    `${nameOf(inputs[0]) ?? 'input[0]'} × ${nameOf(inputs[i]) ?? `input[${i}]`} — ${msg}`, { cause });
+                // GOTCHA: OCCT 的 *WithHistory 在两输入共享子结构/历史（如布尔产物的布尔）
+                // 时可能 "operation failed"，而同一几何的裸布尔可以成功。降级重试一次裸
+                // kernel[op]：几何结果正确，代价是丢本次面演化/roleTable（如实降级，同下方
+                // 裸路径语义）。裸布尔也失败时，再试 unifySameDomain(两输入) 后重算——
+                // 真实语料（disk-drive）中 tool 是布尔产物且与 target 共享子域，裸 cut 仍失败、
+                // unify 后成功。全部失败才真正抛错。
+                try {
+                    resultSolid = kernel[op](prev, tool);
+                    lastEvolution = undefined;
+                    roleTable = undefined;
+                    if (i > 1)
+                        kernel.release(prev);
+                    continue;
+                }
+                catch {
+                    try {
+                        const uPrev = kernel.unifySameDomain(prev);
+                        const uTool = kernel.unifySameDomain(tool);
+                        resultSolid = kernel[op](uPrev, uTool);
+                        kernel.release(uPrev);
+                        kernel.release(uTool);
+                        lastEvolution = undefined;
+                        roleTable = undefined;
+                        if (i > 1)
+                            kernel.release(prev);
+                        continue;
+                    }
+                    catch {
+                        const msg = cause instanceof Error ? cause.message : String(cause);
+                        throw new OpError(`boolean/${operation}`, 'E_OP_FAILED', `[api/boolean] ${operation}: kernel ${op} failed for inputs ` +
+                            `${nameOf(inputs[0]) ?? 'input[0]'} × ${nameOf(inputs[i]) ?? `input[${i}]`} — ${msg}`, { cause });
+                    }
+                }
             }
             resultSolid = r.result;
             lastEvolution = r.faceEvolution;
@@ -92,7 +148,7 @@ function booleanBrep(inputs, operation) {
             }
             catch (cause) {
                 const msg = cause instanceof Error ? cause.message : String(cause);
-                throw new OpError(`boolean/${operation}`, 'E_OP_FAILED', `[stdlib/boolean] ${operation}: kernel ${op} failed for inputs ` +
+                throw new OpError(`boolean/${operation}`, 'E_OP_FAILED', `[api/boolean] ${operation}: kernel ${op} failed for inputs ` +
                     `${nameOf(inputs[0]) ?? 'input[0]'} × ${nameOf(inputs[i]) ?? `input[${i}]`} — ${msg}`, { cause });
             }
             lastEvolution = undefined;
@@ -103,12 +159,64 @@ function booleanBrep(inputs, operation) {
     }
     return fromBrep(solidToShape(kernel, resultSolid), lastEvolution ? { solid: resultSolid, faceEvolution: lastEvolution, roleTable } : { solid: resultSolid, roleTable });
 }
+/**
+ * 网格实体路径：brepkit 网格内核的布尔（方案 2026-10-01 §3.5 三明治）。
+ *
+ * 输入**全部**是网格实体——这一点由 `dispatchPath` 的链门禁保证
+ * （`E_MESH_SOLID_MIXED`：网格实体不得与链外几何同处一次调用），此处只复核不补救。
+ *
+ * 无面演化、无 roleTable：近似拓扑没有 hash 演化，造一张恒等映射就是假身份
+ * （与 brepkit 裸布尔降级同一条纪律）。
+ *
+ * 中间结果是本实现自己造的句柄（不是任何输入），故 i>1 步及时释放；**输入句柄一概
+ * 不释放**——生命周期归链（与 BREP 路径 booleanBrep 的 `if (i > 1) kernel.release(prev)`
+ * 同构）。
+ *
+ * @param inputs - the mesh-solid inputs (≥1).
+ * @param operation - union / subtract / intersect.
+ * @returns the boolean result as a new mesh part.
+ */
+function booleanMeshSolid(inputs, operation) {
+    const opLabel = `boolean/${operation}`;
+    const entries = inputs.map((s) => meshSolidEntry(s, opLabel));
+    const first = entries[0];
+    const kernel = first.kernel;
+    const op = operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect';
+    let result = first.solid;
+    for (let i = 1; i < entries.length; i++) {
+        const prev = result;
+        try {
+            result = kernel[op](prev, entries[i].solid);
+        }
+        catch (cause) {
+            throw meshKernelFailure(opLabel, 'E_OP_FAILED', `${op}(${nameOf(inputs[0]) ?? 'input[0]'} × ${nameOf(inputs[i]) ?? `input[${i}]`})`, cause);
+        }
+        // i>1：prev 是本实现上一步造出的中间实体，释放它（i=1 时 prev 是**输入**，不碰）。
+        if (i > 1)
+            first.backend.release(prev);
+    }
+    return meshSolidProduct(first, result);
+}
+/**
+ * 网格路径分流（方案 2026-10-01 §3.4 规则 4）：输入含网格实体 → brepkit 网格内核；
+ * 否则保持历史上限（内置 `mesh/` 的 manifold CSG）。两条路**互不冒充**——
+ * manifold 不认识网格实体（静态门禁），网格内核也不接受裸网格（无句柄）。
+ *
+ * @param inputs - the geometry inputs.
+ * @param operation - union / subtract / intersect.
+ * @returns the boolean product (mesh solid or manifold mesh shape).
+ */
+function booleanMeshPath(inputs, operation) {
+    if (inputs.some(hasMeshSolid))
+        return booleanMeshSolid(inputs, operation);
+    return booleanMesh(inputs, operation);
+}
 /** mesh 路径：manifold-3d mesh-CSG。 */
 async function booleanMesh(inputs, operation) {
     if (inputs.length < 2) {
         if (inputs.length === 1)
             return inputs[0];
-        throw new Error('[stdlib/boolean] boolean needs at least 1 input');
+        throw new Error('[api/boolean] boolean needs at least 1 input');
     }
     if (operation === 'union')
         return cad.union(inputs[0], inputs[1], ...inputs.slice(2));
@@ -141,10 +249,11 @@ async function booleanMesh(inputs, operation) {
  * const a = await cad.union(part0, part1)
   */
 export const union = defineOp({
+    meshEngines: ['brepkit'],
     mesh: (...shapes) => {
         if (shapes.length > 0)
             keepHidden(...shapes);
-        return booleanMesh(reconcileBrepInputs(shapes), 'union');
+        return booleanMeshPath(reconcileBrepInputs(shapes), 'union');
     },
     brep: (...shapes) => {
         if (shapes.length > 0)
@@ -175,9 +284,10 @@ export const union = defineOp({
  * const b = await cad.cut(part0, part1)
   */
 export const cut = defineOp({
+    meshEngines: ['brepkit'],
     mesh: (base, tool) => {
         keepHidden(base, tool);
-        return booleanMesh(reconcileBrepInputs([base, tool]), 'subtract');
+        return booleanMeshPath(reconcileBrepInputs([base, tool]), 'subtract');
     },
     brep: (base, tool) => {
         keepHidden(base, tool);
@@ -199,10 +309,11 @@ export const cut = defineOp({
  * const b = await cad.subtract(part0, part1)
   */
 export const subtract = defineOp({
+    meshEngines: ['brepkit'],
     mesh: (...shapes) => {
         if (shapes.length > 0)
             keepHidden(...shapes);
-        return booleanMesh(reconcileBrepInputs(shapes), 'subtract');
+        return booleanMeshPath(reconcileBrepInputs(shapes), 'subtract');
     },
     brep: (...shapes) => {
         if (shapes.length > 0)
@@ -226,10 +337,11 @@ export const subtract = defineOp({
  * const c = await cad.intersect(part0, part1)
   */
 export const intersect = defineOp({
+    meshEngines: ['brepkit'],
     mesh: (...shapes) => {
         if (shapes.length > 0)
             keepHidden(...shapes);
-        return booleanMesh(reconcileBrepInputs(shapes), 'intersect');
+        return booleanMeshPath(reconcileBrepInputs(shapes), 'intersect');
     },
     brep: (...shapes) => {
         if (shapes.length > 0)

package/dist/api/boolean.js.map

@@ -1 +1 @@
-{"version":3,"file":"boolean.js","sourceRoot":"","sources":["../../src/api/boolean.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib boolean — 布尔库函数（union/subtract/intersect，多输入）\n *\n *\n * dispatchPath 静态判定 brep/mesh，BREP 路径用 *WithHistory 收集面演化。\n *\n * 阶段 1：拆为三个薄函数 union/subtract/intersect + 兼容 boolean 导出（过渡）。\n * 阶段 3 将删除 boolean 兼容导出。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { solidToShape } from '../brep/brep-ops'\nimport {\n  booleanWithRoleTable,\n} from '../brep/face-evolution'\nimport { getCurrentStmt, getBackends, keepHidden, nameOf } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf, inputRoleTable } from '../shape'\nimport { reconcileBrepInputs } from './reconcile'\nimport { OpError } from './internal/result-unwrap'\nimport { defineOp } from '../sdk'\nimport { engineCapabilitySet } from '../cad-runtime/backend-dispatch'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepHandle } from '../brep/engine/types'\n\ntype BooleanOperation = 'union' | 'subtract' | 'intersect'\n\n// ── 共享内部实现 ──\n\n/**\n * BREP 路径：fuse/cut/intersect。\n *\n * 静态双轨（无运行时 try-catch 回退——按引擎**声明**的能力集在执行前定轨）：\n * - 引擎声明了对应 `*WithHistory`（occt 三员全有）→ `booleanWithRoleTable`：\n *   一次内核调用同时产出结果 + 面演化（faceEvolution）+ roleTable 合流（§3.4）。\n * - 引擎只声明了裸布尔方法（brepkit：声明了 `intersect` 但**没有** `intersectWithHistory`）\n *   → 走 L1 裸 `kernel[op](a,b)`：几何正确，但**不产生面演化、不传播 roleTable**。\n *   这是如实降级——绝不用「恒等映射」伪造一张把输入面 hash 指到结果面 hash 的演化表\n *   （结果实体的面 hash 与输入根本不同，恒等映射是假身份）。\n *\n * `intersect` 因此不再声明 `capabilities: ['intersectWithHistory']`（中立 op）：\n * brepkit 上由本函数静态落到裸 `intersect`；occt 上仍走 `intersectWithHistory`。\n * fuse/cut 保留各自 `*WithHistory` 能力声明——dispatchPath 的 gate 保证它们到达本函数时\n * 引擎必已声明对应历史方法，故下方 `useHistory` 对 fuse/cut 恒为 true。\n */\nfunction booleanBrep(inputs: Shape[], operation: BooleanOperation): Shape {\n  const kernel = getBrepApi()\n\n  const inputSolids = inputs.map((s) => brepOf(s) as BrepHandle | undefined)\n  if (inputSolids.some((s) => !s)) {\n    // V-C8 (C6): a non-solid import (wire/face/shell via cad.import_brep) has\n    // no OCCT handle yet — booleans must fail HERE with an explicit, op-named\n    // error, not with OCCT's raw \"boolean operation failed\" (or silently).\n    const offenders = inputs\n      .map((s, i) => (inputSolids[i] ? undefined : nameOf(s) ?? `input[${i}]`))\n      .filter((x): x is string => x !== undefined)\n    throw new OpError(\n      `boolean/${operation}`,\n      'E_BREP_UNSUPPORTED',\n      `[stdlib/boolean] ${operation}: input is not on the BREP chain (no OCCT handle) — ` +\n      `non-solid geometry (wire/face/shell) cannot take part in a boolean. offenders: ${offenders.join(', ')}`,\n    )\n  }\n\n  let resultSolid: BrepHandle\n  let lastEvolution: Map<number, number[]> | undefined\n  let roleTable: ReadonlyMap<unknown, unknown> | undefined\n\n  // 链式布尔：每步 target（累积结果）与下一个 tool 合流\n  const op: 'fuse' | 'cut' | 'intersect' =\n    operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect'\n\n  // 静态定轨：当前引擎是否声明了本 op 的面演化核函数（读的是同一声明源 dispatchPath 用的\n  // 能力集，不是运行时探测）。fuse/cut 因 gate 保证此处恒 true；intersect 在 occt true、\n  // brepkit/mock false（后者走 L1 裸 `kernel[op]`，该方法是 BrepEngineApi 必需成员，必存在）。\n  const historyCap = op === 'fuse' ? 'fuseWithHistory' : op === 'cut' ? 'cutWithHistory' : 'intersectWithHistory'\n  const useHistory = engineCapabilitySet(getBackends().config.brepCapabilities).has(historyCap)\n\n  // 首个输入作为 target 起点\n  resultSolid = inputSolids[0]!\n  roleTable = useHistory\n    ? (inputRoleTable(inputs[0]) as ReadonlyMap<unknown, unknown> | undefined)\n    : undefined\n\n  for (let i = 1; i < inputSolids.length; i++) {\n    const prev = resultSolid\n    const tool = inputSolids[i]!\n\n    if (useHistory) {\n      // §3.4：一次内核调用，A/B 拆流各自传播后合表（缝面 origin=本次语句 StmtId）\n      // V-C8：内核裸错误在此包一层——带上 op 名、两个输入的变量名与 cause。\n      const prevTable = roleTable\n      const toolTable = inputRoleTable(inputs[i]) as ReadonlyMap<unknown, unknown> | undefined\n      // Phase 1.6：新 origin = 本次语句的 StmtId。\n      const outStmt = String(getCurrentStmt()?.id ?? '')\n      let r: ReturnType<typeof booleanWithRoleTable>\n      try {\n        r = booleanWithRoleTable(\n          kernel,\n          op,\n          prev,\n          tool,\n          prevTable ?? new Map(),\n          toolTable ?? new Map(),\n          outStmt,\n        )\n      } catch (cause) {\n        const msg = cause instanceof Error ? cause.message : String(cause)\n        throw new OpError(\n          `boolean/${operation}`,\n          'E_OP_FAILED',\n          `[stdlib/boolean] ${operation}: kernel ${op} failed for inputs ` +\n          `${nameOf(inputs[0]!) ?? 'input[0]'} × ${nameOf(inputs[i]!) ?? `input[${i}]`} — ${msg}`,\n          { cause },\n        )\n      }\n      resultSolid = r.result\n      lastEvolution = r.faceEvolution\n      roleTable = r.roleTable\n    } else {\n      // 裸布尔降级路径：几何正确，但无面演化、无 roleTable 传播（如实降级，不伪造映射）。\n      try {\n        resultSolid = kernel[op](prev, tool)\n      } catch (cause) {\n        const msg = cause instanceof Error ? cause.message : String(cause)\n        throw new OpError(\n          `boolean/${operation}`,\n          'E_OP_FAILED',\n          `[stdlib/boolean] ${operation}: kernel ${op} failed for inputs ` +\n          `${nameOf(inputs[0]!) ?? 'input[0]'} × ${nameOf(inputs[i]!) ?? `input[${i}]`} — ${msg}`,\n          { cause },\n        )\n      }\n      lastEvolution = undefined\n      roleTable = undefined\n    }\n    if (i > 1) kernel.release(prev)\n  }\n\n  return fromBrep(\n    solidToShape(kernel, resultSolid),\n    lastEvolution ? { solid: resultSolid, faceEvolution: lastEvolution, roleTable } : { solid: resultSolid, roleTable },\n  )\n}\n\n/** mesh 路径：manifold-3d mesh-CSG。 */\nasync function booleanMesh(inputs: Shape[], operation: BooleanOperation): Promise<Shape> {\n  if (inputs.length < 2) {\n    if (inputs.length === 1) return inputs[0]\n    throw new Error('[stdlib/boolean] boolean needs at least 1 input')\n  }\n  if (operation === 'union') return cad.union(inputs[0], inputs[1], ...inputs.slice(2))\n  if (operation === 'subtract') {\n    let result = await cad.subtract(inputs[0], inputs[1])\n    for (let i = 2; i < inputs.length; i++) result = await cad.subtract(result, inputs[i])\n    return result\n  }\n  let result = await cad.intersect(inputs[0], inputs[1])\n  for (let i = 2; i < inputs.length; i++) result = await cad.intersect(result, inputs[i])\n  return result\n}\n\n// ── 三个薄导出（多输入 variadic，defineOp 声明双路径 + 逐核函数 face-evolution 能力） ──\n// 函数体 keep 声明（keep-syntax 设计 §2.5）：union/subtract/intersect 保留其\n// 输入且隐藏（R5：3d_editor 现状）——keepHidden 使源变量保持终端但 canvas\n// 不渲染，只有布尔结果正常显示。混合/断链时刻：BREP 侧输入先归约为合法\n// 2-manifold 网格（reconcileBrepInputs），mesh 侧原样透传。\n\n/**\n * 布尔并集：合并所有输入几何（≥2 个输入）。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name union\n * @param shapes - 参与运算的几何（变量引用，≥2 个）。type:Shape[] required:true\n * @returns Shape 所有输入的并集。函数名即操作，输入全是变量引用，可用 `cad.union(a, b, c)` 多输入。\n * @example\n * const a = await cad.union(part0, part1)\n  */\nexport const union = defineOp({\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMesh(reconcileBrepInputs(shapes), 'union')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'union')\n  },\n  // 逐核函数声明（Phase 0.2）：union 需要内核的 fuseWithHistory。\n  // 不再声明族级 'evolution'——族级名会让 brepkit（无 intersectWithHistory）等\n  // 部分实现的内核静默通过静态判定，再死在运行时（红线违规）。\n  capabilities: ['fuseWithHistory'],\n  schema: { shapes: 'Shape*' },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * Boolean cut (subtract): remove `tool` from `base`. Same semantics as\n * {@link subtract} but with the brepjs-compatible `(base, tool, options?)` signature.\n * Overrides the generated projection (compatOp) to do roleTable propagation\n * (Phase 3: L2 requires wall:<i> to survive cut).\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name cut\n * @param base - the target shape. type:Shape required:true\n * @param tool - the shape to subtract. type:Shape required:true\n * @returns Shape base minus tool.\n * @example\n * const b = await cad.cut(part0, part1)\n  */\nexport const cut = defineOp({\n  mesh: (base: Shape, tool: Shape) => {\n    keepHidden(base, tool)\n    return booleanMesh(reconcileBrepInputs([base, tool]), 'subtract')\n  },\n  brep: (base: Shape, tool: Shape) => {\n    keepHidden(base, tool)\n    return booleanBrep([base, tool], 'subtract')\n  },\n  capabilities: ['cutWithHistory'],\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * 布尔差集：第一个为主体，减去其余输入。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name subtract\n * @param shapes - 参与运算的几何（变量引用，第一个为主体）。type:Shape[] required:true\n * @returns Shape part0 减 part1 的差集（第一个为主体）。\n * @example\n * const b = await cad.subtract(part0, part1)\n  */\nexport const subtract = defineOp({\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMesh(reconcileBrepInputs(shapes), 'subtract')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'subtract')\n  },\n  // 逐核函数声明（Phase 0.2）：subtract 需要内核的 cutWithHistory。\n  capabilities: ['cutWithHistory'],\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * 布尔交集：所有输入的重叠部分。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name intersect\n * @param shapes - 参与运算的几何（变量引用）。type:Shape[] required:true\n * @returns Shape 所有输入的交集。\n * @example\n * const c = await cad.intersect(part0, part1)\n  */\nexport const intersect = defineOp({\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMesh(reconcileBrepInputs(shapes), 'intersect')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'intersect')\n  },\n  // 不声明 `capabilities: ['intersectWithHistory']`（中立 op）：\n  // brepkit 声明了裸 `intersect` 但没有 `intersectWithHistory`——若硬声明历史能力，\n  // brepkit brep 模式会在执行前静态报 `lacks capability 'intersectWithHistory'`。\n  // 现由 booleanBrep 按引擎声明的能力集静态分派：occt（声明 intersectWithHistory）\n  // 走历史路径保留面演化/naming；brepkit（只声明裸 intersect）走 L1 裸 `kernel.intersect`，\n  // 几何正确但无面演化（如实降级，不伪造恒等映射）。\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}
+{"version":3,"file":"boolean.js","sourceRoot":"","sources":["../../src/api/boolean.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api boolean — 布尔库函数（union/subtract/intersect，多输入）\n *\n *\n * dispatchPath 静态判定 brep/mesh，BREP 路径用 *WithHistory 收集面演化。\n *\n * 阶段 1：拆为三个薄函数 union/subtract/intersect + 兼容 boolean 导出（过渡）。\n * 阶段 3 将删除 boolean 兼容导出。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { solidToShape } from '../brep/brep-ops'\nimport {\n  booleanWithRoleTable,\n} from '../brep/face-evolution'\nimport { getCurrentStmt, getBackends, keepHidden, nameOf } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf, hasMeshSolid, inputRoleTable } from '../shape'\nimport { reconcileBrepInputs } from './reconcile'\nimport { OpError } from './internal/result-unwrap'\nimport { meshKernelFailure, meshSolidEntry, meshSolidProduct } from './internal/mesh-solid-op'\nimport { defineOp } from '../sdk'\nimport { engineCapabilitySet } from '../cad-runtime/backend-dispatch'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepHandle } from '../brep/engine/types'\n\ntype BooleanOperation = 'union' | 'subtract' | 'intersect'\n\n// ── 共享内部实现 ──\n\n/**\n * BREP 路径：fuse/cut/intersect。\n *\n * 静态双轨（无运行时 try-catch 回退——按引擎**声明**的能力集在执行前定轨）：\n * - 引擎声明了对应 `*WithHistory`（occt 三员全有）→ `booleanWithRoleTable`：\n *   一次内核调用同时产出结果 + 面演化（faceEvolution）+ roleTable 合流（§3.4）。\n * - 引擎只声明了裸布尔方法（brepkit：声明了 `intersect` 但**没有** `intersectWithHistory`）\n *   → 走 L1 裸 `kernel[op](a,b)`：几何正确，但**不产生面演化、不传播 roleTable**。\n *   这是如实降级——绝不用「恒等映射」伪造一张把输入面 hash 指到结果面 hash 的演化表\n *   （结果实体的面 hash 与输入根本不同，恒等映射是假身份）。\n *\n * `intersect` 因此不再声明 `capabilities: ['intersectWithHistory']`（中立 op）：\n * brepkit 上由本函数静态落到裸 `intersect`；occt 上仍走 `intersectWithHistory`。\n * fuse/cut 保留各自 `*WithHistory` 能力声明——dispatchPath 的 gate 保证它们到达本函数时\n * 引擎必已声明对应历史方法，故下方 `useHistory` 对 fuse/cut 恒为 true。\n */\nfunction booleanBrep(inputs: Shape[], operation: BooleanOperation): Shape {\n  const kernel = getBrepApi()\n\n  const inputSolids = inputs.map((s) => brepOf(s) as BrepHandle | undefined)\n  if (inputSolids.some((s) => !s)) {\n    // V-C8 (C6): a non-solid import (wire/face/shell via cad.import_brep) has\n    // no OCCT handle yet — booleans must fail HERE with an explicit, op-named\n    // error, not with OCCT's raw \"boolean operation failed\" (or silently).\n    const offenders = inputs\n      .map((s, i) => (inputSolids[i] ? undefined : nameOf(s) ?? `input[${i}]`))\n      .filter((x): x is string => x !== undefined)\n    throw new OpError(\n      `boolean/${operation}`,\n      'E_BREP_UNSUPPORTED',\n      `[api/boolean] ${operation}: input is not on the BREP chain (no OCCT handle) — ` +\n      `non-solid geometry (wire/face/shell) cannot take part in a boolean. offenders: ${offenders.join(', ')}`,\n    )\n  }\n\n  let resultSolid: BrepHandle\n  let lastEvolution: Map<number, number[]> | undefined\n  let roleTable: ReadonlyMap<unknown, unknown> | undefined\n\n  // 链式布尔：每步 target（累积结果）与下一个 tool 合流\n  const op: 'fuse' | 'cut' | 'intersect' =\n    operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect'\n\n  // F 组（2026-10-03，FAULHABER/Beam-coupling 语料）：import_brep 资产可能是\n  // wire/face（ShapeBinder 冻结几何）——它们带 OCCT handle、能通过上面的\n  // 「无 handle」守卫，但 OCCT 的 BOP 只接受 solid：fuse(wire, solid) 直接\n  // \"operation failed\"（内核直测实证，PartShape5/PartShape6/PartShape93 均\n  // wire/face、vol=0）。C3c-1 已实证 0 体积线框成员对 compound invariants\n  // 零影响 ⇒ union 的语义是 solid 合流，非 solid 输入如实跳过（keepHidden\n  // 语义不变）；全非 solid 才抛错。cut/intersect 语义不变（工具/交域必须 solid）。\n  const NON_SOLID = new Set(['wire', 'face', 'shell', 'vertex', 'edge'])\n  const inputTypes = inputSolids.map((h) => {\n    try { return h ? (kernel.shapeType(h) as string) : 'solid' } catch { return 'solid' }\n  })\n  // compound/compsolid 可能含 solid，是合法 fuse 输入——只跳过确定的非 solid 类型。\n  const boolIdx = operation === 'union'\n    ? inputTypes.map((t, i) => (NON_SOLID.has(t) ? -1 : i)).filter((i) => i >= 0)\n    : inputs.map((_, i) => i)\n  if (operation === 'union' && boolIdx.length === 0) {\n    throw new OpError(\n      `boolean/${operation}`,\n      'E_BREP_UNSUPPORTED',\n      `[api/boolean] ${operation}: no solid input — wire/face/shell geometry cannot fuse (types: ${inputTypes.join(', ')})`,\n    )\n  }\n\n  // 静态定轨：当前引擎是否声明了本 op 的面演化核函数（读的是同一声明源 dispatchPath 用的\n  // 能力集，不是运行时探测）。fuse/cut 因 gate 保证此处恒 true；intersect 在 occt true、\n  // brepkit/mock false（后者走 L1 裸 `kernel[op]`，该方法是 BrepEngineApi 必需成员，必存在）。\n  const historyCap = op === 'fuse' ? 'fuseWithHistory' : op === 'cut' ? 'cutWithHistory' : 'intersectWithHistory'\n  const useHistory = engineCapabilitySet(getBackends().config.brepCapabilities).has(historyCap)\n\n  // 首个 solid 输入作为 target 起点（F 组：可能不是 inputs[0] —— wire/face\n  // 资产常排在前面作为 profile/binder）。\n  resultSolid = inputSolids[boolIdx[0]!]!\n  roleTable = useHistory\n    ? (inputRoleTable(inputs[boolIdx[0]!]) as ReadonlyMap<unknown, unknown> | undefined)\n    : undefined\n\n  for (let bi = 1; bi < boolIdx.length; bi++) {\n    const i = boolIdx[bi]!\n    const prev = resultSolid\n    const tool = inputSolids[i]!\n\n    if (useHistory) {\n      // §3.4：一次内核调用，A/B 拆流各自传播后合表（缝面 origin=本次语句 StmtId）\n      // V-C8：内核裸错误在此包一层——带上 op 名、两个输入的变量名与 cause。\n      const prevTable = roleTable\n      const toolTable = inputRoleTable(inputs[i]) as ReadonlyMap<unknown, unknown> | undefined\n      // Phase 1.6：新 origin = 本次语句的 StmtId。\n      const outStmt = String(getCurrentStmt()?.id ?? '')\n      let r: ReturnType<typeof booleanWithRoleTable>\n      try {\n        r = booleanWithRoleTable(\n          kernel,\n          op,\n          prev,\n          tool,\n          prevTable ?? new Map(),\n          toolTable ?? new Map(),\n          outStmt,\n        )\n      } catch (cause) {\n        // GOTCHA: OCCT 的 *WithHistory 在两输入共享子结构/历史（如布尔产物的布尔）\n        // 时可能 \"operation failed\"，而同一几何的裸布尔可以成功。降级重试一次裸\n        // kernel[op]：几何结果正确，代价是丢本次面演化/roleTable（如实降级，同下方\n        // 裸路径语义）。裸布尔也失败时，再试 unifySameDomain(两输入) 后重算——\n        // 真实语料（disk-drive）中 tool 是布尔产物且与 target 共享子域，裸 cut 仍失败、\n        // unify 后成功。全部失败才真正抛错。\n        try {\n          resultSolid = kernel[op](prev, tool)\n          lastEvolution = undefined\n          roleTable = undefined\n          if (i > 1) kernel.release(prev)\n          continue\n        } catch {\n          try {\n            const uPrev = kernel.unifySameDomain(prev)\n            const uTool = kernel.unifySameDomain(tool)\n            resultSolid = kernel[op](uPrev, uTool)\n            kernel.release(uPrev)\n            kernel.release(uTool)\n            lastEvolution = undefined\n            roleTable = undefined\n            if (i > 1) kernel.release(prev)\n            continue\n          } catch {\n            const msg = cause instanceof Error ? cause.message : String(cause)\n            throw new OpError(\n              `boolean/${operation}`,\n              'E_OP_FAILED',\n              `[api/boolean] ${operation}: kernel ${op} failed for inputs ` +\n              `${nameOf(inputs[0]!) ?? 'input[0]'} × ${nameOf(inputs[i]!) ?? `input[${i}]`} — ${msg}`,\n              { cause },\n            )\n          }\n        }\n      }\n      resultSolid = r.result\n      lastEvolution = r.faceEvolution\n      roleTable = r.roleTable\n    } else {\n      // 裸布尔降级路径：几何正确，但无面演化、无 roleTable 传播（如实降级，不伪造映射）。\n      try {\n        resultSolid = kernel[op](prev, tool)\n      } catch (cause) {\n        const msg = cause instanceof Error ? cause.message : String(cause)\n        throw new OpError(\n          `boolean/${operation}`,\n          'E_OP_FAILED',\n          `[api/boolean] ${operation}: kernel ${op} failed for inputs ` +\n          `${nameOf(inputs[0]!) ?? 'input[0]'} × ${nameOf(inputs[i]!) ?? `input[${i}]`} — ${msg}`,\n          { cause },\n        )\n      }\n      lastEvolution = undefined\n      roleTable = undefined\n    }\n    if (i > 1) kernel.release(prev)\n  }\n\n  return fromBrep(\n    solidToShape(kernel, resultSolid),\n    lastEvolution ? { solid: resultSolid, faceEvolution: lastEvolution, roleTable } : { solid: resultSolid, roleTable },\n  )\n}\n\n/**\n * 网格实体路径：brepkit 网格内核的布尔（方案 2026-10-01 §3.5 三明治）。\n *\n * 输入**全部**是网格实体——这一点由 `dispatchPath` 的链门禁保证\n * （`E_MESH_SOLID_MIXED`：网格实体不得与链外几何同处一次调用），此处只复核不补救。\n *\n * 无面演化、无 roleTable：近似拓扑没有 hash 演化，造一张恒等映射就是假身份\n * （与 brepkit 裸布尔降级同一条纪律）。\n *\n * 中间结果是本实现自己造的句柄（不是任何输入），故 i>1 步及时释放；**输入句柄一概\n * 不释放**——生命周期归链（与 BREP 路径 booleanBrep 的 `if (i > 1) kernel.release(prev)`\n * 同构）。\n *\n * @param inputs - the mesh-solid inputs (≥1).\n * @param operation - union / subtract / intersect.\n * @returns the boolean result as a new mesh part.\n */\nfunction booleanMeshSolid(inputs: Shape[], operation: BooleanOperation): Shape {\n  const opLabel = `boolean/${operation}`\n  const entries = inputs.map((s) => meshSolidEntry(s, opLabel))\n  const first = entries[0]!\n  const kernel = first.kernel\n  const op: 'fuse' | 'cut' | 'intersect' =\n    operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect'\n\n  let result = first.solid\n  for (let i = 1; i < entries.length; i++) {\n    const prev = result\n    try {\n      result = kernel[op](prev, entries[i]!.solid)\n    } catch (cause) {\n      throw meshKernelFailure(\n        opLabel,\n        'E_OP_FAILED',\n        `${op}(${nameOf(inputs[0]!) ?? 'input[0]'} × ${nameOf(inputs[i]!) ?? `input[${i}]`})`,\n        cause,\n      )\n    }\n    // i>1：prev 是本实现上一步造出的中间实体，释放它（i=1 时 prev 是**输入**，不碰）。\n    if (i > 1) first.backend.release(prev)\n  }\n  return meshSolidProduct(first, result)\n}\n\n/**\n * 网格路径分流（方案 2026-10-01 §3.4 规则 4）：输入含网格实体 → brepkit 网格内核；\n * 否则保持历史上限（内置 `mesh/` 的 manifold CSG）。两条路**互不冒充**——\n * manifold 不认识网格实体（静态门禁），网格内核也不接受裸网格（无句柄）。\n *\n * @param inputs - the geometry inputs.\n * @param operation - union / subtract / intersect.\n * @returns the boolean product (mesh solid or manifold mesh shape).\n */\nfunction booleanMeshPath(inputs: Shape[], operation: BooleanOperation): Shape | Promise<Shape> {\n  if (inputs.some(hasMeshSolid)) return booleanMeshSolid(inputs, operation)\n  return booleanMesh(inputs, operation)\n}\n\n/** mesh 路径：manifold-3d mesh-CSG。 */\nasync function booleanMesh(inputs: Shape[], operation: BooleanOperation): Promise<Shape> {\n  if (inputs.length < 2) {\n    if (inputs.length === 1) return inputs[0]\n    throw new Error('[api/boolean] boolean needs at least 1 input')\n  }\n  if (operation === 'union') return cad.union(inputs[0], inputs[1], ...inputs.slice(2))\n  if (operation === 'subtract') {\n    let result = await cad.subtract(inputs[0], inputs[1])\n    for (let i = 2; i < inputs.length; i++) result = await cad.subtract(result, inputs[i])\n    return result\n  }\n  let result = await cad.intersect(inputs[0], inputs[1])\n  for (let i = 2; i < inputs.length; i++) result = await cad.intersect(result, inputs[i])\n  return result\n}\n\n// ── 三个薄导出（多输入 variadic，defineOp 声明双路径 + 逐核函数 face-evolution 能力） ──\n// 函数体 keep 声明（keep-syntax 设计 §2.5）：union/subtract/intersect 保留其\n// 输入且隐藏（R5：3d_editor 现状）——keepHidden 使源变量保持终端但 canvas\n// 不渲染，只有布尔结果正常显示。混合/断链时刻：BREP 侧输入先归约为合法\n// 2-manifold 网格（reconcileBrepInputs），mesh 侧原样透传。\n\n/**\n * 布尔并集：合并所有输入几何（≥2 个输入）。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name union\n * @param shapes - 参与运算的几何（变量引用，≥2 个）。type:Shape[] required:true\n * @returns Shape 所有输入的并集。函数名即操作，输入全是变量引用，可用 `cad.union(a, b, c)` 多输入。\n * @example\n * const a = await cad.union(part0, part1)\n  */\nexport const union = defineOp({\n  meshEngines: ['brepkit'],\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMeshPath(reconcileBrepInputs(shapes), 'union')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'union')\n  },\n  // 逐核函数声明（Phase 0.2）：union 需要内核的 fuseWithHistory。\n  // 不再声明族级 'evolution'——族级名会让 brepkit（无 intersectWithHistory）等\n  // 部分实现的内核静默通过静态判定，再死在运行时（红线违规）。\n  capabilities: ['fuseWithHistory'],\n  schema: { shapes: 'Shape*' },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * Boolean cut (subtract): remove `tool` from `base`. Same semantics as\n * {@link subtract} but with the brepjs-compatible `(base, tool, options?)` signature.\n * Overrides the generated projection (compatOp) to do roleTable propagation\n * (Phase 3: L2 requires wall:<i> to survive cut).\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name cut\n * @param base - the target shape. type:Shape required:true\n * @param tool - the shape to subtract. type:Shape required:true\n * @returns Shape base minus tool.\n * @example\n * const b = await cad.cut(part0, part1)\n  */\nexport const cut = defineOp({\n  meshEngines: ['brepkit'],\n  mesh: (base: Shape, tool: Shape) => {\n    keepHidden(base, tool)\n    return booleanMeshPath(reconcileBrepInputs([base, tool]), 'subtract')\n  },\n  brep: (base: Shape, tool: Shape) => {\n    keepHidden(base, tool)\n    return booleanBrep([base, tool], 'subtract')\n  },\n  capabilities: ['cutWithHistory'],\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * 布尔差集：第一个为主体，减去其余输入。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name subtract\n * @param shapes - 参与运算的几何（变量引用，第一个为主体）。type:Shape[] required:true\n * @returns Shape part0 减 part1 的差集（第一个为主体）。\n * @example\n * const b = await cad.subtract(part0, part1)\n  */\nexport const subtract = defineOp({\n  meshEngines: ['brepkit'],\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMeshPath(reconcileBrepInputs(shapes), 'subtract')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'subtract')\n  },\n  // 逐核函数声明（Phase 0.2）：subtract 需要内核的 cutWithHistory。\n  capabilities: ['cutWithHistory'],\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n\n/**\n * 布尔交集：所有输入的重叠部分。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name intersect\n * @param shapes - 参与运算的几何（变量引用）。type:Shape[] required:true\n * @returns Shape 所有输入的交集。\n * @example\n * const c = await cad.intersect(part0, part1)\n  */\nexport const intersect = defineOp({\n  meshEngines: ['brepkit'],\n  mesh: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanMeshPath(reconcileBrepInputs(shapes), 'intersect')\n  },\n  brep: (...shapes: Shape[]) => {\n    if (shapes.length > 0) keepHidden(...shapes)\n    return booleanBrep(shapes, 'intersect')\n  },\n  // 不声明 `capabilities: ['intersectWithHistory']`（中立 op）：\n  // brepkit 声明了裸 `intersect` 但没有 `intersectWithHistory`——若硬声明历史能力，\n  // brepkit brep 模式会在执行前静态报 `lacks capability 'intersectWithHistory'`。\n  // 现由 booleanBrep 按引擎声明的能力集静态分派：occt（声明 intersectWithHistory）\n  // 走历史路径保留面演化/naming；brepkit（只声明裸 intersect）走 L1 裸 `kernel.intersect`，\n  // 几何正确但无面演化（如实降级，不伪造恒等映射）。\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}

package/dist/api/cadquery-selectors/borrow-bridge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * cadquery-selectors/borrow-bridge — compatOp 提升边界归一（等价搬运自 cq-compat）
+ *
+ * 原实现位于 `packages/faijs-cadquery/src/workplane.ts` 的 `asBrepShape`，本文件为
+ * 原样搬运（仅 import 路径改为 core 内部相对路径），零逻辑改动。
+ */
+import type { Shape } from '../../mesh/types.js';
+/**
+ * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。
+ * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。
+ * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。
+ */
+export declare function asBrepShape(v: unknown): Shape;
+//# sourceMappingURL=borrow-bridge.d.ts.map

package/dist/api/cadquery-selectors/borrow-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"borrow-bridge.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/borrow-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAuB7C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAgB7C"}

package/dist/api/cadquery-selectors/borrow-bridge.js

@@ -0,0 +1,52 @@
+/**
+ * cadquery-selectors/borrow-bridge — compatOp 提升边界归一（等价搬运自 cq-compat）
+ *
+ * 原实现位于 `packages/faijs-cadquery/src/workplane.ts` 的 `asBrepShape`，本文件为
+ * 原样搬运（仅 import 路径改为 core 内部相对路径），零逻辑改动。
+ */
+import { fromHandle } from '../../sdk.js';
+import { isShape } from '../../shape.js';
+// ── compatOp 提升边界归一（GOTCHA：borrowDeep 把实参 Shape 换成借用视图）──
+//
+// 当 cq-compat 命名空间被 registerLib 提升（无 dual-op → autoLift=true）时，
+// 每个裸导出函数的实参先经 borrowDeep：faijs Shape → 借用 brepjs 视图
+// `{ wrapped, disposed, delete, onDispose }`（`isShape=false`、`brepOf=undefined`）。
+// 直接调用（测试进程内）拿到的则是真实 Shape。两个形态都必须能消费：
+//
+//   asBrepShape(v) —
+//   - 真实 Shape → 原样返回；
+//   - 借用视图（有 `.wrapped`）→ 提取原始 OCCT 句柄，fromHandle 还原为真实
+//     Shape（mesh 三角化 + BREP 身份槽登记，brepOf 可恢复），按视图对象缓存
+//     （同句柄多次调用不重复三角化）；
+//   - 其余 → 原样返回（调用方自行判空/报错）。
+//
+// 所有权：归一出的新 Shape 与原 part Shape 的 slot 指向同一 OCCT 句柄，但 slot
+// 按 Shape 对象各自持有（fromBrep 写的是新 Shape 的 slot），无共享释放路径——
+// 与 core fromHandle 收编模式同构，不引入双重释放。
+// 视图 `.wrapped` 是 OcctWasmHandle 对象（{ id, type, __occtWasm }），内核只收
+// 数字 id → 解包方式与 core fromHandle 一致。
+const borrowedShapeCache = new WeakMap();
+/**
+ * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。
+ * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。
+ * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。
+ */
+export function asBrepShape(v) {
+    if (isShape(v))
+        return v;
+    if (v !== null && typeof v === 'object' && 'wrapped' in v) {
+        const view = v;
+        const hit = borrowedShapeCache.get(view);
+        if (hit)
+            return hit;
+        const wrappedAny = view.wrapped;
+        const handle = typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny
+            ? wrappedAny.id
+            : wrappedAny;
+        const s = fromHandle(handle);
+        borrowedShapeCache.set(view, s);
+        return s;
+    }
+    return v;
+}
+//# sourceMappingURL=borrow-bridge.js.map

package/dist/api/cadquery-selectors/borrow-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"borrow-bridge.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/borrow-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAGrC,2DAA2D;AAC3D,EAAE;AACF,gEAAgE;AAChE,qDAAqD;AACrD,kFAAkF;AAClF,uCAAuC;AACvC,EAAE;AACF,qBAAqB;AACrB,uBAAuB;AACvB,wDAAwD;AACxD,sDAAsD;AACtD,uBAAuB;AACvB,6BAA6B;AAC7B,EAAE;AACF,2DAA2D;AAC3D,uDAAuD;AACvD,oCAAoC;AACpC,mEAAmE;AACnE,oCAAoC;AACpC,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAiB,CAAA;AAEvD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,IAAI,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAU,CAAA;IACjC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,CAAyB,CAAA;QACtC,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACxC,IAAI,GAAG;YAAE,OAAO,GAAG,CAAA;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAA;QAC/B,MAAM,MAAM,GACV,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,IAAI,IAAI,IAAI,UAAU;YACzE,CAAC,CAAE,UAA6B,CAAC,EAAE;YACnC,CAAC,CAAC,UAAU,CAAA;QAChB,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAU,CAAA;QACrC,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;QAC/B,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,CAAU,CAAA;AACnB,CAAC","sourcesContent":["/**\n * cadquery-selectors/borrow-bridge — compatOp 提升边界归一（等价搬运自 cq-compat）\n *\n * 原实现位于 `packages/faijs-cadquery/src/workplane.ts` 的 `asBrepShape`，本文件为\n * 原样搬运（仅 import 路径改为 core 内部相对路径），零逻辑改动。\n */\n\nimport { fromHandle } from '../../sdk'\nimport { isShape } from '../../shape'\nimport type { Shape } from '../../mesh/types'\n\n// ── compatOp 提升边界归一（GOTCHA：borrowDeep 把实参 Shape 换成借用视图）──\n//\n// 当 cq-compat 命名空间被 registerLib 提升（无 dual-op → autoLift=true）时，\n// 每个裸导出函数的实参先经 borrowDeep：faijs Shape → 借用 brepjs 视图\n// `{ wrapped, disposed, delete, onDispose }`（`isShape=false`、`brepOf=undefined`）。\n// 直接调用（测试进程内）拿到的则是真实 Shape。两个形态都必须能消费：\n//\n//   asBrepShape(v) —\n//   - 真实 Shape → 原样返回；\n//   - 借用视图（有 `.wrapped`）→ 提取原始 OCCT 句柄，fromHandle 还原为真实\n//     Shape（mesh 三角化 + BREP 身份槽登记，brepOf 可恢复），按视图对象缓存\n//     （同句柄多次调用不重复三角化）；\n//   - 其余 → 原样返回（调用方自行判空/报错）。\n//\n// 所有权：归一出的新 Shape 与原 part Shape 的 slot 指向同一 OCCT 句柄，但 slot\n// 按 Shape 对象各自持有（fromBrep 写的是新 Shape 的 slot），无共享释放路径——\n// 与 core fromHandle 收编模式同构，不引入双重释放。\n// 视图 `.wrapped` 是 OcctWasmHandle 对象（{ id, type, __occtWasm }），内核只收\n// 数字 id → 解包方式与 core fromHandle 一致。\nconst borrowedShapeCache = new WeakMap<object, Shape>()\n\n/**\n * 把可能是借用视图的几何输入归一为真实 faijs Shape（见上方注释）。\n * @param v 真实 Shape、借用视图（`{ wrapped }`）或其他原样透传的输入。\n * @returns 真实 faijs `Shape`（借用视图经 `fromHandle` 还原并缓存）。\n */\nexport function asBrepShape(v: unknown): Shape {\n  if (isShape(v)) return v as Shape\n  if (v !== null && typeof v === 'object' && 'wrapped' in v) {\n    const view = v as { wrapped: unknown }\n    const hit = borrowedShapeCache.get(view)\n    if (hit) return hit\n    const wrappedAny = view.wrapped\n    const handle =\n      typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny\n        ? (wrappedAny as { id: number }).id\n        : wrappedAny\n    const s = fromHandle(handle) as Shape\n    borrowedShapeCache.set(view, s)\n    return s\n  }\n  return v as Shape\n}"]}

package/dist/api/cadquery-selectors/edge.d.ts

@@ -0,0 +1,40 @@
+import type { Shape } from '../../mesh/types.js';
+/**
+ * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY
+ * the new selector engine (upstream `selectors.py` semantics):
+ *
+ *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)
+ *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)
+ *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)
+ *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)
+ *   · `%LINE` / `%CIRCLE` — TypeSelector
+ *   · `and` / `or` / `except` / `not` — set algebra
+ *   · empty / missing — all edges (CadQuery `.edges()`)
+ *
+ * @param shape - Shape whose BREP edges are enumerated for selection.
+ * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.
+ * @returns the matched edge handles (kernel identity space; cast to unknown).
+ */
+export declare function resolveEdgeSelection(shape: Shape, sel: string | null | undefined): unknown[];
+/**
+ * Resolve the edges belonging to the face picked by `sel` — upstream
+ * `.faces(">Z").edges()` semantics. The face selector runs first over the
+ * face candidate set, then the survivors' edges are collected (chain widening
+ * to edges, no filter): the selected face's own edges.
+ *
+ * @param shape - the shape whose BREP faces/edges are enumerated.
+ * @param sel - a face direction / type selector (">Z", "+Y", "%PLANE", etc.).
+ * @returns the handles of the edges belonging to the selected face(s).
+ */
+export declare function resolveFaceEdgeSelection(shape: Shape, sel: string): unknown[];
+/**
+ * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).
+ * Mirrors the narrowing semantics of the engine: direction-less selectors drop,
+ * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.
+ *
+ * @param shape - the shape whose BREP vertices are enumerated.
+ * @param sel - the vertex selector string, or empty/undefined for all vertices.
+ * @returns the matched vertex handles.
+ */
+export declare function resolveVertexSelection(shape: Shape, sel: string | null | undefined): unknown[];
+//# sourceMappingURL=edge.d.ts.map

package/dist/api/cadquery-selectors/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/edge.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAO7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,CAG5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE,CAM7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,CAE9F"}

package/dist/api/cadquery-selectors/edge.js

@@ -0,0 +1,70 @@
+/**
+ * cadquery-selectors/edge — CadQuery edge/vertex 选择器（hoild core 引擎 adapter）
+ *
+ * These are thin projections over the selector engine (plan §4.6). The heavy
+ * lifting (direction rules, Nth clustering, set algebra, type filtering) lives
+ * in `resolve.ts`; this file only bridges a faijs `Shape` into the engine's
+ * kernel-handle space and adapts the result back to the cq-compat-consumed
+ * `unknown[]` handle form.
+ *
+ * The legacy bbox-heuristic implementations (edn.g. `#Z` interpreted as "max
+ * along axis", `|Z` from relative extents) were removed in favour of the
+ * upstream `cadquery/selectors.py` semantics validated by
+ * `selectors.test.ts`.
+ */
+import { resolveSelection, resolveStepHandles } from './resolve.js';
+import { brepOf } from '../../shape.js';
+/** faijs BREP handle for a shape (numeric id space shared with occt-wasm). */
+function ownerHandle(shape) {
+    return brepOf(shape);
+}
+/**
+ * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY
+ * the new selector engine (upstream `selectors.py` semantics):
+ *
+ *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)
+ *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)
+ *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)
+ *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)
+ *   · `%LINE` / `%CIRCLE` — TypeSelector
+ *   · `and` / `or` / `except` / `not` — set algebra
+ *   · empty / missing — all edges (CadQuery `.edges()`)
+ *
+ * @param shape - Shape whose BREP edges are enumerated for selection.
+ * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.
+ * @returns the matched edge handles (kernel identity space; cast to unknown).
+ */
+export function resolveEdgeSelection(shape, sel) {
+    const selStr = sel ?? '';
+    return resolveStepHandles(ownerHandle(shape), 'edge', selStr);
+}
+/**
+ * Resolve the edges belonging to the face picked by `sel` — upstream
+ * `.faces(">Z").edges()` semantics. The face selector runs first over the
+ * face candidate set, then the survivors' edges are collected (chain widening
+ * to edges, no filter): the selected face's own edges.
+ *
+ * @param shape - the shape whose BREP faces/edges are enumerated.
+ * @param sel - a face direction / type selector (">Z", "+Y", "%PLANE", etc.).
+ * @returns the handles of the edges belonging to the selected face(s).
+ */
+export function resolveFaceEdgeSelection(shape, sel) {
+    const owner = ownerHandle(shape);
+    return resolveSelection(owner, [
+        { kind: 'face', sel },
+        { kind: 'edge', sel: '' },
+    ]).handles;
+}
+/**
+ * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).
+ * Mirrors the narrowing semantics of the engine: direction-less selectors drop,
+ * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.
+ *
+ * @param shape - the shape whose BREP vertices are enumerated.
+ * @param sel - the vertex selector string, or empty/undefined for all vertices.
+ * @returns the matched vertex handles.
+ */
+export function resolveVertexSelection(shape, sel) {
+    return resolveStepHandles(ownerHandle(shape), 'vertex', sel ?? '');
+}
+//# sourceMappingURL=edge.js.map

package/dist/api/cadquery-selectors/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../../src/api/cadquery-selectors/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,8EAA8E;AAC9E,SAAS,WAAW,CAAC,KAAY;IAC/B,OAAO,MAAM,CAAC,KAAK,CAAY,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY,EAAE,GAA8B;IAC/E,MAAM,MAAM,GAAG,GAAG,IAAI,EAAE,CAAA;IACxB,OAAO,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAU,EAAE,MAAM,EAAE,MAAM,CAAc,CAAA;AACrF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAY,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAU,CAAA;IACzC,OAAO,gBAAgB,CAAC,KAAK,EAAE;QAC7B,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QACrB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE;KAC1B,CAAC,CAAC,OAAoB,CAAA;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,GAA8B;IACjF,OAAO,kBAAkB,CAAC,WAAW,CAAC,KAAK,CAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAc,CAAA;AAC1F,CAAC","sourcesContent":["/**\n * cadquery-selectors/edge — CadQuery edge/vertex 选择器（hoild core 引擎 adapter）\n *\n * These are thin projections over the selector engine (plan §4.6). The heavy\n * lifting (direction rules, Nth clustering, set algebra, type filtering) lives\n * in `resolve.ts`; this file only bridges a faijs `Shape` into the engine's\n * kernel-handle space and adapts the result back to the cq-compat-consumed\n * `unknown[]` handle form.\n *\n * The legacy bbox-heuristic implementations (edn.g. `#Z` interpreted as \"max\n * along axis\", `|Z` from relative extents) were removed in favour of the\n * upstream `cadquery/selectors.py` semantics validated by\n * `selectors.test.ts`.\n */\nimport { resolveSelection, resolveStepHandles } from './resolve'\nimport { brepOf } from '../../shape'\nimport type { Shape } from '../../mesh/types'\n\n/** faijs BREP handle for a shape (numeric id space shared with occt-wasm). */\nfunction ownerHandle(shape: Shape): unknown {\n  return brepOf(shape) as unknown\n}\n\n/**\n * Resolve a CadQuery EDGE selector string to concrete edge handles, using ONLY\n * the new selector engine (upstream `selectors.py` semantics):\n *\n *   · `|Z` — ParallelDirSelector (edges whose tangent is parallel to the axis)\n *   · `#Z` — PerpendicularDirSelector (edges whose tangent is perpendicular)\n *   · `X` / `+X` / `-X` — DirectionSelector (signed tangent angle≈0)\n *   · `>Z` / `<Z` — DirectionMinMaxSelector (extremal edge center along axis)\n *   · `%LINE` / `%CIRCLE` — TypeSelector\n *   · `and` / `or` / `except` / `not` — set algebra\n *   · empty / missing — all edges (CadQuery `.edges()`)\n *\n * @param shape - Shape whose BREP edges are enumerated for selection.\n * @param sel - CadQuery edge selector, or empty/null/undefined for all edges.\n * @returns the matched edge handles (kernel identity space; cast to unknown).\n */\nexport function resolveEdgeSelection(shape: Shape, sel: string | null | undefined): unknown[] {\n  const selStr = sel ?? ''\n  return resolveStepHandles(ownerHandle(shape) as never, 'edge', selStr) as unknown[]\n}\n\n/**\n * Resolve the edges belonging to the face picked by `sel` — upstream\n * `.faces(\">Z\").edges()` semantics. The face selector runs first over the\n * face candidate set, then the survivors' edges are collected (chain widening\n * to edges, no filter): the selected face's own edges.\n *\n * @param shape - the shape whose BREP faces/edges are enumerated.\n * @param sel - a face direction / type selector (\">Z\", \"+Y\", \"%PLANE\", etc.).\n * @returns the handles of the edges belonging to the selected face(s).\n */\nexport function resolveFaceEdgeSelection(shape: Shape, sel: string): unknown[] {\n  const owner = ownerHandle(shape) as never\n  return resolveSelection(owner, [\n    { kind: 'face', sel },\n    { kind: 'edge', sel: '' },\n  ]).handles as unknown[]\n}\n\n/**\n * Resolve a CadQuery vertex selector string to vertex handles (upstream `.vertices()`).\n * Mirrors the narrowing semantics of the engine: direction-less selectors drop,\n * cluster-based (`>`, `<`, `>>`, `<<`, `(x,y,z)`) apply.\n *\n * @param shape - the shape whose BREP vertices are enumerated.\n * @param sel - the vertex selector string, or empty/undefined for all vertices.\n * @returns the matched vertex handles.\n */\nexport function resolveVertexSelection(shape: Shape, sel: string | null | undefined): unknown[] {\n  return resolveStepHandles(ownerHandle(shape) as never, 'vertex', sel ?? '') as unknown[]\n}"]}