@faicad/faijs 0.29.5 → 0.31.1

package/dist/lang/symbol-table.generated.js

@@ -45,6 +45,59 @@ export default {
     "revolve": {},
     "sweep": {},
     "loft": {},
+    "surface": {},
+    "offset2d": {},
+    "solidFromFaces": {},
+    "halfSpace": {},
+    "exportStl": {},
+    "exportBrep": {},
+    "exportStep": {},
+    "export3mf": {},
+    "isEdge": {},
+    "isFace": {},
+    "isShell": {},
+    "isVertex": {},
+    "isWire": {},
+    "isCompound": {},
+    "isCompSolid": {},
+    "isEqual": {},
+    "toSVG": {},
+    "toMultiviewSVG": {},
+    "toPNG": {},
+    "toMultiviewPNG": {},
+    "edge": {},
+    "circleArc": {},
+    "ellipseEdge": {},
+    "ellipseArc": {},
+    "tangentArc": {},
+    "approximatePoints": {},
+    "interpolateWithTangents": {},
+    "curveDegreeElevate": {},
+    "curveKnotInsert": {},
+    "curveKnotRemove": {},
+    "curveIsPeriodic": {},
+    "faceOnSurface": {},
+    "nonPlanarFace": {},
+    "makeSolid": {},
+    "reverseSurfaceU": {},
+    "outerWire": {},
+    "draftPrism": {},
+    "pipe": {},
+    "containsPoint": {},
+    "distanceBetween": {},
+    "inertia": {},
+    "linearCenterOfMass": {},
+    "projectPointOnEdge": {},
+    "projectPointOnFace": {},
+    "classifyPointOnFace": {},
+    "uvFromPoint": {},
+    "vertexPosition": {},
+    "subShapeCount": {},
+    "iterShapes": {},
+    "liftCurve2d": {},
+    "commonCells": {},
+    "boolean": {},
+    "alignTo": {},
     "faceNormal": {},
     "bboxCenter": {},
     "bboxMin": {},

package/dist/lang/symbol-table.generated.js.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-table.generated.js","sourceRoot":"","sources":["../../src/lang/symbol-table.generated.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAe;IACb,KAAK,EAAE,EAAE;IACT,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,eAAe,EAAE,EAAE;IACnB,cAAc,EAAE,EAAE;IAClB,WAAW,EAAE,EAAE;IACf,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,EAAE;IAClB,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,gBAAgB,EAAE,EAAE;IACpB,cAAc,EAAE,EAAE;IAClB,gBAAgB,EAAE,EAAE;IACpB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,EAAE;IAClB,iBAAiB,EAAE,EAAE;IACrB,KAAK,EAAE,EAAE;IACT,gBAAgB,EAAE,EAAE;IACpB,qBAAqB,EAAE,EAAE;IACzB,OAAO,EAAE,EAAE;IACX,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,EAAE;IAChB,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,EAAE;IACrB,mBAAmB,EAAE,EAAE;IACvB,cAAc,EAAE,EAAE;IAClB,OAAO,EAAE,EAAE;IACX,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,EAAE;IACd,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,EAAE;IACX,eAAe,EAAE,EAAE;IACnB,iBAAiB,EAAE,EAAE;IACrB,aAAa,EAAE,EAAE;IACjB,oBAAoB,EAAE,EAAE;IACxB,YAAY,EAAE,EAAE;IAChB,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,kBAAkB,EAAE,EAAE;IACtB,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,EAAE;IACZ,QAAQ,EAAE,EAAE;IACZ,cAAc,EAAE,EAAE;IAClB,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,EAAE;IACjB,cAAc,EAAE,EAAE;IAClB,gBAAgB,EAAE,EAAE;IACpB,cAAc,EAAE,EAAE;IAClB,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,QAAQ,EAAE,EAAE;IACZ,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,EAAE;IACZ,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,EAAE;IACjB,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,EAAE;IACZ,aAAa,EAAE,EAAE;IACjB,QAAQ,EAAE,EAAE;IACZ,QAAQ,EAAE,EAAE;IACZ,MAAM,EAAE,EAAE;IACV,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,EAAE;IACb,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,qBAAqB,EAAE,EAAE;CAC1B,CAAA","sourcesContent":["/**\n * symbol-table 生成文件 — 禁手改。\n * 由 scripts/gen-symbol-table.ts 从 api-namespace 的 cad 命名空间生成（键存在性）。\n * keep-syntax P1 后符号表只承载 check() 符号检查（\"函数不存在\"判定）；\n * 保留语义由 keep 声明表达，不再有 readonly 标注。\n */\nexport default {\n  \"box\": {},\n  \"sphere\": {},\n  \"cylinder\": {},\n  \"cone\": {},\n  \"wedge\": {},\n  \"screw\": {},\n  \"profile\": {},\n  \"sketchOnPlane\": {},\n  \"sketchOnFace\": {},\n  \"punchHole\": {},\n  \"wire\": {},\n  \"helix\": {},\n  \"sdf\": {},\n  \"translate\": {},\n  \"rotate_euler\": {},\n  \"scale\": {},\n  \"scale3d\": {},\n  \"engrave\": {},\n  \"chamfer\": {},\n  \"fillet\": {},\n  \"knurl\": {},\n  \"shell\": {},\n  \"draft\": {},\n  \"thicken\": {},\n  \"filletVariable\": {},\n  \"splitByPlane\": {},\n  \"sectionByPlane\": {},\n  \"defeature\": {},\n  \"reverseShape\": {},\n  \"unifySameDomain\": {},\n  \"sew\": {},\n  \"sewAndSolidify\": {},\n  \"removeHolesFromFace\": {},\n  \"union\": {},\n  \"subtract\": {},\n  \"intersect\": {},\n  \"extrude\": {},\n  \"revolve\": {},\n  \"sweep\": {},\n  \"loft\": {},\n  \"faceNormal\": {},\n  \"bboxCenter\": {},\n  \"bboxMin\": {},\n  \"bboxMax\": {},\n  \"edgeRef\": {},\n  \"faceRef\": {},\n  \"jointTrajectory\": {},\n  \"inverseKinematics\": {},\n  \"mechanismDOF\": {},\n  \"asset\": {},\n  \"import_brep\": {},\n  \"import_step\": {},\n  \"compound\": {},\n  \"place\": {},\n  \"cut\": {},\n  \"split\": {},\n  \"linearPattern\": {},\n  \"circularPattern\": {},\n  \"gridPattern\": {},\n  \"rectangularPattern\": {},\n  \"mirrorJoin\": {},\n  \"mirror\": {},\n  \"clone\": {},\n  \"torus\": {},\n  \"fuse\": {},\n  \"inspectMassProps\": {},\n  \"area\": {},\n  \"length\": {},\n  \"volume\": {},\n  \"centerOfMass\": {},\n  \"viewCamera\": {},\n  \"projectView\": {},\n  \"projectSheet\": {},\n  \"complexExtrude\": {},\n  \"twistExtrude\": {},\n  \"roof\": {},\n  \"drill\": {},\n  \"pocket\": {},\n  \"boss\": {},\n  \"thread\": {},\n  \"convexHull\": {},\n  \"makeBaseBox\": {},\n  \"ellipsoid\": {},\n  \"rotate\": {},\n  \"applyMatrix\": {},\n  \"locate\": {},\n  \"offset\": {},\n  \"heal\": {},\n  \"simplify\": {},\n  \"isValid\": {},\n  \"isSameShape\": {},\n  \"autoHeal\": {},\n  \"fixShape\": {},\n  \"healSolid\": {},\n  \"fixSelfIntersection\": {}\n}\n"]}
+{"version":3,"file":"symbol-table.generated.js","sourceRoot":"","sources":["../../src/lang/symbol-table.generated.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * symbol-table 生成文件 — 禁手改。\n * 由 scripts/gen-symbol-table.ts 从 api-namespace 的 cad 命名空间生成（键存在性）。\n * keep-syntax P1 后符号表只承载 check() 符号检查（\"函数不存在\"判定）；\n * 保留语义由 keep 声明表达，不再有 readonly 标注。\n */\nexport default {\n  \"box\": {},\n  \"sphere\": {},\n  \"cylinder\": {},\n  \"cone\": {},\n  \"wedge\": {},\n  \"screw\": {},\n  \"profile\": {},\n  \"sketchOnPlane\": {},\n  \"sketchOnFace\": {},\n  \"punchHole\": {},\n  \"wire\": {},\n  \"helix\": {},\n  \"sdf\": {},\n  \"translate\": {},\n  \"rotate_euler\": {},\n  \"scale\": {},\n  \"scale3d\": {},\n  \"engrave\": {},\n  \"chamfer\": {},\n  \"fillet\": {},\n  \"knurl\": {},\n  \"shell\": {},\n  \"draft\": {},\n  \"thicken\": {},\n  \"filletVariable\": {},\n  \"splitByPlane\": {},\n  \"sectionByPlane\": {},\n  \"defeature\": {},\n  \"reverseShape\": {},\n  \"unifySameDomain\": {},\n  \"sew\": {},\n  \"sewAndSolidify\": {},\n  \"removeHolesFromFace\": {},\n  \"union\": {},\n  \"subtract\": {},\n  \"intersect\": {},\n  \"extrude\": {},\n  \"revolve\": {},\n  \"sweep\": {},\n  \"loft\": {},\n  \"surface\": {},\n  \"offset2d\": {},\n  \"solidFromFaces\": {},\n  \"halfSpace\": {},\n  \"exportStl\": {},\n  \"exportBrep\": {},\n  \"exportStep\": {},\n  \"export3mf\": {},\n  \"isEdge\": {},\n  \"isFace\": {},\n  \"isShell\": {},\n  \"isVertex\": {},\n  \"isWire\": {},\n  \"isCompound\": {},\n  \"isCompSolid\": {},\n  \"isEqual\": {},\n  \"toSVG\": {},\n  \"toMultiviewSVG\": {},\n  \"toPNG\": {},\n  \"toMultiviewPNG\": {},\n  \"edge\": {},\n  \"circleArc\": {},\n  \"ellipseEdge\": {},\n  \"ellipseArc\": {},\n  \"tangentArc\": {},\n  \"approximatePoints\": {},\n  \"interpolateWithTangents\": {},\n  \"curveDegreeElevate\": {},\n  \"curveKnotInsert\": {},\n  \"curveKnotRemove\": {},\n  \"curveIsPeriodic\": {},\n  \"faceOnSurface\": {},\n  \"nonPlanarFace\": {},\n  \"makeSolid\": {},\n  \"reverseSurfaceU\": {},\n  \"outerWire\": {},\n  \"draftPrism\": {},\n  \"pipe\": {},\n  \"containsPoint\": {},\n  \"distanceBetween\": {},\n  \"inertia\": {},\n  \"linearCenterOfMass\": {},\n  \"projectPointOnEdge\": {},\n  \"projectPointOnFace\": {},\n  \"classifyPointOnFace\": {},\n  \"uvFromPoint\": {},\n  \"vertexPosition\": {},\n  \"subShapeCount\": {},\n  \"iterShapes\": {},\n  \"liftCurve2d\": {},\n  \"commonCells\": {},\n  \"boolean\": {},\n  \"alignTo\": {},\n  \"faceNormal\": {},\n  \"bboxCenter\": {},\n  \"bboxMin\": {},\n  \"bboxMax\": {},\n  \"edgeRef\": {},\n  \"faceRef\": {},\n  \"jointTrajectory\": {},\n  \"inverseKinematics\": {},\n  \"mechanismDOF\": {},\n  \"asset\": {},\n  \"import_brep\": {},\n  \"import_step\": {},\n  \"compound\": {},\n  \"place\": {},\n  \"cut\": {},\n  \"split\": {},\n  \"linearPattern\": {},\n  \"circularPattern\": {},\n  \"gridPattern\": {},\n  \"rectangularPattern\": {},\n  \"mirrorJoin\": {},\n  \"mirror\": {},\n  \"clone\": {},\n  \"torus\": {},\n  \"fuse\": {},\n  \"inspectMassProps\": {},\n  \"area\": {},\n  \"length\": {},\n  \"volume\": {},\n  \"centerOfMass\": {},\n  \"viewCamera\": {},\n  \"projectView\": {},\n  \"projectSheet\": {},\n  \"complexExtrude\": {},\n  \"twistExtrude\": {},\n  \"roof\": {},\n  \"drill\": {},\n  \"pocket\": {},\n  \"boss\": {},\n  \"thread\": {},\n  \"convexHull\": {},\n  \"makeBaseBox\": {},\n  \"ellipsoid\": {},\n  \"rotate\": {},\n  \"applyMatrix\": {},\n  \"locate\": {},\n  \"offset\": {},\n  \"heal\": {},\n  \"simplify\": {},\n  \"isValid\": {},\n  \"isSameShape\": {},\n  \"autoHeal\": {},\n  \"fixShape\": {},\n  \"healSolid\": {},\n  \"fixSelfIntersection\": {}\n}\n"]}

