@faicad/faijs 0.29.3 → 0.30.9

package/dist/brep/brep-ops.d.ts

@@ -22,6 +22,7 @@ import * as THREE from 'three';
 import type { BrepHandle } from './engine/types.js';
 import type { BrepEngineApi } from './engine/primitives.js';
 import type { Shape, Vec3 } from '../mesh/types.js';
+import type { ImportAssemblyNode } from '../mesh/import-model.js';
 import type { BrepChainState } from './brep-chain.js';
 import type { PartName } from '../identity.js';
 /**
@@ -62,13 +63,62 @@ export declare function translateBrep(kernel: BrepEngineApi, solid: BrepHandle,
  * @returns 新实体
  */
 export declare function rotateBrep(kernel: BrepEngineApi, solid: BrepHandle, angles: Vec3, pivot?: Vec3): BrepHandle;
+/**
+ * 判定 3×4 行主序仿射矩阵的线性部分是否为**相似变换**（旋转/反射 × 等比缩放）——
+ * 即 `gp_Trsf` 能精确承载、`kernel.transform`（BRepBuilderAPI_Transform）唯一
+ * 正确处理的那一类。
+ *
+ * 判据必须用**相对**容差，不能像 2026-10-07 之前那样用绝对容差：
+ * GOTCHA（2026-10-07，openscad example023 parity）——一个 60° 刚体旋转只要按
+ * 7 位小数打印（`0.8660254`），行范数就是 `0.99999999645`（与 1 相差 3.6e-9）。
+ * 绝对容差 1e-9 会判定 `|‖row2‖ − ‖row0‖| = 3.6e-9 > 1e-9` ⇒ 把这个**纯旋转**
+ * 判成"非相似"，从而错误地走进 `generalTransform`；而 occt 侧 `gp_GTrsf` 路径在
+ * **已三角化**的形状上会重复计入被平移面的 TopLoc（顶盖 z 由 5 变 10，绕过在
+ * `occt-kernel/occt-primitives.ts` 的 `generalTransform` 适配层，本层不感知）。
+ * 相对容差 1e-6 覆盖 7 位小数打印精度，同时仍能区分真正的非等比缩放
+ * （如 z×2.5 行范数相差 2.5 倍）。正交性同用 1e-6：7 位小数打印的旋转，行点积
+ * 误差上界约 2e-7。
+ *
+ * @param m12 - 3×4 行主序矩阵（12 元素：`[r00,r01,r02,tx, r10,r11,r12,ty, r20,r21,r22,tz]`）。
+ * @returns `true` 当且仅当线性部分可逆且为相似变换。
+ */
+export declare function isSimilarityAffine(m12: readonly number[]): boolean;
+/**
+ * 施加 3×4 行主序仿射矩阵，按矩阵类别选**唯一正确**的 OCCT 路径。
+ *
+ * 两条路径的差异是**正确性**而不只是性能：
+ * - 相似（旋转/反射 × 等比缩放）→ `kernel.transform`（BRepBuilderAPI_Transform）。
+ * - 其余（非等比缩放、错切）→ `kernel.generalTransform`（gp_GTrsf）。
+ *
+ * GOTCHA（2026-10-07）：occt 的 `generalTransform` 在**已经三角化过**的形状上会
+ * 重复计入被平移面的 TopLoc（精确 z∈[0,5]，网格顶盖却落在 z=10；非等比 z×2.5 时
+ * 12.5 vs 17.5）。该缺陷是 **occt 专属**（brepkit 的 GTrsf 路径干净），因此绕过
+ * **不在本层**——本层是引擎中立分派，让每个引擎都为 occt 的毛病多付一次句柄分配
+ * 是错的（还会扰动 brepkit 的 `cut` bbox，见 multi-engine-op-parity）。
+ * 绕过落在 occt 适配层：`occt-kernel/occt-primitives.ts` 的 `generalTransform`
+ * 先 `copy` 再变换。`kernel.transform` 无此问题，故相似矩阵不付这份深拷贝成本。
+ *
+ * 反向陷阱：把非相似矩阵交给 `kernel.transform` 是**静默错误**——OCCT 会按
+ * `det^(1/3)` 取等比因子近似（实测 z×2.5 被当成 1.357 倍等比缩放）。所以分类
+ * 判据既不能过严（把刚体旋转推给 GTrsf），也不能过宽（把非等比缩放塞给 Trsf）。
+ *
+ * @param kernel - L1 引擎句柄。
+ * @param solid - 输入实体（不被消费、不被释放；调用方保留其所有权）。
+ * @param m12 - 3×4 行主序矩阵（12 元素）。
+ * @returns 变换后的新实体（调用方负责释放）。
+ */
+export declare function applyAffineBrep(kernel: BrepEngineApi, solid: BrepHandle, m12: readonly number[]): BrepHandle;
 /**
  * BREP 缩放：使用 OCCT transform（3x4 仿射矩阵）。
  *
  * 与 mesh 路径 scale（P6 §4.6）一致：
  * - factor 为 number（均匀缩放）或 Vec3 [sx, sy, sz]（非均匀）
  * - center 为缩放不动点（p' = center + S·(p − center)）；缺省 [0,0,0]（原点），
- *   与 vendored brepjs `scale(shape, factor, { center? })` 的默认一致。
+ *   与早期 brepjs `scale(shape, factor, { center? })` 的默认一致。
+ *
+ * 路径分派交给 {@link applyAffineBrep}：等比走 `transform`，非等比走
+ * `generalTransform`（gp_Trsf 表达不了非等比）。注意判据是**数值**相似性而非
+ * 因子逐分量相等——`[1, 1, 1+1e-9]` 这种数值上就是等比，归 `transform` 一侧。
  *
  * @param kernel  OCCT 内核
  * @param solid   输入实体
@@ -294,6 +344,44 @@ export declare function loadBrep(kernel: BrepEngineApi, buffer: ArrayBuffer, bre
     shape: Shape;
     multiSolidCount?: number;
 };
+/** 多零件 STEP 导入中的一个零件（几何 + solid 句柄 + 身份）。 */
+export interface LoadBrepAssemblyPart {
+    /** 零件序号（0 起，DFS 声明序）。 */
+    index: number;
+    /** 零件名（XCAF label；无则回退 `imported:<index>`）。 */
+    name: string;
+    /** 显示色 sRGB 0..1，无则 null。 */
+    color: [number, number, number] | null;
+    /** 三角化显示 mesh。 */
+    shape: Shape;
+    /** OCCT solid 句柄（已烘 location；生命周期归 brepChain，调用方经 fromBrep 绑定）。 */
+    solid: BrepHandle;
+}
+/**
+ * BREP-native 多零件 STEP 导入（XCAF 装配树 → 逐零件 Shape + 装配层级）。
+ *
+ * 与 `loadBrep`（单零件收敛，§5.4 旧行为）对照：loadBrepAssembly 走
+ * `importAssemblyFromStep`（XCAF），返回**全部**叶零件（DFS 声明序）与装配树。
+ *
+ * - 装配树叶子 = 零件；合成节点（syntheticGroup：单一产品含多 MANIFOLD_SOLID_BREP）
+ *   如实表达为中间节点；
+ * - 无装配结构的单叶文件 → 1 个零件、无 assembly（行为与现状单零件一致）；
+ * - 句柄互通（T0）：`importAssemblyFromStep` 内部用 initOcctWasm() 全局单例内核，
+ *   与注入的 `BrepEngineApi`（createOcctPrimitives 包装同一单例）句柄数值互通——
+ *   探针见 test/brep/load-brep-assembly.test.ts；
+ * - 释放：装配节点句柄已由 walkLabel 释放，叶句柄随返回 parts 交给调用方
+ *   （fromBrep 绑定后归 brepChain 管理，不在此释放）。
+ *
+ * @param kernel - the initialized OCCT kernel (L1 contract face).
+ * @param buffer - the raw STEP file bytes (text-encoded ArrayBuffer; stpz
+ *   unzipping is the caller's job — faijs never unzips implicitly).
+ * @returns 全部零件 + 装配层级（多叶时）+ 叶数（>1 时）。
+ */
+export declare function loadBrepAssembly(kernel: BrepEngineApi, buffer: ArrayBuffer): Promise<{
+    parts: LoadBrepAssemblyPart[];
+    assembly?: ImportAssemblyNode;
+    multiSolidCount?: number;
+}>;
 /**
  * Convert a THREE.Matrix4 into the 3x4 row-major array (12 doubles) the OCCT
  * transform expects.

package/dist/brep/brep-ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brep-ops.d.ts","sourceRoot":"","sources":["../../src/brep/brep-ops.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"brep-ops.d.ts","sourceRoot":"","sources":["../../src/brep/brep-ops.ts"],"names":[],"mappings":"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"}

package/dist/brep/brep-ops.js

@@ -19,7 +19,8 @@
  * 坐标系：Z-up、毫米，与 mesh 路径一致。
  */
 import * as THREE from 'three';
