@faicad/faijs 0.30.9 → 0.32.2

package/dist/brep/engine/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/brep/engine/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAU,CAAA;AAgCxE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAA","sourcesContent":["/**\n * engine/types — BREP 引擎中立类型（零具体实现依赖，不 import 任何内核包）\n *\n *\n * 契约（对应 brepjs 的 KernelShape 约定）：\n * - L1 及以上代码永远不对句柄调用任何方法，只把它传回产生它的那个引擎；\n * - 句柄不得跨引擎传递——跨引擎必须先经 mesh 层（§8.3 的结构保证）。\n * - OCCT 适配器的句柄运行时就是 number，加 brand 是零成本的类型层转换。\n */\n\n/**\n * BREP 引擎身份（D11-1，2026-09-24 narrowing plan）。\n *\n * 三个值来自三个已存在的引擎 id 常量（`OCCT_BREP_ENGINE_ID` / `BREPKIT_BREP_ENGINE_ID`\n * / `BREP_MOCK_ENGINE_ID`，各自适配器导出）；本类型由常量数组推导，禁止裸 `string`。\n * 适配器常量用 `satisfies BrepEngineId` 收窄（typecheck 钉住集合一致）。\n *\n * 消费点：`defineOp` 的 `engines` 声明（平台 op 自证身份）、`dispatchPath` 的平台\n * 身份分支（D11-2）、`script-face-manifest` 的平台 op 标注（§3.8）。\n */\nexport const BREP_ENGINE_IDS = ['occt', 'brepkit', 'brep_mock'] as const\n\n/** BREP 引擎身份（固定三值联合；由 {@link BREP_ENGINE_IDS} 推导）。 */\nexport type BrepEngineId = (typeof BREP_ENGINE_IDS)[number]\n\ndeclare const BrepHandleBrand: unique symbol\n\n/**\n * BREP 实体句柄——不透明值。\n *\n * 与 occt-wasm 的 ShapeHandle 同构（number & brand）。OCCT 适配器\n * （occt-kernel/）内部以 `as unknown as` 双向转换，跨适配器边界零运行时成本。\n */\nexport type BrepHandle = number & { readonly [BrepHandleBrand]: never }\n\n/** 三维点/向量（与内核无关的中立形态）。 */\nexport interface BrepVec3 {\n  x: number\n  y: number\n  z: number\n}\n\n/** 轴对齐包围盒。 */\nexport interface BrepBoundingBox {\n  xmin: number\n  ymin: number\n  zmin: number\n  xmax: number\n  ymax: number\n  zmax: number\n}\n\n/**\n * 面/边 hash 的上界（唯一真源）。\n *\n * 拓扑提取侧用 `kernel.hashCode(subShape, BREP_HASH_BOUND)` 查面/边，\n * 三角化/线框侧把 hash 写进 `faceGroups[·+2]` / `edgeGroups[·+2]`——\n * **两侧必须对同一上界取模**，否则查表恒 miss（实测 2026-10-01：\n * brepkit 适配器曾用 1e9、topologyExt 用 INT32_MAX → 面行 triangleCount 全 0）。\n * 值取自 OCCT `HASH_CODE_MAX` 惯例，也是 occt-wasm 的实际口径（实测一致）。\n */\nexport const BREP_HASH_BOUND = 2147483647\n\n/**\n * BRepMesh 三角化输出（镜像 occt-wasm Mesh 的中立形态）。\n *\n * ⚠️ 单位口径（L1 契约的一部分，实测钉死）：\n * - `faceGroups` 三元组 = `[triStart, triCount, faceHash]`，前两元是**索引单位**\n *   （3/三角形），不是三角形单位；\n * - `wireframe().edgeGroups` = `[pointStart, pointCount, edgeHash]`，前两元是\n *   **浮点单位**（3/点）。\n * 修订任何一侧都要同步改另一侧与 brepkit 适配器（跨引擎一致性测试\n * `topology/face-group-units.test.ts` 钉住）。\n */\nexport interface BrepMeshResult {\n  /** XYZ 交错顶点坐标，长度 = vertexCount * 3 */\n  positions: Float32Array\n  /** XYZ 交错顶点法线，长度 = vertexCount * 3 */\n  normals: Float32Array\n  /** 三角形索引 */\n  indices: Uint32Array\n  /** 顶点数（positions.length / 3） */\n  vertexCount: number\n  /** 三角形数（indices.length / 3） */\n  triangleCount: number\n  /** 面组：[triStart, triCount, faceHash] 三元组（meshShape 时存在） */\n  faceGroups?: Int32Array\n  /** 面组数（meshShape 时存在） */\n  faceCount?: number\n}\n\n/** 三角化精度选项。 */\nexport interface BrepTessellateOptions {\n  /** 最大弦偏差（mm），默认 0.1 */\n  linearDeflection?: number\n  /** 最大角偏差（弧度），默认 0.5 */\n  angularDeflection?: number\n  /** 按每条边长度相对解释 linearDeflection */\n  relative?: boolean\n}\n\n/** 边折线数据（wireframe 输出）。 */\nexport interface BrepEdgeData {\n  /** XYZ 交错边采样点 */\n  points: Float32Array\n  /** 每边分组：[pointStart, pointCount, edgeHash] 三元组；前两元为**浮点单位**（3/点）。 */\n  edgeGroups: Int32Array\n  /** points 中的浮点数总数（= XYZ 坐标数） */\n  pointCount: number\n  /** 不同边的数量 */\n  edgeCount: number\n}\n\n/**\n * *WithHistory 面演化数据（modified/generated/deleted 用面 hash 编码）。\n *\n * ⚠️ **三个字段的编码不同，实测于 2026-09-22（`brep/engine/phase0-kernel-probes.test.ts`），\n * 与 occt-wasm 自己的文档（`dist/types.d.ts:227-231`）不符**：\n *\n * | 字段 | 实际编码 | 键/值语义 |\n * |---|---|---|\n * | `modified` | **分段** `[inHash, count, outHash…] × N` | 键 = 输入面 hash；值 = 该输入面在结果里的**后继**（可 1→N） |\n * | `generated` | **同构分段**，**键集与 `modified` 相同** | 值 = 该输入面派生出的**中间形**（实测结果里 0 存活） |\n * | `deleted` | **扁平** hash 数组 | 输入面中已不存在的面 |\n *\n * 「扁平数组」的读法会把 `generated` 的 count 字段当成 hash——\n * 实测 `cut` 的 `generated` 里真的含 `2`（一个 count），故该误读不会自己暴露。\n *\n * ⚠️ **未受影响的面有两种上报形态，两种都表示\"未变\"**：自映射（`i -> [i]`）。\n * 或者**整个不上报**（`fillet` 实测两者并存）。⇒ 读法必须是\n * `modified.get(h) ?? [h]`，不能只看\"是否出现在 `modified` 里\"。\n *\n * ⇒ 结果面的三种命运（判据见 `phase0-kernel-probes.test.ts`）：\n * **原样幸存**（hash ∈ 输入 hash 集合，hash 逐字不变）/ **改型幸存**（在 `modified` 输出里）/\n * **新造**（两者皆非——这才是真正需要派生词汇命名的面，如 `fillet` 的过渡面）。\n */\nexport interface BrepEvolutionData {\n  /** 结果句柄 */\n  result: BrepHandle\n  /** 分段：`[inHash, count, outHash…] × N`；值 = 该输入面的结果后继 */\n  modified: number[]\n  /** 分段（键集同 `modified`）：该输入面派生的中间形 hash，实测结果里 0 存活 */\n  generated: number[]\n  /** 扁平：输入面中已不存在的面 hash */\n  deleted: number[]\n}\n\n/** 曲线参数区间（与内核 curveParameters 返回同构：first/last）。 */\nexport interface BrepCurveParameters {\n  first: number\n  last: number\n}\n\n/**\n * NURBS control data of one edge's BASIS curve.\n *\n * ⚠️ This is the WHOLE basis curve, not the edge: an OCCT edge is often only a\n * sub-range of its curve, so `curveParameters(edge)` is the trim to apply on top\n * of this (`BRep_Tool::Curve` hands back both halves). Rebuilding an edge from\n * this data without honouring that trim produces a curve running past its\n * neighbour's start (measured 2026-09-29).\n *\n * `poles` is flat `[x,y,z, x,y,z, …]`; `weights` has one entry per pole (all 1\n * for a non-rational curve, and `rational` then says whether they mean anything);\n * `knots`/`multiplicities` are parallel arrays (expanded, the knot vector is\n * `knots[i]` repeated `multiplicities[i]` times and has `poles + degree + 1`\n * entries).\n */\nexport interface BrepNurbsCurveData {\n  /** Polynomial degree. */\n  degree: number\n  /** True when `weights` are meaningful (a rational curve). */\n  rational: boolean\n  /** True for a periodic (closed, wrap-around) curve. */\n  periodic: boolean\n  /** Distinct knot values, parallel to `multiplicities`. */\n  knots: number[]\n  /** Multiplicity of each entry in `knots`. */\n  multiplicities: number[]\n  /** Flat control points: `[x, y, z, x, y, z, …]`. */\n  poles: number[]\n  /** One weight per control point. */\n  weights: number[]\n}\n\n/** 曲面 UV 边界。 */\nexport interface BrepUvBounds {\n  uMin: number\n  uMax: number\n  vMin: number\n  vMax: number\n}\n\n/** 子形状类型（getSubShapes / subShapeHashes 等）。 */\nexport type BrepSubShapeType = 'vertex' | 'edge' | 'wire' | 'face' | 'shell' | 'solid'\n\n/**\n * XCAF 装配文档句柄（可选能力槽 AssemblyCapability 的文档形态）。\n *\n * 形态来自 occt-wasm XCAFDocumentImpl 的被调用子集（step.ts / occt-kernel 装配链）。\n */\nexport interface BrepXcafDocument {\n  addShape(shape: BrepHandle, opts?: { name?: string; color?: [number, number, number] }): void\n  exportSTEP(): string\n  close(): void\n}\n\n/**\n * 曲面细分精度控制模型（与 brepjs KernelCapabilities.tessellationModel 同构的中立镜像，\n * P7 并入；faijs 侧零内核依赖，不 import 外部子包——D8 反向只允许发生在 api/）。\n *\n * - `'build-time'`  — 网格在实体构造时固定（如 manifold 全局分段设置）；质量参数须在构造前应用。\n * - `'extract-time'`— 形状是精确的，按需以每调用 deflection 细分（如 OCCT）；质量是\n *                    `mesh()`/导出时的默认 deflection。\n * - `'none'`        — 无细分控制（或非网格内核）。\n */\nexport type BrepTessellationModel = 'build-time' | 'extract-time' | 'none'\n\n/**\n * 面演化（`*WithHistory`）核函数名——与内核方法同名，**逐核函数**声明。\n *\n * ⚠️ **为什么不能是一个布尔位**（2026-09-22 Phase 0.2）：`evolution: true` 是**族级**声明。\n * 而「本内核提供面演化」这句话在建面上不成立——每个 `*WithHistory` 是一个独立核函数，\n * 内核可以只提供其中一部分。`brepkit` 就是活例：它提供 `fuse`/`cut`/`fillet`，\n * `chamfer`/`intersect`/`translate`/… 一律 `unsupported(...)`\n * （`brepkit-kernel/brepkitKernel.ts:220-537`）。\n *\n * 族级布尔的后果不是\"少报\"而是**多报**：`cad.intersect` 声明需要 `evolution`，\n * 在 `evolution: true` 下通过静态判定 → 落到运行时才撞 `unsupported('intersectWithHistory')`。\n * 这直接违反 AGENTS.md 红线「BREP 路径能否走由静态规则判定，禁止运行时回退」——\n * 静态判定之所以能成立，前提是引擎的能力声明**说的是逐核函数的实话**。\n *\n * ⇒ 引擎声明\"我提供哪几个\"（`BrepCapabilities.evolution`），op 声明\"我要哪一个\"\n * （`defineOp.capabilities`），两者**按名字求交集**（`cad-runtime/backend-dispatch.ts`）。\n */\nexport type BrepEvolutionKind =\n  // 布尔族\n  | 'fuseWithHistory'\n  | 'cutWithHistory'\n  | 'intersectWithHistory'\n  // 倒圆/倒角族\n  | 'filletWithHistory'\n  | 'chamferWithHistory'\n  // 刚体变换族\n  | 'translateWithHistory'\n  | 'rotateWithHistory'\n  | 'mirrorWithHistory'\n  | 'scaleWithHistory'\n  // 抽壳/偏置/加厚族\n  | 'shellWithHistory'\n  | 'offsetWithHistory'\n  | 'thickenWithHistory'\n\n/**\n * 非演化内核方法真名（`*WithHistory` 之外的 `BrepEngineApi` 方法）。\n *\n * 与 `BrepEvolutionKind` 分名（P3 冲突消除）：`'mirror'` 一个字符串不能同时表示\n * \"提供 `mirrorWithHistory`\"与\"提供 `mirror`\"，两族必须互不共用字符串。\n * 语义与 evolution 相同——**逐核函数**声明：声明 = 实现（诚实原则），\n * 缺省/空 = 一个都不提供。\n *\n * 初始全集 = Phase 0 能力映射表（`api/surface/capability-map.json`）盘点的\n * compat op 依赖内核方法 + 方案初始项；Phase 3 全量收敛时按映射表滚动补全。\n */\nexport type BrepMethodKind =\n  // pattern 族\n  | 'linearPattern'\n  | 'circularPattern'\n  | 'gridPattern'\n  | 'rectangularPattern'\n  // 基础方法族（裸方法，无历史）\n  | 'mirror'\n  | 'rotate'\n  | 'translate'\n  | 'scale'\n  // 倒角/圆角基础方法（directEdit 族下的逐核真名，Phase 2：chamfer op 能力声明\n  // 精确到内核方法——brepkit 无 chamfer/chamferDistAngle，静态判定执行前报错）\n  | 'chamfer'\n  | 'chamferDistAngle'\n  | 'fillet'\n  | 'filletVariable'\n  // 构形/拉伸/放样族\n  | 'makeRectangle'\n  | 'shell'\n  | 'extrude'\n  | 'loft'\n  | 'loftAdvanced'\n  | 'section'\n  | 'sweepPipeShell'\n  | 'simplePipe'\n  | 'revolveVec'\n  | 'buildExtrusionLaw'\n  // 布尔/装配辅助（裸方法）\n  | 'fuse'\n  | 'cut'\n  | 'intersect'\n  | 'fuseAll'\n  // 构造方法族\n  | 'makeArcEdge'\n  | 'makeCircleEdge'\n  | 'makeBezierEdge'\n  | 'makeCylinder'\n  | 'makeEllipsoid'\n  | 'makeFace'\n  | 'makeFaceOnSurface'\n  | 'makeLineEdge'\n  | 'makeTorus'\n  | 'makeVertex'\n  | 'makeWire'\n  | 'makeWireFromMixed'\n  | 'buildEdgeOnSurface'\n  | 'addHolesInFace'\n  | 'buildTriFace'\n  | 'sew'\n  | 'sewAndSolidify'\n  // 修复/校验族\n  | 'healFace'\n  | 'healSolid'\n  | 'healWire'\n  | 'fixShape'\n  | 'fixSelfIntersection'\n  | 'isValid'\n  | 'removeDegenerateEdges'\n  | 'simplify'\n  | 'split'\n  // 查询/测量族\n  // ⚠️ 测量族能力名用 L1 中立名（D5，narrowing plan）：`getBoundingBox` / `getVolume`\n  // / `getSurfaceArea` / `getLength` / `getCenterOfMass` ——能力名 == BrepEngineApi 接口名，\n  // 守卫「能力声明诚实」据此逐名断言适配器是 function。旧面自己的原生名\n  // （boundingBox/volume/area/length）按其自身命名，\n  // 不是能力名空间成员。\n  | 'getBoundingBox'\n  | 'getVolume'\n  | 'getSurfaceArea'\n  | 'getLength'\n  | 'getCenterOfMass'\n  | 'curveParameters'\n  | 'curvePointAtParam'\n  | 'curveTangent'\n  | 'hullFromPoints'\n  | 'isNull'\n  | 'iterShapes'\n  | 'locate'\n  | 'shapeType'\n  | 'surfaceCenterOfMass'\n  | 'surfaceNormal'\n  | 'surfaceType'\n  | 'uvBounds'\n  // 变换族（非演化真名）\n  | 'composeTransform'\n  | 'applyComposedTransformWithHistory'\n  | 'generalTransformNonOrthogonal'\n  | 'generalTransformWithHistory'\n  // 2026-09-26 C batch: section/drill/pocket/boss/mirrorJoin downgrade wiring.\n  | 'sectionByPlane'\n  | 'makeCompound'\n  | 'located'\n  | 'getSubShapes'\n  | 'transform'\n  | 'generalTransform'\n  // 交换/导入族\n  | 'importStl'\n  | 'createXCAFDocument'\n  | 'importXCAFFromSTEP'\n  // 生命周期辅助\n  | 'copyShape'\n  | 'dispose'\n  | 'downcast'\n  | 'hashCode'\n\n/**\n * 可选能力槽声明（§7.5，Phase 1 钉死成员）。\n *\n * 缺失的能力 → 依赖它的功能静态降级走 mesh（§8.4），绝不伪造。\n *\n * P7 并入（D4）：移植 brepjs `KernelCapabilities` 的数据字段（exact/brepExport/\n * exactMeasurement/tessellationModel）进本模型，由适配器在注册时如实声明；分派逻辑\n * （backend-dispatch 的 BrepCapabilityName 路由）不改——新字段是引擎本质描述，不是\n * 逐 op 路由键。\n *\n * 未并入 `disposalModel`（D5 决策，与旧 port 一致）：faijs 的句柄释放由\n * `cad-runtime` 顶替释放统一编排（增量失败回滚前提），brepjs 的 DisposalScope/arena\n * 语义不强制统一，故不作为能力位记录。\n */\nexport interface BrepCapabilities {\n  /**\n   * 面演化族：本引擎**实际提供**的 `*WithHistory` 核函数名（不是族级布尔，见\n   * `BrepEvolutionKind`）。空数组 / 缺省 = 一个都不提供。\n   */\n  evolution?: readonly BrepEvolutionKind[]\n  /**\n   * 非演化内核方法族：本引擎**实际提供**的 `BrepEngineApi` 方法真名\n   * （逐核声明，与 `evolution` 同语义；空数组 / 缺省 = 一个都不提供）。\n   */\n  methods?: readonly BrepMethodKind[]\n  /** 修复族（healSolid/fixShape/fixFaceOrientations/...） */\n  heal?: boolean\n  /** 直接编辑族（C1：moveFace/replaceFace/...） */\n  directEdit?: boolean\n  /** 高级曲面族（C1：boundarySurface/fillSurface/...） */\n  advSurface?: boolean\n  /** XCAF 装配族 */\n  assembly?: boolean\n  /** mesh→BREP 提升（buildTriFace/sewAndSolidify） */\n  meshLift?: boolean\n  /** 精确 B-rep 几何（vs mesh 近似）——brepjs KernelCapabilities.exact 并入 */\n  exact?: boolean\n  /** 可序列化为 B-rep 交换格式（BREP/STEP）——brepjs brepExport 并入 */\n  brepExport?: boolean\n  /** 体积/面积/长度匹配解析值（vs mesh 近似）——brepjs exactMeasurement 并入 */\n  exactMeasurement?: boolean\n  /** 细分精度控制模型——brepjs tessellationModel 并入 */\n  tessellationModel?: BrepTessellationModel\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/brep/engine/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAU,CAAA;AAgCxE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAA","sourcesContent":["/**\n * engine/types — BREP 引擎中立类型（零具体实现依赖，不 import 任何内核包）\n *\n *\n * 契约（对应 brepjs 的 KernelShape 约定）：\n * - L1 及以上代码永远不对句柄调用任何方法，只把它传回产生它的那个引擎；\n * - 句柄不得跨引擎传递——跨引擎必须先经 mesh 层（§8.3 的结构保证）。\n * - OCCT 适配器的句柄运行时就是 number，加 brand 是零成本的类型层转换。\n */\n\n/**\n * BREP 引擎身份（D11-1，2026-09-24 narrowing plan）。\n *\n * 三个值来自三个已存在的引擎 id 常量（`OCCT_BREP_ENGINE_ID` / `BREPKIT_BREP_ENGINE_ID`\n * / `BREP_MOCK_ENGINE_ID`，各自适配器导出）；本类型由常量数组推导，禁止裸 `string`。\n * 适配器常量用 `satisfies BrepEngineId` 收窄（typecheck 钉住集合一致）。\n *\n * 消费点：`defineOp` 的 `engines` 声明（平台 op 自证身份）、`dispatchPath` 的平台\n * 身份分支（D11-2）、`script-face-manifest` 的平台 op 标注（§3.8）。\n */\nexport const BREP_ENGINE_IDS = ['occt', 'brepkit', 'brep_mock'] as const\n\n/** BREP 引擎身份（固定三值联合；由 {@link BREP_ENGINE_IDS} 推导）。 */\nexport type BrepEngineId = (typeof BREP_ENGINE_IDS)[number]\n\ndeclare const BrepHandleBrand: unique symbol\n\n/**\n * BREP 实体句柄——不透明值。\n *\n * 与 occt-wasm 的 ShapeHandle 同构（number & brand）。OCCT 适配器\n * （occt-kernel/）内部以 `as unknown as` 双向转换，跨适配器边界零运行时成本。\n */\nexport type BrepHandle = number & { readonly [BrepHandleBrand]: never }\n\n/** 三维点/向量（与内核无关的中立形态）。 */\nexport interface BrepVec3 {\n  x: number\n  y: number\n  z: number\n}\n\n/** 轴对齐包围盒。 */\nexport interface BrepBoundingBox {\n  xmin: number\n  ymin: number\n  zmin: number\n  xmax: number\n  ymax: number\n  zmax: number\n}\n\n/**\n * 面/边 hash 的上界（唯一真源）。\n *\n * 拓扑提取侧用 `kernel.hashCode(subShape, BREP_HASH_BOUND)` 查面/边，\n * 三角化/线框侧把 hash 写进 `faceGroups[·+2]` / `edgeGroups[·+2]`——\n * **两侧必须对同一上界取模**，否则查表恒 miss（实测 2026-10-01：\n * brepkit 适配器曾用 1e9、topologyExt 用 INT32_MAX → 面行 triangleCount 全 0）。\n * 值取自 OCCT `HASH_CODE_MAX` 惯例，也是 occt-wasm 的实际口径（实测一致）。\n */\nexport const BREP_HASH_BOUND = 2147483647\n\n/**\n * BRepMesh 三角化输出（镜像 occt-wasm Mesh 的中立形态）。\n *\n * ⚠️ 单位口径（L1 契约的一部分，实测钉死）：\n * - `faceGroups` 三元组 = `[triStart, triCount, faceHash]`，前两元是**索引单位**\n *   （3/三角形），不是三角形单位；\n * - `wireframe().edgeGroups` = `[pointStart, pointCount, edgeHash]`，前两元是\n *   **浮点单位**（3/点）。\n * 修订任何一侧都要同步改另一侧与 brepkit 适配器（跨引擎一致性测试\n * `topology/face-group-units.test.ts` 钉住）。\n */\nexport interface BrepMeshResult {\n  /** XYZ 交错顶点坐标，长度 = vertexCount * 3 */\n  positions: Float32Array\n  /** XYZ 交错顶点法线，长度 = vertexCount * 3 */\n  normals: Float32Array\n  /** 三角形索引 */\n  indices: Uint32Array\n  /** 顶点数（positions.length / 3） */\n  vertexCount: number\n  /** 三角形数（indices.length / 3） */\n  triangleCount: number\n  /** 面组：[triStart, triCount, faceHash] 三元组（meshShape 时存在） */\n  faceGroups?: Int32Array\n  /** 面组数（meshShape 时存在） */\n  faceCount?: number\n}\n\n/** 三角化精度选项。 */\nexport interface BrepTessellateOptions {\n  /** 最大弦偏差（mm），默认 0.1 */\n  linearDeflection?: number\n  /** 最大角偏差（弧度），默认 0.5 */\n  angularDeflection?: number\n  /** 按每条边长度相对解释 linearDeflection */\n  relative?: boolean\n}\n\n/** 边折线数据（wireframe 输出）。 */\nexport interface BrepEdgeData {\n  /** XYZ 交错边采样点 */\n  points: Float32Array\n  /** 每边分组：[pointStart, pointCount, edgeHash] 三元组；前两元为**浮点单位**（3/点）。 */\n  edgeGroups: Int32Array\n  /** points 中的浮点数总数（= XYZ 坐标数） */\n  pointCount: number\n  /** 不同边的数量 */\n  edgeCount: number\n}\n\n/**\n * *WithHistory 面演化数据（modified/generated/deleted 用面 hash 编码）。\n *\n * ⚠️ **三个字段的编码不同，实测于 2026-09-22（`brep/engine/phase0-kernel-probes.test.ts`），\n * 与 occt-wasm 自己的文档（`dist/types.d.ts:227-231`）不符**：\n *\n * | 字段 | 实际编码 | 键/值语义 |\n * |---|---|---|\n * | `modified` | **分段** `[inHash, count, outHash…] × N` | 键 = 输入面 hash；值 = 该输入面在结果里的**后继**（可 1→N） |\n * | `generated` | **同构分段**，**键集与 `modified` 相同** | 值 = 该输入面派生出的**中间形**（实测结果里 0 存活） |\n * | `deleted` | **扁平** hash 数组 | 输入面中已不存在的面 |\n *\n * 「扁平数组」的读法会把 `generated` 的 count 字段当成 hash——\n * 实测 `cut` 的 `generated` 里真的含 `2`（一个 count），故该误读不会自己暴露。\n *\n * ⚠️ **未受影响的面有两种上报形态，两种都表示\"未变\"**：自映射（`i -> [i]`）。\n * 或者**整个不上报**（`fillet` 实测两者并存）。⇒ 读法必须是\n * `modified.get(h) ?? [h]`，不能只看\"是否出现在 `modified` 里\"。\n *\n * ⇒ 结果面的三种命运（判据见 `phase0-kernel-probes.test.ts`）：\n * **原样幸存**（hash ∈ 输入 hash 集合，hash 逐字不变）/ **改型幸存**（在 `modified` 输出里）/\n * **新造**（两者皆非——这才是真正需要派生词汇命名的面，如 `fillet` 的过渡面）。\n */\nexport interface BrepEvolutionData {\n  /** 结果句柄 */\n  result: BrepHandle\n  /** 分段：`[inHash, count, outHash…] × N`；值 = 该输入面的结果后继 */\n  modified: number[]\n  /** 分段（键集同 `modified`）：该输入面派生的中间形 hash，实测结果里 0 存活 */\n  generated: number[]\n  /** 扁平：输入面中已不存在的面 hash */\n  deleted: number[]\n}\n\n/** 曲线参数区间（与内核 curveParameters 返回同构：first/last）。 */\nexport interface BrepCurveParameters {\n  first: number\n  last: number\n}\n\n/**\n * NURBS control data of one edge's BASIS curve.\n *\n * ⚠️ This is the WHOLE basis curve, not the edge: an OCCT edge is often only a\n * sub-range of its curve, so `curveParameters(edge)` is the trim to apply on top\n * of this (`BRep_Tool::Curve` hands back both halves). Rebuilding an edge from\n * this data without honouring that trim produces a curve running past its\n * neighbour's start (measured 2026-09-29).\n *\n * `poles` is flat `[x,y,z, x,y,z, …]`; `weights` has one entry per pole (all 1\n * for a non-rational curve, and `rational` then says whether they mean anything);\n * `knots`/`multiplicities` are parallel arrays (expanded, the knot vector is\n * `knots[i]` repeated `multiplicities[i]` times and has `poles + degree + 1`\n * entries).\n */\nexport interface BrepNurbsCurveData {\n  /** Polynomial degree. */\n  degree: number\n  /** True when `weights` are meaningful (a rational curve). */\n  rational: boolean\n  /** True for a periodic (closed, wrap-around) curve. */\n  periodic: boolean\n  /** Distinct knot values, parallel to `multiplicities`. */\n  knots: number[]\n  /** Multiplicity of each entry in `knots`. */\n  multiplicities: number[]\n  /** Flat control points: `[x, y, z, x, y, z, …]`. */\n  poles: number[]\n  /** One weight per control point. */\n  weights: number[]\n}\n\n/** 曲面 UV 边界。 */\nexport interface BrepUvBounds {\n  uMin: number\n  uMax: number\n  vMin: number\n  vMax: number\n}\n\n/** 子形状类型（getSubShapes / subShapeHashes 等）。 */\nexport type BrepSubShapeType = 'vertex' | 'edge' | 'wire' | 'face' | 'shell' | 'solid'\n\n/**\n * XCAF label 句柄（`addShape` / `addChild` 的返回值，仅在所属文档内有效）。\n */\nexport type BrepXcafLabel = number & { readonly __brepXcafLabel: 'BrepXcafLabel' }\n\n/**\n * XCAF 装配文档句柄（可选能力槽 AssemblyCapability 的文档形态）。\n *\n * 形态来自 occt-wasm XCAFDocumentImpl 的被调用子集（step.ts / occt-kernel 装配链）。\n * `addChild` 支撑真装配写入（方案 2026-10-08 步骤 7 / P3）：组件位姿经\n * `location`（平移 + Euler 弧度）落到 XCAF location，导出为装配引用而非平级 PRODUCT。\n */\nexport interface BrepXcafDocument {\n  /** 顶层 part / 装配 label。返回的 label 可作为 `addChild` 的父。 */\n  addShape(shape: BrepHandle, opts?: { name?: string; color?: [number, number, number] }): BrepXcafLabel\n  /**\n   * 把 shape 作为 parent 的子组件加入（parent 是 part 时，首个 child 使其转为\n   * assembly：原几何移入 identity 首组件并携带 part 的名与色）。\n   */\n  addChild(\n    parent: BrepXcafLabel,\n    shape: BrepHandle,\n    opts?: {\n      name?: string\n      color?: [number, number, number]\n      /** 组件相对父的位姿：平移 + Euler 角（弧度）。⚠️ occt-wasm 当前只生效平移\n       * （旋转分量写出→回读恒 identity，step-export.test.ts P7 钉住）——旋转由\n       * 调用方烘进几何，wasm 修复后恢复 location 携带完整位姿。 */\n      location?: { tx?: number; ty?: number; tz?: number; rx?: number; ry?: number; rz?: number }\n    },\n  ): BrepXcafLabel\n  exportSTEP(): string\n  close(): void\n}\n\n/**\n * 面演化（`*WithHistory`）核函数名——与内核方法同名，**逐核函数**。\n *\n * ⚠️ **为什么不是一个布尔位**（2026-09-22 Phase 0.2，事实不变）：家族化命名会**多报**。\n * 「本内核提供面演化」这句话在建面上不成立——每个 `*WithHistory` 是一个独立核函数，\n * 内核可以只提供其中一部分。`brepkit` 就是活例：它提供 `fuse`/`cut`/`fillet`，\n * `chamfer`/`intersect`/`translate`/… 一律 `unsupported(...)`\n * （`brepkit-kernel/brepkitKernel.ts:220-537`）。\n *\n * 本类型是「面演化核函数有哪些」的**名字全集**，供 `hasNativeHistory`\n * （`brep/engine/native-history.ts`）按引擎身份逐名回答\"这个引擎原生有没有它\"。\n * 没有声明轴：op 不声明要哪个核函数，分派时也不查任何能力表。\n */\nexport type BrepEvolutionKind =\n  // 布尔族\n  | 'fuseWithHistory'\n  | 'cutWithHistory'\n  | 'intersectWithHistory'\n  // 倒圆/倒角族\n  | 'filletWithHistory'\n  | 'chamferWithHistory'\n  // 刚体变换族\n  | 'translateWithHistory'\n  | 'rotateWithHistory'\n  | 'mirrorWithHistory'\n  | 'scaleWithHistory'\n  // 抽壳/偏置/加厚族\n  | 'shellWithHistory'\n  | 'offsetWithHistory'\n  | 'thickenWithHistory'\n"]}

