@faicad/faijs 0.13.0

package/dist/api/boolean.js.map

@@ -0,0 +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 { getBackends, getCurrentStmt, keepHidden } from '../runtime-state'\nimport { fromBrep, brepOf, getSlot } from '../shape'\nimport { reconcileBrepInputs } from './reconcile'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\ntype BooleanOperation = 'union' | 'subtract' | 'intersect'\n\n// ── 共享内部实现 ──\n\n/** BREP 路径：fuse/cut/common（*WithHistory 封装，收集面演化 + roleTable 合流 §3.4）。 */\nfunction booleanBrep(inputs: Shape[], operation: BooleanOperation): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/boolean] no OCCT kernel')\n\n  const inputSolids = inputs.map((s) => brepOf(s) as BrepHandle | undefined)\n  if (inputSolids.some((s) => !s)) {\n    throw new Error('[stdlib/boolean] input is not BREP')\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  // 首个输入作为 target 起点\n  resultSolid = inputSolids[0]!\n  roleTable = getSlot(inputs[0])?.roleTable as ReadonlyMap<unknown, unknown> | undefined\n\n  for (let i = 1; i < inputSolids.length; i++) {\n    const prev = resultSolid\n    const prevTable = roleTable\n    const toolTable = getSlot(inputs[i])?.roleTable as ReadonlyMap<unknown, unknown> | undefined\n    const outPart = String(getCurrentStmt()?.outputs[0] ?? '')\n\n    // §3.4：一次内核调用，A/B 拆流各自传播后合表（缝面以本次语句 LHS 为新 origin）\n    const r = booleanWithRoleTable(\n      kernel,\n      op,\n      prev,\n      inputSolids[i]!,\n      prevTable ?? new Map(),\n      toolTable ?? new Map(),\n      outPart,\n    )\n    resultSolid = r.result\n    lastEvolution = r.faceEvolution\n    roleTable = r.roleTable\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 声明双路径 + 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  capabilities: ['evolution'],\n  schema: { shapes: 'Shape*' },\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  capabilities: ['evolution'],\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: ['evolution'],\n})\n"]}

package/dist/api/brep-mirror/joinery-brep.d.ts