-import { getOcctKernel } from '../occt-kernel/occtKernel.js';
+import { getOcctKernel, importAssemblyFromStep, collectLeafParts, } from '../occt-kernel/occtKernel.js';
+import { getSolidColorsOrdered } from '../occt-kernel/stepColorParser.js';
 import { getSolidBoundingBox } from './brep-utils.js';
 import { DEFAULT_LINEAR_DEFLECTION } from '../tolerance.js';
 import { mm } from '../units.js';
@@ -89,13 +90,79 @@ export function rotateBrep(kernel, solid, angles, pivot) {
     }
     return kernel.transform(solid, matrixToArray(matrix));
 }
+/**
+ * 判定 3×4 行主序仿射矩阵的线性部分是否为**相似变换**（旋转/反射 × 等比缩放）——
+ * 即 `gp_Trsf` 能精确承载、`kernel.transform`（BRepBuilderAPI_Transform）唯一
+ * 正确处理的那一类。
+ *
+ * 判据必须用**相对**容差，不能像 2026-10-07 之前那样用绝对容差：
+ * GOTCHA（2026-10-07，openscad example023 parity）——一个 60° 刚体旋转只要按
+ * 7 位小数打印（`0.8660254`），行范数就是 `0.99999999645`（与 1 相差 3.6e-9）。
+ * 绝对容差 1e-9 会判定 `|‖row2‖ − ‖row0‖| = 3.6e-9 > 1e-9` ⇒ 把这个**纯旋转**
+ * 判成"非相似"，从而错误地走进 `generalTransform`；而 occt 侧 `gp_GTrsf` 路径在
+ * **已三角化**的形状上会重复计入被平移面的 TopLoc（顶盖 z 由 5 变 10，绕过在
+ * `occt-kernel/occt-primitives.ts` 的 `generalTransform` 适配层，本层不感知）。
+ * 相对容差 1e-6 覆盖 7 位小数打印精度，同时仍能区分真正的非等比缩放
+ * （如 z×2.5 行范数相差 2.5 倍）。正交性同用 1e-6：7 位小数打印的旋转，行点积
+ * 误差上界约 2e-7。
+ *
+ * @param m12 - 3×4 行主序矩阵（12 元素：`[r00,r01,r02,tx, r10,r11,r12,ty, r20,r21,r22,tz]`）。
+ * @returns `true` 当且仅当线性部分可逆且为相似变换。
+ */
+export function isSimilarityAffine(m12) {
+    const s0 = Math.hypot(m12[0], m12[1], m12[2]);
+    const s1 = Math.hypot(m12[4], m12[5], m12[6]);
+    const s2 = Math.hypot(m12[8], m12[9], m12[10]);
+    if (!(s0 > 1e-12) || !(s1 > 1e-12) || !(s2 > 1e-12))
+        return false;
+    const REL = 1e-6;
+    if (Math.abs(s1 - s0) > REL * s0 || Math.abs(s2 - s0) > REL * s0)
+        return false;
+    const dot = (r, c) => m12[r * 4] * m12[c * 4] + m12[r * 4 + 1] * m12[c * 4 + 1] + m12[r * 4 + 2] * m12[c * 4 + 2];
+    return (Math.abs(dot(0, 1)) <= REL * s0 * s1 &&
+        Math.abs(dot(0, 2)) <= REL * s0 * s2 &&
+        Math.abs(dot(1, 2)) <= REL * s1 * s2);
+}
+/**
+ * 施加 3×4 行主序仿射矩阵，按矩阵类别选**唯一正确**的 OCCT 路径。
+ *
+ * 两条路径的差异是**正确性**而不只是性能：
+ * - 相似（旋转/反射 × 等比缩放）→ `kernel.transform`（BRepBuilderAPI_Transform）。
+ * - 其余（非等比缩放、错切）→ `kernel.generalTransform`（gp_GTrsf）。
+ *
+ * GOTCHA（2026-10-07）：occt 的 `generalTransform` 在**已经三角化过**的形状上会
+ * 重复计入被平移面的 TopLoc（精确 z∈[0,5]，网格顶盖却落在 z=10；非等比 z×2.5 时
+ * 12.5 vs 17.5）。该缺陷是 **occt 专属**（brepkit 的 GTrsf 路径干净），因此绕过
+ * **不在本层**——本层是引擎中立分派，让每个引擎都为 occt 的毛病多付一次句柄分配
+ * 是错的（还会扰动 brepkit 的 `cut` bbox，见 multi-engine-op-parity）。
+ * 绕过落在 occt 适配层：`occt-kernel/occt-primitives.ts` 的 `generalTransform`
+ * 先 `copy` 再变换。`kernel.transform` 无此问题，故相似矩阵不付这份深拷贝成本。
+ *
+ * 反向陷阱：把非相似矩阵交给 `kernel.transform` 是**静默错误**——OCCT 会按
+ * `det^(1/3)` 取等比因子近似（实测 z×2.5 被当成 1.357 倍等比缩放）。所以分类
+ * 判据既不能过严（把刚体旋转推给 GTrsf），也不能过宽（把非等比缩放塞给 Trsf）。
+ *
+ * @param kernel - L1 引擎句柄。
+ * @param solid - 输入实体（不被消费、不被释放；调用方保留其所有权）。
+ * @param m12 - 3×4 行主序矩阵（12 元素）。
+ * @returns 变换后的新实体（调用方负责释放）。
+ */
+export function applyAffineBrep(kernel, solid, m12) {
+    if (isSimilarityAffine(m12))
+        return kernel.transform(solid, m12);
+    return kernel.generalTransform(solid, m12);
+}
 /**
  * BREP 缩放：使用 OCCT transform（3x4 仿射矩阵）。
  *
  * 与 mesh 路径 scale（P6 §4.6）一致：
  * - factor 为 number（均匀缩放）或 Vec3 [sx, sy, sz]（非均匀）
  * - center 为缩放不动点（p' = center + S·(p − center)）；缺省 [0,0,0]（原点），
- *   与 vendored brepjs `scale(shape, factor, { center? })` 的默认一致。
+ *   与早期 brepjs `scale(shape, factor, { center? })` 的默认一致。
+ *
+ * 路径分派交给 {@link applyAffineBrep}：等比走 `transform`，非等比走
+ * `generalTransform`（gp_Trsf 表达不了非等比）。注意判据是**数值**相似性而非
+ * 因子逐分量相等——`[1, 1, 1+1e-9]` 这种数值上就是等比，归 `transform` 一侧。
  *
  * @param kernel  OCCT 内核
  * @param solid   输入实体
@@ -113,13 +180,7 @@ export function scaleBrep(kernel, solid, factor, center) {
             .multiply(scale)
             .multiply(new THREE.Matrix4().makeTranslation(-center[0], -center[1], -center[2]))
         : scale;
-    const isUniform = f[0] === f[1] && f[1] === f[2];
-    // OCCT gp_Trsf (kernel.transform) only supports uniform scaling.
-    // Non-uniform scaling requires gp_GTrsf (kernel.generalTransform).
-    if (isUniform) {
-        return kernel.transform(solid, matrixToArray(matrix));
-    }
-    return kernel.generalTransform(solid, matrixToArray(matrix));
+    return applyAffineBrep(kernel, solid, matrixToArray(matrix));
 }
 // ─── 装配变换 ───
 /**
@@ -328,9 +389,20 @@ export function splitBrep(kernel, solid, params) {
     const halfSpaceBox = kernel.transform(localBox, matrixToArray(finalMatrix));
     kernel.release(localBox);
     try {
-        const front = kernel.common(solid, halfSpaceBox);
+        // P2（2026-10-06）：规避 occt-wasm 在 Chrome worker 下 common 对"平面退化 BOP"
+        // 挂死（common(solid, 半边盒) 不稳定；cut 稳定——drill 打孔 cut 在 worker 正常）。
+        // 差集对偶：back（负侧）= solid - 正盒；front（正侧）= solid - 负盒。
+        // 数学等价于 common/cut（盒覆盖 solid 全尺寸，边界同为切割平面），node 探针验证
+        // 三角化结果与原实现一致。common 保留在 node/非 worker 环境的回退不可行——
+        // 静态行为应一致，故统一走两 cut。
         const back = kernel.cut(solid, halfSpaceBox);
+        // 负盒：local 系 z ∈ [-halfSize, 0]，同 finalMatrix（平面沿 -normal 方向扩展）
+        const localBoxNeg = kernel.makeBoxFromCorners({ x: -halfSize, y: -halfSize, z: -halfSize }, { x: halfSize, y: halfSize, z: 0 });
+        const negBox = kernel.transform(localBoxNeg, matrixToArray(finalMatrix));
+        kernel.release(localBoxNeg);
+        const front = kernel.cut(solid, negBox);
         kernel.release(halfSpaceBox);
+        kernel.release(negBox);
         return { front, back };
     }
     catch (err) {
@@ -495,6 +567,30 @@ export function extrudeBrep(kernel, solid, params) {
     return result;
 }
 // ─── STEP/BREP 导入操作 ───
+/**
+ * 单零件导入的 STEP 颜色挂载（P2，方案 §5 STEP 行）。
+ *
+ * `getSolidColorsOrdered`（stepColorParser）把 STYLED_ITEM → COLOUR_RGB 引用链
+ * 解析为按 MANIFOLD_SOLID_BREP 文件序的颜色数组；该序与 OCCT
+ * `getSubShapes(compound,'solid')` 一致（stepColorParser 注释），因此取 `[0]`
+ * 即「loadBrep 单零件收敛取第一个 solid」的颜色，语义对齐。
+ *
+ * 宽容兼容外部数据：BREP（CASCADE Topology 文本）无颜色概念直接跳过；STEP
+ * 文本无 `STYLED_ITEM` 早退（零额外开销）；引用链缺失/未知预定义色返回 null，
+ * 一律不挂外观、不抛错（AGENTS.md 全局铁律：不得以内部严格性拒收正常文件）。
+ */
+function applyFirstStepColor(shape, buffer) {
+    const head = new TextDecoder('utf-8').decode(buffer.slice(0, 64));
+    if (head.includes('CASCADE Topology'))
+        return shape;
+    const text = new TextDecoder('utf-8').decode(buffer);
+    if (!text.includes('STYLED_ITEM'))
+        return shape;
+    const c0 = getSolidColorsOrdered(text)[0];
+    if (c0)
+        shape.appearance = { color: [c0[0], c0[1], c0[2]] };
+    return shape;
+}
 /**
  * BREP-native STEP 导入：使用 OCCT kernel.importStep 导入 STEP 文件为精确实体。
  *
@@ -548,7 +644,7 @@ export function loadBrep(kernel, buffer, brepChain, stmtId, opts) {
         // failed"），调用方必须自己保证它只流向变换/聚合。
         if (opts?.allowNonSolid && hasAnyTopology(kernel, top)) {
             const shape = solidToShape(kernel, top, undefined, brepChain, stmtId);
-            return { solid: top, shape };
+            return { solid: top, shape: applyFirstStepColor(shape, buffer) };
         }
         kernel.release(top);
         throw new Error(`[loadBrep] imported shape contains no solid sub-shapes ` +
@@ -560,7 +656,7 @@ export function loadBrep(kernel, buffer, brepChain, stmtId, opts) {
         const realSolid = solids[0];
         kernel.release(top); // 释放 Compound 包裹，realSolid 独立持有
         const shape = solidToShape(kernel, realSolid, undefined, brepChain, stmtId);
-        return { solid: realSolid, shape };
+        return { solid: realSolid, shape: applyFirstStepColor(shape, buffer) };
     }
     // 多 solid（§5.4 单零件收敛）：只支持单零件 —— 降级取**第一个** solid，
     // 返回单一非复合 Shape，并回传 multiSolidCount（≥2 表示本文件被降级取件，
@@ -582,7 +678,7 @@ export function loadBrep(kernel, buffer, brepChain, stmtId, opts) {
     }
     kernel.release(top); // 释放 Compound 包裹，first 独立持有（同单 solid 模式）
     const shape = solidToShape(kernel, first, undefined, brepChain, stmtId);
-    return { solid: first, shape, multiSolidCount: solids.length };
+    return { solid: first, shape: applyFirstStepColor(shape, buffer), multiSolidCount: solids.length };
 }
 /** Sub-shape kinds that make an imported shape "addressable but not a solid". */
 const NON_SOLID_KINDS = ['vertex', 'edge', 'wire', 'face', 'shell'];