package/dist/brep/export/export-model.d.ts

@@ -14,6 +14,7 @@
  * 红线（§10.3 3a）：绝不文本级改坐标 — 坐标只在几何层缩放，文本层只碰单位实体。
  */
 import { type UnitName } from '../../units.js';
+import type { Vec3 } from '../../mesh/types.js';
 import type { BrepHandle } from '../engine/types.js';
 import type { PbrAppearance } from '../../api/appearance.js';
 import type { ShapeMeta, FileMeta } from '../../api/meta.js';
@@ -44,6 +45,25 @@ export interface ExportEntry {
      * `<object name/partnumber>` + `<metadatagroup>`；STEP 走 PRODUCT name（既有）。
      */
     meta?: ShapeMeta;
+    /**
+     * 装配子节点（方案 2026-10-08 §2.1 / 第 4 步）：存在时本条目是装配容器，写出器据此
+     * 生成 3MF `<components>`（每个 child 一个 `<component objectid>`，子节点的 `transform`
+     * 写进 `<component transform>`）；STL / STEP 分支忽略此字段或将其展平（逐层烘焙 /
+     * 逐实体通道，第 5、7 步）。
+     */
+    children?: ExportEntry[];
+    /**
+     * 本节点相对父的位姿（与 `Shape.transform` 同形态，方案 §2.1）。写出器消费：3MF 写
+     * `<component transform>`、STEP 写 XCAF location（第 7 步）、STL 顶点烘焙（第 5 步）。
+     */
+    transform?: {
+        translate?: Vec3;
+        rotate?: {
+            angle: number;
+            axis?: Vec3;
+        };
+        matrix?: number[];
+    };
 }
 /** Output formats supported by the unified {@link exportModel} entry. */
 export type ExportFormat = 'stl' | 'step' | '3mf';