@@ -0,0 +1,172 @@
+/**
+ * BREP 榫卯结构操作 — 用 OCCT 精确实体复刻 mesh 路径的榫卯布尔序列
+ *
+ * See docs/api-contract.md §8 (dual-path geometry contract) and §10.5 (split).
+ *
+ * 与 mesh 路径（joinery-shapes.ts + csg-worker.ts）对照：
+ * - mesh 路径：buildWedgeGeometry/buildDowelGeometry/buildStraightTenonGeometry → Manifold CSG
+ * - BREP 路径：buildWedgeSolid/buildDowelSolid/buildTenonSolid → OCCT fuse/cut/common
+ *
+ * 坐标框架与 mesh 路径完全一致：
+ * - normal: 切割平面法线（单位向量，指向上方）
+ * - widthDir: 挤出方向（单位向量）
+ * - depthDir = normalize(cross(normal, widthDir))
+ * - planeCenter: 切割平面中心
+ *
+ * 所有函数都是纯函数，输入输出均为 OCCT BrepHandle，调用方负责句柄生命周期。
+ */
+import type { BrepHandle } from '../../brep/engine/types.js';
+import type { BrepEngineApi } from '../../brep/engine/primitives.js';
+import type { Vec3 } from '../../mesh/types.js';
+/** 榫卯操作的坐标框架（与 joinery-shapes.ts 一致） */
+export interface JoineryBasis {
+    /** 切割平面法线（单位向量） */
+    normal: Vec3;
+    /** 宽度/挤出方向（单位向量） */
+    widthDir: Vec3;
+    /** 深度方向 = normalize(cross(normal, widthDir)) */
+    depthDir: Vec3;
+    /** 切割平面中心 */
+    planeCenter: Vec3;
+    /** 平面原点偏移 = dot(normal, planeCenter) */
+    originOffset: number;
+}
+/**
+ * 梯形棱柱（燕尾楔）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildWedgeGeometry 的 8 顶点拓扑：
+ * - 梯形截面在 normal-depthDir 平面
+ * - 底边（宽）在 planeCenter - normal*depth
+ * - 顶边（窄）在 planeCenter
+ * - 沿 widthDir 拉伸 extrudeLength，居中于 planeCenter
+ *
+ * 用 kernel.makeLineEdge + makeWire + makeFace + extrude 构造实体，
+ * 然后用 transform 对齐到世界坐标系。
+ * @param kernel - the BREP engine API.
+ * @param basis - the joinery coordinate frame (normal/widthDir/depthDir/planeCenter).
+ * @param depth - the wedge depth along the normal direction.
+ * @param width - the wedge bottom width.
+ * @param angleDeg - the dovetail flap angle in degrees.
+ * @param extrudeLength - the extrusion length along the width direction.
+ * @returns the constructed wedge solid handle.
+ */
+export declare function buildWedgeSolid(kernel: BrepEngineApi, basis: JoineryBasis, depth: number, width: number, angleDeg: number, extrudeLength: number): BrepHandle;
+/**
+ * 圆柱（定位销）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildDowelGeometry：
+ * - 圆截面在 widthDir-depthDir 平面，中心在 centroid
+ * - 从切割平面向下延伸 height（沿 -normal）
+ *
+ * 用 kernel.makeCylinder + transform 对齐方向。
+ * @param kernel - the BREP engine API.
+ * @param centroid - the centroid where the dowel is placed.
+ * @param basis - the joinery coordinate frame.
+ * @param diameter - the dowel diameter.
+ * @param height - the dowel height along the normal direction.
+ * @returns the constructed dowel solid handle.
+ */
+export declare function buildDowelSolid(kernel: BrepEngineApi, centroid: Vec3, basis: JoineryBasis, diameter: number, height: number): BrepHandle;
+/**
+ * 长方体（直榫）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildStraightTenonGeometry：
+ * - 方截面在 widthDir-depthDir 平面，中心在 centroid
+ * - 从切割平面向下延伸 height（沿 -normal）
+ *
+ * 用 kernel.makeBoxFromCorners + transform 对齐方向。
+ * @param kernel - the BREP engine API.
+ * @param centroid - the centroid where the tenon is placed.
+ * @param basis - the joinery coordinate frame.
+ * @param sideLength - the tenon square side length.
+ * @param height - the tenon height along the normal direction.
+ * @returns the constructed tenon solid handle.
+ */
+export declare function buildTenonSolid(kernel: BrepEngineApi, centroid: Vec3, basis: JoineryBasis, sideLength: number, height: number): BrepHandle;
+/** 截面分量信息 */
+export interface CrossSectionComponent {
+    /** 分量质心 */
+    centroid: Vec3;
+    /** 分量面积（近似，用于排序） */
+    area: number;
+}
+/**
+ * 检测上部实体在切割平面上的截面连通分量。
+ *
+ * BREP 等价物：将 upper solid 三角化后，用与 mesh 路径 detectCapComponents
+ * 完全相同的算法（找帽面三角形 → union-find）检测连通分量。
+ *
+ * 与 csg-worker.ts detectCapComponents + computeCrossSectionCentroid 一致。
+ * @param kernel - the BREP engine API.
+ * @param upper - the upper solid whose cross section is analyzed.
+ * @param basis - the joinery coordinate frame.
+ * @returns the detected cross-section components (centroid + area).
+ */
+export declare function detectCrossSectionComponents(kernel: BrepEngineApi, upper: BrepHandle, basis: JoineryBasis): CrossSectionComponent[];
+/** dovetail 布尔分割的结果 */
+export interface DovetailSplitBrepResult {
+    /** 上部 + 楔（法线正方向半部分加燕尾榫） */
+    front: BrepHandle;
+    /** 下部 - 凹腔（法线负方向半部分减燕尾槽） */
+    back: BrepHandle;
+}
+/** dowel/tenon 布尔分割的结果 */
+export interface DowelOrTenonSplitBrepResult {
+    /** 上部 + 销/榫（法线正方向半部分加圆柱/方柱） */
+    front: BrepHandle;
+    /** 下部 - 孔（法线负方向半部分减圆柱/方柱） */
+    back: BrepHandle;
+}
+/** groove 参数 */
+export interface GrooveParams {
+    depth: number;
+    depthTolerance: number;
+    width: number;
+    widthTolerance: number;
+    flapsAngle: number;
+}
+/**
+ * Dovetail（燕尾）布尔分割 — BREP 等价物。
+ *
+ * 1:1 复刻 csg-worker.ts dovetailBooleanSplit：
+ * 1. splitBrep → upper + lower
+ * 2. 计算 crossSectionWidth（bbox 投影近似）
+ * 3. buildWedgeSolid（overhang=20）→ common(wedge, lower) 裁剪贴合
+ * 4. fuse(upper, wedgeTrimmed) → upper'
+ * 5. buildWedgeSolid（公差）→ cut(lower, wedgeTol) → lower'
+ * @param kernel - the BREP engine API.
+ * @param original - the original solid to split.
+ * @param basis - the joinery coordinate frame.
+ * @param groove - the dovetail groove parameters.
+ * @returns the split result with front (upper + wedge) and back (lower - cavity) handles.
+ */
+export declare function dovetailBooleanSplitBrep(kernel: BrepEngineApi, original: BrepHandle, basis: JoineryBasis, groove: GrooveParams): DovetailSplitBrepResult;
+/** dowel/tenon 参数 */
+export interface DowelOrTenonParams {
+    /** 直径（dowel）或边长（tenon） */
+    size: number;
+    /** 尺寸公差 */
+    sizeTolerance: number;
+    /** 高度 */
+    height: number;
+    /** 高度公差 */
+    heightTolerance: number;
+}
+/**
+ * Dowel（定位销）/ Tenon（直榫）布尔分割 — BREP 等价物。
+ *
+ * 1:1 复刻 csg-worker.ts dowelOrTenonBooleanSplit：
+ * 1. splitBrep → upper + lower
+ * 2. detectCrossSectionComponents → 截面质心列表
+ * 3. 对每个质心：buildShapeSolid → fuse(upper, shape) → upper'
+ * 4. 对每个质心：buildShapeSolid（公差）→ cut(lower, shapeTol) → lower'
+ * @param kernel - the BREP engine API.
+ * @param original - the original solid to split.
+ * @param basis - the joinery coordinate frame.
+ * @param shape - whether to build a dowel or a tenon.
+ * @param params - the dowel/tenon size and tolerance parameters.
+ * @param selectedSections - optional indices of cross-section components to place shapes on.
+ * @returns the split result with front (upper + shape) and back (lower - hole) handles.
+ */
+export declare function dowelOrTenonBooleanSplitBrep(kernel: BrepEngineApi, original: BrepHandle, basis: JoineryBasis, shape: 'dowel' | 'tenon', params: DowelOrTenonParams, selectedSections?: number[] | null): DowelOrTenonSplitBrepResult;
+//# sourceMappingURL=joinery-brep.d.ts.map