package/dist/mesh/import-model.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ImportModel — 一次文件导入的完整结构数据（非几何）。
+ *
+ * 方案 2026-10-06-step-3mf-multipart-import-plan.md §5.1：
+ * - `ImportModel` 描述「一次导入」的零件身份表 + 装配层级 + 文件元数据；
+ * - 与 `compounds` / `detectedUnits` 同层，不进 `.fai.js`、不参与几何运算、
+ *   不影响确定性（内容由文件决定）；
+ * - 几何由 `cad.load` 返回的 Shape（单零件）或 CompoundShape.children
+ *   （多零件，children 序 = `parts.index` 一一对应）承载。
+ *
+ * R5 边界（显示/导出判别，衔接草图方案）：`ImportPart.exportable` 默认 true；
+ * 仅显示几何（草图等）由草图方案置 false——宿主「导出依据场景树」红线据此过滤。
+ */
+import type { UnitName } from '../units.js';
+import type { FileMeta, ShapeMeta } from '../api/meta.js';
+/** 一次导入中的一个零件（身份数据；几何在 Shape/CompoundShape.children 对应下标）。 */
+export interface ImportPart {
+    /** 零件在本次导入中的序号（0 起，等于 load 返回 compound.children 的下标）。 */
+    index: number;
+    /** 零件名（STEP XCAF label / 3MF `<object name>`；无则回退 `imported:<index>`）。 */
+    name: string;
+    /** 显示色 sRGB 0..1（STEP STYLED_ITEM / 3MF basematerials）。 */
+    color?: [number, number, number];
+    /** 3MF `<object id>`（Bambu 视图变换查表键）。 */
+    objectId?: string;
+    /** Bambu part id（`objectId:partId` 查 importTransforms 键；经父 object components 关联）。 */
+    partId?: string;
+    /** Bambu 盘号（多盘分组依据）。 */
+    plateId?: number;
+    /** Bambu 挤出机序号（1 起）。 */
+    extruder?: number;
+    /** 零件级说明性元数据（复用 ShapeMeta）。 */
+    meta?: ShapeMeta;
+    /** 是否可导出（R5）：默认 true；仅显示几何（草图等）由草图方案置 false。 */
+    exportable?: boolean;
+}
+/** STEP 装配层级节点（XCAF 树 / syntheticGroup 合成节点；DFS 序与 parts 顺序一致）。 */
+export interface ImportAssemblyNode {
+    name: string;
+    /** 叶节点：指向 parts 下标。 */
+    partIndex?: number;
+    /** 装配/合成节点：子节点（DFS 序与 parts 顺序一致）。 */
+    children?: ImportAssemblyNode[];
+}
+/** Bambu 显示视图数据（仅 3MF）：多盘布局 / print·assembly·import 视图 delta。
+ *  显示通道删除后宿主不再解析 3mf archive，视图数据必须由 faijs 结果承载。
+ *  字段覆盖宿主（ModelGroup view delta / 多盘布局 / 挤出机材质）的完整消费面，
+ *  宿主经 `bambuViewsToMetadata` 重建 Bambu3mfMetadata 时无需再回读 archive。 */
+export interface ImportBambuViews {
+    /** 盘号列表（升序、去重）。 */
+    plates: number[];
+    /** `<assemble>` 装配视图位姿（键 = objectId）。 */
+    assembleTransforms?: Record<string, {
+        transform: number[];
+        offset: [number, number, number];
+    }>;
+    /** per-part 导入位姿（键 = `objectId:partId`）。 */
+    importTransforms?: Record<string, {
+        matrix: number[];
+        sourceOffset: [number, number, number];
+    }>;
+    /** `<build>` 打印视图 item 表（print 布局位姿判定用）。 */
+    buildItems?: Array<{
+        objectId: string;
+        transform: number[] | null;
+    }>;
+    /** 挤出机颜色表（下标 = extruder-1，材质继承用）。 */
+    filamentColors?: string[];
+    filamentTypes?: string[];
+    /** per-part 身份表（序 = ImportModel.parts = compound.children；view delta 键匹配用）。 */
+    parts?: Array<{
+        partIndex: number;
+        objectId: string;
+        partId: string;
+        name: string;
+        extruder: number;
+        plateId: number;
+    }>;
+}
+/** 一次文件导入的完整结构产物。 */
+export interface ImportModel {
+    format: 'step' | '3mf' | 'stl' | 'brep';
+    /** 文件声明单位（元数据；坐标已是基准值）。 */
+    unit: UnitName | null;
+    /** 整体级元数据（文件级；无声明则省略）。 */
+    fileMeta?: FileMeta;
+    /** 零件表，顺序与 load 返回 compound.children 一致（单零件时长度 1）。 */
+    parts: ImportPart[];
+    /** STEP 装配层级（XCAF 树）；无装配结构时省略。 */
+    assembly?: ImportAssemblyNode;
+    /** Bambu 显示视图数据（仅 3MF）。 */
+    bambuViews?: ImportBambuViews;
+}
+//# sourceMappingURL=import-model.d.ts.map

