@faicad/faijs 0.22.2 → 0.29.5

package/dist/api/measurement/index.js

@@ -18,54 +18,81 @@
  * 由 gen-l3-surface.ts re-export 进 api/generated/script-face.ts / script-face-manifest.ts，
  * gen-symbol-table.ts 同步 check() 符号表——cad 命名空间、manifest、符号表三处同源。
  */
-import { brepOf } from '../../shape.js';
+import { brepOf, meshSolidOf } from '../../shape.js';
 import { getBrepApi } from '../../brep/handle-bridge.js';
-/** 读该 Shape 的 BREP 句柄；mesh-only 输入在测量前显式报错（不静默降级）。 */
-function requireBrepHandle(shape, op) {
-    const h = brepOf(shape);
-    if (h === undefined) {
-        throw new Error(`[faijs/measurement] ${op}: E_BREP_ONLY_INPUT: measurement requires a BREP-backed shape (mesh-only input has no BREP handle)`);
+import { getBackends } from '../../runtime-state.js';
+/**
+ * 取量测目标：精度链句柄优先，其次是网格零件句柄；两者都没有 → 显式报错。
+ *
+ * 网格零件（方案 2026-10-01 §4 Phase 4 / B4 批）走**网格后端**的 L1 内核。它的
+ * 量测值是对**面片几何**的精确量（STL 的曲面本来就是离散的：立方体 1000 与解析值
+ * 一致，圆柱侧面则是 32 个面片之和）——不是对原始设计的还原，也不是估算。所以
+ * 这里如实量、如实说，不额外加"近似"折扣，也不静默返回 0。
+ *
+ * @param shape - the shape being measured.
+ * @param op - the measurement op name (error messages).
+ * @returns the handle to measure plus the kernel that can read it.
+ * @throws {Error} `E_MEASUREMENT_NO_HANDLE` when the shape carries neither chain handle.
+ */
+function requireMeasurementTarget(shape, op) {
+    const brep = brepOf(shape);
+    if (brep !== undefined) {
+        return { kernel: getBrepApi(), handle: brep, chain: 'brep' };
+    }
+    const mesh = meshSolidOf(shape);
+    if (mesh !== undefined) {
+        const backend = getBackends().kernel.meshSolid;
+        if (!backend) {
+            throw new Error(`[faijs/measurement] ${op}: E_MESH_SOLID_UNSUPPORTED: this shape is a mesh solid but no mesh ` +
+                'backend is assembled in this host');
+        }
+        return { kernel: backend.kernel, handle: mesh, chain: 'mesh' };
     }
-    return h;
+    throw new Error(`[faijs/measurement] ${op}: E_MEASUREMENT_NO_HANDLE: measurement requires a shape with a chain handle ` +
+        '(a bare mesh has neither a BREP handle nor a mesh solid handle)');
 }
 /**
  * 测量形状的表面积（L1 getSurfaceArea，两引擎同口径）。
  *
- * @param shape - 被测量的形状（Face / Shape3D / compound）。
- * @returns 表面积（mm²）。
+ * @param shape - 被测量的形状（Face / Shape3D / compound / 网格零件）。
+ * @returns 表面积（mm²；网格零件按面片几何计）。
  */
 export async function area(shape) {
-    const h = requireBrepHandle(shape, 'area');
-    return getBrepApi().getSurfaceArea(h);
+    const t = requireMeasurementTarget(shape, 'area');
+    return t.kernel.getSurfaceArea(t.handle);
 }
 /**
  * 测量形状的边长/线长（L1 getLength，两引擎同口径）。
  *
- * @param shape - 被测量的形状（edge / wire / solid，solid 按内核口径计边）。
+ * 口径 = **shape 中所有唯一 edge 的弧长之和**：edge 取自身弧长，wire 取其边之和，
+ * face 取边界边之和，solid 取全部边之和，compound 取各子实体之和。两个 BREP 引擎
+ * 在此口径下逐位一致（2026-10-02 归一化，见 occt / brepkit 适配器的 getLength）。
+ *
+ * @param shape - 被测量的形状（edge / wire / face / solid / compound）。
  * @returns 长度（mm）。
  */
 export async function length(shape) {
-    const h = requireBrepHandle(shape, 'length');
-    return getBrepApi().getLength(h);
+    const t = requireMeasurementTarget(shape, 'length');
+    return t.kernel.getLength(t.handle);
 }
 /**
  * 测量形状的体素体积（L1 getVolume，两引擎同口径）。
  *
  * @param shape - 被测量的形状（solid / compound；对 wire / face 内核按自身口径计，可能返回 0）。
- * @returns 体积（mm³）。
+ * @returns 体积（mm³；网格零件按面片几何计）。
  */
 export async function volume(shape) {
-    const h = requireBrepHandle(shape, 'volume');
-    return getBrepApi().getVolume(h);
+    const t = requireMeasurementTarget(shape, 'volume');
+    return t.kernel.getVolume(t.handle);
 }
 /**
  * 测量形状的质心（L1 getCenterOfMass，两引擎同口径）。
  *
- * @param shape - 被测量的形状（solid / compound / face）。
+ * @param shape - 被测量的形状（solid / compound / face / 网格零件）。
  * @returns 质心坐标（mm，BREP 中立形态 {x,y,z}）。
  */
 export async function centerOfMass(shape) {
-    const h = requireBrepHandle(shape, 'centerOfMass');
-    return getBrepApi().getCenterOfMass(h);
+    const t = requireMeasurementTarget(shape, 'centerOfMass');
+    return t.kernel.getCenterOfMass(t.handle);
 }
 //# sourceMappingURL=index.js.map

package/dist/api/measurement/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/measurement/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAIrD,sDAAsD;AACtD,SAAS,iBAAiB,CAAC,KAAY,EAAE,EAAU;IACjD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACvB,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,oGAAoG,CAC9H,CAAA;IACH,CAAC;IACD,OAAO,CAAe,CAAA;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,KAAY;IACrC,MAAM,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC1C,OAAO,UAAU,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAA;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAY;IACvC,MAAM,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC5C,OAAO,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAY;IACvC,MAAM,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC5C,OAAO,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAY;IAC7C,MAAM,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,cAAc,CAAC,CAAA;IAClD,OAAO,UAAU,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;AACxC,CAAC","sourcesContent":["/**\n * measurement — cad 脚本面测量 op（Phase 7，narrowing plan §Phase 7 / Q4）\n *\n * 补齐 §1.5 的反向缺口：BrepEngineApi 的 L1 测量面（getSurfaceArea / getLength）\n * 在脚本面此前没有任何入口——脚本里量不出面积、长度。本模块提供两个**中立**测量\n * op（走 getBrepApi() 的 L1 契约面，occt / brepkit / 小程序端同一份 .fai.js 都可跑）：\n *   - area(shape)         → 表面积（getSurfaceArea）；\n *   - length(shape)       → 边长/线长（getLength）；\n *   - volume(shape)       → 体积（getVolume）；\n *   - centerOfMass(shape) → 质心坐标（getCenterOfMass，BrepVec3 {x,y,z}）。\n *\n * 与 vendored 测量面（api/generated/measurement.ts 的 measureArea / measureLength）\n * 的区别：那些 op 经 l3-bridge 借入层 + vendored 函数绑定 occt-wasm，整体 occt-only\n * （Phase 6 已声明 engines: ['occt']）；本模块直接调 L1 方法，无借入层、无引擎绑定，\n * 是脚本面的中立测量入口。返回纯数字，不产出 Shape、不消费 shape。\n *\n * 三源一致（B1）：本模块经 arg-spec 的 `scriptFace: true` 条目（kind 'faijs'）登记，\n * 由 gen-l3-surface.ts re-export 进 api/generated/script-face.ts / script-face-manifest.ts，\n * gen-symbol-table.ts 同步 check() 符号表——cad 命名空间、manifest、符号表三处同源。\n */\n\nimport { brepOf } from '../../shape'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport type { Shape } from '../../mesh/types'\nimport type { BrepHandle, BrepVec3 } from '../../brep/engine/types'\n\n/** 读该 Shape 的 BREP 句柄；mesh-only 输入在测量前显式报错（不静默降级）。 */\nfunction requireBrepHandle(shape: Shape, op: string): BrepHandle {\n  const h = brepOf(shape)\n  if (h === undefined) {\n    throw new Error(\n      `[faijs/measurement] ${op}: E_BREP_ONLY_INPUT: measurement requires a BREP-backed shape (mesh-only input has no BREP handle)`,\n    )\n  }\n  return h as BrepHandle\n}\n\n/**\n * 测量形状的表面积（L1 getSurfaceArea，两引擎同口径）。\n *\n * @param shape - 被测量的形状（Face / Shape3D / compound）。\n * @returns 表面积（mm²）。\n */\nexport async function area(shape: Shape): Promise<number> {\n  const h = requireBrepHandle(shape, 'area')\n  return getBrepApi().getSurfaceArea(h)\n}\n\n/**\n * 测量形状的边长/线长（L1 getLength，两引擎同口径）。\n *\n * @param shape - 被测量的形状（edge / wire / solid，solid 按内核口径计边）。\n * @returns 长度（mm）。\n */\nexport async function length(shape: Shape): Promise<number> {\n  const h = requireBrepHandle(shape, 'length')\n  return getBrepApi().getLength(h)\n}\n\n/**\n * 测量形状的体素体积（L1 getVolume，两引擎同口径）。\n *\n * @param shape - 被测量的形状（solid / compound；对 wire / face 内核按自身口径计，可能返回 0）。\n * @returns 体积（mm³）。\n */\nexport async function volume(shape: Shape): Promise<number> {\n  const h = requireBrepHandle(shape, 'volume')\n  return getBrepApi().getVolume(h)\n}\n\n/**\n * 测量形状的质心（L1 getCenterOfMass，两引擎同口径）。\n *\n * @param shape - 被测量的形状（solid / compound / face）。\n * @returns 质心坐标（mm，BREP 中立形态 {x,y,z}）。\n */\nexport async function centerOfMass(shape: Shape): Promise<BrepVec3> {\n  const h = requireBrepHandle(shape, 'centerOfMass')\n  return getBrepApi().getCenterOfMass(h)\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/measurement/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAgBjD;;;;;;;;;;;;GAYG;AACH,SAAS,wBAAwB,CAAC,KAAY,EAAE,EAAU;IACxD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACpD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;IAC9D,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAA2B,CAAA;IACzD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,SAAyC,CAAA;QAC9E,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,qEAAqE;gBAC9F,mCAAmC,CACpC,CAAA;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;IAChE,CAAC;IACD,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,8EAA8E;QACvG,iEAAiE,CAClE,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,KAAY;IACrC,MAAM,CAAC,GAAG,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjD,OAAO,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAY;IACvC,MAAM,CAAC,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACnD,OAAO,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAY;IACvC,MAAM,CAAC,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACnD,OAAO,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAY;IAC7C,MAAM,CAAC,GAAG,wBAAwB,CAAC,KAAK,EAAE,cAAc,CAAC,CAAA;IACzD,OAAO,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAC3C,CAAC","sourcesContent":["/**\n * measurement — cad 脚本面测量 op（Phase 7，narrowing plan §Phase 7 / Q4）\n *\n * 补齐 §1.5 的反向缺口：BrepEngineApi 的 L1 测量面（getSurfaceArea / getLength）\n * 在脚本面此前没有任何入口——脚本里量不出面积、长度。本模块提供两个**中立**测量\n * op（走 getBrepApi() 的 L1 契约面，occt / brepkit / 小程序端同一份 .fai.js 都可跑）：\n *   - area(shape)         → 表面积（getSurfaceArea）；\n *   - length(shape)       → 边长/线长（getLength）；\n *   - volume(shape)       → 体积（getVolume）；\n *   - centerOfMass(shape) → 质心坐标（getCenterOfMass，BrepVec3 {x,y,z}）。\n *\n * 与 vendored 测量面（api/generated/measurement.ts 的 measureArea / measureLength）\n * 的区别：那些 op 经 l3-bridge 借入层 + vendored 函数绑定 occt-wasm，整体 occt-only\n * （Phase 6 已声明 engines: ['occt']）；本模块直接调 L1 方法，无借入层、无引擎绑定，\n * 是脚本面的中立测量入口。返回纯数字，不产出 Shape、不消费 shape。\n *\n * 三源一致（B1）：本模块经 arg-spec 的 `scriptFace: true` 条目（kind 'faijs'）登记，\n * 由 gen-l3-surface.ts re-export 进 api/generated/script-face.ts / script-face-manifest.ts，\n * gen-symbol-table.ts 同步 check() 符号表——cad 命名空间、manifest、符号表三处同源。\n */\n\nimport { brepOf, meshSolidOf } from '../../shape'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport { getBackends } from '../../runtime-state'\nimport type { MeshSolidBackend } from '../../brep/mesh-solid'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { Shape } from '../../mesh/types'\nimport type { BrepHandle, BrepVec3 } from '../../brep/engine/types'\n\n/** 量测目标：句柄 + 读它的内核（精度链用 BREP 引擎，网格链用网格后端）。 */\ninterface MeasurementTarget {\n  /** 读该句柄的 L1 契约面。 */\n  readonly kernel: BrepEngineApi\n  /** 被量测的句柄。 */\n  readonly handle: BrepHandle\n  /** 量测所在链（`mesh` = 网格零件，量的是面片几何）。 */\n  readonly chain: 'brep' | 'mesh'\n}\n\n/**\n * 取量测目标：精度链句柄优先，其次是网格零件句柄；两者都没有 → 显式报错。\n *\n * 网格零件（方案 2026-10-01 §4 Phase 4 / B4 批）走**网格后端**的 L1 内核。它的\n * 量测值是对**面片几何**的精确量（STL 的曲面本来就是离散的：立方体 1000 与解析值\n * 一致，圆柱侧面则是 32 个面片之和）——不是对原始设计的还原，也不是估算。所以\n * 这里如实量、如实说，不额外加\"近似\"折扣，也不静默返回 0。\n *\n * @param shape - the shape being measured.\n * @param op - the measurement op name (error messages).\n * @returns the handle to measure plus the kernel that can read it.\n * @throws {Error} `E_MEASUREMENT_NO_HANDLE` when the shape carries neither chain handle.\n */\nfunction requireMeasurementTarget(shape: Shape, op: string): MeasurementTarget {\n  const brep = brepOf(shape) as BrepHandle | undefined\n  if (brep !== undefined) {\n    return { kernel: getBrepApi(), handle: brep, chain: 'brep' }\n  }\n  const mesh = meshSolidOf(shape) as BrepHandle | undefined\n  if (mesh !== undefined) {\n    const backend = getBackends().kernel.meshSolid as MeshSolidBackend | undefined\n    if (!backend) {\n      throw new Error(\n        `[faijs/measurement] ${op}: E_MESH_SOLID_UNSUPPORTED: this shape is a mesh solid but no mesh ` +\n        'backend is assembled in this host',\n      )\n    }\n    return { kernel: backend.kernel, handle: mesh, chain: 'mesh' }\n  }\n  throw new Error(\n    `[faijs/measurement] ${op}: E_MEASUREMENT_NO_HANDLE: measurement requires a shape with a chain handle ` +\n    '(a bare mesh has neither a BREP handle nor a mesh solid handle)',\n  )\n}\n\n/**\n * 测量形状的表面积（L1 getSurfaceArea，两引擎同口径）。\n *\n * @param shape - 被测量的形状（Face / Shape3D / compound / 网格零件）。\n * @returns 表面积（mm²；网格零件按面片几何计）。\n */\nexport async function area(shape: Shape): Promise<number> {\n  const t = requireMeasurementTarget(shape, 'area')\n  return t.kernel.getSurfaceArea(t.handle)\n}\n\n/**\n * 测量形状的边长/线长（L1 getLength，两引擎同口径）。\n *\n * 口径 = **shape 中所有唯一 edge 的弧长之和**：edge 取自身弧长，wire 取其边之和，\n * face 取边界边之和，solid 取全部边之和，compound 取各子实体之和。两个 BREP 引擎\n * 在此口径下逐位一致（2026-10-02 归一化，见 occt / brepkit 适配器的 getLength）。\n *\n * @param shape - 被测量的形状（edge / wire / face / solid / compound）。\n * @returns 长度（mm）。\n */\nexport async function length(shape: Shape): Promise<number> {\n  const t = requireMeasurementTarget(shape, 'length')\n  return t.kernel.getLength(t.handle)\n}\n\n/**\n * 测量形状的体素体积（L1 getVolume，两引擎同口径）。\n *\n * @param shape - 被测量的形状（solid / compound；对 wire / face 内核按自身口径计，可能返回 0）。\n * @returns 体积（mm³；网格零件按面片几何计）。\n */\nexport async function volume(shape: Shape): Promise<number> {\n  const t = requireMeasurementTarget(shape, 'volume')\n  return t.kernel.getVolume(t.handle)\n}\n\n/**\n * 测量形状的质心（L1 getCenterOfMass，两引擎同口径）。\n *\n * @param shape - 被测量的形状（solid / compound / face / 网格零件）。\n * @returns 质心坐标（mm，BREP 中立形态 {x,y,z}）。\n */\nexport async function centerOfMass(shape: Shape): Promise<BrepVec3> {\n  const t = requireMeasurementTarget(shape, 'centerOfMass')\n  return t.kernel.getCenterOfMass(t.handle)\n}\n"]}

package/dist/api/meta.d.ts

@@ -0,0 +1,93 @@
+/**
+ * api/meta — faijs 零件名称/描述/料号 与 整体文件元数据 权威类型与 Shape 方法
+ *
+ * 设计文档：docs/plans/2026-10-05-faijs-meta-name-note-api-design.md
+ *
+ * 定位（与 api/appearance.ts 同款方法模式）：
+ * - 名称/描述设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape
+ *   实例方法（`box1.setName('…')`，复用 `asm1.solve()` 的成员调用语句形态）。
+ * - `ShapeMeta`（零件级）与 `FileMeta`（整体级）引擎无关、JSON 可序列化；
+ *   `Shape.meta` 随 Shape 走 mesh/brep 双链路，编辑器/查看器只读字段。
+ * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types
+ *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，
+ *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/meta.ts）。
+ *
+ * 命名约定（camelCase，faijs 全 TS/JS 生态）：
+ * - 零件级：`name` / `description` / `partNumber` / `metadata`（键值）。
+ * - 方法：`setName` / `setDescription` / `setPartNumber` / `setMetaField` /
+ *   `setMeta` / `getMeta`。字段名与 3MF/STEP 规范一致（不用 note）。
+ *   空串 = 清除：`setName('')` 删除 name（与「undefined 不覆盖」互补，用户可
+ *   显式去掉继承来的名称）。
+ */
+import type { Shape } from '../mesh/types.js';
+/** 零件级说明性元数据 —— 引擎无关、JSON 可序列化、随 Shape 走双链路。 */
+export interface ShapeMeta {
+    /** 零件名：3MF `<object name>` / STEP `PRODUCT().name`。 */
+    name?: string;
+    /** 描述：STEP `PRODUCT.description`；3MF 写 `faijs:description` metadatagroup。 */
+    description?: string;
+    /** 料号：3MF `<object partnumber>`；STEP `PRODUCT_IDENTIFICATION` 或 UDA。 */
+    partNumber?: string;
+    /**
+     * 自定义键值：3MF `<object><metadatagroup>`（vendor 前缀）；STEP UDA。
+     * 键为规范/厂商原始名（3MF 含命名空间前缀）；faijs 不解释值语义，
+     * 读入保留、写出回写。
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * 整体/文档级说明性元数据 —— 导入结果 / 导出选项，不挂 Shape。
+ *
+ * 不叫 `ModelMeta`：CAD 直觉里 "model" 偏单个零件（那是 `ShapeMeta` 的活）；
+ * 本类型承载整个交换文件（3MF `<model>` / STEP P21 header）的元数据，故用
+ * `FileMeta`。
+ */
+export interface FileMeta {
+    title?: string;
+    description?: string;
+    designer?: string;
+    author?: string;
+    organization?: string;
+    copyright?: string;
+    licenseTerms?: string;
+    rating?: string;
+    creationDate?: string;
+    modificationDate?: string;
+    application?: string;
+    /** 未知/厂商自定义 metadata 兜底（3MF model 级带前缀名；STEP header 其余字段）。 */
+    metadata?: Record<string, string>;
+}
+/** Shape 元数据方法签名（运行时由 attachMetaMethods 挂载；纯数据判定不受影响）。 */
+export interface ShapeMetaMethods {
+    /** 合并 meta：`{...cur, ...spec}`，spec 中 undefined 字段保留旧值。 */
+    setMeta(spec: ShapeMeta): this;
+    /** 便捷：等价 setMeta({ name })（空串视为清除）。 */
+    setName(name: string): this;
+    /** 便捷：等价 setMeta({ description })（空串视为清除）。 */
+    setDescription(description: string): this;
+    /** 便捷：等价 setMeta({ partNumber }）。 */
+    setPartNumber(partNumber: string): this;
+    /** 便捷：等价 setMeta({ metadata: {...cur.metadata, ...kv} })；值为空串的键删除。 */
+    setMetaField(key: string, value: string): this;
+    /** 读取当前 meta（可能 undefined）。 */
+    getMeta(): Readonly<ShapeMeta> | undefined;
+}
+/**
+ * 合并零件级元数据：spec 中 undefined 字段不覆盖旧值；空串覆盖为清除。
+ * @param cur 当前 meta（可为 undefined）
+ * @param spec 待合并字段（undefined 字段跳过；'' 显式清除）
+ * @returns 合并后的 meta（新对象；cur 为 undefined 时仅含 spec 非空字段）
+ */
+export declare function mergeMeta(cur: ShapeMeta | undefined, spec: ShapeMeta): ShapeMeta;
+/**
+ * 给 Shape 实例挂载元数据方法（幂等：已有 setMeta 则跳过）。
+ *
+ * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一
+ * 调用本函数，保证 mesh/brep 双支路产物都可用 `box1.setName(...)`。
+ * 方法**不序列化**（JSON 丢弃函数）；`meta` 字段随产物跨打印，编辑器/
+ * 查看器只读字段即可，不依赖方法。
+ * @param shape 产物 Shape 实例（solid/curve 产物）
+ * @returns 挂载后的 shape（类型提升为 `Shape & ShapeMetaMethods`；同一实例原地挂载）
+ */
+export declare function attachMetaMethods(shape: Shape): Shape & ShapeMetaMethods;
+//# sourceMappingURL=meta.d.ts.map

package/dist/api/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/api/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAI1C,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAC9B,uCAAuC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,8CAA8C;IAC9C,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,qCAAqC;IACrC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,sEAAsE;IACtE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9C,+BAA+B;IAC/B,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,CAAA;CAC3C;AAID;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAuBhF;AAID;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,gBAAgB,CA2BxE"}

package/dist/api/meta.js

@@ -0,0 +1,99 @@
+/**
+ * api/meta — faijs 零件名称/描述/料号 与 整体文件元数据 权威类型与 Shape 方法
+ *
+ * 设计文档：docs/plans/2026-10-05-faijs-meta-name-note-api-design.md
+ *
+ * 定位（与 api/appearance.ts 同款方法模式）：
+ * - 名称/描述设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape
+ *   实例方法（`box1.setName('…')`，复用 `asm1.solve()` 的成员调用语句形态）。
+ * - `ShapeMeta`（零件级）与 `FileMeta`（整体级）引擎无关、JSON 可序列化；
+ *   `Shape.meta` 随 Shape 走 mesh/brep 双链路，编辑器/查看器只读字段。
+ * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types
+ *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，
+ *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/meta.ts）。
+ *
+ * 命名约定（camelCase，faijs 全 TS/JS 生态）：
+ * - 零件级：`name` / `description` / `partNumber` / `metadata`（键值）。
+ * - 方法：`setName` / `setDescription` / `setPartNumber` / `setMetaField` /
+ *   `setMeta` / `getMeta`。字段名与 3MF/STEP 规范一致（不用 note）。
+ *   空串 = 清除：`setName('')` 删除 name（与「undefined 不覆盖」互补，用户可
+ *   显式去掉继承来的名称）。
+ */
+// ── 合并 ──
+/**
+ * 合并零件级元数据：spec 中 undefined 字段不覆盖旧值；空串覆盖为清除。
+ * @param cur 当前 meta（可为 undefined）
+ * @param spec 待合并字段（undefined 字段跳过；'' 显式清除）
+ * @returns 合并后的 meta（新对象；cur 为 undefined 时仅含 spec 非空字段）
+ */
+export function mergeMeta(cur, spec) {
+    const clean = {};
+    for (const [k, v] of Object.entries(spec)) {
+        if (v === undefined)
+            continue;
+        if (k === 'metadata' && v && typeof v === 'object') {
+            // 键值子合并：保留旧 metadata 的未覆盖键。
+            const base = { ...(cur?.metadata ?? {}) };
+            for (const [kk, vv] of Object.entries(v)) {
+                if (vv === '')
+                    delete base[kk]; // 空串清除该键
+                else
+                    base[kk] = vv;
+            }
+            clean[k] = base;
+            continue;
+        }
+        if (v === '')
+            clean[k] = undefined; // 空串清除顶层字段
+        else
+            clean[k] = v;
+    }
+    const merged = { ...(cur ?? {}), ...clean };
+    // 清理合并后为 undefined 的顶层键（空串清除写入 undefined）。
+    for (const k of Object.keys(merged)) {
+        if (merged[k] === undefined)
+            delete merged[k];
+    }
+    return merged;
+}
+// ── Shape 方法挂载 ──
+/**
+ * 给 Shape 实例挂载元数据方法（幂等：已有 setMeta 则跳过）。
+ *
+ * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一
+ * 调用本函数，保证 mesh/brep 双支路产物都可用 `box1.setName(...)`。
+ * 方法**不序列化**（JSON 丢弃函数）；`meta` 字段随产物跨打印，编辑器/
+ * 查看器只读字段即可，不依赖方法。
+ * @param shape 产物 Shape 实例（solid/curve 产物）
+ * @returns 挂载后的 shape（类型提升为 `Shape & ShapeMetaMethods`；同一实例原地挂载）
+ */
+export function attachMetaMethods(shape) {
+    const s = shape;
+    if (typeof s.setMeta === 'function')
+        return s;
+    s.setMeta = function setMeta(spec) {
+        this.meta = mergeMeta(this.meta, spec);
+        return this;
+    };
+    s.setName = function setName(name) {
+        this.meta = mergeMeta(this.meta, { name });
+        return this;
+    };
+    s.setDescription = function setDescription(description) {
+        this.meta = mergeMeta(this.meta, { description });
+        return this;
+    };
+    s.setPartNumber = function setPartNumber(partNumber) {
+        this.meta = mergeMeta(this.meta, { partNumber });
+        return this;
+    };
+    s.setMetaField = function setMetaField(key, value) {
+        this.meta = mergeMeta(this.meta, { metadata: { [key]: value } });
+        return this;
+    };
+    s.getMeta = function getMeta() {
+        return this.meta;
+    };
+    return s;
+}
+//# sourceMappingURL=meta.js.map

package/dist/api/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/api/meta.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/meta — faijs 零件名称/描述/料号 与 整体文件元数据 权威类型与 Shape 方法\n *\n * 设计文档：docs/plans/2026-10-05-faijs-meta-name-note-api-design.md\n *\n * 定位（与 api/appearance.ts 同款方法模式）：\n * - 名称/描述设置**不是 op**（不进 defineOp/api-namespace/args-schema），是 Shape\n *   实例方法（`box1.setName('…')`，复用 `asm1.solve()` 的成员调用语句形态）。\n * - `ShapeMeta`（零件级）与 `FileMeta`（整体级）引擎无关、JSON 可序列化；\n *   `Shape.meta` 随 Shape 走 mesh/brep 双链路，编辑器/查看器只读字段。\n * - 本文件零依赖（不 import THREE / occt / store）；唯一 import 是 mesh/types\n *   的 `Shape` 类型（type-only），mesh/types 亦只 type-import 本文件的类型，\n *   两者为类型环、无运行时环（值依赖单向：shape.ts → api/meta.ts）。\n *\n * 命名约定（camelCase，faijs 全 TS/JS 生态）：\n * - 零件级：`name` / `description` / `partNumber` / `metadata`（键值）。\n * - 方法：`setName` / `setDescription` / `setPartNumber` / `setMetaField` /\n *   `setMeta` / `getMeta`。字段名与 3MF/STEP 规范一致（不用 note）。\n *   空串 = 清除：`setName('')` 删除 name（与「undefined 不覆盖」互补，用户可\n *   显式去掉继承来的名称）。\n */\n\nimport type { Shape } from '../mesh/types'\n\n// ── 类型 ──\n\n/** 零件级说明性元数据 —— 引擎无关、JSON 可序列化、随 Shape 走双链路。 */\nexport interface ShapeMeta {\n  /** 零件名：3MF `<object name>` / STEP `PRODUCT().name`。 */\n  name?: string\n  /** 描述：STEP `PRODUCT.description`；3MF 写 `faijs:description` metadatagroup。 */\n  description?: string\n  /** 料号：3MF `<object partnumber>`；STEP `PRODUCT_IDENTIFICATION` 或 UDA。 */\n  partNumber?: string\n  /**\n   * 自定义键值：3MF `<object><metadatagroup>`（vendor 前缀）；STEP UDA。\n   * 键为规范/厂商原始名（3MF 含命名空间前缀）；faijs 不解释值语义，\n   * 读入保留、写出回写。\n   */\n  metadata?: Record<string, string>\n}\n\n/**\n * 整体/文档级说明性元数据 —— 导入结果 / 导出选项，不挂 Shape。\n *\n * 不叫 `ModelMeta`：CAD 直觉里 \"model\" 偏单个零件（那是 `ShapeMeta` 的活）；\n * 本类型承载整个交换文件（3MF `<model>` / STEP P21 header）的元数据，故用\n * `FileMeta`。\n */\nexport interface FileMeta {\n  title?: string // 3MF Title / STEP FILE_NAME.name\n  description?: string      // 3MF Description / STEP FILE_DESCRIPTION.description\n  designer?: string         // 3MF Designer / STEP FILE_NAME.originator\n  author?: string           // STEP FILE_NAME.author（3MF 无对应；跨格式不互转）\n  organization?: string     // STEP FILE_NAME.organization（3MF 无对应）\n  copyright?: string        // 3MF Copyright（STEP 无标准位置）\n  licenseTerms?: string     // 3MF LicenseTerms（STEP 无标准位置）\n  rating?: string           // 3MF Rating（STEP 无标准位置）\n  creationDate?: string     // 3MF CreationDate / STEP FILE_NAME.timestamp\n  modificationDate?: string // 3MF ModificationDate（STEP 无标准位置）\n  application?: string      // 3MF Application / STEP FILE_NAME.preprocessor\n  /** 未知/厂商自定义 metadata 兜底（3MF model 级带前缀名；STEP header 其余字段）。 */\n  metadata?: Record<string, string>\n}\n\n/** Shape 元数据方法签名（运行时由 attachMetaMethods 挂载；纯数据判定不受影响）。 */\nexport interface ShapeMetaMethods {\n  /** 合并 meta：`{...cur, ...spec}`，spec 中 undefined 字段保留旧值。 */\n  setMeta(spec: ShapeMeta): this\n  /** 便捷：等价 setMeta({ name })（空串视为清除）。 */\n  setName(name: string): this\n  /** 便捷：等价 setMeta({ description })（空串视为清除）。 */\n  setDescription(description: string): this\n  /** 便捷：等价 setMeta({ partNumber }）。 */\n  setPartNumber(partNumber: string): this\n  /** 便捷：等价 setMeta({ metadata: {...cur.metadata, ...kv} })；值为空串的键删除。 */\n  setMetaField(key: string, value: string): this\n  /** 读取当前 meta（可能 undefined）。 */\n  getMeta(): Readonly<ShapeMeta> | undefined\n}\n\n// ── 合并 ──\n\n/**\n * 合并零件级元数据：spec 中 undefined 字段不覆盖旧值；空串覆盖为清除。\n * @param cur 当前 meta（可为 undefined）\n * @param spec 待合并字段（undefined 字段跳过；'' 显式清除）\n * @returns 合并后的 meta（新对象；cur 为 undefined 时仅含 spec 非空字段）\n */\nexport function mergeMeta(cur: ShapeMeta | undefined, spec: ShapeMeta): ShapeMeta {\n  const clean: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(spec)) {\n    if (v === undefined) continue\n    if (k === 'metadata' && v && typeof v === 'object') {\n      // 键值子合并：保留旧 metadata 的未覆盖键。\n      const base: Record<string, string> = { ...((cur?.metadata as Record<string, string> | undefined) ?? {}) }\n      for (const [kk, vv] of Object.entries(v as Record<string, string>)) {\n        if (vv === '') delete base[kk] // 空串清除该键\n        else base[kk] = vv\n      }\n      clean[k] = base\n      continue\n    }\n    if (v === '') clean[k] = undefined as unknown as string // 空串清除顶层字段\n    else clean[k] = v\n  }\n  const merged = { ...(cur ?? {}), ...clean } as ShapeMeta\n  // 清理合并后为 undefined 的顶层键（空串清除写入 undefined）。\n  for (const k of Object.keys(merged)) {\n    if ((merged as Record<string, unknown>)[k] === undefined) delete (merged as Record<string, unknown>)[k]\n  }\n  return merged\n}\n\n// ── Shape 方法挂载 ──\n\n/**\n * 给 Shape 实例挂载元数据方法（幂等：已有 setMeta 则跳过）。\n *\n * 所有产物构造点（solid/curve → fromBrep/fromMeshSolid/fromBrepCurve）统一\n * 调用本函数，保证 mesh/brep 双支路产物都可用 `box1.setName(...)`。\n * 方法**不序列化**（JSON 丢弃函数）；`meta` 字段随产物跨打印，编辑器/\n * 查看器只读字段即可，不依赖方法。\n * @param shape 产物 Shape 实例（solid/curve 产物）\n * @returns 挂载后的 shape（类型提升为 `Shape & ShapeMetaMethods`；同一实例原地挂载）\n */\nexport function attachMetaMethods(shape: Shape): Shape & ShapeMetaMethods {\n  const s = shape as Shape & ShapeMetaMethods\n  if (typeof s.setMeta === 'function') return s\n  s.setMeta = function setMeta(this: Shape & ShapeMetaMethods, spec: ShapeMeta) {\n    this.meta = mergeMeta(this.meta, spec)\n    return this\n  }\n  s.setName = function setName(this: Shape & ShapeMetaMethods, name: string) {\n    this.meta = mergeMeta(this.meta, { name })\n    return this\n  }\n  s.setDescription = function setDescription(this: Shape & ShapeMetaMethods, description: string) {\n    this.meta = mergeMeta(this.meta, { description })\n    return this\n  }\n  s.setPartNumber = function setPartNumber(this: Shape & ShapeMetaMethods, partNumber: string) {\n    this.meta = mergeMeta(this.meta, { partNumber })\n    return this\n  }\n  s.setMetaField = function setMetaField(this: Shape & ShapeMetaMethods, key: string, value: string) {\n    this.meta = mergeMeta(this.meta, { metadata: { [key]: value } })\n    return this\n  }\n  s.getMeta = function getMeta(this: Shape) {\n    return this.meta\n  }\n  return s\n}"]}

package/dist/api/pattern.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）
+ * api pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）
  *
  * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径
  * 用质心聚类把结果面按份数 k 分组、回投影到输入面角色，产出 `replica[k]/<inner>`。
@@ -16,8 +16,10 @@ import type { Shape, Vec3 } from '../mesh/types.js';
  * @async true
  * @qual ok
  * @name linearPattern
- * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。结果面按份数 k 回投影到输入面
- *       角色，产出 `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）。
+ * @note BREP 输入走质心聚类回投，结果面按份数 k 回投影到输入面角色，产出
+ *       `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）；**网格实体**输入走网格后端，
+ *       阵列后融合为一个新的网格零件，近似拓扑没有 role 层故不产 replica 命名。
+ *       裸网格输入仍抛 `E_MESH_UNSUPPORTED`。
  * @returns Shape 所有副本 fused 后的几何。
  * @param input - 目标几何。type:Shape required:true
  * @param direction - 阵列方向。type:[x,y,z] required:true

package/dist/api/pattern.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/api/pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAoDhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;;CAUxB,CAAA"}
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/api/pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AA0EhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa;;CAiBxB,CAAA"}

package/dist/api/pattern.js

@@ -1,5 +1,5 @@
 /**
- * stdlib pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）
+ * api pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）
  *
  * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径
  * 用质心聚类把结果面按份数 k 分组、回投影到输入面角色，产出 `replica[k]/<inner>`。
@@ -14,6 +14,7 @@ import { getBrepApi } from '../brep/handle-bridge.js';
 import { fromBrep, brepOf } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { buildReplicaRoleTable } from './internal/replica-role-table.js';
+import { meshPatternProduct, meshSolidBasicEntry } from './internal/mesh-solid-op.js';
 /** 归一化向量（零向量 → [0,0,1] 兜底）。 */
 function norm(v) {
     const len = Math.hypot(v[0], v[1], v[2]);
@@ -26,7 +27,7 @@ function linearPatternBrep(input, direction, count, spacing) {
     const kernel = getBrepApi();
     const inputSolid = brepOf(input);
     if (!inputSolid)
-        throw new Error('[stdlib/pattern] input is not BREP');
+        throw new Error('[api/pattern] input is not BREP');
     // Phase 1.6：origin = 本次语句 StmtId。
     const outStmt = String(getCurrentStmt()?.id ?? '');
     // 取 count 份副本。Phase 2：BrepEngineApi.linearPattern 契约统一返回 BrepHandle[]
@@ -53,6 +54,24 @@ function linearPatternBrep(input, direction, count, spacing) {
     const roleTable = buildReplicaRoleTable(kernel, input, resultSolid, replicas, outStmt);
     return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, roleTable });
 }
+/**
+ * 网格实体路径：沿 direction 阵列并把副本融成一个网格零件。
+ *
+ * 与 BREP 路径同一条内核契约（`linearPattern` 返回含原位置在内的 count 个句柄，
+ * 再 `fuseAll` 成一体），差别只在**没有 quality 面角色可回投**——近似拓扑没有 role
+ * 层，故不产 `replica[k]/<inner>` 命名（如实缺席，不伪造恒等映射）。
+ *
+ * @param input - the mesh-solid input.
+ * @param direction - the pattern direction.
+ * @param count - total number of copies (including the original).
+ * @param spacing - the spacing between copies.
+ * @returns the fused mesh solid as a new mesh part.
+ */
+function linearPatternMeshSolid(input, direction, count, spacing) {
+    const entry = meshSolidBasicEntry(input, 'linearPattern');
+    const d = norm(direction);
+    return meshPatternProduct(entry, 'linearPattern', 'E_PATTERN_FAILED', () => entry.kernel.linearPattern(entry.solid, { x: d[0], y: d[1], z: d[2] }, spacing, count));
+}
 /**
  * 线性阵列：沿 direction 复制 count 份（含原位置）。
  * @group 特征
@@ -60,8 +79,10 @@ function linearPatternBrep(input, direction, count, spacing) {
  * @async true
  * @qual ok
  * @name linearPattern
- * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。结果面按份数 k 回投影到输入面
- *       角色，产出 `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）。
+ * @note BREP 输入走质心聚类回投，结果面按份数 k 回投影到输入面角色，产出
+ *       `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）；**网格实体**输入走网格后端，
+ *       阵列后融合为一个新的网格零件，近似拓扑没有 role 层故不产 replica 命名。
+ *       裸网格输入仍抛 `E_MESH_UNSUPPORTED`。
  * @returns Shape 所有副本 fused 后的几何。
  * @param input - 目标几何。type:Shape required:true
  * @param direction - 阵列方向。type:[x,y,z] required:true
@@ -71,6 +92,13 @@ function linearPatternBrep(input, direction, count, spacing) {
  * const p = await cad.linearPattern(part0, [1, 0, 0], 3, 20)
  */
 export const linearPattern = defineOp({
+    meshEngines: ['brepkit'],
+    mesh(input, direction, count, spacing) {
+        keep(input);
+        // 裸网格输入由 `meshSolidBasicEntry` 如实拒绝（近似链没有 role 层，也没有句柄）——
+        // 这里不复刻一遍判定，失败面只有一处。
+        return linearPatternMeshSolid(input, direction, count, spacing);
+    },
     brep(input, direction, count, spacing) {
         // copy-like keep semantics: replicate ops preserve their source shape.
         keep(input);

package/dist/api/pattern.js.map

@@ -1 +1 @@
-{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../../src/api/pattern.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）\n *\n * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径\n * 用质心聚类把结果面按份数 k 分组、回投影到输入面角色，产出 `replica[k]/<inner>`。\n *\n * 机制（无内核历史，纯几何推理）：pattern 的每份副本都是输入的精确平移，副本面\n * 几何相同但质心不同。结果面沿 pattern 方向投影得到份数坐标 t，四舍五入到 spacing\n * 倍数即得 k；再按「面内坐标」（centroid − t·dir）匹配输入面对应面，回投其 inner role。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getCurrentStmt, keep } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { buildReplicaRoleTable, type ReplicaTransform } from './internal/replica-role-table'\n\n/** 归一化向量（零向量 → [0,0,1] 兜底）。 */\nfunction norm(v: Vec3): [number, number, number] {\n  const len = Math.hypot(v[0], v[1], v[2])\n  if (len < 1e-9) return [0, 0, 1]\n  return [v[0] / len, v[1] / len, v[2] / len]\n}\n\n/** BREP 路径：沿 direction 复制 count 份，质心聚类回投输入面角色。 */\nfunction linearPatternBrep(input: Shape, direction: Vec3, count: number, spacing: number): Shape {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[stdlib/pattern] input is not BREP')\n\n  // Phase 1.6：origin = 本次语句 StmtId。\n  const outStmt = String(getCurrentStmt()?.id ?? '')\n\n  // 取 count 份副本。Phase 2：BrepEngineApi.linearPattern 契约统一返回 BrepHandle[]\n  // （两内核原生都返回 compound，由适配器拆成数组）——不再有「单句柄 fused」形态。\n  const dir = norm(direction)\n  const raw = kernel.linearPattern(inputSolid, { x: dir[0], y: dir[1], z: dir[2] }, spacing, count)\n\n  let resultSolid: BrepHandle\n  try {\n    resultSolid = kernel.fuseAll(raw)\n  } finally {\n    for (const c of raw) kernel.release(c)\n  }\n\n  // 第 k 份副本是输入沿 dir 平移 k*spacing：质心反投回输入坐标系（T_k⁻¹）。\n  const replicas: ReplicaTransform[] = []\n  for (let k = 0; k < count; k++) {\n    const off = k * spacing\n    replicas.push({\n      label: `replica[${k}]`,\n      inverse: (c) => ({ x: c.x - off * dir[0], y: c.y - off * dir[1], z: c.z - off * dir[2] }),\n    })\n  }\n  const roleTable = buildReplicaRoleTable(kernel, input, resultSolid, replicas, outStmt)\n\n  return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, roleTable })\n}\n\n/**\n * 线性阵列：沿 direction 复制 count 份（含原位置）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name linearPattern\n * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。结果面按份数 k 回投影到输入面\n *       角色，产出 `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）。\n * @returns Shape 所有副本 fused 后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param direction - 阵列方向。type:[x,y,z] required:true\n * @param count - 副本总数（含原位置）。type:number required:true\n * @param spacing - 副本间距。type:number required:true\n * @example\n * const p = await cad.linearPattern(part0, [1, 0, 0], 3, 20)\n */\nexport const linearPattern = defineOp({\n  brep(input: Shape, direction: Vec3, count: number, spacing: number) {\n    // copy-like keep semantics: replicate ops preserve their source shape.\n    keep(input)\n    return linearPatternBrep(input, direction, count, spacing)\n  },\n  // Phase 1（Brep 引擎可切换重构）：能力前置判定——linearPattern 需要内核的\n  // 线性阵列方法（BrepMethodKind），brepkit 装配下缺失时执行前静态报错。\n  capabilities: ['linearPattern'],\n  naming: { kind: 'replicate', k: 0 } as Provenance,\n})\n"]}
+{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../../src/api/pattern.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）\n *\n * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径\n * 用质心聚类把结果面按份数 k 分组、回投影到输入面角色，产出 `replica[k]/<inner>`。\n *\n * 机制（无内核历史，纯几何推理）：pattern 的每份副本都是输入的精确平移，副本面\n * 几何相同但质心不同。结果面沿 pattern 方向投影得到份数坐标 t，四舍五入到 spacing\n * 倍数即得 k；再按「面内坐标」（centroid − t·dir）匹配输入面对应面，回投其 inner role。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getCurrentStmt, keep } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { buildReplicaRoleTable, type ReplicaTransform } from './internal/replica-role-table'\nimport { meshPatternProduct, meshSolidBasicEntry } from './internal/mesh-solid-op'\n\n/** 归一化向量（零向量 → [0,0,1] 兜底）。 */\nfunction norm(v: Vec3): [number, number, number] {\n  const len = Math.hypot(v[0], v[1], v[2])\n  if (len < 1e-9) return [0, 0, 1]\n  return [v[0] / len, v[1] / len, v[2] / len]\n}\n\n/** BREP 路径：沿 direction 复制 count 份，质心聚类回投输入面角色。 */\nfunction linearPatternBrep(input: Shape, direction: Vec3, count: number, spacing: number): Shape {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[api/pattern] input is not BREP')\n\n  // Phase 1.6：origin = 本次语句 StmtId。\n  const outStmt = String(getCurrentStmt()?.id ?? '')\n\n  // 取 count 份副本。Phase 2：BrepEngineApi.linearPattern 契约统一返回 BrepHandle[]\n  // （两内核原生都返回 compound，由适配器拆成数组）——不再有「单句柄 fused」形态。\n  const dir = norm(direction)\n  const raw = kernel.linearPattern(inputSolid, { x: dir[0], y: dir[1], z: dir[2] }, spacing, count)\n\n  let resultSolid: BrepHandle\n  try {\n    resultSolid = kernel.fuseAll(raw)\n  } finally {\n    for (const c of raw) kernel.release(c)\n  }\n\n  // 第 k 份副本是输入沿 dir 平移 k*spacing：质心反投回输入坐标系（T_k⁻¹）。\n  const replicas: ReplicaTransform[] = []\n  for (let k = 0; k < count; k++) {\n    const off = k * spacing\n    replicas.push({\n      label: `replica[${k}]`,\n      inverse: (c) => ({ x: c.x - off * dir[0], y: c.y - off * dir[1], z: c.z - off * dir[2] }),\n    })\n  }\n  const roleTable = buildReplicaRoleTable(kernel, input, resultSolid, replicas, outStmt)\n\n  return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, roleTable })\n}\n\n/**\n * 网格实体路径：沿 direction 阵列并把副本融成一个网格零件。\n *\n * 与 BREP 路径同一条内核契约（`linearPattern` 返回含原位置在内的 count 个句柄，\n * 再 `fuseAll` 成一体），差别只在**没有 quality 面角色可回投**——近似拓扑没有 role\n * 层，故不产 `replica[k]/<inner>` 命名（如实缺席，不伪造恒等映射）。\n *\n * @param input - the mesh-solid input.\n * @param direction - the pattern direction.\n * @param count - total number of copies (including the original).\n * @param spacing - the spacing between copies.\n * @returns the fused mesh solid as a new mesh part.\n */\nfunction linearPatternMeshSolid(input: Shape, direction: Vec3, count: number, spacing: number): Shape {\n  const entry = meshSolidBasicEntry(input, 'linearPattern')\n  const d = norm(direction)\n  return meshPatternProduct(entry, 'linearPattern', 'E_PATTERN_FAILED', () =>\n    entry.kernel.linearPattern(entry.solid, { x: d[0], y: d[1], z: d[2] }, spacing, count),\n  )\n}\n\n/**\n * 线性阵列：沿 direction 复制 count 份（含原位置）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name linearPattern\n * @note BREP 输入走质心聚类回投，结果面按份数 k 回投影到输入面角色，产出\n *       `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）；**网格实体**输入走网格后端，\n *       阵列后融合为一个新的网格零件，近似拓扑没有 role 层故不产 replica 命名。\n *       裸网格输入仍抛 `E_MESH_UNSUPPORTED`。\n * @returns Shape 所有副本 fused 后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param direction - 阵列方向。type:[x,y,z] required:true\n * @param count - 副本总数（含原位置）。type:number required:true\n * @param spacing - 副本间距。type:number required:true\n * @example\n * const p = await cad.linearPattern(part0, [1, 0, 0], 3, 20)\n */\nexport const linearPattern = defineOp({\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, direction: Vec3, count: number, spacing: number) {\n    keep(input)\n    // 裸网格输入由 `meshSolidBasicEntry` 如实拒绝（近似链没有 role 层，也没有句柄）——\n    // 这里不复刻一遍判定，失败面只有一处。\n    return linearPatternMeshSolid(input, direction, count, spacing)\n  },\n  brep(input: Shape, direction: Vec3, count: number, spacing: number) {\n    // copy-like keep semantics: replicate ops preserve their source shape.\n    keep(input)\n    return linearPatternBrep(input, direction, count, spacing)\n  },\n  // Phase 1（Brep 引擎可切换重构）：能力前置判定——linearPattern 需要内核的\n  // 线性阵列方法（BrepMethodKind），brepkit 装配下缺失时执行前静态报错。\n  capabilities: ['linearPattern'],\n  naming: { kind: 'replicate', k: 0 } as Provenance,\n})\n"]}

package/dist/api/place.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib place — 平台刚性放置 op（H11 / 方案 §4.3）
+ * api place — 平台刚性放置 op（H11 / 方案 §4.3）
  *
  *
  * 一个刚体变换：先绕局部原点按 `rotation`（四元数）旋转，再平移 `position`

package/dist/api/place.js

@@ -1,5 +1,5 @@
 /**
- * stdlib place — 平台刚性放置 op（H11 / 方案 §4.3）
+ * api place — 平台刚性放置 op（H11 / 方案 §4.3）
  *
  *
  * 一个刚体变换：先绕局部原点按 `rotation`（四元数）旋转，再平移 `position`

package/dist/api/place.js.map

@@ -1 +1 @@
-{"version":3,"file":"place.js","sourceRoot":"","sources":["../../src/api/place.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib place — 平台刚性放置 op（H11 / 方案 §4.3）\n *\n *\n * 一个刚体变换：先绕局部原点按 `rotation`（四元数）旋转，再平移 `position`\n * （= FreeCAD `Placement` 的 T(P)∘R(Q)）。不接受 pivot——FCStd 语义就是绕局部原点。\n *\n * 路径：\n * - brep 路径：`applyTransformBrep(kernel, solid, quat, [0,0,0], position)`\n *   （复用 api/compound 装配求解已标定的代码，矩阵约定见 §4.3 必做标定）。\n * - mesh 路径：`applyTransform`（与 brep 路径同数学：p' = R·(p−0) + 0 + t）。\n *   四元数→row-major 3×3 用手动 Hamilton 公式（与 THREE / FreeCAD gp_Quaternion\n *   同约定），不引入 three 依赖。\n *\n * 变换不改变拓扑，面 ordinal 不变——roleTable 恒等传播（与 transform.ts 同）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf, inputRoleTable, isCompoundLike } from '../shape'\nimport { solidToShape, applyTransformBrep } from '../brep/brep-ops'\nimport { applyTransform } from '../mesh/rigid-transform'\nimport { identityEvolution, identityHashEvolution } from '../brep/face-evolution'\nimport { propagateAllOrigins } from '../topology/naming/roles'\nimport type { RoleTable } from '../topology/naming/types'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 四元数 (x,y,z,w) → row-major 3×3 旋转矩阵（Hamilton，与 THREE/FreeCAD 同约定）。 */\nfunction quatToMat3(q: [number, number, number, number]): number[] {\n  const [x, y, z, w] = q\n  const x2 = x * x\n  const y2 = y * y\n  const z2 = z * z\n  return [\n    1 - 2 * (y2 + z2), 2 * (x * y - w * z), 2 * (x * z + w * y),\n    2 * (x * y + w * z), 1 - 2 * (x2 + z2), 2 * (y * z - w * x),\n    2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x2 + y2),\n  ]\n}\n\n/** mesh 路径：展平结构 compound 子节点，逐子 mesh 变换后合并。 */\nfunction placeMesh(\n  input: Shape,\n  rotation: [number, number, number, number],\n  position: [number, number, number],\n  mat3: number[],\n): Shape {\n  const collect = (s: Shape, out: Shape[]): void => {\n    if (isCompoundLike(s) && (s as { children?: Shape[] }).children) {\n      for (const c of (s as { children: Shape[] }).children) collect(c, out)\n      return\n    }\n    if (s.positions && s.indices) out.push(s)\n  }\n  const subs: Shape[] = []\n  collect(input, subs)\n  const positions: number[] = []\n  const indices: number[] = []\n  for (const sub of subs) {\n    const t = applyTransform(sub, rotation, [0, 0, 0], position, mat3)\n    const base = positions.length / 3\n    positions.push(...t.positions)\n    for (let i = 0; i < t.indices.length; i++) indices.push(t.indices[i] + base)\n  }\n  return { positions: new Float32Array(positions), indices: new Uint32Array(indices) }\n}\n\n/** brep 路径：刚体变换实体 + 恒等面演化 + 恒等 roleTable 传播 + 三角化 + fromBrep 登记。 */\nfunction placeBrep(input: Shape, rotation: [number, number, number, number], position: [number, number, number]): Shape {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[api/place] input is not BREP')\n\n  const resultSolid = applyTransformBrep(kernel, inputSolid, rotation, [0, 0, 0], position)\n\n  const inputTable = inputRoleTable(input) as RoleTable | undefined\n  let roleTable: RoleTable | undefined\n  if (inputTable && inputTable.size > 0) {\n    roleTable = propagateAllOrigins(inputTable, identityHashEvolution(kernel, inputSolid, resultSolid))\n  }\n\n  return fromBrep(solidToShape(kernel, resultSolid), {\n    solid: resultSolid,\n    faceEvolution: identityEvolution(kernel, resultSolid),\n    roleTable,\n  })\n}\n\n/**\n * 刚性放置几何体：旋转（四元数，绕局部原点）后平移。两者皆可缺省 = 恒等。\n * @group 变换\n * @inputs 1\n * @async false\n * @qual ok\n * @name place\n * @returns Shape 放置后的几何（持 OCCT 句柄，可继续变换/导出）。\n * @param input - 目标几何。type:Shape required:true\n * @param params.rotation - 旋转四元数 [x,y,z,w]（Hamilton，绕局部原点）。type:[number,number,number,number]\n * @param params.position - 平移向量 [x,y,z]（mm）。type:[number,number,number]\n * @example\n * const p = cad.place(part0, { rotation: [0, 0, Math.sin(Math.PI/4), Math.cos(Math.PI/4)], position: [10, 0, 0] })\n */\nexport const place = defineOp({\n  name: 'place',\n  mesh: (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/place] no input geometry')\n    const rotation = (params.rotation as [number, number, number, number]) ?? [0, 0, 0, 1]\n    const position = (params.position as [number, number, number]) ?? [0, 0, 0]\n    return placeMesh(input, rotation, position, quatToMat3(rotation))\n  },\n  brep: (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/place] no input geometry')\n    const rotation = (params.rotation as [number, number, number, number]) ?? [0, 0, 0, 1]\n    const position = (params.position as [number, number, number]) ?? [0, 0, 0]\n    return placeBrep(input, rotation, position)\n  },\n  schema: { position: 'vec3?', rotation: 'quat?' },\n  naming: { kind: 'identity' } as Provenance,\n})\n"]}
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../src/api/place.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api place — 平台刚性放置 op（H11 / 方案 §4.3）\n *\n *\n * 一个刚体变换：先绕局部原点按 `rotation`（四元数）旋转，再平移 `position`\n * （= FreeCAD `Placement` 的 T(P)∘R(Q)）。不接受 pivot——FCStd 语义就是绕局部原点。\n *\n * 路径：\n * - brep 路径：`applyTransformBrep(kernel, solid, quat, [0,0,0], position)`\n *   （复用 api/compound 装配求解已标定的代码，矩阵约定见 §4.3 必做标定）。\n * - mesh 路径：`applyTransform`（与 brep 路径同数学：p' = R·(p−0) + 0 + t）。\n *   四元数→row-major 3×3 用手动 Hamilton 公式（与 THREE / FreeCAD gp_Quaternion\n *   同约定），不引入 three 依赖。\n *\n * 变换不改变拓扑，面 ordinal 不变——roleTable 恒等传播（与 transform.ts 同）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrep, brepOf, inputRoleTable, isCompoundLike } from '../shape'\nimport { solidToShape, applyTransformBrep } from '../brep/brep-ops'\nimport { applyTransform } from '../mesh/rigid-transform'\nimport { identityEvolution, identityHashEvolution } from '../brep/face-evolution'\nimport { propagateAllOrigins } from '../topology/naming/roles'\nimport type { RoleTable } from '../topology/naming/types'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 四元数 (x,y,z,w) → row-major 3×3 旋转矩阵（Hamilton，与 THREE/FreeCAD 同约定）。 */\nfunction quatToMat3(q: [number, number, number, number]): number[] {\n  const [x, y, z, w] = q\n  const x2 = x * x\n  const y2 = y * y\n  const z2 = z * z\n  return [\n    1 - 2 * (y2 + z2), 2 * (x * y - w * z), 2 * (x * z + w * y),\n    2 * (x * y + w * z), 1 - 2 * (x2 + z2), 2 * (y * z - w * x),\n    2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x2 + y2),\n  ]\n}\n\n/** mesh 路径：展平结构 compound 子节点，逐子 mesh 变换后合并。 */\nfunction placeMesh(\n  input: Shape,\n  rotation: [number, number, number, number],\n  position: [number, number, number],\n  mat3: number[],\n): Shape {\n  const collect = (s: Shape, out: Shape[]): void => {\n    if (isCompoundLike(s) && (s as { children?: Shape[] }).children) {\n      for (const c of (s as { children: Shape[] }).children) collect(c, out)\n      return\n    }\n    if (s.positions && s.indices) out.push(s)\n  }\n  const subs: Shape[] = []\n  collect(input, subs)\n  const positions: number[] = []\n  const indices: number[] = []\n  for (const sub of subs) {\n    const t = applyTransform(sub, rotation, [0, 0, 0], position, mat3)\n    const base = positions.length / 3\n    positions.push(...t.positions)\n    for (let i = 0; i < t.indices.length; i++) indices.push(t.indices[i] + base)\n  }\n  return { positions: new Float32Array(positions), indices: new Uint32Array(indices) }\n}\n\n/** brep 路径：刚体变换实体 + 恒等面演化 + 恒等 roleTable 传播 + 三角化 + fromBrep 登记。 */\nfunction placeBrep(input: Shape, rotation: [number, number, number, number], position: [number, number, number]): Shape {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[api/place] input is not BREP')\n\n  const resultSolid = applyTransformBrep(kernel, inputSolid, rotation, [0, 0, 0], position)\n\n  const inputTable = inputRoleTable(input) as RoleTable | undefined\n  let roleTable: RoleTable | undefined\n  if (inputTable && inputTable.size > 0) {\n    roleTable = propagateAllOrigins(inputTable, identityHashEvolution(kernel, inputSolid, resultSolid))\n  }\n\n  return fromBrep(solidToShape(kernel, resultSolid), {\n    solid: resultSolid,\n    faceEvolution: identityEvolution(kernel, resultSolid),\n    roleTable,\n  })\n}\n\n/**\n * 刚性放置几何体：旋转（四元数，绕局部原点）后平移。两者皆可缺省 = 恒等。\n * @group 变换\n * @inputs 1\n * @async false\n * @qual ok\n * @name place\n * @returns Shape 放置后的几何（持 OCCT 句柄，可继续变换/导出）。\n * @param input - 目标几何。type:Shape required:true\n * @param params.rotation - 旋转四元数 [x,y,z,w]（Hamilton，绕局部原点）。type:[number,number,number,number]\n * @param params.position - 平移向量 [x,y,z]（mm）。type:[number,number,number]\n * @example\n * const p = cad.place(part0, { rotation: [0, 0, Math.sin(Math.PI/4), Math.cos(Math.PI/4)], position: [10, 0, 0] })\n */\nexport const place = defineOp({\n  name: 'place',\n  mesh: (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/place] no input geometry')\n    const rotation = (params.rotation as [number, number, number, number]) ?? [0, 0, 0, 1]\n    const position = (params.position as [number, number, number]) ?? [0, 0, 0]\n    return placeMesh(input, rotation, position, quatToMat3(rotation))\n  },\n  brep: (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[api/place] no input geometry')\n    const rotation = (params.rotation as [number, number, number, number]) ?? [0, 0, 0, 1]\n    const position = (params.position as [number, number, number]) ?? [0, 0, 0]\n    return placeBrep(input, rotation, position)\n  },\n  schema: { position: 'vec3?', rotation: 'quat?' },\n  naming: { kind: 'identity' } as Provenance,\n})\n"]}

package/dist/api/primitives.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib primitives — 基本体创建库函数（box/sphere/cylinder/cone/wedge）
+ * api primitives — 基本体创建库函数（box/sphere/cylinder/cone/wedge）
  *
  *
  * dispatchPath 静态判定 brep/mesh，产物经 solid()/fromBrep() 构造器创建。

package/dist/api/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/api/primitives.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAgB1C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS1E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKvE;AAmBD;;;;;;;;;;;;;;;;;;;;;;KAsBK;AACL,eAAO,MAAM,GAAG;;CAwBd,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM;;CAgBjB,CAAA;AAWF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,QAAQ;;CAgBnB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,IAAI;;CAuBf,CAAA;AAEF;;;;;;;;;;;;;;;;IAgBI;AACJ,eAAO,MAAM,KAAK;;CAchB,CAAA"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/api/primitives.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAmB1C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS1E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKvE;AAyHD;;;;;;;;;;;;;;;;;;;;;;KAsBK;AACL,eAAO,MAAM,GAAG;;CAwBd,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM;;CAgBjB,CAAA;AAWF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,QAAQ;;CAgBnB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,IAAI;;CAuBf,CAAA;AAEF;;;;;;;;;;;;;;;;IAgBI;AACJ,eAAO,MAAM,KAAK;;CAchB,CAAA"}