@faicad/faijs 0.29.5 → 0.31.1

package/dist/mesh/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mesh/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8DH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,WAAW,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED,aAAa;AAEb,8DAA8D;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAA;AAC9B,4CAA4C;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAA;AACzB,4CAA4C;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,CAAqB;IAC7C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IACxC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9D,CAAC","sourcesContent":["/**\n * mesh 类型定义 — 纯数据几何 API 的类型契约\n *\n * 设计原则（§5.1）：\n * - 全部纯数据：输入输出是 ManifoldMeshData 或 JSON 值，不碰 THREE 场景、不读 store\n * - 不可变：每个 API 返回新几何，不修改输入\n * - 坐标系：右手系 +Z 向上、毫米、角度用度\n * - 坐标空间：所有 API 输入/输出均为**世界空间** ManifoldMeshData\n *   （局部↔世界变换由执行器负责，mesh 不感知 mesh.matrixWorld）\n *\n * P1 阶段 Shape = ManifoldMeshData（无 worker）。\n * P3+ 阶段 Shape 将变为 worker 内 Manifold 对象的句柄。\n */\n\nimport type { PbrAppearance } from '../api/appearance'\nimport type { ShapeMeta } from '../api/meta'\n\n// ── 基础类型 ──\n\n/** 三维坐标 / RGB 颜色元组（分量 sRGB 0–1）。 */\nexport type Vec3 = [number, number, number]\n\n/**\n * A JSON-serializable value: scalar, null, array, or plain object.\n */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [k: string]: JsonValue }\n\n// ── Shape ──\n\n/**\n * A mesh shape — the core data type of the mesh API.\n *\n * Shape is defined directly in mesh/types.ts rather than re-exported from\n * ops/types.ts; ops/types.ts imports it from here, removing the type cycle.\n *\n * 外观（PBR）：`appearance` 为可选数据字段（设计文档 2026-10-05 v2 §4.2），\n * 双链路产物自解释、可序列化；外观设置是 Shape **方法**（非 op，见\n * `api/appearance.ts` 的 `ShapeAppearanceMethods` / `attachAppearanceMethods`），\n * 方法只挂载在产物构造点（solid/curve）返回的实例上，基础 Shape 保持纯数据\n * 契约——因此本接口**不** extends 方法接口，`isMeshShape` 鸭子判定不受影响。\n */\nexport interface Shape {\n  positions: Float32Array\n  indices: Uint32Array\n  /** 可选：形状级外观（mesh/brep 双链路产物自解释；worker 序列化保留字段、不保留方法）。 */\n  appearance?: PbrAppearance\n  /** Phase 2：面级外观分组 [三角形起始, 数量, 外观]；存在时优先于 appearance 作为未分组默认。 */\n  materialGroups?: Array<{ start: number; count: number; appearance: PbrAppearance }>\n  /** Phase 2：顶点颜色（3MF colorgroup / 面级 mesh 链），sRGB 0–1，长度 = positions 长度。 */\n  vertexColors?: Float32Array\n  /**\n   * 零件级说明性元数据（设计文档 2026-10-05-meta §4.3）：名称/描述/料号/自定义\n   * 键值，随 Shape 走 mesh/brep 双链路、JSON 可序列化。设置方法是 Shape 实例\n   * 方法（非 op，见 `api/meta.ts` 的 `ShapeMetaMethods` / `attachMetaMethods`），\n   * 方法只挂载在产物构造点（solid/curve）返回的实例上，基础 Shape 保持纯数据\n   * 契约——因此本接口**不** extends 方法接口，`isMeshShape` 鸭子判定不受影响。\n   */\n  meta?: ShapeMeta\n  /**\n   * 面结构元数据：面序号 → 三角形区间 [start, count)（start/count 为三角形索引，\n   * 对应 positions/indices 焊接后的三角形序列）。仅参数化 primitives 构造时记录\n   * （面结构构造时已知、三角形顺序固定）；manifold 布尔/组合/导入后无 CAD 面\n   * 概念，本字段不存在。`setFaceColor`/`setFaceMaterial` 依赖本字段把面序号映射\n   * 到三角形区间并写入 materialGroups。\n   */\n  faceRanges?: Array<{ start: number; count: number }>\n}\n\n/**\n * Structural guard: returns true when the value looks like a mesh Shape\n * (duck-typed via positions/indices, with no requirements on third-party\n * types).\n *\n * Per the keep-syntax design, hosts use this guard to distinguish mesh Shapes\n * from compounds when consuming ExecutionResult.outputs, in the same style as\n * the runtime-internal isShapeLike.\n * @param v - the value to test.\n * @returns true when the value is a mesh Shape.\n */\nexport function isMeshShape(v: unknown): v is Shape {\n  return !!v && typeof v === 'object' && 'positions' in v && 'indices' in v\n}\n\n// ── 创建参数 ──\n\n/** Default radial segment count used for rounded geometry. */\nexport const NRAD_DEFAULT = 64\n/** Minimum allowed radial segment count. */\nexport const NRAD_MIN = 3\n/** Maximum allowed radial segment count. */\nexport const NRAD_MAX = 128\n\n/**\n * Clamp an nRad value into the legal range [NRAD_MIN, NRAD_MAX], rounding to\n * the nearest integer; undefined falls back to NRAD_DEFAULT.\n * @param n - the requested radial segment count, or undefined.\n * @returns the clamped radial segment count.\n */\nexport function clampNRad(n: number | undefined): number {\n  if (n === undefined) return NRAD_DEFAULT\n  return Math.max(NRAD_MIN, Math.min(NRAD_MAX, Math.round(n)))\n}\n\n/**\n * Parameters for creating a box (brepjs `box(width, depth, height, {at?, centered?, segments?})`\n * contract, §4.1 A 决策). Default: min-corner at the origin. `centered: true` shifts so the\n * box is centered at the origin; `at` is CENTER semantics and takes precedence over `centered`.\n */\nexport interface BoxParams {\n  /** Side length along X (mm). */\n  width: number\n  /** Side length along Y (mm). */\n  depth: number\n  /** Side length along Z (mm). */\n  height: number\n  /** Center position (brepjs `at`, CENTER semantics); takes precedence over `centered`. */\n  at?: Vec3\n  /** Center the box at the origin when `at` is absent. Default: false (min-corner at origin). */\n  centered?: boolean\n  /** Tessellation segment count (box: affects only brep/mesh tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/** Parameters for creating a sphere. */\nexport interface SphereParams {\n  radius: number\n  segments?: number\n  center?: Vec3\n  nRad?: number\n}\n\n/** Parameters for creating a cylinder (brepjs contract, §4.3 A). */\nexport interface CylinderParams {\n  /** Radius (mm). */\n  radius: number\n  /** Height along +Z (mm). */\n  height: number\n  /** Base circle center (brepjs `at`, BASE semantics; default [0, 0, 0]). */\n  at?: Vec3\n  /** Center the cylinder (base at −h/2 / center at `at`) instead of base at `at`/origin. */\n  centered?: boolean\n  /** Tessellation segment count (cylinder: affects only tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/** Parameters for creating a cone (or a truncated cone). */\nexport interface ConeParams {\n  /** Radius at the base (mm). */\n  radiusBottom: number\n  /** Radius at the top (mm); 0 for a pointed cone, === radiusBottom for a cylinder. */\n  radiusTop: number\n  /** Height along +Z (mm). */\n  height: number\n  /** Base circle center (brepjs `at`, BASE semantics; default [0, 0, 0]). */\n  at?: Vec3\n  /** Center the cone (base at −h/2 / center at `at`) instead of base at `at`/origin. */\n  centered?: boolean\n  /** Tessellation segment count (cone: affects only mere tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/**\n * Parameters for creating a wedge (trapezoidal prism).\n */\nexport interface WedgeParams {\n  /** Width of the base edge (mm), along the Y axis. */\n  width: number\n  /** Height of the trapezoid (mm), along the Z axis. */\n  height: number\n  /** Angle between the base edge and the slope (degrees). */\n  angle: number\n  /** Total extrusion length (mm), along the X axis. */\n  length: number\n  center?: Vec3\n  nRad?: number\n}\n\n/** Parameters for creating 3D text. */\nexport interface TextParams {\n  text: string\n  size: number\n  depth: number\n}\n\n/** Parameters for extruding an SVG into a solid. */\nexport interface SvgExtrudeParams {\n  svg: string\n  depth: number\n  targetLongSide: number\n  naturalWidth?: number\n  naturalHeight?: number\n}\n\n/** Parameters for building a solid from an SDF (signed distance function). */\nexport interface SdfParams {\n  code: string\n  box?: [Vec3, Vec3]\n  resolution?: number\n  params?: Record<string, number>\n}\n\n// ── 变换参数 ──\n\n/** Parameters for translating a shape. */\nexport interface TranslateParams {\n  offset: Vec3\n}\n\n/** Parameters for rotating a shape. */\nexport interface RotateParams {\n  angles: Vec3\n  pivot?: Vec3\n}\n\n/** Parameters for scaling a shape. */\nexport interface ScaleParams {\n  factor: number | Vec3\n}\n\n// ── 布尔参数 ──\n\n/** Kinds of binary boolean operations. */\nexport type BooleanOperation = 'union' | 'subtract' | 'intersect'\n\n// ── 分割参数 ──\n\n/** A cutting plane defined by a unit normal and a signed offset. */\nexport interface SplitPlane {\n  normal: Vec3\n  offset: number\n}\n\n/** Parameters for a dovetail split, including the cutting plane setup. */\nexport interface DovetailSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  bboxWidthOnWidthDir: number\n  groove: {\n    depth: number\n    depthTolerance: number\n    width: number\n    widthTolerance: number\n    flapsAngle: number\n  }\n}\n\n/** Parameters for a dowel-pin split, including the cutting plane setup. */\nexport interface DowelSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  dowel: {\n    diameter: number\n    diameterTolerance: number\n    height: number\n    heightTolerance: number\n  }\n  selectedSections?: number[] | null\n}\n\n/** Parameters for a straight-tenon split, including the cutting plane setup. */\nexport interface TenonSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  tenon: {\n    sideLength: number\n    sideLengthTolerance: number\n    height: number\n    heightTolerance: number\n  }\n  selectedSections?: number[] | null\n}\n\n/** Result of a joinery split: the two halves plus the cut-out wedge. */\nexport interface SplitResult {\n  front: Shape\n  back: Shape\n  wedge: Shape | null\n}\n\n// ── 钻孔参数 ──\n\n/** Parameters for drilling a hole. */\nexport interface DrillParams {\n  diameter: number\n  depth?: number\n  type: 'through' | 'blind'\n  position: Vec3\n  direction: Vec3\n  faceNormal: Vec3\n  tolerance?: number\n  holeType?: 'simple' | 'screw'\n  screwSystem?: string\n  screwSpecIdx?: number\n  screwThread?: string\n  screwHead?: string\n}\n\n// ── 拉伸参数 ──\n\n/** Parameters for extruding a face bounded by a plane. */\nexport interface ExtrudeParams {\n  normal: Vec3\n  planeDistance: number\n  length: number\n  mode?: 'centered' | 'forward' | 'backward'\n}\n\n// ── 雕刻参数 ──\n\n/** Parameters for engraving text or an SVG onto a face. */\nexport interface EngraveParams {\n  mode: 'convex' | 'concave'\n  depth: number\n  face: {\n    center: Vec3\n    normal: Vec3\n  }\n  text?: string\n  textSize?: number\n  svg?: string\n  svgNaturalWidth?: number\n  svgNaturalHeight?: number\n  svgSize?: number\n}\n\n/** Parameters for applying a knurl texture to a face. */\nexport interface KnurlParams {\n  face: {\n    center: Vec3\n    normal: Vec3\n  }\n  knurlTextureHeight: number\n  knurlInvertDisplacement: boolean\n  knurlRefineLength: number\n  knurlScaleU: number\n  knurlScaleV: number\n  knurlMappingMode: number\n}\n\n// ── 查询结果 ──\n\n/** Axis-aligned bounding box in world space. */\nexport interface BoundingBox {\n  min: Vec3\n  max: Vec3\n}\n\n/** Description of a face on a shape: center, normal and area. */\nexport interface FaceDescriptor {\n  center: Vec3\n  normal: Vec3\n  area: number\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mesh/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqFH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,WAAW,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED,aAAa;AAEb,8DAA8D;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAA;AAC9B,4CAA4C;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAA;AACzB,4CAA4C;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,CAAqB;IAC7C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IACxC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9D,CAAC","sourcesContent":["/**\n * mesh 类型定义 — 纯数据几何 API 的类型契约\n *\n * 设计原则（§5.1）：\n * - 全部纯数据：输入输出是 ManifoldMeshData 或 JSON 值，不碰 THREE 场景、不读 store\n * - 不可变：每个 API 返回新几何，不修改输入\n * - 坐标系：右手系 +Z 向上、毫米、角度用度\n * - 坐标空间：所有 API 输入/输出均为**世界空间** ManifoldMeshData\n *   （局部↔世界变换由执行器负责，mesh 不感知 mesh.matrixWorld）\n *\n * P1 阶段 Shape = ManifoldMeshData（无 worker）。\n * P3+ 阶段 Shape 将变为 worker 内 Manifold 对象的句柄。\n */\n\nimport type { PbrAppearance } from '../api/appearance'\nimport type { ShapeMeta } from '../api/meta'\n\n// ── 基础类型 ──\n\n/** 三维坐标 / RGB 颜色元组（分量 sRGB 0–1）。 */\nexport type Vec3 = [number, number, number]\n\n/**\n * A JSON-serializable value: scalar, null, array, or plain object.\n */\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [k: string]: JsonValue }\n\n// ── Shape ──\n\n/**\n * A mesh shape — the core data type of the mesh API.\n *\n * Shape is defined directly in mesh/types.ts rather than re-exported from\n * ops/types.ts; ops/types.ts imports it from here, removing the type cycle.\n *\n * 外观（PBR）：`appearance` 为可选数据字段（设计文档 2026-10-05 v2 §4.2），\n * 双链路产物自解释、可序列化；外观设置是 Shape **方法**（非 op，见\n * `api/appearance.ts` 的 `ShapeAppearanceMethods` / `attachAppearanceMethods`），\n * 方法只挂载在产物构造点（solid/curve）返回的实例上，基础 Shape 保持纯数据\n * 契约——因此本接口**不** extends 方法接口，`isMeshShape` 鸭子判定不受影响。\n */\nexport interface Shape {\n  positions: Float32Array\n  indices: Uint32Array\n  /** 可选：形状级外观（mesh/brep 双链路产物自解释；worker 序列化保留字段、不保留方法）。 */\n  appearance?: PbrAppearance\n  /** Phase 2：面级外观分组 [三角形起始, 数量, 外观]；存在时优先于 appearance 作为未分组默认。 */\n  materialGroups?: Array<{ start: number; count: number; appearance: PbrAppearance }>\n  /** Phase 2：顶点颜色（3MF colorgroup / 面级 mesh 链），sRGB 0–1，长度 = positions 长度。 */\n  vertexColors?: Float32Array\n  /**\n   * 零件级说明性元数据（设计文档 2026-10-05-meta §4.3）：名称/描述/料号/自定义\n   * 键值，随 Shape 走 mesh/brep 双链路、JSON 可序列化。设置方法是 Shape 实例\n   * 方法（非 op，见 `api/meta.ts` 的 `ShapeMetaMethods` / `attachMetaMethods`），\n   * 方法只挂载在产物构造点（solid/curve）返回的实例上，基础 Shape 保持纯数据\n   * 契约——因此本接口**不** extends 方法接口，`isMeshShape` 鸭子判定不受影响。\n   */\n  meta?: ShapeMeta\n  /**\n   * 装配节点位姿（方案 2026-10-08 §2.1「装配模型 = 节点属性，单一真源」）：节点\n   * **相对其父**的位置/姿态。可选、纯数据、JSON 可序列化——与 `appearance` /\n   * `meta` 同为**字段**而非方法，随 Shape 一起过 worker 序列化与 `structuredClone`\n   * （`isMeshShape` 鸭子判定不看本字段）。装配层级就是 Shape / CompoundShape\n   * 自身的 `children` + 本字段，**没有**平行的装配树。\n   *\n   * 取值形态（三种等价书写，均为可序列化纯数据）：`translate` 平移；`rotate`\n   * 单一轴角（`angle` 按本文件约定用**度**，`axis` 为轴向量）；`matrix` 3×4\n   * 行主序 12 元组——即 3MF `<component transform>` 与 XCAF location 的直接形态。\n   * 三者的复合顺序与形态间优先级由读侧实现固定（§5 第 4、5 步），本字段只定\n   * 义取值形态。\n   *\n   * 写入方两个、写回同一字段：导入侧（XCAF location / 3MF component transform）\n   * 与求解侧（`AssemblyTransform[]`）。导出侧**只读**它：STL 顶点烘焙、3MF\n   * `<component transform>`、STEP XCAF location（§2.1 映射表）。分量刻度与\n   * `positions` 同（基准单位），换算到声明单位由写出器成对完成（§2.1）。\n   *\n   * 阶段说明：本字段随 §5 第 3 步引入；写出器在 §5 第 4（3MF components）、第 5\n   * （导入归一 / STL 烘焙）步之前不消费它（`export-model.test.ts` 用「带与不带\n   * `transform` 的导出字节相等」钉住这一当前事实，届时翻转）。\n   */\n  transform?: { translate?: Vec3; rotate?: { angle: number; axis?: Vec3 }; matrix?: number[] }\n  /**\n   * 面结构元数据：面序号 → 三角形区间 [start, count)（start/count 为三角形索引，\n   * 对应 positions/indices 焊接后的三角形序列）。仅参数化 primitives 构造时记录\n   * （面结构构造时已知、三角形顺序固定）；manifold 布尔/组合/导入后无 CAD 面\n   * 概念，本字段不存在。`setFaceColor`/`setFaceMaterial` 依赖本字段把面序号映射\n   * 到三角形区间并写入 materialGroups。\n   */\n  faceRanges?: Array<{ start: number; count: number }>\n}\n\n/**\n * Structural guard: returns true when the value looks like a mesh Shape\n * (duck-typed via positions/indices, with no requirements on third-party\n * types).\n *\n * Per the keep-syntax design, hosts use this guard to distinguish mesh Shapes\n * from compounds when consuming ExecutionResult.outputs, in the same style as\n * the runtime-internal isShapeLike.\n * @param v - the value to test.\n * @returns true when the value is a mesh Shape.\n */\nexport function isMeshShape(v: unknown): v is Shape {\n  return !!v && typeof v === 'object' && 'positions' in v && 'indices' in v\n}\n\n// ── 创建参数 ──\n\n/** Default radial segment count used for rounded geometry. */\nexport const NRAD_DEFAULT = 64\n/** Minimum allowed radial segment count. */\nexport const NRAD_MIN = 3\n/** Maximum allowed radial segment count. */\nexport const NRAD_MAX = 128\n\n/**\n * Clamp an nRad value into the legal range [NRAD_MIN, NRAD_MAX], rounding to\n * the nearest integer; undefined falls back to NRAD_DEFAULT.\n * @param n - the requested radial segment count, or undefined.\n * @returns the clamped radial segment count.\n */\nexport function clampNRad(n: number | undefined): number {\n  if (n === undefined) return NRAD_DEFAULT\n  return Math.max(NRAD_MIN, Math.min(NRAD_MAX, Math.round(n)))\n}\n\n/**\n * Parameters for creating a box (原 brepjs `box(width, depth, height, {at?, centered?, segments?})`\n * contract, §4.1 A 决策). Default: min-corner at the origin. `centered: true` shifts so the\n * box is centered at the origin; `at` is CENTER semantics and takes precedence over `centered`.\n */\nexport interface BoxParams {\n  /** Side length along X (mm). */\n  width: number\n  /** Side length along Y (mm). */\n  depth: number\n  /** Side length along Z (mm). */\n  height: number\n  /** Center position (原 brepjs `at`, CENTER semantics); takes precedence over `centered`. */\n  at?: Vec3\n  /** Center the box at the origin when `at` is absent. Default: false (min-corner at origin). */\n  centered?: boolean\n  /** Tessellation segment count (box: affects only brep/mesh tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/** Parameters for creating a sphere. */\nexport interface SphereParams {\n  radius: number\n  segments?: number\n  center?: Vec3\n  nRad?: number\n}\n\n/** Parameters for creating a cylinder (原 brepjs contract, §4.3 A). */\nexport interface CylinderParams {\n  /** Radius (mm). */\n  radius: number\n  /** Height along +Z (mm). */\n  height: number\n  /** Base circle center (原 brepjs `at`, BASE semantics; default [0, 0, 0]). */\n  at?: Vec3\n  /** Center the cylinder (base at −h/2 / center at `at`) instead of base at `at`/origin. */\n  centered?: boolean\n  /** Tessellation segment count (cylinder: affects only tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/** Parameters for creating a cone (or a truncated cone). */\nexport interface ConeParams {\n  /** Radius at the base (mm). */\n  radiusBottom: number\n  /** Radius at the top (mm); 0 for a pointed cone, === radiusBottom for a cylinder. */\n  radiusTop: number\n  /** Height along +Z (mm). */\n  height: number\n  /** Base circle center (原 brepjs `at`, BASE semantics; default [0, 0, 0]). */\n  at?: Vec3\n  /** Center the cone (base at −h/2 / center at `at`) instead of base at `at`/origin. */\n  centered?: boolean\n  /** Tessellation segment count (cone: affects only mere tessellation, not topology). */\n  segments?: number\n  /** Internal historical alias for `segments` (accepted by clampNRad, §5.1). */\n  nRad?: number\n}\n\n/**\n * Parameters for creating a wedge (trapezoidal prism).\n */\nexport interface WedgeParams {\n  /** Width of the base edge (mm), along the Y axis. */\n  width: number\n  /** Height of the trapezoid (mm), along the Z axis. */\n  height: number\n  /** Angle between the base edge and the slope (degrees). */\n  angle: number\n  /** Total extrusion length (mm), along the X axis. */\n  length: number\n  center?: Vec3\n  nRad?: number\n}\n\n/** Parameters for creating 3D text. */\nexport interface TextParams {\n  text: string\n  size: number\n  depth: number\n}\n\n/** Parameters for extruding an SVG into a solid. */\nexport interface SvgExtrudeParams {\n  svg: string\n  depth: number\n  targetLongSide: number\n  naturalWidth?: number\n  naturalHeight?: number\n}\n\n/** Parameters for building a solid from an SDF (signed distance function). */\nexport interface SdfParams {\n  code: string\n  box?: [Vec3, Vec3]\n  resolution?: number\n  params?: Record<string, number>\n}\n\n// ── 变换参数 ──\n\n/** Parameters for translating a shape. */\nexport interface TranslateParams {\n  offset: Vec3\n}\n\n/** Parameters for rotating a shape. */\nexport interface RotateParams {\n  angles: Vec3\n  pivot?: Vec3\n}\n\n/** Parameters for scaling a shape. */\nexport interface ScaleParams {\n  factor: number | Vec3\n}\n\n// ── 布尔参数 ──\n\n/** Kinds of binary boolean operations. */\nexport type BooleanOperation = 'union' | 'subtract' | 'intersect'\n\n// ── 分割参数 ──\n\n/** A cutting plane defined by a unit normal and a signed offset. */\nexport interface SplitPlane {\n  normal: Vec3\n  offset: number\n}\n\n/** Parameters for a dovetail split, including the cutting plane setup. */\nexport interface DovetailSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  bboxWidthOnWidthDir: number\n  groove: {\n    depth: number\n    depthTolerance: number\n    width: number\n    widthTolerance: number\n    flapsAngle: number\n  }\n}\n\n/** Parameters for a dowel-pin split, including the cutting plane setup. */\nexport interface DowelSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  dowel: {\n    diameter: number\n    diameterTolerance: number\n    height: number\n    heightTolerance: number\n  }\n  selectedSections?: number[] | null\n}\n\n/** Parameters for a straight-tenon split, including the cutting plane setup. */\nexport interface TenonSplitParams {\n  plane: SplitPlane\n  planeCenter: Vec3\n  widthDir: Vec3\n  tenon: {\n    sideLength: number\n    sideLengthTolerance: number\n    height: number\n    heightTolerance: number\n  }\n  selectedSections?: number[] | null\n}\n\n/** Result of a joinery split: the two halves plus the cut-out wedge. */\nexport interface SplitResult {\n  front: Shape\n  back: Shape\n  wedge: Shape | null\n}\n\n// ── 钻孔参数 ──\n\n/** Parameters for drilling a hole. */\nexport interface DrillParams {\n  diameter: number\n  depth?: number\n  type: 'through' | 'blind'\n  position: Vec3\n  direction: Vec3\n  faceNormal: Vec3\n  tolerance?: number\n  holeType?: 'simple' | 'screw'\n  screwSystem?: string\n  screwSpecIdx?: number\n  screwThread?: string\n  screwHead?: string\n}\n\n// ── 拉伸参数 ──\n\n/** Parameters for extruding a face bounded by a plane. */\nexport interface ExtrudeParams {\n  normal: Vec3\n  planeDistance: number\n  length: number\n  mode?: 'centered' | 'forward' | 'backward'\n}\n\n// ── 雕刻参数 ──\n\n/** Parameters for engraving text or an SVG onto a face. */\nexport interface EngraveParams {\n  mode: 'convex' | 'concave'\n  depth: number\n  face: {\n    center: Vec3\n    normal: Vec3\n  }\n  text?: string\n  textSize?: number\n  svg?: string\n  svgNaturalWidth?: number\n  svgNaturalHeight?: number\n  svgSize?: number\n}\n\n/** Parameters for applying a knurl texture to a face. */\nexport interface KnurlParams {\n  face: {\n    center: Vec3\n    normal: Vec3\n  }\n  knurlTextureHeight: number\n  knurlInvertDisplacement: boolean\n  knurlRefineLength: number\n  knurlScaleU: number\n  knurlScaleV: number\n  knurlMappingMode: number\n}\n\n// ── 查询结果 ──\n\n/** Axis-aligned bounding box in world space. */\nexport interface BoundingBox {\n  min: Vec3\n  max: Vec3\n}\n\n/** Description of a face on a shape: center, normal and area. */\nexport interface FaceDescriptor {\n  center: Vec3\n  normal: Vec3\n  area: number\n}\n"]}