package/dist/mesh/import-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-model.d.ts","sourceRoot":"","sources":["../../src/mesh/import-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAChC;AAED;;;qEAGqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,yCAAyC;IACzC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAA;IAC9F,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAA;IAC/F,4CAA4C;IAC5C,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IACpE,qCAAqC;IACrC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;KAChB,CAAC,CAAA;CACH;AAED,qBAAqB;AACrB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IACvC,2BAA2B;IAC3B,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IACrB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,sDAAsD;IACtD,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,2BAA2B;IAC3B,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B"}

package/dist/mesh/import-model.js

@@ -0,0 +1,15 @@
+/**
+ * ImportModel — 一次文件导入的完整结构数据（非几何）。
+ *
+ * 方案 2026-10-06-step-3mf-multipart-import-plan.md §5.1：
+ * - `ImportModel` 描述「一次导入」的零件身份表 + 装配层级 + 文件元数据；
+ * - 与 `compounds` / `detectedUnits` 同层，不进 `.fai.js`、不参与几何运算、
+ *   不影响确定性（内容由文件决定）；
+ * - 几何由 `cad.load` 返回的 Shape（单零件）或 CompoundShape.children
+ *   （多零件，children 序 = `parts.index` 一一对应）承载。
+ *
+ * R5 边界（显示/导出判别，衔接草图方案）：`ImportPart.exportable` 默认 true；
+ * 仅显示几何（草图等）由草图方案置 false——宿主「导出依据场景树」红线据此过滤。
+ */
+export {};
+//# sourceMappingURL=import-model.js.map