package/dist/api/brep-mirror/joinery-brep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joinery-brep.d.ts","sourceRoot":"","sources":["../../../src/api/brep-mirror/joinery-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAM5C,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,MAAM,EAAE,IAAI,CAAA;IACZ,oBAAoB;IACpB,QAAQ,EAAE,IAAI,CAAA;IACd,gDAAgD;IAChD,QAAQ,EAAE,IAAI,CAAA;IACd,aAAa;IACb,WAAW,EAAE,IAAI,CAAA;IACjB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;CACrB;AAsND;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,UAAU,CAwCZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,IAAI,EACd,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAsBZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,IAAI,EACd,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,UAAU,CAgBZ;AAID,aAAa;AACb,MAAM,WAAW,qBAAqB;IACpC,WAAW;IACX,QAAQ,EAAE,IAAI,CAAA;IACd,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,YAAY,GAClB,qBAAqB,EAAE,CAgBzB;AAID,uBAAuB;AACvB,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,KAAK,EAAE,UAAU,CAAA;IACjB,4BAA4B;IAC5B,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,0BAA0B;AAC1B,MAAM,WAAW,2BAA2B;IAC1C,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAA;IACjB,6BAA6B;IAC7B,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,gBAAgB;AAChB,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,uBAAuB,CAoDzB;AAED,qBAAqB;AACrB,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS;IACT,MAAM,EAAE,MAAM,CAAA;IACd,WAAW;IACX,eAAe,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,OAAO,GAAG,OAAO,EACxB,MAAM,EAAE,kBAAkB,EAC1B,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GACjC,2BAA2B,CAsE7B"}

package/dist/api/brep-mirror/joinery-brep.js