package/dist/node-host/cli.d.ts

@@ -18,8 +18,15 @@
  *   --sheet <front,top,right,iso>       — (view) 多视图图纸（projectSheet；与 --view 互斥）
  */
 import type { LibNamespace } from '../runtime-state.js';
-import type { ExecutionMode } from '../cad-runtime/ports.js';
+import type { ExecutionMode, HostPorts } from '../cad-runtime/ports.js';
+import type { BrepHandle, BrepSubShapeType } from '../brep/engine/types.js';
 import type { ViewSpec } from '../api/view/view-camera.js';
+/**
+ * 注入 libLoader 到 node ports（CLI 宿主白名单装载）。Exported for executeScript (B6).
+ * @param ports - Node host ports to augment with the CLI lib loader.
+ * @returns The augmented ports (`libLoader` set to the CLI scoped-package loader).
+ */
+export declare function withCliLibLoader(ports: HostPorts): HostPorts;
 /** Options accepted by the `check` command. */
 export interface CliCheckOptions {
     /** Asset directory used by the node ports. */
@@ -163,6 +170,47 @@ export declare function selectExportableTerminals<T extends {
     exportable: T[];
     hiddenCount: number;
 };
+/** 判据取 shapeType/getSubShapes 的最小接口面（用真 kernel 时即 BrepEngineApi 的这两个方法）。 */
+export interface ShapeTypeProbe {
+    shapeType(shape: BrepHandle): string;
+    getSubShapes(shape: BrepHandle, type: BrepSubShapeType): BrepHandle[];
+}
+/**
+ * 终端 BREP 句柄是否「可落成零件」——即含至少一个三维实体。
+ *
+ * **为什么需要它**：终端集合（`live-shapes.ts`）只回答「谁该被看见」，未消费的 2D 草图
+ * 同样是顶层未消费变量 ⇒ 也是终端 ⇒ 会走到导出层落一个 `.step`。而 2D 面片（实测厚度
+ * 2e-07、solids=0）一旦落盘，`fcstd-port` 的 `parity-judge.py merge_parts` 会把它的 area
+ * 加进真实件（5.04e+06 vs 5.50e+06 ⇒ ~91% 误差），parity 必 FAIL。所以「谁该被看见」与
+ * 「什么能落成零件」是两件事：本判据只管后者，不去动终端集合。
+ *
+ * **判决表**（实测标定，2026-10-06）：
+ * | shapeType | 判决 | 依据 |
+ * |---|---|---|
+ * | `SOLID` / `COMPSOLID` | 导出 | 真零件 |
+ * | `COMPOUND` | 含 ≥1 solid → 导出；否则跳过 | 装配体是 compound；`getSubShapes` 递归取子实体 |
+ * | `SHELL` | 含 ≥1 solid → 导出；否则跳过 | 旧栈基线 9/9 真实件皆 solid/compound；实测 8 个游离草图中 5 个顶层恰是 SHELL |
+ * | `FACE`/`WIRE`/`EDGE`/`VERTEX` | 跳过 | 无实体的 2D 片面 / 1D 线框 |
+ * | 其它（`SHAPE` 枚举兜底、空串） | 导出 | 保守，零回归 |
+ * | 无句柄（纯 mesh 终端） | 导出 | mesh 零件导出 STEP 是既有能力，不借本批收紧 |
+ *
+ * **`SHELL` 的裁决**：方案 §3 初稿把 shell 判为「导出（保留现状）」，理由是"面模型是合法
+ * 产物的先例存在"。但 2026-10-06 的 E-1 探针推翻了该前提：
+ * ① 旧栈 parity 基线（A 组 9 个真实件）顶层全为 `SOLID`/`COMPOUND`、`solids ≥ 1`，无一面模型；
+ * ② 新栈多出的 8 个游离草图中 **5 个顶层就是 `SHELL`** ⇒ 按初稿判决**根本拦不住**，方案失效；
+ * ③ `cli.ts` 改动前 0 处 shell 逻辑，不存在需要兼容的既有行为。
+ * ⇒ 改判为 **`SHELL` 且无子实体 → 跳过**。若日后语料真出现「合法的 2D 面模型产物」需求，
+ * 应由脚本侧或显式开关承接，而不是让导出层无法区分草图与零件（登记于相邻缺陷 D-2）。
+ *
+ * 实现上不分层递归：内核 `getSubShapes`（OCCT `TopExp_Explorer` 语义）对任意嵌套深度的
+ * compound **一次即可取到全部子实体**（E-1 探针：顶层 COMPOUND 的草图也能数出 solids=0）。
+ * 探针抛错 → **保守放行**（宁可多导一个，不可误删真零件）。
+ *
+ * @param shape - 终端 BREP 句柄（无句柄传 undefined）
+ * @param probe - shapeType/getSubShapes 提供者（生产用 `brepSolids` 条目的 kernel；测试可注入假 kernel）
+ * @returns 该句柄是否含至少一个实体（可落成零件）
+ */
+export declare function isExportableSolid(shape: BrepHandle | undefined, probe: ShapeTypeProbe | undefined): boolean;
 /**
  * Execute the `view` command: execute a .fai.js file and write view SVG(s).
  *

package/dist/node-host/cli.d.ts.map

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

package/dist/node-host/cli.js

@@ -105,8 +105,12 @@ const cliPortsLibLoader = {
         },
     },
 };
-/** 注入 libLoader 到 node ports（CLI 宿主白名单装载）。 */
-function withCliLibLoader(ports) {
+/**
+ * 注入 libLoader 到 node ports（CLI 宿主白名单装载）。Exported for executeScript (B6).
+ * @param ports - Node host ports to augment with the CLI lib loader.
+ * @returns The augmented ports (`libLoader` set to the CLI scoped-package loader).
+ */
+export function withCliLibLoader(ports) {
     return { ...ports, libLoader: cliPortsLibLoader };
 }
 /**
@@ -188,7 +192,7 @@ export async function cliRun(filePath, outPath, opts) {
     // 否则入口在子目录时它的 `./parts/x.fai.js` 会以根为基准解析而错位。
     const projectRoot = opts?.projectRoot ? resolve(opts.projectRoot) : findProjectRoot(filePath);
     const entryKey = projectKeyOf(projectRoot, filePath);
-    // Initialize OCCT and bind the vendored brepjs kernel registry (D10) so that
+    // Initialize OCCT and bind the brep engine registry (D10) so that
     // cq-compat parts (which project ops through compatFn) run end-to-end under
     // the CLI. registerOcctBrepEngine is idempotent and itself boots initOcctWasm.
     await registerOcctBrepEngine();
@@ -250,6 +254,76 @@ export function selectExportableTerminals(terminals, includeHidden = false) {
     const exportable = includeHidden ? [...terminals] : terminals.filter((t) => !t.hidden);
     return { exportable, hiddenCount };
 }
+/**
+ * 终端 BREP 句柄是否「可落成零件」——即含至少一个三维实体。
+ *
+ * **为什么需要它**：终端集合（`live-shapes.ts`）只回答「谁该被看见」，未消费的 2D 草图
+ * 同样是顶层未消费变量 ⇒ 也是终端 ⇒ 会走到导出层落一个 `.step`。而 2D 面片（实测厚度
+ * 2e-07、solids=0）一旦落盘，`fcstd-port` 的 `parity-judge.py merge_parts` 会把它的 area
+ * 加进真实件（5.04e+06 vs 5.50e+06 ⇒ ~91% 误差），parity 必 FAIL。所以「谁该被看见」与
+ * 「什么能落成零件」是两件事：本判据只管后者，不去动终端集合。
+ *
+ * **判决表**（实测标定，2026-10-06）：
+ * | shapeType | 判决 | 依据 |
+ * |---|---|---|
+ * | `SOLID` / `COMPSOLID` | 导出 | 真零件 |
+ * | `COMPOUND` | 含 ≥1 solid → 导出；否则跳过 | 装配体是 compound；`getSubShapes` 递归取子实体 |
+ * | `SHELL` | 含 ≥1 solid → 导出；否则跳过 | 旧栈基线 9/9 真实件皆 solid/compound；实测 8 个游离草图中 5 个顶层恰是 SHELL |
+ * | `FACE`/`WIRE`/`EDGE`/`VERTEX` | 跳过 | 无实体的 2D 片面 / 1D 线框 |
+ * | 其它（`SHAPE` 枚举兜底、空串） | 导出 | 保守，零回归 |
+ * | 无句柄（纯 mesh 终端） | 导出 | mesh 零件导出 STEP 是既有能力，不借本批收紧 |
+ *
+ * **`SHELL` 的裁决**：方案 §3 初稿把 shell 判为「导出（保留现状）」，理由是"面模型是合法
+ * 产物的先例存在"。但 2026-10-06 的 E-1 探针推翻了该前提：
+ * ① 旧栈 parity 基线（A 组 9 个真实件）顶层全为 `SOLID`/`COMPOUND`、`solids ≥ 1`，无一面模型；
+ * ② 新栈多出的 8 个游离草图中 **5 个顶层就是 `SHELL`** ⇒ 按初稿判决**根本拦不住**，方案失效；
+ * ③ `cli.ts` 改动前 0 处 shell 逻辑，不存在需要兼容的既有行为。
+ * ⇒ 改判为 **`SHELL` 且无子实体 → 跳过**。若日后语料真出现「合法的 2D 面模型产物」需求，
+ * 应由脚本侧或显式开关承接，而不是让导出层无法区分草图与零件（登记于相邻缺陷 D-2）。
+ *
+ * 实现上不分层递归：内核 `getSubShapes`（OCCT `TopExp_Explorer` 语义）对任意嵌套深度的
+ * compound **一次即可取到全部子实体**（E-1 探针：顶层 COMPOUND 的草图也能数出 solids=0）。
+ * 探针抛错 → **保守放行**（宁可多导一个，不可误删真零件）。
+ *
+ * @param shape - 终端 BREP 句柄（无句柄传 undefined）
+ * @param probe - shapeType/getSubShapes 提供者（生产用 `brepSolids` 条目的 kernel；测试可注入假 kernel）
+ * @returns 该句柄是否含至少一个实体（可落成零件）
+ */
+export function isExportableSolid(shape, probe) {
+    // 无 BREP 句柄（纯 mesh 终端）→ 导出（既有能力，零回归）。
+    if (!shape || !probe)
+        return true;
+    let type;
+    try {
+        type = probe.shapeType(shape).toUpperCase();
+    }
+    catch {
+        // 探针抛错（异常句柄）→ 保守放行。
+        return true;
+    }
+    switch (type) {
+        case 'SOLID':
+        case 'COMPSOLID':
+            return true;
+        case 'COMPOUND':
+        case 'SHELL':
+            // 无实体的 compound / shell = 2D 面片（游离草图）。`getSubShapes('solid')` 递归取子实体。
+            try {
+                return probe.getSubShapes(shape, 'solid').length > 0;
+            }
+            catch {
+                return true;
+            }
+        case 'FACE':
+        case 'WIRE':
+        case 'EDGE':
+        case 'VERTEX':
+            return false;
+        default:
+            // 枚举兜底（'SHAPE' / 空串 / 未知方言）→ 保守导出。
+            return true;
+    }
+}
 /** Export an executed result to `outPath` (shared body of cliRun's export path). */
 async function exportExecutionResult(outPath, ext, execResult, terminals, includeHidden = false) {
     const { exportable, hiddenCount } = selectExportableTerminals(terminals, includeHidden);
@@ -264,7 +338,32 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
             error: `All ${hiddenCount} live terminal(s) are hidden — nothing to export (pass includeHidden to export them)`,
         };
     }
-    if (exportable.length === 0) {
+    // ── 二维终端过滤（G0-D）──：终端集合回答「谁该被看见」，导出层回答「什么能落成零件」。
+    // 未消费的 2D 草图同样是顶层未消费变量 ⇒ 也是终端，但落成 `.step` 会污染 parity 的 area。
+    // 过滤后**不得**回退到「最后一个 output」，否则等于把刚剔除的草图从后门写回去。
+    const skipped2d = [];
+    let solidExportable = exportable;
+    if (!includeHidden) {
+        solidExportable = [];
+        for (const t of exportable) {
+            const entry = execResult.brepSolids?.get(t.id);
+            if (isExportableSolid(entry?.solid, entry?.kernel)) {
+                solidExportable.push(t);
+            }
+            else {
+                skipped2d.push(String(t.meta?.name ?? t.id));
+            }
+        }
+        if (solidExportable.length === 0 && exportable.length > 0) {
+            return {
+                ok: false,
+                error: `All ${exportable.length} live terminal(s) are 2D (no solid) — nothing to export as a 3D part` +
+                    (skipped2d.length > 0 ? ` (skipped: ${skipped2d.join(', ')})` : ''),
+            };
+        }
+    }
+    const solidInfos = skipped2d.length > 0 ? [`Skipped ${skipped2d.length} 2D terminal(s): ${skipped2d.join(', ')}`] : [];
+    if (solidExportable.length === 0) {
         // No terminals — use last output
         const outputNames = [...execResult.outputs.keys()];
         if (outputNames.length === 0) {
@@ -276,11 +375,12 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
             return { ok: false, error: `No output for part "${lastPartName}"` };
         }
         const solidEntry = execResult.brepSolids?.get(asPartName(lastPartName));
-        return writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        const r = writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        return solidInfos.length > 0 ? { ...r, infos: [...(r.infos ?? []), ...solidInfos] } : r;
     }
     // Single terminal
-    if (exportable.length === 1) {
-        const terminal = exportable[0];
+    if (solidExportable.length === 1) {
+        const terminal = solidExportable[0];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape) {
             return { ok: false, error: `No output for terminal "${terminal.id}"` };
@@ -288,29 +388,32 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
         // Assembly (compound with behavior) → expand members with colors
         if (!('positions' in shape) || !('indices' in shape)) {
             const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
-            if (asmResult)
-                return asmResult;
+            if (asmResult) {
+                return solidInfos.length > 0 ? { ...asmResult, infos: [...(asmResult.infos ?? []), ...solidInfos] } : asmResult;
+            }
         }
         const solidEntry = execResult.brepSolids?.get(terminal.id);
-        return writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        const r = writeOutput(outPath, ext, shape, solidEntry ? { solid: solidEntry.solid, kernel: solidEntry.kernel } : undefined);
+        return solidInfos.length > 0 ? { ...r, infos: [...(r.infos ?? []), ...solidInfos] } : r;
     }
     // Multiple terminals — write each to a separate file
     // First, check if any terminal is a compound (assembly) — export it as a single STEP
-    for (let i = 0; i < exportable.length; i++) {
-        const terminal = exportable[i];
+    for (let i = 0; i < solidExportable.length; i++) {
+        const terminal = solidExportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
         if (!('positions' in shape) || !('indices' in shape)) {
             // Compound terminal — try assembly STEP export
             const asmResult = writeAssemblyStep(outPath, ext, shape, execResult, hiddenTerminals);
-            if (asmResult)
-                return asmResult;
+            if (asmResult) {
+                return solidInfos.length > 0 ? { ...asmResult, infos: [...(asmResult.infos ?? []), ...solidInfos] } : asmResult;
+            }
         }
     }
     // Then export non-compound terminals
-    for (let i = 0; i < exportable.length; i++) {
-        const terminal = exportable[i];
+    for (let i = 0; i < solidExportable.length; i++) {
+        const terminal = solidExportable[i];
         const shape = execResult.outputs.get(terminal.id);
         if (!shape)
             continue;
@@ -324,7 +427,7 @@ async function exportExecutionResult(outPath, ext, execResult, terminals, includ
         if (!result.ok)
             return result;
     }
-    return { ok: true, outputFormat: ext };
+    return { ok: true, outputFormat: ext, ...(solidInfos.length > 0 ? { infos: solidInfos } : {}) };
 }
 /**
  * 解析 `--view` 参数：三数字逗号串 → 方向对象（"1,-1,1" → { dir: [1,-1,1] }），
@@ -386,8 +489,8 @@ export async function cliView(filePath, outPath, opts) {
     const projectRoot = opts?.projectRoot ? resolve(opts.projectRoot) : findProjectRoot(filePath);
     const entryKey = projectKeyOf(projectRoot, filePath);
     // Initialize OCCT（投影 HLR 依赖 brep 内核）。registerOcctBrepEngine is
-    // idempotent and itself boots initOcctWasm, and also binds the vendored
-    // brepjs kernel registry (D10) — same boot path as cliRun above.
+    // idempotent and itself boots initOcctWasm, and also binds the
+    // brep engine registry (D10) — same boot path as cliRun above.
     await registerOcctBrepEngine();
     const ports = withCliProjectLoader(withCliLibLoader(createNodePorts({
         assetsDir: opts?.assetsDir,
@@ -554,6 +657,9 @@ function writeAssemblyStep(outPath, ext, compound, execResult, hiddenTerminals)
             // 与主导出路径同一判据（includeHidden 时 hiddenTerminals 传 undefined，不过滤）。
             if (hiddenTerminals?.has(String(key)))
                 continue;
+            // 同一 3D 判据：兜底路径直接遍历全体 brepSolids，2D 草图句柄同样会进这里（G0-D I-4）。
+            if (!isExportableSolid(solidEntry.solid, solidEntry.kernel))
+                continue;
             if (!kernel)
                 kernel = solidEntry.kernel;
             entries.push({