package/dist/mesh/import-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-model.js","sourceRoot":"","sources":["../../src/mesh/import-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * ImportModel — 一次文件导入的完整结构数据（非几何）。\n *\n * 方案 2026-10-06-step-3mf-multipart-import-plan.md §5.1：\n * - `ImportModel` 描述「一次导入」的零件身份表 + 装配层级 + 文件元数据；\n * - 与 `compounds` / `detectedUnits` 同层，不进 `.fai.js`、不参与几何运算、\n *   不影响确定性（内容由文件决定）；\n * - 几何由 `cad.load` 返回的 Shape（单零件）或 CompoundShape.children\n *   （多零件，children 序 = `parts.index` 一一对应）承载。\n *\n * R5 边界（显示/导出判别，衔接草图方案）：`ImportPart.exportable` 默认 true；\n * 仅显示几何（草图等）由草图方案置 false——宿主「导出依据场景树」红线据此过滤。\n */\n\nimport type { UnitName } from '../units'\nimport type { FileMeta, ShapeMeta } from '../api/meta'\n\n/** 一次导入中的一个零件（身份数据；几何在 Shape/CompoundShape.children 对应下标）。 */\nexport interface ImportPart {\n  /** 零件在本次导入中的序号（0 起，等于 load 返回 compound.children 的下标）。 */\n  index: number\n  /** 零件名（STEP XCAF label / 3MF `<object name>`；无则回退 `imported:<index>`）。 */\n  name: string\n  /** 显示色 sRGB 0..1（STEP STYLED_ITEM / 3MF basematerials）。 */\n  color?: [number, number, number]\n  /** 3MF `<object id>`（Bambu 视图变换查表键）。 */\n  objectId?: string\n  /** Bambu part id（`objectId:partId` 查 importTransforms 键；经父 object components 关联）。 */\n  partId?: string\n  /** Bambu 盘号（多盘分组依据）。 */\n  plateId?: number\n  /** Bambu 挤出机序号（1 起）。 */\n  extruder?: number\n  /** 零件级说明性元数据（复用 ShapeMeta）。 */\n  meta?: ShapeMeta\n  /** 是否可导出（R5）：默认 true；仅显示几何（草图等）由草图方案置 false。 */\n  exportable?: boolean\n}\n\n/** STEP 装配层级节点（XCAF 树 / syntheticGroup 合成节点；DFS 序与 parts 顺序一致）。 */\nexport interface ImportAssemblyNode {\n  name: string\n  /** 叶节点：指向 parts 下标。 */\n  partIndex?: number\n  /** 装配/合成节点：子节点（DFS 序与 parts 顺序一致）。 */\n  children?: ImportAssemblyNode[]\n}\n\n/** Bambu 显示视图数据（仅 3MF）：多盘布局 / print·assembly·import 视图 delta。\n *  显示通道删除后宿主不再解析 3mf archive，视图数据必须由 faijs 结果承载。\n *  字段覆盖宿主（ModelGroup view delta / 多盘布局 / 挤出机材质）的完整消费面，\n *  宿主经 `bambuViewsToMetadata` 重建 Bambu3mfMetadata 时无需再回读 archive。 */\nexport interface ImportBambuViews {\n  /** 盘号列表（升序、去重）。 */\n  plates: number[]\n  /** `<assemble>` 装配视图位姿（键 = objectId）。 */\n  assembleTransforms?: Record<string, { transform: number[]; offset: [number, number, number] }>\n  /** per-part 导入位姿（键 = `objectId:partId`）。 */\n  importTransforms?: Record<string, { matrix: number[]; sourceOffset: [number, number, number] }>\n  /** `<build>` 打印视图 item 表（print 布局位姿判定用）。 */\n  buildItems?: Array<{ objectId: string; transform: number[] | null }>\n  /** 挤出机颜色表（下标 = extruder-1，材质继承用）。 */\n  filamentColors?: string[]\n  filamentTypes?: string[]\n  /** per-part 身份表（序 = ImportModel.parts = compound.children；view delta 键匹配用）。 */\n  parts?: Array<{\n    partIndex: number\n    objectId: string\n    partId: string\n    name: string\n    extruder: number\n    plateId: number\n  }>\n}\n\n/** 一次文件导入的完整结构产物。 */\nexport interface ImportModel {\n  format: 'step' | '3mf' | 'stl' | 'brep'\n  /** 文件声明单位（元数据；坐标已是基准值）。 */\n  unit: UnitName | null\n  /** 整体级元数据（文件级；无声明则省略）。 */\n  fileMeta?: FileMeta\n  /** 零件表，顺序与 load 返回 compound.children 一致（单零件时长度 1）。 */\n  parts: ImportPart[]\n  /** STEP 装配层级（XCAF 树）；无装配结构时省略。 */\n  assembly?: ImportAssemblyNode\n  /** Bambu 显示视图数据（仅 3MF）。 */\n  bambuViews?: ImportBambuViews\n}\n"]}

