@faicad/faijs 0.30.9 → 0.32.2

package/dist/mesh/engrave.js

@@ -11,8 +11,10 @@
  * 不包含：store 读写、commitGeometry、undo snapshot、toast。
  * 这些由执行器负责（P1 不改变现有执行器行为）。
  */
-import * as THREE from 'three';
+import { Vec3 as Vec3C, Quat, Mat4 } from '../math3d/index.js';
+import { transformShape, translateShape } from './meshdata/ops.js';
 import { computeBoolean, geoToManifoldMesh, manifoldMeshToGeo } from '../boolean/csg-backend.js';
+import { boundingBox } from './query.js';
 import { getEngraveDecorationProvider } from './decoration-provider.js';
 /**
  * Execute an engraving: generate the decoration geometry (text or SVG),
@@ -39,7 +41,7 @@ export async function engrave(shape, params) {
             'installEditorMeshProviders() from @faicad/faijs-extra) before engraving in mesh mode, ' +
             'or run the op on the BREP path');
     }
-    const decorationGeo = await provider({
+    let decoration = await provider({
         text: params.text,
         textSize: params.textSize,
         svg: params.svg,
@@ -49,27 +51,25 @@ export async function engrave(shape, params) {
         depth: params.depth,
     });
     // 2. 定位装饰几何到面
-    const faceCenter = new THREE.Vector3(...params.face.center);
-    const faceNormal = new THREE.Vector3(...params.face.normal);
+    const faceCenter = new Vec3C(...params.face.center);
+    const faceNormal = new Vec3C(...params.face.normal);
     // Center geometry at origin
-    decorationGeo.computeBoundingBox();
-    const center = new THREE.Vector3();
-    decorationGeo.boundingBox.getCenter(center);
-    decorationGeo.translate(-center.x, -center.y, -center.z);
+    const bb = boundingBox(decoration);
+    const center = new Vec3C((bb.min[0] + bb.max[0]) / 2, (bb.min[1] + bb.max[1]) / 2, (bb.min[2] + bb.max[2]) / 2);
+    decoration = translateShape(decoration, -center.x, -center.y, -center.z);
     // Rotate +Z to align with face normal
-    const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 0, 1), faceNormal);
-    decorationGeo.applyQuaternion(quat);
+    const quat = new Quat().setFromUnitVectors(new Vec3C(0, 0, 1), faceNormal);
+    const rotMatrix = new Mat4().makeRotationFromQuaternion(quat);
+    decoration = transformShape(decoration, rotMatrix);
     // Offset along normal (convex = outward, concave = inward)
     const offset = params.mode === 'convex' ? params.depth / 2 : -params.depth / 2;
     const pos = faceCenter.clone().add(faceNormal.clone().multiplyScalar(offset));
-    decorationGeo.translate(pos.x, pos.y, pos.z);
+    decoration = translateShape(decoration, pos.x, pos.y, pos.z);
     // 3. 转换为 ManifoldMeshData
-    const decorationData = geoToManifoldMesh(decorationGeo);
+    const decorationData = geoToManifoldMesh(decoration);
     // 4. 布尔运算
     const op = params.mode === 'convex' ? 'union' : 'subtract';
     const result = await computeBoolean([shape, decorationData], op);
-    // 5. 清理
-    decorationGeo.dispose();
     return result;
 }
 /**
@@ -84,22 +84,21 @@ export async function engrave(shape, params) {
  */
 export async function knurl(shape, params) {
     const { applyKnurlDisplacement, KNURL_DEFAULTS } = await import('./knurl/KnurlGenerator.js');
-    // 1. Shape → THREE.BufferGeometry
+    // 1. Shape → Shape (with normals)
     const geo = manifoldMeshToGeo(shape, { computeNormals: true });
     // 2. 计算面排除权重：法向与 face.normal 不接近的面标记为排除
-    const posAttr = geo.getAttribute('position');
-    const triCount = posAttr.count / 3;
-    const faceNormal = new THREE.Vector3(...params.face.normal).normalize();
+    const positions = geo.positions;
+    const triCount = positions.length / 3;
+    const faceNormal = new Vec3C(...params.face.normal).normalize();
     // 计算每个三角形的法向
-    const positions = posAttr.array;
-    const indices = geo.index ? geo.index.array : null;
-    const faceWeights = new Float32Array(posAttr.count);
-    const v0 = new THREE.Vector3();
-    const v1 = new THREE.Vector3();
-    const v2 = new THREE.Vector3();
-    const edge1 = new THREE.Vector3();
-    const edge2 = new THREE.Vector3();
-    const triNormal = new THREE.Vector3();
+    const indices = geo.indices.length > 0 ? geo.indices : null;
+    const faceWeights = new Float32Array(positions.length);
+    const v0 = new Vec3C();
+    const v1 = new Vec3C();
+    const v2 = new Vec3C();
+    const edge1 = new Vec3C();
+    const edge2 = new Vec3C();
+    const triNormal = new Vec3C();
     for (let t = 0; t < triCount; t++) {
         const i0 = indices ? indices[t * 3] : t * 3;
         const i1 = indices ? indices[t * 3 + 1] : t * 3 + 1;
@@ -119,16 +118,17 @@ export async function knurl(shape, params) {
         }
     }
     // 3. 计算包围盒
-    geo.computeBoundingBox();
-    const bb = geo.boundingBox;
+    const bb = boundingBox(geo);
+    const bbMin = new Vec3C(bb.min[0], bb.min[1], bb.min[2]);
+    const bbMax = new Vec3C(bb.max[0], bb.max[1], bb.max[2]);
     const partBounds = {
-        min: bb.min.clone(),
-        max: bb.max.clone(),
-        size: new THREE.Vector3().subVectors(bb.max, bb.min),
-        center: new THREE.Vector3().addVectors(bb.min, bb.max).multiplyScalar(0.5),
+        min: bbMin,
+        max: bbMax,
+        size: new Vec3C().subVectors(bbMax, bbMin),
+        center: new Vec3C().addVectors(bbMin, bbMax).multiplyScalar(0.5),
     };
     // 4. 调用 applyKnurlDisplacement
-    const resultGeo = await applyKnurlDisplacement(geo, {
+    const result = await applyKnurlDisplacement(geo, {
         ...KNURL_DEFAULTS,
         textureHeight: params.knurlTextureHeight,
         invertDisplacement: params.knurlInvertDisplacement,
@@ -138,8 +138,7 @@ export async function knurl(shape, params) {
         mappingMode: params.knurlMappingMode,
         faceWeights,
     }, undefined, partBounds);
-    geo.dispose();
-    // 5. THREE.BufferGeometry → Shape
-    return geoToManifoldMesh(resultGeo);
+    // 5. Shape → ManifoldMeshData
+    return geoToManifoldMesh(result);
 }
 //# sourceMappingURL=engrave.js.map

package/dist/mesh/engrave.js.map

@@ -1 +1 @@
-{"version":3,"file":"engrave.js","sourceRoot":"","sources":["../../src/mesh/engrave.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * mesh 雕刻 API\n *\n * 提取来源：engine/components/engraving/EngravingCore.ts\n *\n * 从 executeEngraving 中提取纯几何计算部分：\n * 1. 生成装饰几何（文字或 SVG）\n * 2. 定位到面\n * 3. 布尔运算（凸=union，凹=subtract）\n *\n * 不包含：store 读写、commitGeometry、undo snapshot、toast。\n * 这些由执行器负责（P1 不改变现有执行器行为）。\n */\n\nimport * as THREE from 'three'\nimport { computeBoolean, geoToManifoldMesh, manifoldMeshToGeo } from '../boolean/csg-backend'\nimport { getEngraveDecorationProvider } from './decoration-provider'\nimport type { Shape, EngraveParams, KnurlParams } from './types'\n\n/**\n * Execute an engraving: generate the decoration geometry (text or SVG),\n * position it onto a face, then run a boolean union (convex) or subtract\n * (concave).\n *\n * The decoration geometry itself comes from the host-installed provider\n * (`setEngraveDecorationProvider`) — three's `Shape`/`ExtrudeGeometry`/`SVGLoader`\n * chain belongs to `@faicad/faijs-extra`, not to the platform surface.\n *\n * @param shape - the world-space target shape.\n * @param params - engrave parameters (text/svg, depth, face, mode).\n * @returns the engraved shape in world space.\n */\nexport async function engrave(shape: Shape, params: EngraveParams): Promise<Shape> {\n  // 1. 生成装饰几何（局部空间，+Z = 挤出方向）\n  if (!params.text && !params.svg) {\n    throw new Error('engrave requires either text or svg')\n  }\n  const provider = getEngraveDecorationProvider()\n  if (!provider) {\n    throw new Error(\n      'engrave: no mesh decoration provider installed — the text/SVG geometry chain ' +\n      'lives in @faicad/faijs-extra; call setEngraveDecorationProvider() (or ' +\n      'installEditorMeshProviders() from @faicad/faijs-extra) before engraving in mesh mode, ' +\n      'or run the op on the BREP path',\n    )\n  }\n  const decorationGeo: THREE.BufferGeometry = await provider({\n    text: params.text,\n    textSize: params.textSize,\n    svg: params.svg,\n    svgSize: params.svgSize,\n    svgNaturalWidth: params.svgNaturalWidth,\n    svgNaturalHeight: params.svgNaturalHeight,\n    depth: params.depth,\n  })\n\n  // 2. 定位装饰几何到面\n  const faceCenter = new THREE.Vector3(...params.face.center)\n  const faceNormal = new THREE.Vector3(...params.face.normal)\n\n  // Center geometry at origin\n  decorationGeo.computeBoundingBox()\n  const center = new THREE.Vector3()\n  decorationGeo.boundingBox!.getCenter(center)\n  decorationGeo.translate(-center.x, -center.y, -center.z)\n\n  // Rotate +Z to align with face normal\n  const quat = new THREE.Quaternion().setFromUnitVectors(\n    new THREE.Vector3(0, 0, 1),\n    faceNormal,\n  )\n  decorationGeo.applyQuaternion(quat)\n\n  // Offset along normal (convex = outward, concave = inward)\n  const offset = params.mode === 'convex' ? params.depth / 2 : -params.depth / 2\n  const pos = faceCenter.clone().add(faceNormal.clone().multiplyScalar(offset))\n  decorationGeo.translate(pos.x, pos.y, pos.z)\n\n  // 3. 转换为 ManifoldMeshData\n  const decorationData = geoToManifoldMesh(decorationGeo)\n\n  // 4. 布尔运算\n  const op = params.mode === 'convex' ? 'union' : 'subtract'\n  const result = await computeBoolean([shape, decorationData], op)\n\n  // 5. 清理\n  decorationGeo.dispose()\n\n  return result\n}\n\n/**\n * Apply a knurling texture displacement to a shape (vertex displacement, not a\n * boolean op). The replay path approximates UI face selection by excluding\n * faces whose normal deviates from the given face normal; the angle limits act\n * as an angular mask.\n *\n * @param shape - the world-space shape to knurl.\n * @param params - knurl parameters (texture height, refine length, UV scale, mapping mode).\n * @returns the displaced shape in world space.\n */\nexport async function knurl(shape: Shape, params: KnurlParams): Promise<Shape> {\n  const { applyKnurlDisplacement, KNURL_DEFAULTS } = await import(\n    './knurl/KnurlGenerator'\n  )\n\n  // 1. Shape → THREE.BufferGeometry\n  const geo = manifoldMeshToGeo(shape, { computeNormals: true })\n\n  // 2. 计算面排除权重：法向与 face.normal 不接近的面标记为排除\n  const posAttr = geo.getAttribute('position')\n  const triCount = posAttr.count / 3\n  const faceNormal = new THREE.Vector3(...params.face.normal).normalize()\n\n  // 计算每个三角形的法向\n  const positions = posAttr.array as Float32Array\n  const indices = geo.index ? (geo.index.array as Uint32Array) : null\n  const faceWeights = new Float32Array(posAttr.count)\n\n  const v0 = new THREE.Vector3()\n  const v1 = new THREE.Vector3()\n  const v2 = new THREE.Vector3()\n  const edge1 = new THREE.Vector3()\n  const edge2 = new THREE.Vector3()\n  const triNormal = new THREE.Vector3()\n\n  for (let t = 0; t < triCount; t++) {\n    const i0 = indices ? indices[t * 3] : t * 3\n    const i1 = indices ? indices[t * 3 + 1] : t * 3 + 1\n    const i2 = indices ? indices[t * 3 + 2] : t * 3 + 2\n\n    v0.set(positions[i0 * 3], positions[i0 * 3 + 1], positions[i0 * 3 + 2])\n    v1.set(positions[i1 * 3], positions[i1 * 3 + 1], positions[i1 * 3 + 2])\n    v2.set(positions[i2 * 3], positions[i2 * 3 + 1], positions[i2 * 3 + 2])\n\n    edge1.subVectors(v1, v0)\n    edge2.subVectors(v2, v0)\n    triNormal.crossVectors(edge1, edge2).normalize()\n\n    // 法向相似度：dot > 0.5 (~60° within) → 不排除\n    const dot = triNormal.dot(faceNormal)\n    if (dot < 0.5) {\n      faceWeights[t * 3] = 1.0\n      faceWeights[t * 3 + 1] = 1.0\n      faceWeights[t * 3 + 2] = 1.0\n    }\n  }\n\n  // 3. 计算包围盒\n  geo.computeBoundingBox()\n  const bb = geo.boundingBox!\n  const partBounds = {\n    min: bb.min.clone(),\n    max: bb.max.clone(),\n    size: new THREE.Vector3().subVectors(bb.max, bb.min),\n    center: new THREE.Vector3().addVectors(bb.min, bb.max).multiplyScalar(0.5),\n  }\n\n  // 4. 调用 applyKnurlDisplacement\n  const resultGeo = await applyKnurlDisplacement(\n    geo,\n    {\n      ...KNURL_DEFAULTS,\n      textureHeight: params.knurlTextureHeight,\n      invertDisplacement: params.knurlInvertDisplacement,\n      refineLength: params.knurlRefineLength,\n      scaleU: params.knurlScaleU,\n      scaleV: params.knurlScaleV,\n      mappingMode: params.knurlMappingMode,\n      faceWeights,\n    },\n    undefined,\n    partBounds,\n  )\n\n  geo.dispose()\n\n  // 5. THREE.BufferGeometry → Shape\n  return geoToManifoldMesh(resultGeo)\n}\n"]}
+{"version":3,"file":"engrave.js","sourceRoot":"","sources":["../../src/mesh/engrave.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * mesh 雕刻 API\n *\n * 提取来源：engine/components/engraving/EngravingCore.ts\n *\n * 从 executeEngraving 中提取纯几何计算部分：\n * 1. 生成装饰几何（文字或 SVG）\n * 2. 定位到面\n * 3. 布尔运算（凸=union，凹=subtract）\n *\n * 不包含：store 读写、commitGeometry、undo snapshot、toast。\n * 这些由执行器负责（P1 不改变现有执行器行为）。\n */\n\nimport { Vec3 as Vec3C, Quat, Mat4 } from '../math3d'\nimport { transformShape, translateShape } from './meshdata/ops'\nimport { computeBoolean, geoToManifoldMesh, manifoldMeshToGeo } from '../boolean/csg-backend'\nimport { boundingBox } from './query'\nimport { getEngraveDecorationProvider } from './decoration-provider'\nimport type { Shape, EngraveParams, KnurlParams } from './types'\n\n/**\n * Execute an engraving: generate the decoration geometry (text or SVG),\n * position it onto a face, then run a boolean union (convex) or subtract\n * (concave).\n *\n * The decoration geometry itself comes from the host-installed provider\n * (`setEngraveDecorationProvider`) — three's `Shape`/`ExtrudeGeometry`/`SVGLoader`\n * chain belongs to `@faicad/faijs-extra`, not to the platform surface.\n *\n * @param shape - the world-space target shape.\n * @param params - engrave parameters (text/svg, depth, face, mode).\n * @returns the engraved shape in world space.\n */\nexport async function engrave(shape: Shape, params: EngraveParams): Promise<Shape> {\n  // 1. 生成装饰几何（局部空间，+Z = 挤出方向）\n  if (!params.text && !params.svg) {\n    throw new Error('engrave requires either text or svg')\n  }\n  const provider = getEngraveDecorationProvider()\n  if (!provider) {\n    throw new Error(\n      'engrave: no mesh decoration provider installed — the text/SVG geometry chain ' +\n      'lives in @faicad/faijs-extra; call setEngraveDecorationProvider() (or ' +\n      'installEditorMeshProviders() from @faicad/faijs-extra) before engraving in mesh mode, ' +\n      'or run the op on the BREP path',\n    )\n  }\n  let decoration = await provider({\n    text: params.text,\n    textSize: params.textSize,\n    svg: params.svg,\n    svgSize: params.svgSize,\n    svgNaturalWidth: params.svgNaturalWidth,\n    svgNaturalHeight: params.svgNaturalHeight,\n    depth: params.depth,\n  })\n\n  // 2. 定位装饰几何到面\n  const faceCenter = new Vec3C(...params.face.center)\n  const faceNormal = new Vec3C(...params.face.normal)\n\n  // Center geometry at origin\n  const bb = boundingBox(decoration)\n  const center = new Vec3C(\n    (bb.min[0] + bb.max[0]) / 2,\n    (bb.min[1] + bb.max[1]) / 2,\n    (bb.min[2] + bb.max[2]) / 2,\n  )\n  decoration = translateShape(decoration, -center.x, -center.y, -center.z)\n\n  // Rotate +Z to align with face normal\n  const quat = new Quat().setFromUnitVectors(\n    new Vec3C(0, 0, 1),\n    faceNormal,\n  )\n  const rotMatrix = new Mat4().makeRotationFromQuaternion(quat)\n  decoration = transformShape(decoration, rotMatrix)\n\n  // Offset along normal (convex = outward, concave = inward)\n  const offset = params.mode === 'convex' ? params.depth / 2 : -params.depth / 2\n  const pos = faceCenter.clone().add(faceNormal.clone().multiplyScalar(offset))\n  decoration = translateShape(decoration, pos.x, pos.y, pos.z)\n\n  // 3. 转换为 ManifoldMeshData\n  const decorationData = geoToManifoldMesh(decoration)\n\n  // 4. 布尔运算\n  const op = params.mode === 'convex' ? 'union' : 'subtract'\n  const result = await computeBoolean([shape, decorationData], op)\n\n  return result\n}\n\n/**\n * Apply a knurling texture displacement to a shape (vertex displacement, not a\n * boolean op). The replay path approximates UI face selection by excluding\n * faces whose normal deviates from the given face normal; the angle limits act\n * as an angular mask.\n *\n * @param shape - the world-space shape to knurl.\n * @param params - knurl parameters (texture height, refine length, UV scale, mapping mode).\n * @returns the displaced shape in world space.\n */\nexport async function knurl(shape: Shape, params: KnurlParams): Promise<Shape> {\n  const { applyKnurlDisplacement, KNURL_DEFAULTS } = await import(\n    './knurl/KnurlGenerator'\n  )\n\n  // 1. Shape → Shape (with normals)\n  const geo = manifoldMeshToGeo(shape, { computeNormals: true })\n\n  // 2. 计算面排除权重：法向与 face.normal 不接近的面标记为排除\n  const positions = geo.positions\n  const triCount = positions.length / 3\n  const faceNormal = new Vec3C(...params.face.normal).normalize()\n\n  // 计算每个三角形的法向\n  const indices = geo.indices.length > 0 ? geo.indices : null\n  const faceWeights = new Float32Array(positions.length)\n\n  const v0 = new Vec3C()\n  const v1 = new Vec3C()\n  const v2 = new Vec3C()\n  const edge1 = new Vec3C()\n  const edge2 = new Vec3C()\n  const triNormal = new Vec3C()\n\n  for (let t = 0; t < triCount; t++) {\n    const i0 = indices ? indices[t * 3] : t * 3\n    const i1 = indices ? indices[t * 3 + 1] : t * 3 + 1\n    const i2 = indices ? indices[t * 3 + 2] : t * 3 + 2\n\n    v0.set(positions[i0 * 3], positions[i0 * 3 + 1], positions[i0 * 3 + 2])\n    v1.set(positions[i1 * 3], positions[i1 * 3 + 1], positions[i1 * 3 + 2])\n    v2.set(positions[i2 * 3], positions[i2 * 3 + 1], positions[i2 * 3 + 2])\n\n    edge1.subVectors(v1, v0)\n    edge2.subVectors(v2, v0)\n    triNormal.crossVectors(edge1, edge2).normalize()\n\n    // 法向相似度：dot > 0.5 (~60° within) → 不排除\n    const dot = triNormal.dot(faceNormal)\n    if (dot < 0.5) {\n      faceWeights[t * 3] = 1.0\n      faceWeights[t * 3 + 1] = 1.0\n      faceWeights[t * 3 + 2] = 1.0\n    }\n  }\n\n  // 3. 计算包围盒\n  const bb = boundingBox(geo)\n  const bbMin = new Vec3C(bb.min[0], bb.min[1], bb.min[2])\n  const bbMax = new Vec3C(bb.max[0], bb.max[1], bb.max[2])\n  const partBounds = {\n    min: bbMin,\n    max: bbMax,\n    size: new Vec3C().subVectors(bbMax, bbMin),\n    center: new Vec3C().addVectors(bbMin, bbMax).multiplyScalar(0.5),\n  }\n\n  // 4. 调用 applyKnurlDisplacement\n  const result = await applyKnurlDisplacement(\n    geo,\n    {\n      ...KNURL_DEFAULTS,\n      textureHeight: params.knurlTextureHeight,\n      invertDisplacement: params.knurlInvertDisplacement,\n      refineLength: params.knurlRefineLength,\n      scaleU: params.knurlScaleU,\n      scaleV: params.knurlScaleV,\n      mappingMode: params.knurlMappingMode,\n      faceWeights,\n    },\n    undefined,\n    partBounds,\n  )\n\n  // 5. Shape → ManifoldMeshData\n  return geoToManifoldMesh(result)\n}\n"]}

package/dist/mesh/index.d.ts

@@ -9,29 +9,24 @@
  * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理
  * 4. 坐标系：右手系 +Z 向上、毫米、角度用度
  *
- * ⚠️ B3 补正（2026-10-06，用户决定）：本文件**不再导出任何聚合对象**。
- *
- * 此前这里有一个把 primitives / brep / transform / boolean / engrave / query / io
- * 全量聚合进来的对象（曾名 `cad`，B3 一度改名 `meshCad`）。它把内核实现包装成一个
- * 「形似平台 API」的门面，使下游（含本仓测试）能 `import { cad } from '../mesh/index.js'`
- * 把内核当成 faijs 的公开 API——这正是要根除的混淆。改名只是换了张皮，因此聚合
- * 对象已整体删除，不再以任何名字存在。
- *
- * 要哪一层的实现，就从对应模块具名导入：
- * - `mesh/primitives`   box / sphere / cylinder / cone / wedge / screw / sdf
- * - `mesh/transform`    translate / rotate_euler / scale / scale3d / transformMatrix
- * - `mesh/boolean`      union / subtract / intersect
- * - `mesh/engrave`      engrave / knurl
- * - `mesh/query`        boundingBox / bboxCenter / volume / faceAt
- * - `mesh/io`           importFile / detectStepUnit
- * - `brep`、`brep/primitives-brep`  BREP（OCCT）路径
- *
- * 注意：脚本面的 `cad`（宿主经 `registerLib('cad', …)` 注入的 op 命名空间）与这一层
- * 是两回事——它不在这里，也不该被这里 import。见 AGENTS.md「库开发者 vs 脚本开发者」。
+ * ⚠️ B3 补正（2026-10-06）：本文件不导出任何聚合对象（`cad` / `meshCad` 已删除）。
+ * 要内核实现就从对应模块具名导入。门面层经 `export * from './mesh.js'` 消费。
  */
-export type { Shape, Vec3, BoundingBox, FaceDescriptor } from './types.js';
+export type { Shape, BoundingBox, FaceDescriptor, BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams, TextParams, SvgExtrudeParams, SdfParams, DrillParams, ExtrudeParams, EngraveParams, KnurlParams, SplitPlane, SplitResult, DovetailSplitParams, TenonSplitParams, } from './types.js';
+export { NRAD_DEFAULT, NRAD_MIN, NRAD_MAX, clampNRad } from './types.js';
+export { isMeshShape } from './types.js';
 export { guessStlUnit } from './stl-unit.js';
-export type { BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams, TextParams, SvgExtrudeParams, SdfParams, DrillParams, ExtrudeParams, EngraveParams, KnurlParams, SplitPlane, SplitResult, DovetailSplitParams, DowelSplitParams, TenonSplitParams, } from './types.js';
-export type { BrepChainState, DrillBrepParams, SplitBrepParams, SplitBrepResult, ExtrudeBrepParams, } from '../brep/index.js';
-export { createBrepChainState, initBrepChainState, releaseBrepChainState, solidToShape, isCadFormat, } from '../brep/index.js';
+export { setEngraveDecorationProvider, getEngraveDecorationProvider } from './decoration-provider.js';
+export type { EngraveDecorationProvider, EngraveDecorationParams } from './decoration-provider.js';
+export { setManifoldWasmUrl, getManifoldWasmUrl, getManifoldModule } from './manifold-loader.js';
+export { faceAt } from './query.js';
+export { applyKnurlDisplacement, KNURL_DEFAULTS } from './knurl/KnurlGenerator.js';
+export type { KnurlBounds } from './knurl/KnurlGenerator.js';
+export { subdivide } from './knurl/subdivision.js';
+export { loadKnurlingTexture, setKnurlTextureLoader } from './knurl/textureLoader.js';
+export type { TextureData } from './knurl/textureLoader.js';
+export { QuantizedPointMap, weldVertices } from './knurl/meshIndex.js';
+export { computeUV, MODE_TRIPLANAR, getCubicBlendWeights, type MappingSettings } from './knurl/mapping.js';
+export { applyDisplacement, type DisplacementSettings } from './knurl/displacement.js';
+export type { ImportModel, ImportPart, ImportAssemblyNode, ImportBambuViews, } from './import-model.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/mesh/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mesh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,YAAY,EACV,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAChE,UAAU,EAAE,gBAAgB,EAAE,SAAS,EACvC,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACtD,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,GACjF,MAAM,SAAS,CAAA;AAGhB,YAAY,EACV,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EACjE,iBAAiB,GAClB,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,oBAAoB,EAAE,kBAAkB,EAAE,qBAAqB,EAC/D,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mesh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,YAAY,EACV,KAAK,EAAE,WAAW,EAAE,cAAc,EAClC,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAChE,UAAU,EAAE,gBAAgB,EAAE,SAAS,EACvC,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACtD,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,GAC/D,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAGrC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAGzC,OAAO,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AAClG,YAAY,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAG/F,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAG7F,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAGhC,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACvG,OAAO,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAGnF,YAAY,EACV,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,GAC9D,MAAM,gBAAgB,CAAA"}

package/dist/mesh/index.js

@@ -9,26 +9,24 @@
  * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理
  * 4. 坐标系：右手系 +Z 向上、毫米、角度用度
  *
- * ⚠️ B3 补正（2026-10-06，用户决定）：本文件**不再导出任何聚合对象**。
- *
- * 此前这里有一个把 primitives / brep / transform / boolean / engrave / query / io
- * 全量聚合进来的对象（曾名 `cad`，B3 一度改名 `meshCad`）。它把内核实现包装成一个
- * 「形似平台 API」的门面，使下游（含本仓测试）能 `import { cad } from '../mesh/index.js'`
- * 把内核当成 faijs 的公开 API——这正是要根除的混淆。改名只是换了张皮，因此聚合
- * 对象已整体删除，不再以任何名字存在。
- *
- * 要哪一层的实现，就从对应模块具名导入：
- * - `mesh/primitives`   box / sphere / cylinder / cone / wedge / screw / sdf
- * - `mesh/transform`    translate / rotate_euler / scale / scale3d / transformMatrix
- * - `mesh/boolean`      union / subtract / intersect
- * - `mesh/engrave`      engrave / knurl
- * - `mesh/query`        boundingBox / bboxCenter / volume / faceAt
- * - `mesh/io`           importFile / detectStepUnit
- * - `brep`、`brep/primitives-brep`  BREP（OCCT）路径
- *
- * 注意：脚本面的 `cad`（宿主经 `registerLib('cad', …)` 注入的 op 命名空间）与这一层
- * 是两回事——它不在这里，也不该被这里 import。见 AGENTS.md「库开发者 vs 脚本开发者」。
+ * ⚠️ B3 补正（2026-10-06）：本文件不导出任何聚合对象（`cad` / `meshCad` 已删除）。
+ * 要内核实现就从对应模块具名导入。门面层经 `export * from './mesh.js'` 消费。
  */
+export { NRAD_DEFAULT, NRAD_MIN, NRAD_MAX, clampNRad } from './types.js';
+export { isMeshShape } from './types.js';
+// ── stl-unit ──
 export { guessStlUnit } from './stl-unit.js';
-export { createBrepChainState, initBrepChainState, releaseBrepChainState, solidToShape, isCadFormat, } from '../brep/index.js';
+// ── decoration-provider ──
+export { setEngraveDecorationProvider, getEngraveDecorationProvider } from './decoration-provider.js';
+// ── manifold-loader ──
+export { setManifoldWasmUrl, getManifoldWasmUrl, getManifoldModule } from './manifold-loader.js';
+// ── query ──
+export { faceAt } from './query.js';
+// ── knurl ──
+export { applyKnurlDisplacement, KNURL_DEFAULTS } from './knurl/KnurlGenerator.js';
+export { subdivide } from './knurl/subdivision.js';
+export { loadKnurlingTexture, setKnurlTextureLoader } from './knurl/textureLoader.js';
+export { QuantizedPointMap, weldVertices } from './knurl/meshIndex.js';
+export { computeUV, MODE_TRIPLANAR, getCubicBlendWeights } from './knurl/mapping.js';
+export { applyDisplacement } from './knurl/displacement.js';
 //# sourceMappingURL=index.js.map

package/dist/mesh/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mesh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAazC,OAAO,EACL,oBAAoB,EAAE,kBAAkB,EAAE,qBAAqB,EAC/D,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAA","sourcesContent":["/**\n * mesh — 纯数据几何内核（按模块组织的实现层）\n *\n * See docs/api-contract.md §1 (architecture layers) and §10 (api function catalog).\n *\n * 原则（§5.1）：\n * 1. 全部纯数据：输入输出是 Shape (ManifoldMeshData)，不碰 THREE 场景、不读 store\n * 2. 不可变：每个 API 返回新几何，不修改输入\n * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理\n * 4. 坐标系：右手系 +Z 向上、毫米、角度用度\n *\n * ⚠️ B3 补正（2026-10-06，用户决定）：本文件**不再导出任何聚合对象**。\n *\n * 此前这里有一个把 primitives / brep / transform / boolean / engrave / query / io\n * 全量聚合进来的对象（曾名 `cad`，B3 一度改名 `meshCad`）。它把内核实现包装成一个\n * 「形似平台 API」的门面，使下游（含本仓测试）能 `import { cad } from '../mesh'`\n * 把内核当成 faijs 的公开 API——这正是要根除的混淆。改名只是换了张皮，因此聚合\n * 对象已整体删除，不再以任何名字存在。\n *\n * 要哪一层的实现，就从对应模块具名导入：\n * - `mesh/primitives`   box / sphere / cylinder / cone / wedge / screw / sdf\n * - `mesh/transform`    translate / rotate_euler / scale / scale3d / transformMatrix\n * - `mesh/boolean`      union / subtract / intersect\n * - `mesh/engrave`      engrave / knurl\n * - `mesh/query`        boundingBox / bboxCenter / volume / faceAt\n * - `mesh/io`           importFile / detectStepUnit\n * - `brep`、`brep/primitives-brep`  BREP（OCCT）路径\n *\n * 注意：脚本面的 `cad`（宿主经 `registerLib('cad', …)` 注入的 op 命名空间）与这一层\n * 是两回事——它不在这里，也不该被这里 import。见 AGENTS.md「库开发者 vs 脚本开发者」。\n */\n\n// ── 类型导出 ──\n\nexport type { Shape, Vec3, BoundingBox, FaceDescriptor } from './types'\nexport { guessStlUnit } from './stl-unit'\nexport type {\n  BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams,\n  TextParams, SvgExtrudeParams, SdfParams,\n  DrillParams, ExtrudeParams, EngraveParams, KnurlParams,\n  SplitPlane, SplitResult, DovetailSplitParams, DowelSplitParams, TenonSplitParams,\n} from './types'\n\n// BREP ops 类型导出\nexport type {\n  BrepChainState, DrillBrepParams, SplitBrepParams, SplitBrepResult,\n  ExtrudeBrepParams,\n} from '../brep'\nexport {\n  createBrepChainState, initBrepChainState, releaseBrepChainState,\n  solidToShape,\n  isCadFormat,\n} from '../brep'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mesh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAErC,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzC,4BAA4B;AAC5B,OAAO,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AAGlG,wBAAwB;AACxB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE7F,cAAc;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAEhC,cAAc;AACd,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElF,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,oBAAoB,EAAwB,MAAM,iBAAiB,CAAA;AACvG,OAAO,EAAE,iBAAiB,EAA6B,MAAM,sBAAsB,CAAA","sourcesContent":["/**\n * mesh — 纯数据几何内核（按模块组织的实现层）\n *\n * See docs/api-contract.md §1 (architecture layers) and §10 (api function catalog).\n *\n * 原则（§5.1）：\n * 1. 全部纯数据：输入输出是 Shape (ManifoldMeshData)，不碰 THREE 场景、不读 store\n * 2. 不可变：每个 API 返回新几何，不修改输入\n * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理\n * 4. 坐标系：右手系 +Z 向上、毫米、角度用度\n *\n * ⚠️ B3 补正（2026-10-06）：本文件不导出任何聚合对象（`cad` / `meshCad` 已删除）。\n * 要内核实现就从对应模块具名导入。门面层经 `export * from './mesh'` 消费。\n */\n\n// ── types ──\nexport type {\n  Shape, BoundingBox, FaceDescriptor,\n  BoxParams, SphereParams, CylinderParams, ConeParams, WedgeParams,\n  TextParams, SvgExtrudeParams, SdfParams,\n  DrillParams, ExtrudeParams, EngraveParams, KnurlParams,\n  SplitPlane, SplitResult, DovetailSplitParams, TenonSplitParams,\n} from './types'\nexport { NRAD_DEFAULT, NRAD_MIN, NRAD_MAX, clampNRad } from './types'\nexport { isMeshShape } from './types'\n\n// ── stl-unit ──\nexport { guessStlUnit } from './stl-unit'\n\n// ── decoration-provider ──\nexport { setEngraveDecorationProvider, getEngraveDecorationProvider } from './decoration-provider'\nexport type { EngraveDecorationProvider, EngraveDecorationParams } from './decoration-provider'\n\n// ── manifold-loader ──\nexport { setManifoldWasmUrl, getManifoldWasmUrl, getManifoldModule } from './manifold-loader'\n\n// ── query ──\nexport { faceAt } from './query'\n\n// ── knurl ──\nexport { applyKnurlDisplacement, KNURL_DEFAULTS } from './knurl/KnurlGenerator'\nexport type { KnurlBounds } from './knurl/KnurlGenerator'\nexport { subdivide } from './knurl/subdivision'\nexport { loadKnurlingTexture, setKnurlTextureLoader } from './knurl/textureLoader'\nexport type { TextureData } from './knurl/textureLoader'\nexport { QuantizedPointMap, weldVertices } from './knurl/meshIndex'\nexport { computeUV, MODE_TRIPLANAR, getCubicBlendWeights, type MappingSettings } from './knurl/mapping'\nexport { applyDisplacement, type DisplacementSettings } from './knurl/displacement'\n\n// ── import-model ──\nexport type {\n  ImportModel, ImportPart, ImportAssemblyNode, ImportBambuViews,\n} from './import-model'\n"]}

package/dist/mesh/io.d.ts

@@ -6,20 +6,29 @@
  * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。
  *
  * 单位换算边界（unit-system §5.2）：
- * - STL 无单位元数据 → 由 `opts.unit` 显式声明优先；未声明时 faijs 按历史
- *   host 行为做启发式猜测（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
- *   迁移回归的单位断言依赖此行为）。猜测收敛在 faijs 内（红线 R0：宿主不
- *   自实现单位换算），G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - 本模块只处理 **mesh 格式（STL/3MF）**，坐标可直接折算 → `opts.unit` 提供即
+ *   **强制设置模型的源单位**（直接指定，覆盖/忽略模型内部记录的单位——STL 无
+ *   内部单位、3MF `<model unit>` 声明被覆盖），按 `unitScale(unit)` 折算坐标。
+ *   它**只可能来自调用方的显式知识**（脚本作者手写 `cad.load({ file, unit })`、
+ *   或宿主让用户选定单位后传入）；调用方不知道单位时**必须省略**——省略时：
+ *   STL 走 faijs 启发式（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
+ *   迁移回归的单位断言依赖此行为）、3MF 走文件 `<model unit>`（无声明 →
+ *   millimeter）。猜测/折算收敛在 faijs 内（红线 R0：宿主不自实现单位换算），
+ *   G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - **STEP/.brep 不经过本模块**（走 BREP 链，load op 内 OCCT 读取）：OCCT 按
+ *   文件内部单位声明折算（SI_UNIT），**不支持强制设置单位**——load op 对
+ *   BREP 路径 + 用户显式 unit 直接**明确报错**（不缩放、不 workaround）。
  * - 3MF `<model unit>` 由解析器读取并换算（micron/mm/cm/inch/foot/meter）。
  *
  * 返回契约（unit-system §10.6）：`importFile` 返回 `{ shape, unit }` — `unit`
- * 是文件源单位（必然有值；faijs 是单一真源）：3MF/STEP 取文件声明（STEP 无声明
- * → 'mm'，与 OCCT 一致），STL 取 opts.unit 或 guessStlUnit 启发式猜测。坐标恒
- * 为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不参与几何
- * 缩放（读入折算已由内核/解析器完成，二次缩放 = 双重换算）。
+ * 是文件源单位（必然有值；faijs 是单一真源）：3MF 取 opts.unit（强制）或文件
+ * 声明（无声明 → millimeter），STL 取 opts.unit 或 guessStlUnit 启发式猜测。
+ * 坐标恒为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不
+ * 参与几何缩放（读入折算已由解析器完成，二次缩放 = 双重换算）。
  */
 import { type UnitName } from '../units.js';
 import type { Shape } from './types.js';
+import type { CompoundShape } from '../shape.js';
 import type { FileMeta } from '../api/meta.js';
 import type { ImportModel } from './import-model.js';
 /** Result of a unit-aware file import. */
@@ -33,8 +42,10 @@ export interface ImportFileResult {
     parts: Shape[];
     /**
      * The file's source unit (always present; faijs is the single source of truth).
-     * 3MF/STEP: the file's declared unit (STEP 无声明 → 'mm', 与 OCCT 一致).
-     * STL: opts.unit if declared, else the guessStlUnit heuristic result.
+     * 3MF: opts.unit (forced) if provided, else the file's declared unit
+     * (无声明 → millimeter). STL: opts.unit (forced) if provided, else the
+     * guessStlUnit heuristic result. STEP/BREP 不经过本模块（OCCT 链不支持
+     * 强制设置单位，load op 报错）。
      * Metadata only — coordinates are already in the faijs base unit (mm).
      */
     unit: UnitName;
@@ -54,6 +65,15 @@ export interface ImportFileResult {
      * 单/多零件均登记（单零件 parts 长度 1）。
      */
     importModel?: ImportModel;
+    /**
+     * 装配层级（方案 2026-10-08 §2.1 / 第 5 步「导入归一」）：当 3MF 含 `<components>`
+     * 装配结构时，按层级重建为 `CompoundShape`，每个子节点携带相对父的 `transform`
+     * （来自 3MF `<component transform>` / build `<item transform>`，行主序 3×4，平移在
+     * 末列，与写出器同源）。仅当存在真实装配（多 item 或任一 item 带 components）时存在；
+     * 单零件平铺导入不走它（`shape` / `parts` 已覆盖）。viewer 用 `parts`（已烘焙实例），
+     * 往返/层级消费者用 `assembly`（局部几何 + 节点 transform）。
+     */
+    assembly?: Shape | CompoundShape;
 }
 /**
  * Bounded scan window for `detectStepUnit`. Unit entities sit at the front of
@@ -88,10 +108,18 @@ export declare function detectStepUnit(stepText: string): UnitName | null;
  * @param buffer - the raw file bytes to parse (already decompressed; stpz
  *   unzipping is the caller's job — faijs never unzips implicitly).
  * @param format - format identifier such as 'stl', '3mf'/'threemf' or 'step'
- *   (defaults to 'stl').
- * @param opts - optional settings; `unit` (a UnitName string) declares the
- *   source unit for formats without unit metadata (e.g. STL). Defaults to
- *   the guessStlUnit heuristic when omitted.
+ *   (defaults to 'stl'). **仅 mesh 格式（STL/3MF）走本模块**；STEP/BREP 走
+ *   BREP 链（load op 内 OCCT 读取，不支持强制设置单位）。
+ * @param opts - optional settings; `unit` (a UnitName string) **force-sets the
+ *   model's source unit** (STL/3MF): it is NOT a default, it directly specifies
+ *   the unit and overrides/ignores any unit recorded inside the model (3MF
+ *   `<model unit>`; STL has none), geometry scaled by `unitScale(unit)`. Only
+ *   provide it when the caller actually knows the unit (author-written
+ *   `cad.load({ file, unit })`, or a host unit picker). When the caller does
+ *   NOT know the unit, it MUST omit `unit` — STL then guesses via
+ *   `guessStlUnit` (the only allowed guessing path), 3MF uses the file
+ *   declaration (none → millimeter). A wrong explicit unit scales geometry
+ *   wrongly and is never re-guessed.
  * @returns the shape with base-unit coordinates plus the file's source unit
  *   (`unit`, metadata only; always present — faijs is the single source of truth).
  */

package/dist/mesh/io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/mesh/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,KAAK,EAAE,CAAA;IACd;;;;;OAKG;IACH,IAAI,EAAE,QAAQ,CAAA;IACd;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqBhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA6F3B"}
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/mesh/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,KAAK,EAAE,CAAA;IACd;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,CAAA;IACd;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,aAAa,CAAA;CACjC;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqBhE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAiG3B"}

package/dist/mesh/io.js

@@ -6,20 +6,29 @@
  * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。
  *
  * 单位换算边界（unit-system §5.2）：
- * - STL 无单位元数据 → 由 `opts.unit` 显式声明优先；未声明时 faijs 按历史
- *   host 行为做启发式猜测（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
- *   迁移回归的单位断言依赖此行为）。猜测收敛在 faijs 内（红线 R0：宿主不
- *   自实现单位换算），G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - 本模块只处理 **mesh 格式（STL/3MF）**，坐标可直接折算 → `opts.unit` 提供即
+ *   **强制设置模型的源单位**（直接指定，覆盖/忽略模型内部记录的单位——STL 无
+ *   内部单位、3MF `<model unit>` 声明被覆盖），按 `unitScale(unit)` 折算坐标。
+ *   它**只可能来自调用方的显式知识**（脚本作者手写 `cad.load({ file, unit })`、
+ *   或宿主让用户选定单位后传入）；调用方不知道单位时**必须省略**——省略时：
+ *   STL 走 faijs 启发式（`guessStlUnit`，unified 方案 §6.1/§8 —— 3d_editor
+ *   迁移回归的单位断言依赖此行为）、3MF 走文件 `<model unit>`（无声明 →
+ *   millimeter）。猜测/折算收敛在 faijs 内（红线 R0：宿主不自实现单位换算），
+ *   G0 = 折算后坐标，渲染 = 拓扑 = G0。
+ * - **STEP/.brep 不经过本模块**（走 BREP 链，load op 内 OCCT 读取）：OCCT 按
+ *   文件内部单位声明折算（SI_UNIT），**不支持强制设置单位**——load op 对
+ *   BREP 路径 + 用户显式 unit 直接**明确报错**（不缩放、不 workaround）。
  * - 3MF `<model unit>` 由解析器读取并换算（micron/mm/cm/inch/foot/meter）。
  *
  * 返回契约（unit-system §10.6）：`importFile` 返回 `{ shape, unit }` — `unit`
- * 是文件源单位（必然有值；faijs 是单一真源）：3MF/STEP 取文件声明（STEP 无声明
- * → 'mm'，与 OCCT 一致），STL 取 opts.unit 或 guessStlUnit 启发式猜测。坐标恒
- * 为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不参与几何
- * 缩放（读入折算已由内核/解析器完成，二次缩放 = 双重换算）。
+ * 是文件源单位（必然有值；faijs 是单一真源）：3MF 取 opts.unit（强制）或文件
+ * 声明（无声明 → millimeter），STL 取 opts.unit 或 guessStlUnit 启发式猜测。
+ * 坐标恒为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不
+ * 参与几何缩放（读入折算已由解析器完成，二次缩放 = 双重换算）。
  */
 import { geoToManifoldMesh } from '../boolean/geo-convert.js';
 import { parseStl } from './stl-loader.js';
+import { boundingBox } from './query.js';
 import { parseThreemf } from './threemf-loader.js';
 import { parseBambu3mfFromEntries } from './threemf-bambu.js';
 import { unitScale } from '../units.js';
@@ -97,17 +106,25 @@ export function detectStepUnit(stepText) {
  * @param buffer - the raw file bytes to parse (already decompressed; stpz
  *   unzipping is the caller's job — faijs never unzips implicitly).
  * @param format - format identifier such as 'stl', '3mf'/'threemf' or 'step'
- *   (defaults to 'stl').
- * @param opts - optional settings; `unit` (a UnitName string) declares the
- *   source unit for formats without unit metadata (e.g. STL). Defaults to
- *   the guessStlUnit heuristic when omitted.
+ *   (defaults to 'stl'). **仅 mesh 格式（STL/3MF）走本模块**；STEP/BREP 走
+ *   BREP 链（load op 内 OCCT 读取，不支持强制设置单位）。
+ * @param opts - optional settings; `unit` (a UnitName string) **force-sets the
+ *   model's source unit** (STL/3MF): it is NOT a default, it directly specifies
+ *   the unit and overrides/ignores any unit recorded inside the model (3MF
+ *   `<model unit>`; STL has none), geometry scaled by `unitScale(unit)`. Only
+ *   provide it when the caller actually knows the unit (author-written
+ *   `cad.load({ file, unit })`, or a host unit picker). When the caller does
+ *   NOT know the unit, it MUST omit `unit` — STL then guesses via
+ *   `guessStlUnit` (the only allowed guessing path), 3MF uses the file
+ *   declaration (none → millimeter). A wrong explicit unit scales geometry
+ *   wrongly and is never re-guessed.
  * @returns the shape with base-unit coordinates plus the file's source unit
  *   (`unit`, metadata only; always present — faijs is the single source of truth).
  */
 export async function importFile(buffer, format, opts) {
     const fmt = (format ?? 'stl').toLowerCase();
     if (fmt === '3mf' || fmt === 'threemf') {
-        const archive = await parseThreemf(buffer);
+        const archive = await parseThreemf(buffer, opts);
         // P0（方案 §5.4）：不再折叠——返回全部 `<build><item>` 对象（declaration order，
         // 坐标已在 parseThreemf 里折算为 faijs 基准单位）。`shape` 保留为 parts[0]
         // （单零件兼容，过渡期）。
@@ -153,6 +170,11 @@ export async function importFile(buffer, format, opts) {
         const bambuViews = buildBambuViews(bambu);
         if (bambuViews)
             importModel.bambuViews = bambuViews;
+        // 装配层级重建（方案 §2.1 / 第 5 步）：含 `<components>` 时还原 CompoundShape，
+        // 叶节点携带相对父 transform；单零件平铺导入不挂载。
+        const assembly = archive.hierarchy && archive.localGeomById
+            ? buildAssemblyFromArchive(archive.hierarchy, archive.localGeomById)
+            : undefined;
         return {
             shape: parts[0],
             parts,
@@ -161,6 +183,7 @@ export async function importFile(buffer, format, opts) {
             importModel,
             // 整体级元数据（`<model><metadata>`）随导入结果上抛（方案 §5.1）。
             ...(archive.fileMeta ? { fileMeta: archive.fileMeta } : {}),
+            ...(assembly ? { assembly } : {}),
         };
     }
     if (fmt === 'stl') {
@@ -177,19 +200,17 @@ export async function importFile(buffer, format, opts) {
             scale = unitScale(declared);
         }
         else {
-            geo.computeBoundingBox();
-            const bb = geo.boundingBox;
-            if (bb) {
+            const bb = boundingBox(geo);
+            if (bb.min[0] !== Infinity) {
                 sourceUnit = guessStlUnit({
-                    min: [bb.min.x, bb.min.y, bb.min.z],
-                    max: [bb.max.x, bb.max.y, bb.max.z],
+                    min: [bb.min[0], bb.min[1], bb.min[2]],
+                    max: [bb.max[0], bb.max[1], bb.max[2]],
                 });
                 scale = unitScale(sourceUnit);
             }
         }
         if (scale !== 1) {
-            const attr = geo.getAttribute('position');
-            const arr = attr.array;
+            const arr = geo.positions;
             for (let i = 0; i < arr.length; i++)
                 arr[i] *= scale;
         }
@@ -226,6 +247,48 @@ function threemfObjectToShape(obj) {
         ...(obj.meta ? { meta: obj.meta } : {}),
     };
 }
+/**
+ * 由 3MF 装配层级重建 `CompoundShape`（方案 §2.1 / 第 5 步「导入归一」）。
+ *
+ * 见 `ThreemfArchive.hierarchy` / `localGeomById`：节点带**相对父**位姿（行主序 3×4，
+ * 平移在末列，与写出器 `transformToMatrix12` 同源）；几何来自 `localGeomById` 的**未烘焙**
+ * 局部网格。叶节点的最终 `Shape.transform` 即该相对位姿（写回 `Shape.transform`，供
+ * 后续导出按 3MF `<component transform>` 原样还原——D1 往返）。容器节点落为
+ * `CompoundShape`（不含 `transform` / `meta`，与 `shape.ts` 的 `CompoundShape` 形态一致）。
+ *
+ * 注：`shape.ts` 的 `CompoundShape.children` 当前声明为 `Shape[]`（非递归），故嵌套装配
+ * 在类型层面暂不表达；运行时子节点可为子 `CompoundShape`（由 `isCompoundLike` 结构判定消费）。
+ * 把 `CompoundShape` 改为递归类型是独立的后续重构（会波及 faijs-extra / cad-runtime），本步
+ * 以最小改动桥接——见下方 `children` 处的收窄断言。
+ *
+ * 仅在存在真实装配（多 item 或任一 item 带 components）时返回非空；单零件平铺导入返回
+ * `undefined`（由调用方决定是否挂载到 `result.assembly`，避免改变单零件结果形状）。
+ */
+function buildAssemblyFromArchive(hierarchy, localGeomById) {
+    const hasHierarchy = hierarchy.length > 1 || hierarchy.some((n) => (n.children?.length ?? 0) > 0);
+    if (!hasHierarchy)
+        return undefined;
+    const buildNode = (node) => {
+        const obj = localGeomById.get(node.objectId);
+        if (node.children && node.children.length > 0) {
+            // 收窄断言：共享 CompoundShape 非递归声明，运行时子节点可含子 CompoundShape。
+            return { kind: 'compound', children: node.children.map(buildNode) };
+        }
+        // 叶节点：局部几何 + 相对父位姿。
+        if (!obj || !obj.positions || !obj.indices) {
+            return { kind: 'compound', children: [] };
+        }
+        const leaf = threemfObjectToShape(obj);
+        if (node.transform) {
+            ;
+            leaf.transform = { matrix: Array.from(node.transform) };
+        }
+        return leaf;
+    };
+    return hierarchy.length === 1
+        ? buildNode(hierarchy[0])
+        : { kind: 'compound', children: hierarchy.map(buildNode) };
+}
 /** Bambu 显示视图数据 → ImportModel.bambuViews（无任何 Bambu 结构时省略）。 */
 function buildBambuViews(bambu) {
     const plates = [...bambu.plates.keys()].sort((a, b) => a - b);