@@ -600,6 +696,101 @@ const NON_SOLID_KINDS = ['vertex', 'edge', 'wire', 'face', 'shell'];
 function hasAnyTopology(kernel, top) {
     return NON_SOLID_KINDS.some((kind) => kernel.getSubShapes(top, kind).length > 0);
 }
+/**
+ * BREP-native 多零件 STEP 导入（XCAF 装配树 → 逐零件 Shape + 装配层级）。
+ *
+ * 与 `loadBrep`（单零件收敛，§5.4 旧行为）对照：loadBrepAssembly 走
+ * `importAssemblyFromStep`（XCAF），返回**全部**叶零件（DFS 声明序）与装配树。
+ *
+ * - 装配树叶子 = 零件；合成节点（syntheticGroup：单一产品含多 MANIFOLD_SOLID_BREP）
+ *   如实表达为中间节点；
+ * - 无装配结构的单叶文件 → 1 个零件、无 assembly（行为与现状单零件一致）；
+ * - 句柄互通（T0）：`importAssemblyFromStep` 内部用 initOcctWasm() 全局单例内核，
+ *   与注入的 `BrepEngineApi`（createOcctPrimitives 包装同一单例）句柄数值互通——
+ *   探针见 test/brep/load-brep-assembly.test.ts；
+ * - 释放：装配节点句柄已由 walkLabel 释放，叶句柄随返回 parts 交给调用方
+ *   （fromBrep 绑定后归 brepChain 管理，不在此释放）。
+ *
+ * @param kernel - the initialized OCCT kernel (L1 contract face).
+ * @param buffer - the raw STEP file bytes (text-encoded ArrayBuffer; stpz
+ *   unzipping is the caller's job — faijs never unzips implicitly).
+ * @returns 全部零件 + 装配层级（多叶时）+ 叶数（>1 时）。
+ */
+export async function loadBrepAssembly(kernel, buffer) {
+    const nodes = await importAssemblyFromStep(buffer);
+    const leaves = collectLeafParts(nodes);
+    // DFS 声明序：leaf 序 = parts 序 = ImportModel.parts.index。
+    // 实体校验（与 load op「要求导入物含实体」契约一致）：leaf 必须持有实体
+    // （自身是 solid，或 label 内含 solid）；空 label / wireframe 零件跳过，
+    // 全部跳过则报错（不静默回退）。parts 下标保持连续（0..N-1）。
+    const leafIndex = new Map();
+    const parts = [];
+    for (const leaf of leaves) {
+        if (!leaf.shapeHandle || !leafHasSolid(kernel, leaf.shapeHandle))
+            continue;
+        const idx = parts.length;
+        leafIndex.set(leaf, idx);
+        const h = leaf.shapeHandle;
+        parts.push({
+            index: idx,
+            name: leaf.name || `imported:${idx}`,
+            color: leaf.color,
+            shape: solidToShape(kernel, h),
+            solid: h,
+        });
+    }
+    // 无叶零件（空/异常/纯 wireframe 文件）→ 报错暴露（不静默回退）。
+    if (parts.length === 0) {
+        throw new Error('[loadBrepAssembly] imported STEP contains no solid leaf parts');
+    }
+    const assembly = toImportAssemblyNode(nodes, leafIndex);
+    return {
+        parts,
+        ...(assembly ? { assembly } : {}),
+        ...(parts.length > 1 ? { multiSolidCount: parts.length } : {}),
+    };
+}
+/**
+ * leaf 是否持有实体（loadBrepAssembly 实体校验）：自身是 solid（syntheticGroup
+ * 拆出的单个 solid 句柄），或 label compound 内含 solid。getSubShapes 的引用
+ * 句柄须立即 release（walkLabel 只释放了它自己取的副本）。
+ */
+function leafHasSolid(kernel, h) {
+    const bh = h;
+    if (kernel.isSolid(bh))
+        return true;
+    const solids = kernel.getSubShapes(bh, 'solid');
+    const n = solids.length;
+    for (const s of solids)
+        kernel.release(s);
+    return n > 0;
+}
+/**
+ * XCAF 装配树 → ImportAssemblyNode（DFS 序与 parts 一致）。
+ *
+ * - 单根且根为叶（无装配结构）→ undefined（单零件路径，与现状一致）；
+ * - 单根装配 → 该根；
+ * - 多根 → 合成虚拟根 `{ name: 'imported' }`（确定性结构名，非零件身份）。
+ */
+function toImportAssemblyNode(nodes, leafIndex) {
+    if (nodes.length === 0)
+        return undefined;
+    const convert = (node) => {
+        if (node.children.length === 0) {
+            const idx = leafIndex.get(node);
+            return { name: node.name, ...(idx !== undefined ? { partIndex: idx } : {}) };
+        }
+        return { name: node.name, children: node.children.map(convert) };
+    };
+    if (nodes.length === 1) {
+        const root = convert(nodes[0]);
+        // 单根且根为叶（无装配结构）→ 不表达装配层级
+        if (root.partIndex !== undefined)
+            return undefined;
+        return root;
+    }
+    return { name: 'imported', children: nodes.map(convert) };
+}
 // ─── 辅助函数 ───
 /**
  * Convert a THREE.Matrix4 into the 3x4 row-major array (12 doubles) the OCCT