package/dist/mesh/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * mesh — 纯数据几何 API 统一入口
+ * mesh — 纯数据几何内核（按模块组织的实现层）
  *
  * See docs/api-contract.md §1 (architecture layers) and §10 (api function catalog).
  *
@@ -9,68 +9,24 @@
  * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理
  * 4. 坐标系：右手系 +Z 向上、毫米、角度用度
  *
- * P1 阶段：mesh 是对现有纯函数的薄包装层，行为完全不变。
- * P3+ 阶段：mesh 将由 ScriptEngine 驱动，在 worker 中执行。
+ * ⚠️ B3 补正（2026-10-06）：本文件不导出任何聚合对象（`cad` / `meshCad` 已删除）。
+ * 要内核实现就从对应模块具名导入。门面层经 `export * from './mesh.js'` 消费。
  */
-import * as primitives from './primitives.js';
-import * as brepPrimitives from '../brep/primitives-brep.js';
-import * as brepOps from '../brep/index.js';
-import * as booleanOps from './boolean.js';
-import * as engraveOps from './engrave.js';
-import * as transformOps from './transform.js';
-import * as queryOps from './query.js';
-import * as ioOps from './io.js';
-/**
- * Unified `cad` API object aggregating the pure-data mesh operations: mesh and
- * BREP primitives, transforms, booleans, engrave/knurl, geometry queries, file
- * IO, and BREP feature operations.
- *
- * D1（2026-09-23 扩展库拆分）：`text` / `svgExtrude` / `fai_*` 键已随
- * `@faicad/faijs-extra` 迁出——它们的实现在扩展库的 mesh 面（`editorCad`）。
- */
-export declare const cad: {
-    box: typeof primitives.box;
-    sphere: typeof primitives.sphere;
-    cylinder: typeof primitives.cylinder;
-    cone: typeof primitives.cone;
-    wedge: typeof primitives.wedge;
-    screw: typeof primitives.screw;
-    sdf: typeof primitives.sdf;
-    boxBrep: typeof brepPrimitives.boxBrep;
-    sphereBrep: typeof brepPrimitives.sphereBrep;
-    cylinderBrep: typeof brepPrimitives.cylinderBrep;
-    coneBrep: typeof brepPrimitives.coneBrep;
-    wedgeBrep: typeof brepPrimitives.wedgeBrep;
-    translate: typeof transformOps.translate;
-    rotate_euler: typeof transformOps.rotate_euler;
-    scale: typeof transformOps.scale;
-    scale3d: typeof transformOps.scale3d;
-    transformMatrix: typeof transformOps.transformMatrix;
-    union: typeof booleanOps.union;
-    subtract: typeof booleanOps.subtract;
-    intersect: typeof booleanOps.intersect;
-    engrave: typeof engraveOps.engrave;
-    knurl: typeof engraveOps.knurl;
-    boundingBox: typeof queryOps.boundingBox;
-    bboxCenter: typeof queryOps.bboxCenter;
-    volume: typeof queryOps.volume;
-    faceAt: typeof queryOps.faceAt;
-    load: typeof ioOps.importFile;
-    translateBrep: typeof brepOps.translateBrep;
-    rotateBrep: typeof brepOps.rotateBrep;
-    scaleBrep: typeof brepOps.scaleBrep;
-    fuseBrep: typeof brepOps.fuseBrep;
-    cutBrep: typeof brepOps.cutBrep;
-    commonBrep: typeof brepOps.commonBrep;
-    drillBrep: typeof brepOps.drillBrep;
-    splitBrep: typeof brepOps.splitBrep;
-    extrudeBrep: typeof brepOps.extrudeBrep;
-    loadBrep: typeof brepOps.loadBrep;
-    solidToShape: typeof brepOps.solidToShape;
-};
-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;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,UAAU,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,cAAc,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,UAAU,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,YAAY,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,QAAQ,MAAM,SAAS,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,MAAM,CAAA;AAI7B;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0Df,CAAA;AAID,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