@@ -86,6 +106,7 @@ export declare const UNIT_NAME_TO_3MF: Partial<Record<UnitName, 'micron' | 'mill
  * @returns 改写后的 STEP 文本。
  */
 export declare function rewriteFileMetaHeader(stepText: string, fileMeta: FileMeta): string;
+export { transformToMatrix12 } from './transform12.js';
 /**
  * Synchronous twin of {@link exportModel} for hosts already holding a live
  * kernel (CLI, in-process consumers). Same invariants: declared unit ==

package/dist/brep/export/export-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export-model.d.ts","sourceRoot":"","sources":["../../../src/brep/export/export-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAKjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzD,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAA;IACxD,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;IACnF;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;AAEjD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,gCAAgC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAQ1H,CAAA;AAuED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA6ClF;AAsND;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE,aAAa,GACnB,WAAW,CA6Db;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,WAAW,CAAC,CA6EtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,IAAI,CAgBtG"}
+{"version":3,"file":"export-model.d.ts","sourceRoot":"","sources":["../../../src/brep/export/export-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAMjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzD,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE;QAAE,SAAS,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAA;IACxD,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;IACnF;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,IAAI,CAAA;SAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC7F;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAA;AAEjD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,gCAAgC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAED,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAQ1H,CAAA;AA+ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA6ClF;AAuPD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAmDnD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE,aAAa,GACnB,WAAW,CAmFb;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,WAAW,CAAC,CAyEtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,IAAI,CAgBtG"}

package/dist/brep/export/export-model.js

@@ -13,10 +13,11 @@
  *
  * 红线（§10.3 3a）：绝不文本级改坐标 — 坐标只在几何层缩放，文本层只碰单位实体。
  */