@@ -0,0 +1,461 @@
+/**
+ * BREP 榫卯结构操作 — 用 OCCT 精确实体复刻 mesh 路径的榫卯布尔序列
+ *
+ * See docs/api-contract.md §8 (dual-path geometry contract) and §10.5 (split).
+ *
+ * 与 mesh 路径（joinery-shapes.ts + csg-worker.ts）对照：
+ * - mesh 路径：buildWedgeGeometry/buildDowelGeometry/buildStraightTenonGeometry → Manifold CSG
+ * - BREP 路径：buildWedgeSolid/buildDowelSolid/buildTenonSolid → OCCT fuse/cut/common
+ *
+ * 坐标框架与 mesh 路径完全一致：
+ * - normal: 切割平面法线（单位向量，指向上方）
+ * - widthDir: 挤出方向（单位向量）
+ * - depthDir = normalize(cross(normal, widthDir))
+ * - planeCenter: 切割平面中心
+ *
+ * 所有函数都是纯函数，输入输出均为 OCCT BrepHandle，调用方负责句柄生命周期。
+ */
+import * as THREE from 'three';
+import { getSolidBoundingBox } from '../../brep/brep-utils.js';
+import { splitBrep, matrixToArray } from '../../brep/brep-ops.js';
+// ─── Union-Find（与 csg-worker.ts SimpleUnionFind 一致） ───
+class SimpleUnionFind {
+    parent;
+    rank;
+    constructor(n) {
+        this.parent = Array.from({ length: n }, (_, i) => i);
+        this.rank = new Array(n).fill(0);
+    }
+    find(x) {
+        if (this.parent[x] !== x) {
+            this.parent[x] = this.find(this.parent[x]);
+        }
+        return this.parent[x];
+    }
+    union(x, y) {
+        const px = this.find(x);
+        const py = this.find(y);
+        if (px === py)
+            return;
+        if (this.rank[px] < this.rank[py]) {
+            this.parent[px] = py;
+        }
+        else if (this.rank[px] > this.rank[py]) {
+            this.parent[py] = px;
+        }
+        else {
+            this.parent[py] = px;
+            this.rank[px]++;
+        }
+    }
+}
+/**
+ * 检测切割平面上的帽面连通分量。
+ *
+ * 与 csg-worker.ts detectCapComponents 算法一致：
+ * 1. 找到所有顶点在切割平面上的三角形
+ * 2. 用 union-find 按共享顶点分组
+ * 3. 返回每分量的顶点索引集合
+ */
+function detectCapComponentsFromMesh(mesh, normal, originOffset) {
+    const eps = 0.001;
+    const { positions, indices } = mesh;
+    const vertCount = positions.length / 3;
+    if (indices.length === 0)
+        return [];
+    // 找到所有帽面三角形
+    const capVertSet = new Set();
+    const capTris = [];
+    const triCount = indices.length / 3;
+    for (let t = 0; t < triCount; t++) {
+        const i0 = indices[t * 3];
+        const i1 = indices[t * 3 + 1];
+        const i2 = indices[t * 3 + 2];
+        const d0 = Math.abs(positions[i0 * 3] * normal[0] +
+            positions[i0 * 3 + 1] * normal[1] +
+            positions[i0 * 3 + 2] * normal[2] - originOffset);
+        const d1 = Math.abs(positions[i1 * 3] * normal[0] +
+            positions[i1 * 3 + 1] * normal[1] +
+            positions[i1 * 3 + 2] * normal[2] - originOffset);
+        const d2 = Math.abs(positions[i2 * 3] * normal[0] +
+            positions[i2 * 3 + 1] * normal[1] +
+            positions[i2 * 3 + 2] * normal[2] - originOffset);
+        if (d0 < eps && d1 < eps && d2 < eps) {
+            capTris.push({ v0: i0, v1: i1, v2: i2 });
+            capVertSet.add(i0);
+            capVertSet.add(i1);
+            capVertSet.add(i2);
+        }
+    }
+    if (capTris.length === 0)
+        return [];
+    // Union-find 按共享顶点分组
+    const uf = new SimpleUnionFind(vertCount);
+    for (const tri of capTris) {
+        uf.union(tri.v0, tri.v1);
+        uf.union(tri.v1, tri.v2);
+        uf.union(tri.v0, tri.v2);
+    }
+    // 按根节点分组
+    const compMap = new Map();
+    for (const vi of capVertSet) {
+        const root = uf.find(vi);
+        if (!compMap.has(root))
+            compMap.set(root, new Set());
+        compMap.get(root).add(vi);
+    }
+    return Array.from(compMap.values());
+}
+/**
+ * 计算切割平面上截面顶点的质心。
+ *
+ * 与 csg-worker.ts computeCrossSectionCentroid 算法一致。
+ */
+function computeCrossSectionCentroidFromMesh(mesh, normal, originOffset, fallback, comp) {
+    const eps = 0.001;
+    const { positions } = mesh;
+    let cx = 0, cy = 0, cz = 0;
+    let count = 0;
+    const vertCount = positions.length / 3;
+    for (let i = 0; i < vertCount; i++) {
+        if (comp && !comp.has(i))
+            continue;
+        const x = positions[i * 3];
+        const y = positions[i * 3 + 1];
+        const z = positions[i * 3 + 2];
+        const dist = x * normal[0] + y * normal[1] + z * normal[2] - originOffset;
+        if (Math.abs(dist) < eps) {
+            cx += x;
+            cy += y;
+            cz += z;
+            count++;
+        }
+    }
+    if (count === 0)
+        return fallback;
+    return [cx / count, cy / count, cz / count];
+}
+/**
+ * 计算切割平面上截面沿指定方向的宽度。
+ *
+ * 与 csg-worker.ts computeCrossSectionWidth 算法一致。
+ */
+function computeCrossSectionWidthFromMesh(mesh, normal, originOffset, widthDir, comp) {
+    const eps = 0.001;
+    const { positions } = mesh;
+    let minProj = Infinity;
+    let maxProj = -Infinity;
+    let found = false;
+    const vertCount = positions.length / 3;
+    for (let i = 0; i < vertCount; i++) {
+        if (comp && !comp.has(i))
+            continue;
+        const x = positions[i * 3];
+        const y = positions[i * 3 + 1];
+        const z = positions[i * 3 + 2];
+        const dist = x * normal[0] + y * normal[1] + z * normal[2] - originOffset;
+        if (Math.abs(dist) < eps) {
+            const proj = x * widthDir[0] + y * widthDir[1] + z * widthDir[2];
+            if (proj < minProj)
+                minProj = proj;
+            if (proj > maxProj)
+                maxProj = proj;
+            found = true;
+        }
+    }
+    if (!found)
+        return 0;
+    return maxProj - minProj;
+}
+/** 将 OCCT solid 三角化为 MeshData（用于截面分析） */
+function solidToMeshData(kernel, solid) {
+    const mesh = kernel.meshShape(solid, {
+        linearDeflection: 0.1,
+        angularDeflection: (2 * Math.PI) / 32,
+    });
+    return {
+        positions: new Float32Array(mesh.positions),
+        indices: new Uint32Array(mesh.indices),
+    };
+}
+// ─── 基本体构造（BREP 等价物） ───
+/**
+ * 构造局部的变换矩阵：local X → widthDir, Y → depthDir, Z → normal，再平移到 origin。
+ */
+function makeBasisTransform(basis, origin) {
+    const basisMatrix = new THREE.Matrix4().makeBasis(new THREE.Vector3(...basis.widthDir), new THREE.Vector3(...basis.depthDir), new THREE.Vector3(...basis.normal));
+    const transMatrix = new THREE.Matrix4().makeTranslation(origin[0], origin[1], origin[2]);
+    return new THREE.Matrix4().multiplyMatrices(transMatrix, basisMatrix);
+}
+/**
+ * 梯形棱柱（燕尾楔）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildWedgeGeometry 的 8 顶点拓扑：
+ * - 梯形截面在 normal-depthDir 平面
+ * - 底边（宽）在 planeCenter - normal*depth
+ * - 顶边（窄）在 planeCenter
+ * - 沿 widthDir 拉伸 extrudeLength，居中于 planeCenter
+ *
+ * 用 kernel.makeLineEdge + makeWire + makeFace + extrude 构造实体，
+ * 然后用 transform 对齐到世界坐标系。
+ * @param kernel - the BREP engine API.
+ * @param basis - the joinery coordinate frame (normal/widthDir/depthDir/planeCenter).
+ * @param depth - the wedge depth along the normal direction.
+ * @param width - the wedge bottom width.
+ * @param angleDeg - the dovetail flap angle in degrees.
+ * @param extrudeLength - the extrusion length along the width direction.
+ * @returns the constructed wedge solid handle.
+ */
+export function buildWedgeSolid(kernel, basis, depth, width, angleDeg, extrudeLength) {
+    const { planeCenter } = basis;
+    const angleRad = (angleDeg * Math.PI) / 180;
+    const halfWidth = width / 2;
+    const halfTopWidth = Math.max(0, halfWidth - depth / Math.tan(angleRad));
+    const halfExtrude = extrudeLength / 2;
+    // 在局部坐标系中构造梯形面（YZ 平面，X = -halfExtrude）
+    // 局部: X → widthDir, Y → depthDir, Z → normal
+    const xLocal = -halfExtrude;
+    const v0 = { x: xLocal, y: -halfWidth, z: -depth }; // bottomLeft
+    const v1 = { x: xLocal, y: halfWidth, z: -depth }; // bottomRight
+    const v2 = { x: xLocal, y: halfTopWidth, z: 0 }; // topRight
+    const v3 = { x: xLocal, y: -halfTopWidth, z: 0 }; // topLeft
+    // 构建梯形 wire
+    const edges = [];
+    edges.push(kernel.makeLineEdge(v0, v1));
+    edges.push(kernel.makeLineEdge(v1, v2));
+    edges.push(kernel.makeLineEdge(v2, v3));
+    edges.push(kernel.makeLineEdge(v3, v0));
+    const wire = kernel.makeWire(edges);
+    const face = kernel.makeFace(wire);
+    // 沿 X 轴（= widthDir）拉伸 extrudeLength
+    const extruded = kernel.extrude(face, extrudeLength, 0, 0);
+    // 释放中间句柄
+    for (const e of edges)
+        kernel.release(e);
+    kernel.release(wire);
+    kernel.release(face);
+    // 变换到世界坐标系
+    const fullMatrix = makeBasisTransform(basis, planeCenter);
+    const result = kernel.transform(extruded, matrixToArray(fullMatrix));
+    kernel.release(extruded);
+    return result;
+}
+/**
+ * 圆柱（定位销）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildDowelGeometry：
+ * - 圆截面在 widthDir-depthDir 平面，中心在 centroid
+ * - 从切割平面向下延伸 height（沿 -normal）
+ *
+ * 用 kernel.makeCylinder + transform 对齐方向。
+ * @param kernel - the BREP engine API.
+ * @param centroid - the centroid where the dowel is placed.
+ * @param basis - the joinery coordinate frame.
+ * @param diameter - the dowel diameter.
+ * @param height - the dowel height along the normal direction.
+ * @returns the constructed dowel solid handle.
+ */
+export function buildDowelSolid(kernel, centroid, basis, diameter, height) {
+    const radius = diameter / 2;
+    const { normal } = basis;
+    // OCCT makeCylinder 创建 Z 轴方向圆柱（Z=0 → Z=height）
+    // 需要旋转使 Z 轴对齐 -normal（圆柱向下延伸），且顶部在 centroid
+    const cyl = kernel.makeCylinder(radius, height);
+    // 旋转 Z → -normal
+    const zAxis = new THREE.Vector3(0, 0, 1);
+    const negNormal = new THREE.Vector3(-normal[0], -normal[1], -normal[2]).normalize();
+    const quat = new THREE.Quaternion().setFromUnitVectors(zAxis, negNormal);
+    const rotMatrix = new THREE.Matrix4().makeRotationFromQuaternion(quat);
+    // 平移到 centroid（旋转后 Z=0 对应 centroid，即切割平面上的顶面）
+    const transMatrix = new THREE.Matrix4().makeTranslation(centroid[0], centroid[1], centroid[2]);
+    const fullMatrix = new THREE.Matrix4().multiplyMatrices(transMatrix, rotMatrix);
+    const result = kernel.transform(cyl, matrixToArray(fullMatrix));
+    kernel.release(cyl);
+    return result;
+}
+/**
+ * 长方体（直榫）— BREP 等价物。
+ *
+ * 复刻 joinery-shapes.ts buildStraightTenonGeometry：
+ * - 方截面在 widthDir-depthDir 平面，中心在 centroid
+ * - 从切割平面向下延伸 height（沿 -normal）
+ *
+ * 用 kernel.makeBoxFromCorners + transform 对齐方向。
+ * @param kernel - the BREP engine API.
+ * @param centroid - the centroid where the tenon is placed.
+ * @param basis - the joinery coordinate frame.
+ * @param sideLength - the tenon square side length.
+ * @param height - the tenon height along the normal direction.
+ * @returns the constructed tenon solid handle.
+ */
+export function buildTenonSolid(kernel, centroid, basis, sideLength, height) {
+    const half = sideLength / 2;
+    // 在局部坐标系中创建盒子：X ∈ [-half, half], Y ∈ [-half, half], Z ∈ [-height, 0]
+    // 局部: X → widthDir, Y → depthDir, Z → normal
+    const localBox = kernel.makeBoxFromCorners({ x: -half, y: -half, z: -height }, { x: half, y: half, z: 0 });
+    // 变换到世界坐标系
+    const fullMatrix = makeBasisTransform(basis, centroid);
+    const result = kernel.transform(localBox, matrixToArray(fullMatrix));
+    kernel.release(localBox);
+    return result;
+}
+/**
+ * 检测上部实体在切割平面上的截面连通分量。
+ *
+ * BREP 等价物：将 upper solid 三角化后，用与 mesh 路径 detectCapComponents
+ * 完全相同的算法（找帽面三角形 → union-find）检测连通分量。
+ *
+ * 与 csg-worker.ts detectCapComponents + computeCrossSectionCentroid 一致。
+ * @param kernel - the BREP engine API.
+ * @param upper - the upper solid whose cross section is analyzed.
+ * @param basis - the joinery coordinate frame.
+ * @returns the detected cross-section components (centroid + area).
+ */
+export function detectCrossSectionComponents(kernel, upper, basis) {
+    const { normal, originOffset, widthDir, depthDir, planeCenter } = basis;
+    const mesh = solidToMeshData(kernel, upper);
+    const components = detectCapComponentsFromMesh(mesh, normal, originOffset);
+    if (components.length === 0) {
+        // 无帽面 → 返回单个全局质心（planeCenter）作为回退
+        return [{ centroid: planeCenter, area: 0 }];
+    }
+    return components.map(comp => {
+        const centroid = computeCrossSectionCentroidFromMesh(mesh, normal, originOffset, planeCenter, comp);
+        const compWidth = computeCrossSectionWidthFromMesh(mesh, normal, originOffset, widthDir, comp);
+        const compDepth = computeCrossSectionWidthFromMesh(mesh, normal, originOffset, depthDir, comp);
+        return { centroid, area: compWidth * compDepth };
+    });
+}
+/**
+ * Dovetail（燕尾）布尔分割 — BREP 等价物。
+ *
+ * 1:1 复刻 csg-worker.ts dovetailBooleanSplit：
+ * 1. splitBrep → upper + lower
+ * 2. 计算 crossSectionWidth（bbox 投影近似）
+ * 3. buildWedgeSolid（overhang=20）→ common(wedge, lower) 裁剪贴合
+ * 4. fuse(upper, wedgeTrimmed) → upper'
+ * 5. buildWedgeSolid（公差）→ cut(lower, wedgeTol) → lower'
+ * @param kernel - the BREP engine API.
+ * @param original - the original solid to split.
+ * @param basis - the joinery coordinate frame.
+ * @param groove - the dovetail groove parameters.
+ * @returns the split result with front (upper + wedge) and back (lower - cavity) handles.
+ */
+export function dovetailBooleanSplitBrep(kernel, original, basis, groove) {
+    const { normal, widthDir, planeCenter, originOffset } = basis;
+    // Step 1: 平面分割 → upper + lower
+    const splitResult = splitBrep(kernel, original, { normal, originOffset, planeCenter });
+    let upper = splitResult.front;
+    let lower = splitResult.back;
+    // Step 2: 计算截面宽度（bbox 投影近似，后续 common 会裁回真实边界）
+    const upperBbox = getSolidBoundingBox(kernel, upper);
+    const upperSize = [
+        upperBbox.max[0] - upperBbox.min[0],
+        upperBbox.max[1] - upperBbox.min[1],
+        upperBbox.max[2] - upperBbox.min[2],
+    ];
+    let crossSectionWidth = Math.abs(upperSize[0] * widthDir[0]) +
+        Math.abs(upperSize[1] * widthDir[1]) +
+        Math.abs(upperSize[2] * widthDir[2]);
+    if (crossSectionWidth <= 0)
+        crossSectionWidth = 10; // 安全回退
+    const extrudeLength = crossSectionWidth + 0.2;
+    const overhang = 20;
+    // Step 3: 构造楔（带 overhang）
+    const wedgeW = buildWedgeSolid(kernel, basis, groove.depth, groove.width, groove.flapsAngle, extrudeLength + overhang);
+    // Step 4: common(wedge, lower) → 裁剪楔贴合模型边界
+    const wedgeTrimmed = kernel.common(wedgeW, lower);
+    kernel.release(wedgeW);
+    // Step 5: fuse(upper, wedgeTrimmed) → upper'
+    const newUpper = kernel.fuse(upper, wedgeTrimmed);
+    kernel.release(upper);
+    kernel.release(wedgeTrimmed);
+    upper = newUpper;
+    // Step 6: 构造公差楔
+    const wedgeTol = buildWedgeSolid(kernel, basis, groove.depth + groove.depthTolerance, groove.width + groove.widthTolerance, groove.flapsAngle, extrudeLength + overhang);
+    // Step 7: cut(lower, wedgeTol) → lower'
+    const newLower = kernel.cut(lower, wedgeTol);
+    kernel.release(lower);
+    kernel.release(wedgeTol);
+    lower = newLower;
+    return { front: upper, back: lower };
+}
+/**
+ * Dowel（定位销）/ Tenon（直榫）布尔分割 — BREP 等价物。
+ *
+ * 1:1 复刻 csg-worker.ts dowelOrTenonBooleanSplit：
+ * 1. splitBrep → upper + lower
+ * 2. detectCrossSectionComponents → 截面质心列表
+ * 3. 对每个质心：buildShapeSolid → fuse(upper, shape) → upper'
+ * 4. 对每个质心：buildShapeSolid（公差）→ cut(lower, shapeTol) → lower'
+ * @param kernel - the BREP engine API.
+ * @param original - the original solid to split.
+ * @param basis - the joinery coordinate frame.
+ * @param shape - whether to build a dowel or a tenon.
+ * @param params - the dowel/tenon size and tolerance parameters.
+ * @param selectedSections - optional indices of cross-section components to place shapes on.
+ * @returns the split result with front (upper + shape) and back (lower - hole) handles.
+ */
+export function dowelOrTenonBooleanSplitBrep(kernel, original, basis, shape, params, selectedSections) {
+    const { normal, planeCenter, originOffset } = basis;
+    // Step 1: 平面分割 → upper + lower
+    const splitResult = splitBrep(kernel, original, { normal, originOffset, planeCenter });
+    let upper = splitResult.front;
+    let lower = splitResult.back;
+    // Step 2: 检测截面分量
+    const components = detectCrossSectionComponents(kernel, upper, basis);
+    let placements;
+    if (components.length <= 1 || !selectedSections || selectedSections.length === 0) {
+        // 单截面或无选择 → 全局质心（向后兼容）
+        const mesh = solidToMeshData(kernel, upper);
+        const centroid = computeCrossSectionCentroidFromMesh(mesh, normal, originOffset, planeCenter);
+        placements = [{ centroid }];
+    }
+    else {
+        // 多截面：按面积降序排，取选择的分量
+        const sorted = [...components].sort((a, b) => b.area - a.area);
+        placements = [];
+        for (const selId of selectedSections) {
+            if (selId < sorted.length) {
+                placements.push({ centroid: sorted[selId].centroid });
+            }
+        }
+        if (placements.length === 0) {
+            const mesh = solidToMeshData(kernel, upper);
+            const centroid = computeCrossSectionCentroidFromMesh(mesh, normal, originOffset, planeCenter);
+            placements = [{ centroid }];
+        }
+    }
+    // Step 3: 对每个质心构造基本体并 fuse 到 upper
+    for (const { centroid } of placements) {
+        let shapeC;
+        if (shape === 'dowel') {
+            shapeC = buildDowelSolid(kernel, centroid, basis, params.size, params.height);
+        }
+        else {
+            shapeC = buildTenonSolid(kernel, centroid, basis, params.size, params.height);
+        }
+        const newUpper = kernel.fuse(upper, shapeC);
+        kernel.release(upper);
+        kernel.release(shapeC);
+        upper = newUpper;
+    }
+    // Step 4: 对每个质心构造公差体并 cut 从 lower
+    const tolSize = params.size + params.sizeTolerance;
+    const tolHeight = params.height + params.heightTolerance;
+    for (const { centroid } of placements) {
+        let shapeCTol;
+        if (shape === 'dowel') {
+            shapeCTol = buildDowelSolid(kernel, centroid, basis, tolSize, tolHeight);
+        }
+        else {
+            shapeCTol = buildTenonSolid(kernel, centroid, basis, tolSize, tolHeight);
+        }
+        const newLower = kernel.cut(lower, shapeCTol);
+        kernel.release(lower);
+        kernel.release(shapeCTol);
+        lower = newLower;
+    }
+    return { front: upper, back: lower };
+}
+//# sourceMappingURL=joinery-brep.js.map