@@ -1,5 +1,5 @@
 /**
- * mesh — 纯数据几何 API 统一入口
+ * mesh — 纯数据几何内核（按模块组织的实现层）
  *
  * See docs/api-contract.md §1 (architecture layers) and §10 (api function catalog).
  *
@@ -9,77 +9,24 @@
  * 3. 同步签名、异步执行：API 签名同步（或 async）；worker 边界由 ScriptEngine 处理
  * 4. 坐标系：右手系 +Z 向上、毫米、角度用度
  *
- * P1 阶段：mesh 是对现有纯函数的薄包装层，行为完全不变。
- * P3+ 阶段：mesh 将由 ScriptEngine 驱动，在 worker 中执行。
+ * ⚠️ B3 补正（2026-10-06）：本文件不导出任何聚合对象（`cad` / `meshCad` 已删除）。
+ * 要内核实现就从对应模块具名导入。门面层经 `export * from './mesh.js'` 消费。
  */
-import * as primitives from './primitives.js';
-import * as brepPrimitives from '../brep/primitives-brep.js';
-import * as brepOps from '../brep/index.js';
-import * as booleanOps from './boolean.js';
-import * as engraveOps from './engrave.js';
-import * as transformOps from './transform.js';
-import * as queryOps from './query.js';
-import * as ioOps from './io.js';
-// ── 统一 cad API 对象 ──
-/**
- * Unified `cad` API object aggregating the pure-data mesh operations: mesh and
- * BREP primitives, transforms, booleans, engrave/knurl, geometry queries, file
- * IO, and BREP feature operations.
- *
- * D1（2026-09-23 扩展库拆分）：`text` / `svgExtrude` / `fai_*` 键已随
- * `@faicad/faijs-extra` 迁出——它们的实现在扩展库的 mesh 面（`editorCad`）。
- */
-export const cad = {
-    // 创建（mesh 路径）
-    box: primitives.box,
-    sphere: primitives.sphere,
-    cylinder: primitives.cylinder,
-    cone: primitives.cone,
-    wedge: primitives.wedge,
-    screw: primitives.screw,
-    sdf: primitives.sdf,
-    // 创建（BREP 路径 — OCCT 精确实体三角化）
-    boxBrep: brepPrimitives.boxBrep,
-    sphereBrep: brepPrimitives.sphereBrep,
-    cylinderBrep: brepPrimitives.cylinderBrep,
-    coneBrep: brepPrimitives.coneBrep,
-    wedgeBrep: brepPrimitives.wedgeBrep,
-    // 变换
-    translate: transformOps.translate,
-    rotate_euler: transformOps.rotate_euler,
-    scale: transformOps.scale,
-    scale3d: transformOps.scale3d,
-    transformMatrix: transformOps.transformMatrix,
-    // 布尔
-    union: booleanOps.union,
-    subtract: booleanOps.subtract,
-    intersect: booleanOps.intersect,
-    // 分割
-    // `fai_*` 键（编辑器消费面）已随扩展库迁出：@faicad/faijs-extra 的 mesh 面
-    // 经 `mesh/fai_split.ts` / `mesh/fai_drill.ts` / `mesh/fai_extrude.ts` 提供。
-    // 雕刻
-    engrave: engraveOps.engrave,
-    knurl: engraveOps.knurl,
-    // 查询
-    boundingBox: queryOps.boundingBox,
-    bboxCenter: queryOps.bboxCenter,
-    volume: queryOps.volume,
-    faceAt: queryOps.faceAt,
-    // IO
-    load: ioOps.importFile,
-    // BREP 特征操作（Phase 2 — OCCT 精确实体运算）
-    translateBrep: brepOps.translateBrep,
-    rotateBrep: brepOps.rotateBrep,
-    scaleBrep: brepOps.scaleBrep,
-    fuseBrep: brepOps.fuseBrep,
-    cutBrep: brepOps.cutBrep,
-    commonBrep: brepOps.commonBrep,
-    drillBrep: brepOps.drillBrep,
-    splitBrep: brepOps.splitBrep,
-    extrudeBrep: brepOps.extrudeBrep,
-    loadBrep: brepOps.loadBrep,
-    solidToShape: brepOps.solidToShape,
-};
+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;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,UAAU,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,cAAc,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,UAAU,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,YAAY,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,QAAQ,MAAM,SAAS,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,MAAM,CAAA;AAE7B,sBAAsB;AAEtB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,cAAc;IACd,GAAG,EAAE,UAAU,CAAC,GAAG;IACnB,MAAM,EAAE,UAAU,CAAC,MAAM;IACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;IAC7B,IAAI,EAAE,UAAU,CAAC,IAAI;IACrB,KAAK,EAAE,UAAU,CAAC,KAAK;IACvB,KAAK,EAAE,UAAU,CAAC,KAAK;IACvB,GAAG,EAAE,UAAU,CAAC,GAAG;IAEnB,6BAA6B;IAC7B,OAAO,EAAE,cAAc,CAAC,OAAO;IAC/B,UAAU,EAAE,cAAc,CAAC,UAAU;IACrC,YAAY,EAAE,cAAc,CAAC,YAAY;IACzC,QAAQ,EAAE,cAAc,CAAC,QAAQ;IACjC,SAAS,EAAE,cAAc,CAAC,SAAS;IAEnC,KAAK;IACL,SAAS,EAAE,YAAY,CAAC,SAAS;IACjC,YAAY,EAAE,YAAY,CAAC,YAAY;IACvC,KAAK,EAAE,YAAY,CAAC,KAAK;IACzB,OAAO,EAAE,YAAY,CAAC,OAAO;IAC7B,eAAe,EAAE,YAAY,CAAC,eAAe;IAE7C,KAAK;IACL,KAAK,EAAE,UAAU,CAAC,KAAK;IACvB,QAAQ,EAAE,UAAU,CAAC,QAAQ;IAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;IAE/B,KAAK;IACL,wDAAwD;IACxD,0EAA0E;IAE1E,KAAK;IACL,OAAO,EAAE,UAAU,CAAC,OAAO;IAC3B,KAAK,EAAE,UAAU,CAAC,KAAK;IAEvB,KAAK;IACL,WAAW,EAAE,QAAQ,CAAC,WAAW;IACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;IAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM;IACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;IAEvB,KAAK;IACL,IAAI,EAAE,KAAK,CAAC,UAAU;IAEtB,mCAAmC;IACnC,aAAa,EAAE,OAAO,CAAC,aAAa;IACpC,UAAU,EAAE,OAAO,CAAC,UAAU;IAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;IAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,UAAU,EAAE,OAAO,CAAC,UAAU;IAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;IAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;IAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;IAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;CACnC,CAAA;AAKD,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 — 纯数据几何 API 统一入口\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 * P1 阶段：mesh 是对现有纯函数的薄包装层，行为完全不变。\n * P3+ 阶段：mesh 将由 ScriptEngine 驱动，在 worker 中执行。\n */\n\nimport * as primitives from './primitives'\nimport * as brepPrimitives from '../brep/primitives-brep'\nimport * as brepOps from '../brep'\nimport * as booleanOps from './boolean'\nimport * as engraveOps from './engrave'\nimport * as transformOps from './transform'\nimport * as queryOps from './query'\nimport * as ioOps from './io'\n\n// ── 统一 cad API 对象 ──\n\n/**\n * Unified `cad` API object aggregating the pure-data mesh operations: mesh and\n * BREP primitives, transforms, booleans, engrave/knurl, geometry queries, file\n * IO, and BREP feature operations.\n *\n * D1（2026-09-23 扩展库拆分）：`text` / `svgExtrude` / `fai_*` 键已随\n * `@faicad/faijs-extra` 迁出——它们的实现在扩展库的 mesh 面（`editorCad`）。\n */\nexport const cad = {\n  // 创建（mesh 路径）\n  box: primitives.box,\n  sphere: primitives.sphere,\n  cylinder: primitives.cylinder,\n  cone: primitives.cone,\n  wedge: primitives.wedge,\n  screw: primitives.screw,\n  sdf: primitives.sdf,\n\n  // 创建（BREP 路径 — OCCT 精确实体三角化）\n  boxBrep: brepPrimitives.boxBrep,\n  sphereBrep: brepPrimitives.sphereBrep,\n  cylinderBrep: brepPrimitives.cylinderBrep,\n  coneBrep: brepPrimitives.coneBrep,\n  wedgeBrep: brepPrimitives.wedgeBrep,\n\n  // 变换\n  translate: transformOps.translate,\n  rotate_euler: transformOps.rotate_euler,\n  scale: transformOps.scale,\n  scale3d: transformOps.scale3d,\n  transformMatrix: transformOps.transformMatrix,\n\n  // 布尔\n  union: booleanOps.union,\n  subtract: booleanOps.subtract,\n  intersect: booleanOps.intersect,\n\n  // 分割\n  // `fai_*` 键（编辑器消费面）已随扩展库迁出：@faicad/faijs-extra 的 mesh 面\n  // 经 `mesh/fai_split.ts` / `mesh/fai_drill.ts` / `mesh/fai_extrude.ts` 提供。\n\n  // 雕刻\n  engrave: engraveOps.engrave,\n  knurl: engraveOps.knurl,\n\n  // 查询\n  boundingBox: queryOps.boundingBox,\n  bboxCenter: queryOps.bboxCenter,\n  volume: queryOps.volume,\n  faceAt: queryOps.faceAt,\n\n  // IO\n  load: ioOps.importFile,\n\n  // BREP 特征操作（Phase 2 — OCCT 精确实体运算）\n  translateBrep: brepOps.translateBrep,\n  rotateBrep: brepOps.rotateBrep,\n  scaleBrep: brepOps.scaleBrep,\n  fuseBrep: brepOps.fuseBrep,\n  cutBrep: brepOps.cutBrep,\n  commonBrep: brepOps.commonBrep,\n  drillBrep: brepOps.drillBrep,\n  splitBrep: brepOps.splitBrep,\n  extrudeBrep: brepOps.extrudeBrep,\n  loadBrep: brepOps.loadBrep,\n  solidToShape: brepOps.solidToShape,\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,31 +6,53 @@
  * 坐标永远以 faijs 基准长度单位（mm）存储 — Shape 不贴 unit 标签（D3）。
  *
  * 单位换算边界（unit-system §5.2）：