-import { buildStlBufferFromMesh } from './stl.js';
+import { buildStlBufferFromMesh, composeMatrix12, bakeMatrix12ToPositions } from './stl.js';
 import { writeZipEntries } from '../../io/zip.js';
 import { UNIT_SCALE } from '../../units.js';
 import { getBrepApi } from '../handle-bridge.js';
+import { getBackends, BrepUnsupportedError } from '../../runtime-state.js';
 import { exportStepFromSolids } from './step.js';
 import { detectStepUnit, STEP_UNIT_SCAN_PREFIX } from '../../mesh/io.js';
 /** UnitName → 3MF <model unit> 枚举全名（唯一真源；yard 无对应值）。 */
@@ -72,19 +73,27 @@ function rewriteStepUnitEntities(stepText, unit) {
     }
     const lenId = maxId + 1;
     const convId = maxId + 2;
-    // 2) 找到 LENGTH_UNIT() 里挂 SI_UNIT 的实体行，替换为 CONVERSION_BASED_UNIT
-    //    并把 SI_UNIT 挂到 LENGTH_MEASURE 上。OCCT 输出形态（实测）：
-    //    #n=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.));
-    const siLine = out.match(/#(\d+)\s*=\s*\([^)]*SI_UNIT\s*\(\s*\.MILLI\.\s*,\s*\.METRE\.\s*\)[^)]*\)\s*;/);
-    if (!siLine) {
+    // 2) 存在性守卫：必须至少有一条 LENGTH_UNIT 挂 SI_UNIT(.MILLI.,.METRE.)，否则
+    //    没有可改写的声明（凭空插入单位声明 = 伪造文件单位）。
+    //    OCCT 实测形态（实体括号内还有 LENGTH_UNIT() / NAMED_UNIT(*) 的括号，且
+    //    `=`、`)` 前后都有空格）：
+    //      #346 = ( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+    //    故实体体的字符类用 [^;]（STEP 实体行内不含分号）而不是 [^)]——后者跨不过
+    //    `LENGTH_UNIT()` 与 `NAMED_UNIT(*)` 自带的括号，整段永远匹配不上。
+    const siDecl = out.match(/#(\d+)\s*=\s*\([^;]*?SI_UNIT\s*\(\s*\.MILLI\.\s*,\s*\.METRE\.\s*\)[^;]*?\)\s*;/);
+    if (!siDecl) {
         throw new Error(`[export/step] no SI_UNIT(.MILLI.,.METRE.) entity found; cannot rewrite declaration to ${name}`);
     }
-    // 3) 替换原 SI_UNIT 实体为 CONVERSION_BASED_UNIT，插入换算因子与基准米实体：
-    //   #si=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.));
-    // → #si=(LENGTH_UNIT()NAMED_UNIT(*)CONVERSION_BASED_UNIT('INCH',#conv));
+    // 3) 把**全部** SI_UNIT(.MILLI.,.METRE.) 换成 CONVERSION_BASED_UNIT（各 context
+    //    共享同一份换算因子实体），插入换算因子与基准米实体：
+    //   #si=( LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.) );
+    // → #si=( LENGTH_UNIT() NAMED_UNIT(*) CONVERSION_BASED_UNIT('INCH',#conv) );
     //   #conv=LENGTH_MEASURE_WITH_UNIT(LENGTH_MEASURE(25.4),#len);
     //   #len=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT($,.METRE.));
-    out = out.replace(siLine[0], siLine[0].replace(/SI_UNIT\s*\(\s*\.MILLI\.\s*,\s*\.METRE\.\s*\)/, `CONVERSION_BASED_UNIT('${name}',#${convId})`));
+    // 全局替换而不是只改第一条：多零件导出会写出多条 LENGTH_UNIT 声明（每个 part 一个
+    // context，实测 2 个 part → #346 与 #690），只改第一条会让同一文件里并存两种长度
+    // 单位声明——而坐标是按同一 scale 换算过的。
+    out = out.replace(/SI_UNIT\s*\(\s*\.MILLI\.\s*,\s*\.METRE\.\s*\)/g, `CONVERSION_BASED_UNIT('${name}',#${convId})`);
     // 在 DATA 段结束前（ENDSEC;）插入新实体。
     const insert = [
         `#${convId}=LENGTH_MEASURE_WITH_UNIT(LENGTH_MEASURE(${inchFactor}),#${lenId});`,
@@ -282,40 +291,65 @@ function build3mfModelXml(entries, unit, scale, printConfig, fileMeta) {
     const objs = [];
     const mats = [];
     const items = [];
+    let nextObjId = 1;
+    // 逐三角形材质分组的 basematerials id 从「顶层条目数 + 1」起，与 object id（1..N）
+    // 错开（P3：resources 内 id 唯一）。对象级颜色 basematerials 复用其 object id。
     let nextMatId = entries.length + 1;
-    entries.forEach((e, i) => {
-        if (!e.mesh)
-            return;
-        const pos = scalePositions(e.mesh.positions, scale);
-        const verts = [];
-        for (let v = 0; v < pos.length; v += 3) {
-            verts.push(`<vertex x="${pos[v]}" y="${pos[v + 1]}" z="${pos[v + 2]}"/>`);
-        }
-        // P4（3MF Core 逐三角形材质）：materialGroups（appearance.color）→ 每组
-        // 一个独立 basematerials 资源（id 与对象 id 错开，P3 曾与对象共用 id、
-        // 违反 resources 内 id 唯一），分组三角形用 `<triangle pid p1..p3>` 引用。
-        const groupPids = [];
-        const groups = (e.materialGroups ?? []).filter((g) => g.appearance?.color);
-        for (const g of groups) {
-            groupPids.push(nextMatId);
-            mats.push(`<basematerials id="${nextMatId}"><base name="${xmlAttr(`${e.name ?? `part${i + 1}`}_g${groupPids.length}`)}" displaycolor="${hexColor(g.appearance.color)}"/></basematerials>`);
-            nextMatId++;
-        }
-        const tris = [];
-        const triCount = e.mesh.indices.length / 3;
-        let gi = 0;
-        for (let t = 0; t < triCount; t++) {
-            while (gi < groups.length && t >= groups[gi].start + groups[gi].count)
-                gi++;
-            const inGroup = gi < groups.length && t >= groups[gi].start;
-            const matAttr = inGroup ? ` pid="${groupPids[gi]}" p1="0" p2="0" p3="0"` : '';
-            tris.push(`<triangle v1="${e.mesh.indices[t * 3]}" v2="${e.mesh.indices[t * 3 + 1]}" v3="${e.mesh.indices[t * 3 + 2]}"${matAttr}/>`);
+    // 递归发射一个节点为 <object>（叶带 mesh、容器带 <components>），返回其 object id。
+    function emitObject(e) {
+        // P8 契约（库面）：无 mesh 且无子节点的条目 → 静默跳过（不发射 <object>/<item>），
+        // 与 op 层「无三角载荷即 E_EXPORT_3MF_EMPTY 显式报错」形成双值防护。显式容器
+        // （children 已声明，即便为空 []）仍发射，以便装配层级（含空装配）可写。
+        const isContainer = e.children !== undefined;
+        if (!e.mesh && !isContainer)
+            return undefined;
+        const id = nextObjId++;
+        let meshXml = '';
+        if (e.mesh) {
+            const pos = scalePositions(e.mesh.positions, scale);
+            const verts = [];
+            for (let v = 0; v < pos.length; v += 3) {
+                verts.push(`<vertex x="${pos[v]}" y="${pos[v + 1]}" z="${pos[v + 2]}"/>`);
+            }
+            // P4（3MF Core 逐三角形材质）：materialGroups（appearance.color）→ 每组
+            // 一个独立 basematerials 资源（id 与对象 id 错开，P3 曾与对象共用 id、
+            // 违反 resources 内 id 唯一），分组三角形用 `<triangle pid p1..p3>` 引用。
+            const groupPids = [];
+            const groups = (e.materialGroups ?? []).filter((g) => g.appearance?.color);
+            for (const g of groups) {
+                groupPids.push(nextMatId);
+                mats.push(`<basematerials id="${nextMatId}"><base name="${xmlAttr(`${e.name ?? `part${id}`}_g${groupPids.length}`)}" displaycolor="${hexColor(g.appearance.color)}"/></basematerials>`);
+                nextMatId++;
+            }
+            const tris = [];
+            const triCount = e.mesh.indices.length / 3;
+            let gi = 0;
+            for (let t = 0; t < triCount; t++) {
+                while (gi < groups.length && t >= groups[gi].start + groups[gi].count)
+                    gi++;
+                const inGroup = gi < groups.length && t >= groups[gi].start;
+                const matAttr = inGroup ? ` pid="${groupPids[gi]}" p1="0" p2="0" p3="0"` : '';
+                tris.push(`<triangle v1="${e.mesh.indices[t * 3]}" v2="${e.mesh.indices[t * 3 + 1]}" v3="${e.mesh.indices[t * 3 + 2]}"${matAttr}/>`);
+            }
+            meshXml = `<mesh><vertices>${verts.join('')}</vertices><triangles>${tris.join('')}</triangles></mesh>`;
         }
-        // P3（v2 §8 3MF 行，Core 规范）：basematerials 必须声明在 <resources>，
-        // object 用 pid/pindex 引用——此前内联在 <object> 内的写法解析器（
-        // parseThreemf 只读 resources）不识别，导入→导出→导入颜色丢失。
+        // 对象级颜色 basematerials：复用 object id（既有契约，解析器按 id 取首个资源）。
+        let pidAttr = '';
         if (e.color) {
-            mats.push(`<basematerials id="${i + 1}"><base name="${xmlAttr(e.name ?? 'p' + i)}" displaycolor="${hexColor(e.color)}"/></basematerials>`);
+            mats.push(`<basematerials id="${id}"><base name="${xmlAttr(e.name ?? 'p' + id)}" displaycolor="${hexColor(e.color)}"/></basematerials>`);
+            pidAttr = ` pid="${id}" pindex="0"`;
+        }
+        // 装配层级 → <components>（子节点递归；<component transform> 写相对父位姿）。
+        let compXml = '';
+        if (e.children && e.children.length > 0) {
+            const comps = e.children.map((child) => {
+                const cid = emitObject(child);
+                if (cid === undefined)
+                    return '';
+                const tf = child.transform ? ` transform="${matrix12ToAttr(transformToMatrix12(child.transform))}"` : '';
+                return `<component objectid="${cid}"${tf}/>`;
+            }).filter((s) => s !== '');
+            compXml = comps.length > 0 ? `<components>${comps.join('')}</components>` : '';
         }
         // 零件级元数据（设计文档 2026-10-05-meta §6.1）：partnumber 属性 +
         // `<metadatagroup><metadata>`（3MF 自定义标签须带命名空间前缀；faijs
@@ -343,9 +377,17 @@ function build3mfModelXml(entries, unit, scale, printConfig, fileMeta) {
             }
         }
         const metadatagroup = metadatas.length > 0 ? `<metadatagroup>${metadatas.join('')}</metadatagroup>` : '';
-        objs.push(`<object id="${i + 1}" type="model" name="${xmlAttr(e.name ?? `part${i + 1}`)}"${partnumberAttr}${e.color ? ` pid="${i + 1}" pindex="0"` : ''}>${metadatagroup}<mesh><vertices>${verts.join('')}</vertices><triangles>${tris.join('')}</triangles></mesh></object>`);
-        items.push(`<item objectid="${i + 1}"/>`);
-    });
+        const nameAttr = xmlAttr(e.name ?? `part${id}`);
+        objs.push(`<object id="${id}" type="model" name="${nameAttr}"${partnumberAttr}${pidAttr}>${metadatagroup}${meshXml}${compXml}</object>`);
+        return id;
+    }
+    for (const e of entries) {
+        const id = emitObject(e);
+        if (id === undefined)
+            continue;
+        const tf = e.transform ? ` transform="${matrix12ToAttr(transformToMatrix12(e.transform))}"` : '';
+        items.push(`<item objectid="${id}"${tf}/>`);
+    }
     // 整体级元数据（`<model>` 直接子级 `<metadata>`）：well-known 名经映射写标准
     // 3MF 名，vendor 名写 `faijs:` 前缀。排在 `<resources>` 之前（3MF Core）。
     const modelMetas = [];
@@ -381,6 +423,51 @@ function hexColor(c) {
     const h = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, '0');
     return `#${h(c[0])}${h(c[1])}${h(c[2])}`;
 }
+export { transformToMatrix12 } from './transform12.js';
+import { scaleTransform, transformToMatrix12 } from './transform12.js';
+/**
+ * ExportEntry → StepExportEntry 的递归映射器（step 分支同步/异步共用，单一真源）。
+ * 容器只传名/色与子节点（compound 几何 == 成员并集，写出会重复）；位姿平移按
+ * 单位刻度换算，与几何缩放同一 scale 因子（「声明单位 == 坐标刻度」对组件位姿
+ * 同样成立）。solid 经 kernel.scale 的 owned copy 缩放，入 ownedHandles 由调用方
+ * 统一释放。
+ */
+function makeStepEntryMapper(kernel, scale, ownedHandles) {
+    const toStepEntry = (e) => {
+        const head = {
+            ...(e.name ? { name: e.name } : {}),
+            ...(e.color ? { color: [...e.color] } : {}),
+        };
+        const transform = e.transform ? scaleTransform(e.transform, scale) : undefined;
+        if (e.children && e.children.length > 0) {
+            return {
+                ...head,
+                ...(transform ? { transform } : {}),
+                children: e.children.map(toStepEntry),
+            };
+        }
+        if (e.solid) {
+            if (scale === 1)
+                return { solid: e.solid, ...head };
+            const scaled = kernel.scale(e.solid, { x: 0, y: 0, z: 0 }, scale);
+            ownedHandles.push(scaled);
+            return { solid: scaled, ...head };
+        }
+        return {
+            ...head,
+            ...(e.mesh ? { mesh: { positions: scalePositions(e.mesh.positions, scale), indices: e.mesh.indices } } : {}),
+        };
+    };
+    return toStepEntry;
+}
+function fmtNum(v) {
+    if (Number.isInteger(v))
+        return String(v);
+    return String(Math.round(v * 1e6) / 1e6);
+}
+function matrix12ToAttr(m) {
+    return m.map(fmtNum).join(' ');
+}
 /**
  * Synchronous twin of {@link exportModel} for hosts already holding a live
  * kernel (CLI, in-process consumers). Same invariants: declared unit ==
@@ -400,7 +487,29 @@ export function exportModelSync(entries, format, opts) {
         unit = 'mm';
     const scale = 1 / UNIT_SCALE[unit];
     if (format === 'stl') {
-        const bufs = entries.filter((e) => e.mesh).map((e) => ({ pos: scalePositions(e.mesh.positions, scale), idx: e.mesh.indices }));
+        // 步骤 5（方案 §2.1 / §4.3 L1-5）：装配展平 + 顶点烘焙。递归把 children 拍平成叶，
+        // 每个叶的世界变换 = 父世界变换 ∘ 本节点局部 transform（row-major 3×4，平移在末列）。
+        // 先在世界空间烘焙 transform，再按单位换算缩放坐标（缩放同时作用于平移分量，坐标与声明成对）。
+        const flatten = (list, accTf) => {
+            const out = [];
+            for (const e of list) {
+                const tf = e.transform ? transformToMatrix12(e.transform) : null;
+                const world = tf && accTf ? composeMatrix12(accTf, tf) : tf ?? accTf ?? null;
+                if (e.children && e.children.length > 0) {
+                    out.push(...flatten(e.children, world));
+                    continue;
+                }
+                if (!e.mesh)
+                    continue;
+                let pos = e.mesh.positions;
+                if (world)
+                    pos = bakeMatrix12ToPositions(pos, world);
+                pos = scalePositions(pos, scale);
+                out.push({ pos, idx: e.mesh.indices });
+            }
+            return out;
+        };
+        const bufs = flatten(entries, null);
         if (bufs.length === 0)
             throw new Error('[export/stl] no mesh entries');
         if (bufs.length === 1)
@@ -421,22 +530,18 @@ export function exportModelSync(entries, format, opts) {
         return buildStlBufferFromMesh(mergedPos, mergedIdx);
     }
     if (format === 'step') {
+        // 步骤 6（方案 §2.3 / P1）：STEP 装配层级走 XCAF，仅 occt 具备；非 occt 引擎在
+        // 触碰任何句柄之前报 E_BREP_UNSUPPORTED（带当前引擎名），不落入 getBrepApi 的
+        // 未初始化异常，也不把 brepkit 句柄交给 occt 内核（句柄不得跨引擎传递）。
+        const engineId = getBackends().config.brepEngineId;
+        if (engineId !== 'occt') {
+            throw new BrepUnsupportedError(`E_BREP_UNSUPPORTED: op 'exportModel:step' requires engine occt (current=${engineId ?? '<none>'})`);
+        }
         const kernel = getBrepApi();
         const ownedHandles = [];
-        const stepEntries = entries.map((e) => {
-            if (e.solid) {
-                if (scale === 1)
-                    return { solid: e.solid, ...(e.name ? { name: e.name } : {}), ...(e.color ? { color: [...e.color] } : {}) };
-                const scaled = kernel.scale(e.solid, { x: 0, y: 0, z: 0 }, scale);
-                ownedHandles.push(scaled);
-                return { solid: scaled, ...(e.name ? { name: e.name } : {}), ...(e.color ? { color: [...e.color] } : {}) };
-            }
-            return {
-                ...(e.mesh ? { mesh: { positions: scalePositions(e.mesh.positions, scale), indices: e.mesh.indices } } : {}),
-                ...(e.name ? { name: e.name } : {}),
-                ...(e.color ? { color: [...e.color] } : {}),
-            };
-        });
+        // 层级映射（步骤 7 / P3）：ExportEntry 树 → StepExportEntry 树（映射器见
+        // makeStepEntryMapper——同步/异步分支共用，单一真源）。
+        const stepEntries = entries.map(makeStepEntryMapper(kernel, scale, ownedHandles));
         const buffer = exportStepFromSolids(kernel, stepEntries);
         for (const h of ownedHandles) {
             try {
@@ -512,25 +617,18 @@ export async function exportModel(entries, format, opts) {
         return buildStlBufferFromMesh(mergedPos, mergedIdx);
     }
     if (format === 'step') {
+        // 步骤 6（方案 §2.3 / P1）：同同步分支，取内核前先断言 occt 引擎身份。
+        const engineId = getBackends().config.brepEngineId;
+        if (engineId !== 'occt') {
+            throw new BrepUnsupportedError(`E_BREP_UNSUPPORTED: op 'exportModel:step' requires engine occt (current=${engineId ?? '<none>'})`);
+        }
         // 同一 scale 变量喂两类条目（§10.3 规则 7，修 E4）：mesh 缩放 positions，
         // solid 用 owned copy 做 kernel.scale —— 不释放调用方缓存里的原句柄。
         // 先过门禁再取内核（同同步分支：拒绝理由与引擎装配状态无关）。
         const kernel = (await import('../handle-bridge.js')).getBrepApi();
         const ownedHandles = [];
-        const stepEntries = entries.map((e) => {
-            if (e.solid) {
-                if (scale === 1)
-                    return { solid: e.solid, ...(e.name ? { name: e.name } : {}), ...(e.color ? { color: [...e.color] } : {}) };
-                const scaled = kernel.scale(e.solid, { x: 0, y: 0, z: 0 }, scale);
-                ownedHandles.push(scaled);
-                return { solid: scaled, ...(e.name ? { name: e.name } : {}), ...(e.color ? { color: [...e.color] } : {}) };
-            }
-            return {
-                ...(e.mesh ? { mesh: { positions: scalePositions(e.mesh.positions, scale), indices: e.mesh.indices } } : {}),
-                ...(e.name ? { name: e.name } : {}),
-                ...(e.color ? { color: [...e.color] } : {}),
-            };
-        });
+        // 同步分支同一映射器（单一真源）。
+        const stepEntries = entries.map(makeStepEntryMapper(kernel, scale, ownedHandles));
         const buffer = exportStepFromSolids(kernel, stepEntries);
         for (const h of ownedHandles) {
             try {