- * - STL 无单位元数据 → 由 `opts.unit` 显式声明，缺省 mm，不做启发式猜测。
+ * - 本模块只处理 **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`
- * 是文件**自己声明的单位**（3MF `<model unit>`、STEP 单位实体），无声明格式
- * （STL）为 null（此时 `opts.unit` 决定刻度）。坐标恒为基准值 — `unit` 只作
- * 元数据（sourceUnit 记录、导出目标判定），绝不参与几何缩放（读入折算已由
- * 内核/解析器完成，二次缩放 = 双重换算）。
+ * 是文件源单位（必然有值；faijs 是单一真源）：3MF 取 opts.unit（强制）或文件
+ * 声明（无声明 → millimeter），STL 取 opts.unit 或 guessStlUnit 启发式猜测。
+ * 坐标恒为基准值 — `unit` 只作元数据（sourceUnit 记录、导出目标判定），绝不
+ * 参与几何缩放（读入折算已由解析器完成，二次缩放 = 双重换算）。
  */
-import { type UnitName, type ValueWithUnits } from '../units.js';
+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. */
 export interface ImportFileResult {
     shape: Shape;
     /**
-     * The unit the file itself declares (3MF `<model unit>`, STEP unit entities).
-     * null for declaration-less formats (STL) — the caller's opts.unit decided.
+     * All parts the file declared, in declaration order (3MF `<build><item>` 序 /
+     * STL 单零件)。`shape` is `parts[0]`（单零件兼容，过渡期）。
+     * P0（2026-10-06-step-3mf-multipart-import-plan.md §5.4）：多对象 3MF 不再折叠。
      */
-    unit: UnitName | null;
+    parts: Shape[];
+    /**
+     * The file's source unit (always present; faijs is the single source of truth).
+     * 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;
     /**
      * Total parts the single file declared (e.g. 3MF `<build>` object count),
      * present only when > 1. Single-part mesh (STL, single-object 3MF) omits it.
-     * When set, `shape` is only the FIRST part's geometry (feijs `load` op is
-     * single-part; the file was downgraded to its first part — §5.4).
+     * 保留为 `parts.length`（>1 时）；多零件不再折叠后该字段仅供旧宿主判断。
      */
     multiPartCount?: number;
     /**
@@ -38,6 +60,20 @@ export interface ImportFileResult {
      * 是否解析；无声明则省略。仅随导入结果上抛，不挂 Shape。
      */
     fileMeta?: FileMeta;
+    /**
+     * 本次导入的结构数据（P0 §5.1）：零件身份表 + Bambu 视图（3MF 分支填充）。
+     * 单/多零件均登记（单零件 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
@@ -72,13 +108,22 @@ 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` declares the source unit for
- *   formats without unit metadata (e.g. STL). Defaults to mm.
- * @returns the shape with base-unit coordinates plus the file's own declared
- *   unit (`unit`, metadata only; null when the format has no declaration).
+ *   (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 declare function importFile(buffer: ArrayBuffer, format?: string, opts?: {
-    unit?: ValueWithUnits;
+    unit?: UnitName;
 }): Promise<ImportFileResult>;
 //# sourceMappingURL=io.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/mesh/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EAAM,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAA;IACZ;;;OAGG;IACH,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqBhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,cAAc,CAAA;CAAE,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CA2D3B"}
+{"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,CAmG3B"}