@faicad/faijs 0.13.2 → 0.14.1

package/dist/api/import-brep.js

@@ -0,0 +1,72 @@
+/**
+ * stdlib import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）
+ *
+ *
+ * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：
+ * - `cad.load` 是 ../3d_editor 的「文件导入 Feature」（key/path/url 三键分流、
+ *   语句位置约定、partIndex 画布语义），且历史契约要求实体。
+ * - `cad.import_brep` 是 faijs **平台**几何 op：单一 asset 引用（容器资产名，
+ *   去扩展名），语义是「把冻结的 BREP 载体装成持 OCCT 句柄的 Shape」。
+ *
+ * 非实体（wire/face/shell）一等公民（C6）：不要求实体，始终 allowNonSolid。
+ * 需要实体的操作（布尔、up-to 目标面）在使用点报错（V-C8）。
+ *
+ * BREP 专属：`.brp` 无 mesh 解析器；mesh / 无内核模式抛 E_BREP_UNSUPPORTED。
+ */
+import { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state.js';
+import { OpError } from './internal/result-unwrap.js';
+import { loadBrep } from '../brep/brep-ops.js';
+import { fromBrep } from '../shape.js';
+/**
+ * 平台 BREP 资产导入：把容器 `assets/` 里的冻结 BREP 载体装成持 OCCT 句柄的 Shape。
+ *
+ * `asset` = 资产名（去扩展名，沿用 `FsAssetResolver` 的 `key = basename(file)` 规则），
+ * 由宿主资产解析器按 key 解析（与 `cad.load` 同套解析器）。
+ *
+ * @group 创建
+ * @inputs 0
+ * @async true
+ * @qual ok
+ * @name import_brep
+ * @param params.asset - 容器资产名（去扩展名）。type:string required:true
+ * @note 非实体一等（C6）：wire/face/shell 一律可导入，本 op 不设 `allowNonSolid` 一类开关。需要实体的 op（布尔、up-to 目标面）在**使用点**报错，而不是在导入点拒绝。
+ * @note 这是**平台**资产导入 op。编辑器 `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流 + 画布语句位置语义），平台侧不要复用它（C7）。
+ * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。
+ * @example
+ * const a = await cad.import_brep({ asset: 'Array001.Shape' })
+ */
+export async function import_brep(params) {
+    const assets = getBackends().assets;
+    if (!assets || !assets.resolveByKey) {
+        throw new OpError('import_brep', 'E_OP_FAILED', '[api/import_brep] assets backend is required');
+    }
+    const asset = params.asset;
+    if (typeof asset !== 'string' || asset.length === 0) {
+        throw new OpError('import_brep', 'E_ARGS', '[api/import_brep] asset name (string) is required');
+    }
+    const buffer = (await assets.resolveByKey(asset)).bytes;
+    const { kernel: kernels } = getBackends();
+    const kernel = kernels.brep;
+    if (!kernel) {
+        throw new BrepUnsupportedError('E_BREP_UNSUPPORTED: import_brep requires an OCCT kernel (.brp assets have no mesh parser)');
+    }
+    // C6：非实体一等公民——始终允许导入 wire/face/shell（allowNonSolid=true）。
+    const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true });
+    // E3（H12）：链根建 roleTable（与 primitives.ts 同源机制）——冻结资产是
+    // 无名形状，没有这张表下游 edgeRef/faceRef 无法解析（nameless-shape 缺陷）。
+    // Phase 1.6：origin 用导入语句的 StmtId——同一资产导入两次是两条语句，
+    // 各自产出的面天然分属不同 origin（旧实现用资产名，两次导入撞 origin）。
+    // 3.8: imported:<i> — imported faces have no semantic names (arbitrary geometry),
+    // named by enumeration order in the imported file (stable across re-import of same file).
+    const stmtId = String(getCurrentStmt()?.id ?? '');
+    const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647);
+    const roles = new Map();
+    for (let i = 0; i < hashes.length; i++) {
+        roles.set(`imported:${i}`, [hashes[i]]);
+    }
+    return fromBrep(shape, {
+        solid: solidHandle,
+        roleTable: new Map([[stmtId, roles]]),
+    });
+}
+//# sourceMappingURL=import-brep.js.map

package/dist/api/import-brep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-brep.js","sourceRoot":"","sources":["../../src/api/import-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAInC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAEhB,CAAA;IACb,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACpC,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,aAAa,EAAE,8CAA8C,CAAC,CAAA;IACjG,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,mDAAmD,CAAC,CAAA;IACjG,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;IAEvD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,IAA4B,CAAA;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,oBAAoB,CAC5B,2FAA2F,CAC5F,CAAA;IACH,CAAC;IAED,0DAA0D;IAC1D,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC5C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CACzE,CAAA;IACD,qDAAqD;IACrD,wDAAwD;IACxD,iDAAiD;IACjD,6CAA6C;IAC7C,kFAAkF;IAClF,0FAA0F;IAC1F,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE;QACrB,KAAK,EAAE,WAAW;QAClB,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;KACtC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * stdlib import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）\n *\n *\n * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：\n * - `cad.load` 是 ../3d_editor 的「文件导入 Feature」（key/path/url 三键分流、\n *   语句位置约定、partIndex 画布语义），且历史契约要求实体。\n * - `cad.import_brep` 是 faijs **平台**几何 op：单一 asset 引用（容器资产名，\n *   去扩展名），语义是「把冻结的 BREP 载体装成持 OCCT 句柄的 Shape」。\n *\n * 非实体（wire/face/shell）一等公民（C6）：不要求实体，始终 allowNonSolid。\n * 需要实体的操作（布尔、up-to 目标面）在使用点报错（V-C8）。\n *\n * BREP 专属：`.brp` 无 mesh 解析器；mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\n\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * 平台 BREP 资产导入：把容器 `assets/` 里的冻结 BREP 载体装成持 OCCT 句柄的 Shape。\n *\n * `asset` = 资产名（去扩展名，沿用 `FsAssetResolver` 的 `key = basename(file)` 规则），\n * 由宿主资产解析器按 key 解析（与 `cad.load` 同套解析器）。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_brep\n * @param params.asset - 容器资产名（去扩展名）。type:string required:true\n * @note 非实体一等（C6）：wire/face/shell 一律可导入，本 op 不设 `allowNonSolid` 一类开关。需要实体的 op（布尔、up-to 目标面）在**使用点**报错，而不是在导入点拒绝。\n * @note 这是**平台**资产导入 op。编辑器 `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流 + 画布语句位置语义），平台侧不要复用它（C7）。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_brep({ asset: 'Array001.Shape' })\n */\nexport async function import_brep(params: Record<string, unknown>): Promise<Shape> {\n  const assets = getBackends().assets as {\n    resolveByKey?(key: string): Promise<{ bytes: ArrayBuffer }>\n  } | undefined\n  if (!assets || !assets.resolveByKey) {\n    throw new OpError('import_brep', 'E_OP_FAILED', '[api/import_brep] assets backend is required')\n  }\n\n  const asset = params.asset\n  if (typeof asset !== 'string' || asset.length === 0) {\n    throw new OpError('import_brep', 'E_ARGS', '[api/import_brep] asset name (string) is required')\n  }\n\n  const buffer = (await assets.resolveByKey(asset)).bytes\n\n  const { kernel: kernels } = getBackends()\n  const kernel = kernels.brep as BrepEngineApi | null\n  if (!kernel) {\n    throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_brep requires an OCCT kernel (.brp assets have no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民——始终允许导入 wire/face/shell（allowNonSolid=true）。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true },\n  )\n  // E3（H12）：链根建 roleTable（与 primitives.ts 同源机制）——冻结资产是\n  // 无名形状，没有这张表下游 edgeRef/faceRef 无法解析（nameless-shape 缺陷）。\n  // Phase 1.6：origin 用导入语句的 StmtId——同一资产导入两次是两条语句，\n  // 各自产出的面天然分属不同 origin（旧实现用资产名，两次导入撞 origin）。\n  // 3.8: imported:<i> — imported faces have no semantic names (arbitrary geometry),\n  // named by enumeration order in the imported file (stable across re-import of same file).\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, {\n    solid: solidHandle,\n    roleTable: new Map([[stmtId, roles]]),\n  })\n}\n"]}

package/dist/api/import-step.d.ts

@@ -0,0 +1,28 @@
+import type { Shape } from '../mesh/types.js';
+/**
+ * stdlib import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
+ *
+ * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：
+ * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），
+ *   OCCT STEPControl_Reader 读入，返回持 OCCT 句柄 + roleTable 的 Shape。
+ * - `import_brep` 读的是容器 `assets/` 里的冻结 BREP 资产（key，去扩展名）；
+ *   `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流、
+ *   画布语句位置语义），平台侧不要复用它（C7）。
+ *
+ * 非实体（wire/face/shell）一等公民（C6，对齐 import_brep）：始终 allowNonSolid。
+ * STEP 是 BREP 专属格式：mesh / 无内核模式抛 E_BREP_UNSUPPORTED。
+ *
+ * @group 创建
+ * @inputs 0
+ * @async true
+ * @qual ok
+ * @name import_step
+ * @param params.path - 本地绝对路径（宿主 resolveFile 解析）。type:string required:true
+ * @note 平台 STEP 导入 op。读文件经宿主资产解析器（`assets.resolveFile`），与 `cad.load` 同一通道；语义为「任意路径 STEP → OCCT 读入的 Shape」。
+ * @note 非实体一等（C6）：wire/face/shell 一律可导入。需要实体的 op（布尔、up-to 目标面）在**使用点**报错。
+ * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。
+ * @example
+ * const a = await cad.import_step({ path: 'D:/models/box.step' })
+ */
+export declare function import_step(params: Record<string, unknown>): Promise<Shape>;
+//# sourceMappingURL=import-step.d.ts.map

package/dist/api/import-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-step.d.ts","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAO1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAwCjF"}

package/dist/api/import-step.js

@@ -0,0 +1,57 @@
+import { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state.js';
+import { OpError } from './internal/result-unwrap.js';
+import { loadBrep } from '../brep/brep-ops.js';
+import { fromBrep } from '../shape.js';
+/**
+ * stdlib import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
+ *
+ * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：
+ * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），
+ *   OCCT STEPControl_Reader 读入，返回持 OCCT 句柄 + roleTable 的 Shape。
+ * - `import_brep` 读的是容器 `assets/` 里的冻结 BREP 资产（key，去扩展名）；
+ *   `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流、
+ *   画布语句位置语义），平台侧不要复用它（C7）。
+ *
+ * 非实体（wire/face/shell）一等公民（C6，对齐 import_brep）：始终 allowNonSolid。
+ * STEP 是 BREP 专属格式：mesh / 无内核模式抛 E_BREP_UNSUPPORTED。
+ *
+ * @group 创建
+ * @inputs 0
+ * @async true
+ * @qual ok
+ * @name import_step
+ * @param params.path - 本地绝对路径（宿主 resolveFile 解析）。type:string required:true
+ * @note 平台 STEP 导入 op。读文件经宿主资产解析器（`assets.resolveFile`），与 `cad.load` 同一通道；语义为「任意路径 STEP → OCCT 读入的 Shape」。
+ * @note 非实体一等（C6）：wire/face/shell 一律可导入。需要实体的 op（布尔、up-to 目标面）在**使用点**报错。
+ * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。
+ * @example
+ * const a = await cad.import_step({ path: 'D:/models/box.step' })
+ */
+export async function import_step(params) {
+    const path = params.path;
+    if (typeof path !== 'string' || path.length === 0) {
+        throw new OpError('import_step', 'E_ARGS', '[api/import_step] path (string) is required');
+    }
+    const assets = getBackends().assets;
+    if (!assets || !assets.resolveFile) {
+        throw new OpError('import_step', 'E_OP_FAILED', '[api/import_step] assets backend (resolveFile) is required');
+    }
+    const buffer = await assets.resolveFile(path);
+    const kernel = getBackends().kernel.brep;
+    if (!kernel) {
+        throw new BrepUnsupportedError('E_BREP_UNSUPPORTED: import_step requires an OCCT kernel (STEP has no mesh parser)');
+    }
+    // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology
+    // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。
+    const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true });
+    // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名
+    // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。
+    const stmtId = String(getCurrentStmt()?.id ?? '');
+    const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647);
+    const roles = new Map();
+    for (let i = 0; i < hashes.length; i++) {
+        roles.set(`imported:${i}`, [hashes[i]]);
+    }
+    return fromBrep(shape, { solid: solidHandle, roleTable: new Map([[stmtId, roles]]) });
+}
+//# sourceMappingURL=import-step.js.map

package/dist/api/import-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-step.js","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;IACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,6CAA6C,CAAC,CAAA;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAEhB,CAAA;IACb,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,OAAO,CACf,aAAa,EACb,aAAa,EACb,4DAA4D,CAC7D,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IAE7C,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAA4B,CAAA;IAChE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,oBAAoB,CAC5B,mFAAmF,CACpF,CAAA;IACH,CAAC;IAED,2DAA2D;IAC3D,uDAAuD;IACvD,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC5C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CACzE,CAAA;IACD,4CAA4C;IAC5C,+CAA+C;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AACvF,CAAC","sourcesContent":["import type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * stdlib import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）\n *\n * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：\n * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），\n *   OCCT STEPControl_Reader 读入，返回持 OCCT 句柄 + roleTable 的 Shape。\n * - `import_brep` 读的是容器 `assets/` 里的冻结 BREP 资产（key，去扩展名）；\n *   `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流、\n *   画布语句位置语义），平台侧不要复用它（C7）。\n *\n * 非实体（wire/face/shell）一等公民（C6，对齐 import_brep）：始终 allowNonSolid。\n * STEP 是 BREP 专属格式：mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_step\n * @param params.path - 本地绝对路径（宿主 resolveFile 解析）。type:string required:true\n * @note 平台 STEP 导入 op。读文件经宿主资产解析器（`assets.resolveFile`），与 `cad.load` 同一通道；语义为「任意路径 STEP → OCCT 读入的 Shape」。\n * @note 非实体一等（C6）：wire/face/shell 一律可导入。需要实体的 op（布尔、up-to 目标面）在**使用点**报错。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_step({ path: 'D:/models/box.step' })\n */\n\nexport async function import_step(params: Record<string, unknown>): Promise<Shape> {\n  const path = params.path\n  if (typeof path !== 'string' || path.length === 0) {\n    throw new OpError('import_step', 'E_ARGS', '[api/import_step] path (string) is required')\n  }\n\n  const assets = getBackends().assets as {\n    resolveFile?(path: string): Promise<ArrayBuffer>\n  } | undefined\n  if (!assets || !assets.resolveFile) {\n    throw new OpError(\n      'import_step',\n      'E_OP_FAILED',\n      '[api/import_step] assets backend (resolveFile) is required',\n    )\n  }\n\n  const buffer = await assets.resolveFile(path)\n\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) {\n    throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_step requires an OCCT kernel (STEP has no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology\n  // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true },\n  )\n  // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名\n  // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, { solid: solidHandle, roleTable: new Map([[stmtId, roles]]) })\n}\n"]}

package/dist/api/index.d.ts

@@ -14,7 +14,7 @@ export { translate, rotate_euler, scale, scale3d } from './transform.js';
 export { fai_extrude } from './fai_extrude.js';
 export { fai_drill } from './fai_drill.js';
 export { fai_split } from './fai_split.js';
-export { union, subtract, intersect } from './boolean.js';
+export { union, subtract, intersect, cut } from './boolean.js';
 export { engrave } from './engrave.js';
 export { chamfer } from './chamfer.js';
 export { fillet } from './fillet.js';
@@ -29,12 +29,17 @@ export { group, assembly } from './compound.js';
 export { applyTransform } from './compound.js';
 export * from './assembly/index.js';
 export { copy } from './copy.js';
+export { import_brep } from './import-brep.js';
+export { import_step } from './import-step.js';
+export { compound } from './compound-geom.js';
+export { place } from './place.js';
 export type { AssemblyBehavior, AssemblyConstraint, FaceMateConstraint, FaceMateFace, AssemblySolveResult, EntityRef, FaceRef, EdgeRef, AssemblyVec3, MateConstraint, AlignConstraint, CoincidentConstraint, ConcentricConstraint, DistanceConstraint, AngleConstraint, ParallelConstraint, PerpendicularConstraint, FixedConstraint, StructuralConstraint, } from './compound.js';
 export { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom.js';
 export { edgeRef } from './edge-ref.js';
 export { faceRef } from './face-ref.js';
 export { asset } from './asset.js';
-export { solid, compound, isShape, isCompound } from '../shape.js';
+export { solid, isShape, isCompound } from '../shape.js';
+export { compound as structCompound } from '../shape.js';
 export type { ShapeSlot, SolidShape, CompoundShape, StdShape, ShapeKind } from '../shape.js';
 export * from './generated/script-face.js';
 export { extrude } from './extrude.js';

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

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

package/dist/api/index.js

@@ -10,14 +10,18 @@
  * 缺失 brep 能力时经 D10 桥接调移植树 L2（见各 op 实现）。
  */
 export { box, sphere, cylinder, cone, wedge } from './primitives.js';
+// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：transform 家族
+// （translate/rotate_euler/scale/scale3d）为编辑器应用提供（拖拽 / 时间线语句），
+// 不属 faijs 平台面，但服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**；
+// 各 op 的 JSDoc 已带校正后的 @deprecated。
 export { translate, rotate_euler, scale, scale3d } from './transform.js';
-// DEPRECATED: `fai_` 前缀 op（fai_extrude / fai_drill / fai_split）是 ../3d_editor
-// 项目特有的操作，不属于 faijs 平台面。将来会迁往该项目并从 faijs 删除；各 op 的
-// JSDoc 已带 @deprecated。新代码请勿使用。
+// `../3d_editor` 消费面（**不是废弃项**）：`fai_` 前缀 op（fai_extrude / fai_drill /
+// fai_split）为编辑器应用提供，不属 faijs 平台面。**变更其 API 形态必须同步更新
+// `../3d_editor`**；各 op 的 JSDoc 已带校正后的 @deprecated。
 export { fai_extrude } from './fai_extrude.js';
 export { fai_drill } from './fai_drill.js';
 export { fai_split } from './fai_split.js';
-export { union, subtract, intersect } from './boolean.js';
+export { union, subtract, intersect, cut } from './boolean.js';
 export { engrave } from './engrave.js';
 export { chamfer } from './chamfer.js';
 export { fillet } from './fillet.js';
@@ -28,17 +32,27 @@ export { sketch } from './sketch.js';
 export { knurl } from './knurl.js';
 export { load } from './load.js';
 export { sdf } from './sdf.js';
+// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：group/assembly 为
+// 编辑器应用提供（无几何输出的结构分组 / 以编辑器结构语句声明的装配），不属 faijs 平台面；
+// **变更其 API 形态必须同步更新 `../3d_editor`**。
 export { group, assembly } from './compound.js';
 export { applyTransform } from './compound.js';
 // P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面；
 // 与 ./compound 显式导出重名（assembly/AssemblyConstraint 等）时显式优先，不报错）
 export * from './assembly/index.js';
+// DEPRECATED: copy 同上（语义含编辑器画布显示——源与副本各显示一份）。
 export { copy } from './copy.js';
+// ── H11：平台几何 op（方案 §4，替代 FCStd 迁移对编辑器 op 的借用）──
+export { import_brep } from './import-brep.js';
+export { import_step } from './import-step.js';
+export { compound } from './compound-geom.js';
+export { place } from './place.js';
 export { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom.js';
 export { edgeRef } from './edge-ref.js';
 export { faceRef } from './face-ref.js';
 export { asset } from './asset.js';
-export { solid, compound, isShape, isCompound } from '../shape.js';
+export { solid, isShape, isCompound } from '../shape.js';
+export { compound as structCompound } from '../shape.js';
 // ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──
 //
 // ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 API 面（api/）— faijs 库函数命名空间（替代原 packages/stdlib）\n *\n * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）\n *\n * 导出全部官方库函数、Shape 构造器与 schema 表。\n * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；\n * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。\n * 实现来源按 D11：mesh 侧复用 mesh/ 层，brep 侧复用既有 brep/ 层；\n * 缺失 brep 能力时经 D10 桥接调移植树 L2（见各 op 实现）。\n */\n\nexport { box, sphere, cylinder, cone, wedge } from './primitives'\nexport { translate, rotate_euler, scale, scale3d } from './transform'\n// DEPRECATED: `fai_` 前缀 op（fai_extrude / fai_drill / fai_split）是 ../3d_editor\n// 项目特有的操作，不属于 faijs 平台面。将来会迁往该项目并从 faijs 删除；各 op 的\n// JSDoc 已带 @deprecated。新代码请勿使用。\nexport { fai_extrude } from './fai_extrude'\nexport { fai_drill } from './fai_drill'\nexport { fai_split } from './fai_split'\nexport { union, subtract, intersect } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { text } from './text'\nexport { screw } from './screw'\nexport { svgExtrude } from './svgExtrude'\nexport { sketch } from './sketch'\nexport { knurl } from './knurl'\nexport { load } from './load'\nexport { sdf } from './sdf'\nexport { group, assembly } from './compound'\nexport { applyTransform } from './compound'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面；\n// 与 ./compound 显式导出重名（assembly/AssemblyConstraint 等）时显式优先，不报错）\nexport * from './assembly'\nexport { copy } from './copy'\nexport type {\n  AssemblyBehavior, AssemblyConstraint, FaceMateConstraint, FaceMateFace,\n  AssemblySolveResult,\n  EntityRef, FaceRef, EdgeRef, AssemblyVec3,\n  MateConstraint, AlignConstraint, CoincidentConstraint, ConcentricConstraint,\n  DistanceConstraint, AngleConstraint, ParallelConstraint, PerpendicularConstraint,\n  FixedConstraint, StructuralConstraint,\n} from './compound'\nexport { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom'\nexport { edgeRef } from './edge-ref'\nexport { faceRef } from './face-ref'\nexport { asset } from './asset'\nexport { solid, compound, isShape, isCompound } from '../shape'\nexport type { ShapeSlot, SolidShape, CompoundShape, StdShape, ShapeKind } from '../shape'\n\n// ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──\n//\n// ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。\n//    这批 op 经 `compatOp(projectBrepOp(…))` 包装，faijs 形态（Shape 进 / Shape 出、\n//    布尔双形态、brep-only），TS 侧与 `.fai.js` 侧同语义。\nexport * from './generated/script-face'\n// P25: compat extrude/revolve (brep-only, face→prism / face→lathe) share one\n// definition between the TS surface and the cad scripting surface. The fcstd\n// codegen wires Pad/Pocket/Extrusion/Revolution through these (sketch face →\n// cad.extrude / cad.revolve).\n// extrude 是平台手写 op（承载 upTo；长度形态委托生成投影）——见 api/extrude.ts；\n// revolve 仍直接取生成投影。\nexport { extrude } from './extrude'\nexport { revolve } from './generated/operations'\n//\n// ② brepjs 形态的 TS 兼容面（P21）以 `brepjsCompat` 命名空间整体导出（库作者面：\n//    句柄进出、Result 语义）。**op 符号不在此处平铺**——`brepjsCompat.fuse`（brepjs\n//    句柄形态）与脚本面 `fuse`（compatOp 包装的 faijs 形态）是同一 vendored\n//    实现的两个投影，按「一个名字一份实现」红线（§6.3），平铺面只保留脚本面\n//    那份；库作者继续 `import { brepjsCompat } from '@faicad/faijs'` 用上游形态。\n//    此处只平铺**无 op 语义**的组合器与纯工具（Result / 向量 / 平面 / 错误 /\n//    常量），它们在两个面之间语义一致且无同名冲突。\nexport {\n  ok, err, isOk, isErr, unwrap, unwrapOr,\n  vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize,\n  createPlane, createNamedPlane, resolvePlane,\n  kernelError, validationError,\n  DEG2RAD, RAD2DEG,\n} from './brepjs-compat'\nexport type {\n  Result, Ok, Err,\n  Vertex, Edge, Wire, Face, Shell, Solid, CompSolid, Shape3D,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n  Bounds3D,\n} from './brepjs-compat'\n// ── P24（§8.1）：库建造工厂与 Result 组合器平铺。它们不是脚本面 op（不在\n//    符号表/`cad` 面），也不是 dual op——是库作者面的函数，与 P23 平铺的纯\n//    组合器同一规则（`makeExternalGear`/`thread`/`map` 无同名冲突，§6.3）。\nexport {\n  makeExternalGear, makeInternalGear, makePlanetaryGear, thread,\n  map, andThen,\n} from './brepjs-compat'\nexport type {\n  ExternalGearParams, InternalGearParams, PlanetaryGearParams,\n  GearGeometry, GearResult, PlanetaryGearAssembly, ThreadOptions,\n  ValidSolid, ClosedWire,\n} from './brepjs-compat'\nexport * as brepjsCompat from './brepjs-compat'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 API 面（api/）— faijs 库函数命名空间（替代原 packages/stdlib）\n *\n * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）\n *\n * 导出全部官方库函数、Shape 构造器与 schema 表。\n * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；\n * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。\n * 实现来源按 D11：mesh 侧复用 mesh/ 层，brep 侧复用既有 brep/ 层；\n * 缺失 brep 能力时经 D10 桥接调移植树 L2（见各 op 实现）。\n */\n\nexport { box, sphere, cylinder, cone, wedge } from './primitives'\n// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：transform 家族\n// （translate/rotate_euler/scale/scale3d）为编辑器应用提供（拖拽 / 时间线语句），\n// 不属 faijs 平台面，但服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**；\n// 各 op 的 JSDoc 已带校正后的 @deprecated。\nexport { translate, rotate_euler, scale, scale3d } from './transform'\n// `../3d_editor` 消费面（**不是废弃项**）：`fai_` 前缀 op（fai_extrude / fai_drill /\n// fai_split）为编辑器应用提供，不属 faijs 平台面。**变更其 API 形态必须同步更新\n// `../3d_editor`**；各 op 的 JSDoc 已带校正后的 @deprecated。\nexport { fai_extrude } from './fai_extrude'\nexport { fai_drill } from './fai_drill'\nexport { fai_split } from './fai_split'\nexport { union, subtract, intersect, cut } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { text } from './text'\nexport { screw } from './screw'\nexport { svgExtrude } from './svgExtrude'\nexport { sketch } from './sketch'\nexport { knurl } from './knurl'\nexport { load } from './load'\nexport { sdf } from './sdf'\n// `../3d_editor` 消费面（**不是废弃项**，措辞于 2026-09-22 校正）：group/assembly 为\n// 编辑器应用提供（无几何输出的结构分组 / 以编辑器结构语句声明的装配），不属 faijs 平台面；\n// **变更其 API 形态必须同步更新 `../3d_editor`**。\nexport { group, assembly } from './compound'\nexport { applyTransform } from './compound'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面；\n// 与 ./compound 显式导出重名（assembly/AssemblyConstraint 等）时显式优先，不报错）\nexport * from './assembly'\n// DEPRECATED: copy 同上（语义含编辑器画布显示——源与副本各显示一份）。\nexport { copy } from './copy'\n// ── H11：平台几何 op（方案 §4，替代 FCStd 迁移对编辑器 op 的借用）──\nexport { import_brep } from './import-brep'\nexport { import_step } from './import-step'\nexport { compound } from './compound-geom'\nexport { place } from './place'\nexport type {\n  AssemblyBehavior, AssemblyConstraint, FaceMateConstraint, FaceMateFace,\n  AssemblySolveResult,\n  EntityRef, FaceRef, EdgeRef, AssemblyVec3,\n  MateConstraint, AlignConstraint, CoincidentConstraint, ConcentricConstraint,\n  DistanceConstraint, AngleConstraint, ParallelConstraint, PerpendicularConstraint,\n  FixedConstraint, StructuralConstraint,\n} from './compound'\nexport { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom'\nexport { edgeRef } from './edge-ref'\nexport { faceRef } from './face-ref'\nexport { asset } from './asset'\nexport { solid, isShape, isCompound } from '../shape'\nexport { compound as structCompound } from '../shape'\nexport type { ShapeSlot, SolidShape, CompoundShape, StdShape, ShapeKind } from '../shape'\n\n// ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──\n//\n// ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。\n//    这批 op 经 `compatOp(projectBrepOp(…))` 包装，faijs 形态（Shape 进 / Shape 出、\n//    布尔双形态、brep-only），TS 侧与 `.fai.js` 侧同语义。\nexport * from './generated/script-face'\n// P25: compat extrude/revolve (brep-only, face→prism / face→lathe) share one\n// definition between the TS surface and the cad scripting surface. The fcstd\n// codegen wires Pad/Pocket/Extrusion/Revolution through these (sketch face →\n// cad.extrude / cad.revolve).\n// extrude 是平台手写 op（承载 upTo；长度形态委托生成投影）——见 api/extrude.ts；\n// revolve 仍直接取生成投影。\nexport { extrude } from './extrude'\nexport { revolve } from './generated/operations'\n//\n// ② brepjs 形态的 TS 兼容面（P21）以 `brepjsCompat` 命名空间整体导出（库作者面：\n//    句柄进出、Result 语义）。**op 符号不在此处平铺**——`brepjsCompat.fuse`（brepjs\n//    句柄形态）与脚本面 `fuse`（compatOp 包装的 faijs 形态）是同一 vendored\n//    实现的两个投影，按「一个名字一份实现」红线（§6.3），平铺面只保留脚本面\n//    那份；库作者继续 `import { brepjsCompat } from '@faicad/faijs'` 用上游形态。\n//    此处只平铺**无 op 语义**的组合器与纯工具（Result / 向量 / 平面 / 错误 /\n//    常量），它们在两个面之间语义一致且无同名冲突。\nexport {\n  ok, err, isOk, isErr, unwrap, unwrapOr,\n  vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize,\n  createPlane, createNamedPlane, resolvePlane,\n  kernelError, validationError,\n  DEG2RAD, RAD2DEG,\n} from './brepjs-compat'\nexport type {\n  Result, Ok, Err,\n  Vertex, Edge, Wire, Face, Shell, Solid, CompSolid, Shape3D,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n  Bounds3D,\n} from './brepjs-compat'\n// ── P24（§8.1）：库建造工厂与 Result 组合器平铺。它们不是脚本面 op（不在\n//    符号表/`cad` 面），也不是 dual op——是库作者面的函数，与 P23 平铺的纯\n//    组合器同一规则（`makeExternalGear`/`thread`/`map` 无同名冲突，§6.3）。\nexport {\n  makeExternalGear, makeInternalGear, makePlanetaryGear, thread,\n  map, andThen,\n} from './brepjs-compat'\nexport type {\n  ExternalGearParams, InternalGearParams, PlanetaryGearParams,\n  GearGeometry, GearResult, PlanetaryGearAssembly, ThreadOptions,\n  ValidSolid, ClosedWire,\n} from './brepjs-compat'\nexport * as brepjsCompat from './brepjs-compat'\n"]}

package/dist/api/internal/compat-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compat-op.d.ts","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAEL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,aAAa,EAGnB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,kFAAkF;AAClF,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IACtE,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAA;CACb;AAID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AA6ED,gFAAgF;AAChF,KAAK,WAAW,GAAG;IAAE,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAA;CAAE,CAAA;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACnC,IAAI,EAAE,UAAU,GACf,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,WAAW,CAaxD"}
+{"version":3,"file":"compat-op.d.ts","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAEL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,aAAa,EAGnB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,kFAAkF;AAClF,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IACtE,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAA;CACb;AAID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AA6ED,gFAAgF;AAChF,KAAK,WAAW,GAAG;IAAE,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAA;CAAE,CAAA;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACnC,IAAI,EAAE,UAAU,GACf,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,WAAW,CAcxD"}

package/dist/api/internal/compat-op.js

@@ -167,7 +167,7 @@ function buildAdapter(fn, spec) {
  * @returns the compat op facade, carrying dual-op metadata.
  */
 export function compatOp(fn, spec) {
-    const { outputs, capabilities, schema, slotMap } = spec;
+    const { outputs, capabilities, schema, slotMap, naming } = spec;
     // `outputs` flows through defineOp's own wrapping path: the adapter adopts
     // per declared field, then defineOp wraps — isShape passthrough, so no
     // double wrapping (§3.2).
@@ -178,6 +178,7 @@ export function compatOp(fn, spec) {
         outputs,
         schema,
         slotMap,
+        naming,
     });
 }
 //# sourceMappingURL=compat-op.js.map

package/dist/api/internal/compat-op.js.map

@@ -1 +1 @@
-{"version":3,"file":"compat-op.js","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement\n * op, built **on top of** defineOp (single implementation entry, v1).\n *\n * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3\n *\n * compatOp is NOT a second implementation path parallel to defineOp: every\n * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability\n * routing), the Result boundary (runImpl + unwrapResult), product wrapping\n * (wrapBrepOne / wrapByKeys), `DUAL_OP_META` mounting and\n * `assertLibConforms` validation. compatOp only does two things:\n *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of\n *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);\n *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the\n *     three bridging steps that cannot be shared (all reuse shared\n *     infrastructure, §3.2):\n *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →\n *          borrowBrepjsShape view (zero-copy; library-private handles pass\n *          through untouched);\n *       2. call + unwrap — callBrepjs through the shared unwrapResult\n *          (`err` throws an OpError carrying the op name + BrepError code);\n *          async library fns are awaited first, so `Promise<Result<…>>` —\n *          the shape every kernel-awaiting library returns — unwraps too;\n *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared\n *          fields (single handle or handle array) → adoptEntity\n *          (unregister finalizer + fromHandle).\n *\n * The keep / keepHidden contract is untouched: compatOp neither blocks nor\n * rewrites it — any function running inside a DirectExecutor context can use\n * function-body declarations (C1), and call-site declarations override them\n * (`lang/keep.ts` resolveKeep). The decorated product therefore behaves like\n * any defineOp product: `keep`-safe, capability-aware, multi-output\n * (`DUAL_OP_META.outputs` visible).\n *\n * No self-invented fields: `CompatSpec` extends `Omit<DualOpOptions, 'mesh' |\n * 'brep'>` and declares nothing else; the only tweak is `name` tightened\n * (inherited field, not a new one).\n *\n * @module\n */\n\nimport {\n  defineOp,\n  DUAL_OP_META,\n  type DualOpMeta,\n  type DualOpOptions,\n  type BrepImpl,\n  type BrepProduct,\n} from '../../define-op'\nimport { isShape } from '../../shape'\nimport { borrowBrepjsShape, adoptEntity, callBrepjs } from './l3-bridge'\nimport { unwrapResult } from './result-unwrap'\nimport type { Shape } from '../../mesh/types'\n\n/** compatOp's static spec: combinatorial inheritance (single source of truth). */\nexport interface CompatSpec extends Omit<DualOpOptions, 'mesh' | 'brep'> {\n  /** Op name (error messages + metadata; required, unlike defineOp's optional name). */\n  name: string\n}\n\nconst MAX_WALK_DEPTH = 4\n\n/**\n * Inward bridging step: deep walk with faijs Shapes replaced by borrowed\n * brepjs views (zero-copy); everything else passes through.\n * Class instances are not traversed (defensive); library-private handles\n * pass through (§4.3.4 of the design).\n *\n * @param v - the value to borrow from (plain object, array, or primitive).\n * @param depth - current traversal depth (guard against deep recursion).\n * @returns the value with faijs Shapes replaced by borrowed views.\n */\nexport function borrowDeep(v: unknown, depth: number): unknown {\n  if (depth > MAX_WALK_DEPTH || v === null || typeof v !== 'object') return v\n  if (isShape(v)) return borrowBrepjsShape(v)\n  if (Array.isArray(v)) return v.map((x) => borrowDeep(x, depth + 1))\n  if (Object.getPrototypeOf(v) !== Object.prototype) return v\n  const out: Record<string, unknown> = {}\n  for (const [k, x] of Object.entries(v)) out[k] = borrowDeep(x, depth + 1)\n  return out\n}\n\n/**\n * Statement-boundary unwrap — `err` becomes an execution error carrying the op\n * name and the `BrepError` code. Delegates to the shared\n * {@link unwrapResult} so the compat boundary and defineOp's Result boundary\n * share one leaf implementation (no drift).\n *\n * @param r - the Result-like value to unwrap.\n * @param name - the op name used in error messages.\n * @returns the unwrapped ok value.\n */\nexport function unwrapOrThrow(r: unknown, name: string): unknown {\n  return unwrapResult(r, name)\n}\n\n/**\n * Bridging step: outward adoption — top-level handle or `outputs`-declared\n * fields → adoptEntity (unregister finalizer + fromHandle). `outputs` may also\n * name an array field of handles; every element is adopted individually.\n * Deduplication of already-adopted handles lives inside adoptEntity. A field\n * already being a faijs Shape passes through untouched (no double adoption).\n *\n * @param v - the library product.\n * @param spec - the compat spec (name + optional `outputs`).\n * @param segments - caller-provided `segments` (裁决 1,§5.2), forwarded so the\n *  adopted handles' tessellation honors it.\n * @returns the adopted record / Shape, or the plain data untouched.\n */\nfunction adoptOut(v: unknown, spec: CompatSpec, segments?: number): unknown {\n  if (isShape(v)) return v\n  if (spec.outputs && typeof v === 'object' && v !== null && !Array.isArray(v)) {\n    const rec = v as Record<string, unknown>\n    for (const f of spec.outputs) {\n      const field = rec[f]\n      rec[f] = Array.isArray(field)\n        ? field.map((x) => adoptEntity(x, spec.name, segments))\n        : adoptEntity(field, spec.name, segments)\n    }\n    return v\n  }\n  return adoptEntity(v, spec.name, segments)\n}\n\n/**\n * Read the caller-supplied tessellation density from a compat op's args.\n *\n * 裁决 1：faijs 的 `segments` 显式超集在 brepjs 投影侧也必须可选；这里从调用点\n * 的尾参 options（或任一 plain-object 实参）抓取 `segments`，在产出句柄被收编为\n * faijs Shape 时透传给 `fromHandle` 的三角化（§5.2 机制）。默认不传 = 由\n * handle-bridge 的 64 兜底。\n */\nfunction readSegmentsFromArgs(args: unknown[]): number | undefined {\n  for (let i = args.length - 1; i >= 0; i--) {\n    const a = args[i]\n    if (\n      a !== null &&\n      typeof a === 'object' &&\n      !Array.isArray(a) &&\n      Object.getPrototypeOf(a) === Object.prototype\n    ) {\n      const seg = (a as Record<string, unknown>).segments\n      if (typeof seg === 'number' && Number.isFinite(seg)) return seg\n    }\n  }\n  return undefined\n}\n\n/**\n * Build the brep-only adapter: borrow inputs → call the vendor function through\n * the shared unwrap → adopt the product (with the caller's `segments`,\n * 裁决 1/§5.2). The adapter never dispatches and never mounts metadata —\n * those are defineOp's.\n *\n * @param fn   the brepjs-shaped function (dual-form normalization inside, D11).\n * @param spec the static op spec (name + options pass-through).\n * @returns a `BrepImpl` compatible with defineOp's brep-only decl.\n */\nfunction buildAdapter(fn: (...args: unknown[]) => unknown, spec: CompatSpec): BrepImpl<unknown[]> {\n  return async (...args: unknown[]): Promise<BrepProduct> => {\n    const borrowed = args.map((a) => borrowDeep(a, 0))\n    // Async library fns are supported: a library that awaits its kernel (every\n    // `@faicad/fai-cq-gears` factory does — `await getGearKernel()`) returns\n    // `Promise<Result<…>>`, and the shared unwrap is a sync leaf that only\n    // recognizes settled Result records. Awaiting a non-promise product is a\n    // no-op, so sync libraries are unaffected.\n    const value = unwrapOrThrow(await callBrepjs(fn as never, borrowed), spec.name)\n    return adoptOut(value, spec, readSegmentsFromArgs(args)) as BrepProduct\n  }\n}\n\n/** Carrier of the DualOpMeta mounted by defineOp (same shape as defineOp's). */\ntype MetaCarrier = { [DUAL_OP_META]?: DualOpMeta }\n\n/**\n * Lift a brepjs-shaped function into a defineOp-decorated op facade (brep-only).\n *\n * The decorated product is identical to a defineOp product: same `DUAL_OP_META`\n * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,\n * slotMap), same dispatch semantics, same Result boundary. The adapter carries\n * only the brepjs bridging (borrow / call / adopt); every other mechanism\n * belongs to defineOp.\n *\n * @param fn   the brepjs-shaped function.\n * @param spec the static spec (name required; capabilities/outputs/slotMap/\n *  schema pass through and take effect).\n * @returns the compat op facade, carrying dual-op metadata.\n */\nexport function compatOp(\n  fn: (...args: unknown[]) => unknown,\n  spec: CompatSpec,\n): ((...args: unknown[]) => Promise<Shape>) & MetaCarrier {\n  const { outputs, capabilities, schema, slotMap } = spec\n  // `outputs` flows through defineOp's own wrapping path: the adapter adopts\n  // per declared field, then defineOp wraps — isShape passthrough, so no\n  // double wrapping (§3.2).\n  return defineOp({\n    brep: buildAdapter(fn, spec),\n    name: spec.name,\n    capabilities,\n    outputs,\n    schema,\n    slotMap,\n  }) as unknown as ((...args: unknown[]) => Promise<Shape>) & MetaCarrier\n}"]}
+{"version":3,"file":"compat-op.js","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement\n * op, built **on top of** defineOp (single implementation entry, v1).\n *\n * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3\n *\n * compatOp is NOT a second implementation path parallel to defineOp: every\n * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability\n * routing), the Result boundary (runImpl + unwrapResult), product wrapping\n * (wrapBrepOne / wrapByKeys), `DUAL_OP_META` mounting and\n * `assertLibConforms` validation. compatOp only does two things:\n *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of\n *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);\n *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the\n *     three bridging steps that cannot be shared (all reuse shared\n *     infrastructure, §3.2):\n *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →\n *          borrowBrepjsShape view (zero-copy; library-private handles pass\n *          through untouched);\n *       2. call + unwrap — callBrepjs through the shared unwrapResult\n *          (`err` throws an OpError carrying the op name + BrepError code);\n *          async library fns are awaited first, so `Promise<Result<…>>` —\n *          the shape every kernel-awaiting library returns — unwraps too;\n *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared\n *          fields (single handle or handle array) → adoptEntity\n *          (unregister finalizer + fromHandle).\n *\n * The keep / keepHidden contract is untouched: compatOp neither blocks nor\n * rewrites it — any function running inside a DirectExecutor context can use\n * function-body declarations (C1), and call-site declarations override them\n * (`lang/keep.ts` resolveKeep). The decorated product therefore behaves like\n * any defineOp product: `keep`-safe, capability-aware, multi-output\n * (`DUAL_OP_META.outputs` visible).\n *\n * No self-invented fields: `CompatSpec` extends `Omit<DualOpOptions, 'mesh' |\n * 'brep'>` and declares nothing else; the only tweak is `name` tightened\n * (inherited field, not a new one).\n *\n * @module\n */\n\nimport {\n  defineOp,\n  DUAL_OP_META,\n  type DualOpMeta,\n  type DualOpOptions,\n  type BrepImpl,\n  type BrepProduct,\n} from '../../define-op'\nimport { isShape } from '../../shape'\nimport { borrowBrepjsShape, adoptEntity, callBrepjs } from './l3-bridge'\nimport { unwrapResult } from './result-unwrap'\nimport type { Shape } from '../../mesh/types'\n\n/** compatOp's static spec: combinatorial inheritance (single source of truth). */\nexport interface CompatSpec extends Omit<DualOpOptions, 'mesh' | 'brep'> {\n  /** Op name (error messages + metadata; required, unlike defineOp's optional name). */\n  name: string\n}\n\nconst MAX_WALK_DEPTH = 4\n\n/**\n * Inward bridging step: deep walk with faijs Shapes replaced by borrowed\n * brepjs views (zero-copy); everything else passes through.\n * Class instances are not traversed (defensive); library-private handles\n * pass through (§4.3.4 of the design).\n *\n * @param v - the value to borrow from (plain object, array, or primitive).\n * @param depth - current traversal depth (guard against deep recursion).\n * @returns the value with faijs Shapes replaced by borrowed views.\n */\nexport function borrowDeep(v: unknown, depth: number): unknown {\n  if (depth > MAX_WALK_DEPTH || v === null || typeof v !== 'object') return v\n  if (isShape(v)) return borrowBrepjsShape(v)\n  if (Array.isArray(v)) return v.map((x) => borrowDeep(x, depth + 1))\n  if (Object.getPrototypeOf(v) !== Object.prototype) return v\n  const out: Record<string, unknown> = {}\n  for (const [k, x] of Object.entries(v)) out[k] = borrowDeep(x, depth + 1)\n  return out\n}\n\n/**\n * Statement-boundary unwrap — `err` becomes an execution error carrying the op\n * name and the `BrepError` code. Delegates to the shared\n * {@link unwrapResult} so the compat boundary and defineOp's Result boundary\n * share one leaf implementation (no drift).\n *\n * @param r - the Result-like value to unwrap.\n * @param name - the op name used in error messages.\n * @returns the unwrapped ok value.\n */\nexport function unwrapOrThrow(r: unknown, name: string): unknown {\n  return unwrapResult(r, name)\n}\n\n/**\n * Bridging step: outward adoption — top-level handle or `outputs`-declared\n * fields → adoptEntity (unregister finalizer + fromHandle). `outputs` may also\n * name an array field of handles; every element is adopted individually.\n * Deduplication of already-adopted handles lives inside adoptEntity. A field\n * already being a faijs Shape passes through untouched (no double adoption).\n *\n * @param v - the library product.\n * @param spec - the compat spec (name + optional `outputs`).\n * @param segments - caller-provided `segments` (裁决 1,§5.2), forwarded so the\n *  adopted handles' tessellation honors it.\n * @returns the adopted record / Shape, or the plain data untouched.\n */\nfunction adoptOut(v: unknown, spec: CompatSpec, segments?: number): unknown {\n  if (isShape(v)) return v\n  if (spec.outputs && typeof v === 'object' && v !== null && !Array.isArray(v)) {\n    const rec = v as Record<string, unknown>\n    for (const f of spec.outputs) {\n      const field = rec[f]\n      rec[f] = Array.isArray(field)\n        ? field.map((x) => adoptEntity(x, spec.name, segments))\n        : adoptEntity(field, spec.name, segments)\n    }\n    return v\n  }\n  return adoptEntity(v, spec.name, segments)\n}\n\n/**\n * Read the caller-supplied tessellation density from a compat op's args.\n *\n * 裁决 1：faijs 的 `segments` 显式超集在 brepjs 投影侧也必须可选；这里从调用点\n * 的尾参 options（或任一 plain-object 实参）抓取 `segments`，在产出句柄被收编为\n * faijs Shape 时透传给 `fromHandle` 的三角化（§5.2 机制）。默认不传 = 由\n * handle-bridge 的 64 兜底。\n */\nfunction readSegmentsFromArgs(args: unknown[]): number | undefined {\n  for (let i = args.length - 1; i >= 0; i--) {\n    const a = args[i]\n    if (\n      a !== null &&\n      typeof a === 'object' &&\n      !Array.isArray(a) &&\n      Object.getPrototypeOf(a) === Object.prototype\n    ) {\n      const seg = (a as Record<string, unknown>).segments\n      if (typeof seg === 'number' && Number.isFinite(seg)) return seg\n    }\n  }\n  return undefined\n}\n\n/**\n * Build the brep-only adapter: borrow inputs → call the vendor function through\n * the shared unwrap → adopt the product (with the caller's `segments`,\n * 裁决 1/§5.2). The adapter never dispatches and never mounts metadata —\n * those are defineOp's.\n *\n * @param fn   the brepjs-shaped function (dual-form normalization inside, D11).\n * @param spec the static op spec (name + options pass-through).\n * @returns a `BrepImpl` compatible with defineOp's brep-only decl.\n */\nfunction buildAdapter(fn: (...args: unknown[]) => unknown, spec: CompatSpec): BrepImpl<unknown[]> {\n  return async (...args: unknown[]): Promise<BrepProduct> => {\n    const borrowed = args.map((a) => borrowDeep(a, 0))\n    // Async library fns are supported: a library that awaits its kernel (every\n    // `@faicad/fai-cq-gears` factory does — `await getGearKernel()`) returns\n    // `Promise<Result<…>>`, and the shared unwrap is a sync leaf that only\n    // recognizes settled Result records. Awaiting a non-promise product is a\n    // no-op, so sync libraries are unaffected.\n    const value = unwrapOrThrow(await callBrepjs(fn as never, borrowed), spec.name)\n    return adoptOut(value, spec, readSegmentsFromArgs(args)) as BrepProduct\n  }\n}\n\n/** Carrier of the DualOpMeta mounted by defineOp (same shape as defineOp's). */\ntype MetaCarrier = { [DUAL_OP_META]?: DualOpMeta }\n\n/**\n * Lift a brepjs-shaped function into a defineOp-decorated op facade (brep-only).\n *\n * The decorated product is identical to a defineOp product: same `DUAL_OP_META`\n * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,\n * slotMap), same dispatch semantics, same Result boundary. The adapter carries\n * only the brepjs bridging (borrow / call / adopt); every other mechanism\n * belongs to defineOp.\n *\n * @param fn   the brepjs-shaped function.\n * @param spec the static spec (name required; capabilities/outputs/slotMap/\n *  schema pass through and take effect).\n * @returns the compat op facade, carrying dual-op metadata.\n */\nexport function compatOp(\n  fn: (...args: unknown[]) => unknown,\n  spec: CompatSpec,\n): ((...args: unknown[]) => Promise<Shape>) & MetaCarrier {\n  const { outputs, capabilities, schema, slotMap, naming } = spec\n  // `outputs` flows through defineOp's own wrapping path: the adapter adopts\n  // per declared field, then defineOp wraps — isShape passthrough, so no\n  // double wrapping (§3.2).\n  return defineOp({\n    brep: buildAdapter(fn, spec),\n    name: spec.name,\n    capabilities,\n    outputs,\n    schema,\n    slotMap,\n    naming,\n  }) as unknown as ((...args: unknown[]) => Promise<Shape>) & MetaCarrier\n}"]}

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

@@ -1 +1 @@
-{"version":3,"file":"knurl.d.ts","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAMhD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEvE;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,eAAO,MAAM,KAAK;;CAoBhB,CAAA"}
+{"version":3,"file":"knurl.d.ts","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAOhD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEvE;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,eAAO,MAAM,KAAK;;CAqBhB,CAAA"}

package/dist/api/knurl.js

@@ -58,5 +58,6 @@ export const knurl = defineOp({
             knurlMappingMode: params.knurlMappingMode ?? 5,
         });
     },
+    naming: { kind: 'unmodeled', reason: 'knurl is mesh-only, no BREP face identity' },
 });
 //# sourceMappingURL=knurl.js.map

package/dist/api/knurl.js.map

@@ -1 +1 @@
-{"version":3,"file":"knurl.js","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAC/D,oBAAoB,CAAC,MAAM,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE,KAAY,EAAE,MAA+B,EAAE,EAAE;QAC5D,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QAC/D,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACzB,+CAA+C;QAC/C,iEAAiE;QACjE,MAAM,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAChD,OAAO,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;YAC1B,IAAI,EAAE;gBACJ,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAC5E,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC7D;YACD,kBAAkB,EAAG,MAAM,CAAC,kBAAyC,IAAI,GAAG;YAC5E,uBAAuB,EAAG,MAAM,CAAC,uBAA+C,IAAI,KAAK;YACzF,iBAAiB,EAAG,MAAM,CAAC,iBAAwC,IAAI,GAAG;YAC1E,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,gBAAgB,EAAG,MAAM,CAAC,gBAAuC,IAAI,CAAC;SACvE,CAAC,CAAA;IACJ,CAAC;CACF,CAAC,CAAA","sourcesContent":["/**\n * stdlib knurl — 滚花库函数（mesh-only）\n *\n *\n * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。\n * part-brep-lost 事件由引擎统一发（P4，库不再 emit）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { reconcileBrepInputs } from './reconcile'\nimport { defineOp } from '../sdk'\nimport { assertPositiveNumber } from './assert'\n\n/**\n * Validate knurl parameters: `knurlTextureHeight` must be a positive number.\n * @param params - the raw knurl operation parameters.\n */\nexport function assertKnurlParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.knurlTextureHeight, 'knurl.knurlTextureHeight')\n}\n\n/**\n * 施加滚花（顶点位移，非布尔）。mesh-only。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual warn\n * @name knurl\n * @note knurl 无 BREP 实现（mesh-only），本质是顶点位移（网格操作），网格参数可接受；brep 模式下调用前抛 BrepUnsupportedError。面锚定建议用几何引用。\n * @returns Shape 滚花后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.knurlTextureHeight - 纹路高度（mm）。type:number 默认 0.5\n * @param params.knurlScaleU - 纹路 U 向频率。type:number 默认 0.15\n * @param params.knurlScaleV - 纹路 V 向频率。type:number 默认 0.15\n * @param params.knurlInvertDisplacement - 反向位移。type:boolean 默认 false\n * @param params.knurlRefineLength - 细分长度（mm）。type:number 默认 1.0\n * @param params.knurlMappingMode - UV 映射模式。type:number 默认 5\n * @param params.faceCenter - 面锚点中心。type:[x,y,z] 默认 bboxCenter\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @example\n * const p = await cad.knurl(part0, { knurlTextureHeight: 0.5, knurlScaleU: 0.15, knurlScaleV: 0.15, knurlInvertDisplacement: false, knurlRefineLength: 1.0, knurlMappingMode: 5 })\n  */\nexport const knurl = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[stdlib/knurl] no input geometry')\n    assertKnurlParams(params)\n    // 断链时刻（用户点名场景）：BREP 建模的模型最后做滚花 → BREP 输入必须先归约为\n    // 合法 2-manifold 网格再进 mesh 路径（reconcileBrepInputs 对 mesh 侧输入原样透传）\n    const [meshInput] = reconcileBrepInputs([input])\n    return cad.knurl(meshInput, {\n      face: {\n        center: (params.faceCenter as Vec3 | undefined) ?? cad.bboxCenter(meshInput),\n        normal: (params.faceNormal as Vec3 | undefined) ?? [0, 0, 1],\n      },\n      knurlTextureHeight: (params.knurlTextureHeight as number | undefined) ?? 0.5,\n      knurlInvertDisplacement: (params.knurlInvertDisplacement as boolean | undefined) ?? false,\n      knurlRefineLength: (params.knurlRefineLength as number | undefined) ?? 1.0,\n      knurlScaleU: (params.knurlScaleU as number | undefined) ?? 0.15,\n      knurlScaleV: (params.knurlScaleV as number | undefined) ?? 0.15,\n      knurlMappingMode: (params.knurlMappingMode as number | undefined) ?? 5,\n    })\n  },\n})\n"]}
+{"version":3,"file":"knurl.js","sourceRoot":"","sources":["../../src/api/knurl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA+B;IAC/D,oBAAoB,CAAC,MAAM,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;IAoBI;AACJ,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE,KAAY,EAAE,MAA+B,EAAE,EAAE;QAC5D,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QAC/D,iBAAiB,CAAC,MAAM,CAAC,CAAA;QACzB,+CAA+C;QAC/C,iEAAiE;QACjE,MAAM,CAAC,SAAS,CAAC,GAAG,mBAAmB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAChD,OAAO,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE;YAC1B,IAAI,EAAE;gBACJ,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAC5E,MAAM,EAAG,MAAM,CAAC,UAA+B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC7D;YACD,kBAAkB,EAAG,MAAM,CAAC,kBAAyC,IAAI,GAAG;YAC5E,uBAAuB,EAAG,MAAM,CAAC,uBAA+C,IAAI,KAAK;YACzF,iBAAiB,EAAG,MAAM,CAAC,iBAAwC,IAAI,GAAG;YAC1E,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,WAAW,EAAG,MAAM,CAAC,WAAkC,IAAI,IAAI;YAC/D,gBAAgB,EAAG,MAAM,CAAC,gBAAuC,IAAI,CAAC;SACvE,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,2CAA2C,EAAgB;CACjG,CAAC,CAAA","sourcesContent":["/**\n * stdlib knurl — 滚花库函数（mesh-only）\n *\n *\n * knurl 无 BREP 实现（mesh-only）——dispatchPath 在 brep 模式下调用前抛错。\n * part-brep-lost 事件由引擎统一发（P4，库不再 emit）。\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { reconcileBrepInputs } from './reconcile'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { assertPositiveNumber } from './assert'\n\n/**\n * Validate knurl parameters: `knurlTextureHeight` must be a positive number.\n * @param params - the raw knurl operation parameters.\n */\nexport function assertKnurlParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.knurlTextureHeight, 'knurl.knurlTextureHeight')\n}\n\n/**\n * 施加滚花（顶点位移，非布尔）。mesh-only。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual warn\n * @name knurl\n * @note knurl 无 BREP 实现（mesh-only），本质是顶点位移（网格操作），网格参数可接受；brep 模式下调用前抛 BrepUnsupportedError。面锚定建议用几何引用。\n * @returns Shape 滚花后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.knurlTextureHeight - 纹路高度（mm）。type:number 默认 0.5\n * @param params.knurlScaleU - 纹路 U 向频率。type:number 默认 0.15\n * @param params.knurlScaleV - 纹路 V 向频率。type:number 默认 0.15\n * @param params.knurlInvertDisplacement - 反向位移。type:boolean 默认 false\n * @param params.knurlRefineLength - 细分长度（mm）。type:number 默认 1.0\n * @param params.knurlMappingMode - UV 映射模式。type:number 默认 5\n * @param params.faceCenter - 面锚点中心。type:[x,y,z] 默认 bboxCenter\n * @param params.faceNormal - 面法向。type:[x,y,z] 默认 [0,0,1]\n * @example\n * const p = await cad.knurl(part0, { knurlTextureHeight: 0.5, knurlScaleU: 0.15, knurlScaleV: 0.15, knurlInvertDisplacement: false, knurlRefineLength: 1.0, knurlMappingMode: 5 })\n  */\nexport const knurl = defineOp({\n  mesh: async (input: Shape, params: Record<string, unknown>) => {\n    if (!input) throw new Error('[stdlib/knurl] no input geometry')\n    assertKnurlParams(params)\n    // 断链时刻（用户点名场景）：BREP 建模的模型最后做滚花 → BREP 输入必须先归约为\n    // 合法 2-manifold 网格再进 mesh 路径（reconcileBrepInputs 对 mesh 侧输入原样透传）\n    const [meshInput] = reconcileBrepInputs([input])\n    return cad.knurl(meshInput, {\n      face: {\n        center: (params.faceCenter as Vec3 | undefined) ?? cad.bboxCenter(meshInput),\n        normal: (params.faceNormal as Vec3 | undefined) ?? [0, 0, 1],\n      },\n      knurlTextureHeight: (params.knurlTextureHeight as number | undefined) ?? 0.5,\n      knurlInvertDisplacement: (params.knurlInvertDisplacement as boolean | undefined) ?? false,\n      knurlRefineLength: (params.knurlRefineLength as number | undefined) ?? 1.0,\n      knurlScaleU: (params.knurlScaleU as number | undefined) ?? 0.15,\n      knurlScaleV: (params.knurlScaleV as number | undefined) ?? 0.15,\n      knurlMappingMode: (params.knurlMappingMode as number | undefined) ?? 5,\n    })\n  },\n  naming: { kind: 'unmodeled', reason: 'knurl is mesh-only, no BREP face identity' } as Provenance,\n})\n"]}

package/dist/api/load.d.ts

@@ -30,10 +30,12 @@ import type { Shape } from '../mesh/types.js';
  * @param params.url - 网络地址。type:string
  * @param params.format - 格式提示（如 'step'/'stl'；CAD 源走 BREP 精确路径，STL 等三角化源走 mesh 路径）。type:string
  * @note key/path/url 是优先级分流（key 优先，其次 path，最后 url），三者只需其一；同时给多个时按优先级取。`format` 是提示而非强约束——CAD 源（step/stp/brep 等）与三角化源（stl 等）由 `isCadFormat` 静态判定路径。
+ * @note 本 op 要求导入物含实体（历史契约）。非实体（wire/face/shell）的导入是平台 `cad.import_brep` 的一等能力，不由本 op 承担。
+ * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用的「文件导入 Feature」提供——key/path/url 三键分流读的是应用侧 `FileRef`，产物语句位置、命名与 partIndex 都是画布语义。不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。平台侧导入请用 `cad.import_brep`（冻结 BREP 资产）。
  * @example
  * const p = await cad.load({ key: 'file_abc123' })
  * const p = await cad.load({ path: 'D:/models/box.step', format: 'step' })
  * const p = await cad.load({ url: 'https://…/box.3mf' })
-  */
+ */
 export declare function load(params: Record<string, unknown>): Promise<Shape>;
 //# sourceMappingURL=load.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/api/load.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;;;;;IAkBI;AACJ,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA4C1E"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/api/load.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA8C1E"}

package/dist/api/load.js

@@ -35,11 +35,13 @@ import { solid, fromBrep } from '../shape.js';
  * @param params.url - 网络地址。type:string
  * @param params.format - 格式提示（如 'step'/'stl'；CAD 源走 BREP 精确路径，STL 等三角化源走 mesh 路径）。type:string
  * @note key/path/url 是优先级分流（key 优先，其次 path，最后 url），三者只需其一；同时给多个时按优先级取。`format` 是提示而非强约束——CAD 源（step/stp/brep 等）与三角化源（stl 等）由 `isCadFormat` 静态判定路径。
+ * @note 本 op 要求导入物含实体（历史契约）。非实体（wire/face/shell）的导入是平台 `cad.import_brep` 的一等能力，不由本 op 承担。
+ * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用的「文件导入 Feature」提供——key/path/url 三键分流读的是应用侧 `FileRef`，产物语句位置、命名与 partIndex 都是画布语义。不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。平台侧导入请用 `cad.import_brep`（冻结 BREP 资产）。
  * @example
  * const p = await cad.load({ key: 'file_abc123' })
  * const p = await cad.load({ path: 'D:/models/box.step', format: 'step' })
  * const p = await cad.load({ url: 'https://…/box.3mf' })
-  */
+ */
 export async function load(params) {
     const assets = getBackends().assets;
     if (!assets) {

package/dist/api/load.js.map

@@ -1 +1 @@
-{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/api/load.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAG1C;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;;;;;IAkBI;AACJ,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,MAA+B;IACxD,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAIhB,CAAA;IACb,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,8CAA8C,CAAC,CAAA;IAC1F,CAAC;IAED,6BAA6B;IAC7B,IAAI,MAAmB,CAAA;IACvB,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAa,CAAC,CAAC,CAAC,KAAK,CAAA;IAClE,CAAC;SAAM,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC7D,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAc,CAAC,CAAA;IAC1D,CAAC;SAAM,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QAC3D,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,GAAa,CAAC,CAAA;IACxD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,4DAA4D,CAAC,CAAA;IACxG,CAAC;IAED,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,IAA4B,CAAA;IACnD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAE/E,wCAAwC;IACxC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACvC,MAAM,IAAI,oBAAoB,CAAC,wEAAwE,CAAC,CAAA;IAC1G,CAAC;IAED,UAAU;IACV,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAA4B,CAAC,CAAC,CAAA;IAC3E,CAAC;IAED,6CAA6C;IAC7C,gDAAgD;IAChD,0DAA0D;IAC1D,oDAAoD;IACpD,MAAM,SAAS,GAAG,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;IACrF,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,MAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAA;IAChG,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAA;AAChD,CAAC","sourcesContent":["/**\n * stdlib load — 加载库函数（统一 load 函数）\n *\n *\n * buffer 经宿主资产解析器解析，isCadFormat 静态判定 brep/mesh，\n * 产物经 solid()/fromBrep() 构造器创建。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { isCadFormat } from '../brep/brep-chain'\nimport { loadBrep } from '../brep/brep-ops'\nimport { OpError } from './internal/result-unwrap'\nimport { getBackends, BrepUnsupportedError } from '../runtime-state'\nimport { solid, fromBrep } from '../shape'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * 执行加载操作（统一 load 函数）\n *\n * 按 params 中存在的 key/path/url 分流解析 buffer，全部经宿主资产解析器。\n *\n * 静态分派：\n * - CAD 源 + kernel + 非 mesh 模式 → BREP 路径（loadBrep 异常 = 未预期错误，冒泡上报）\n * - 非 CAD 源 / 无 kernel / mesh 模式 → mesh 路径\n * - brep 模式且将走 mesh 路径 → 调用前抛 BrepUnsupportedError（不静默回退）\n */\n/**\n * 加载几何资产。key / path / url 三选一（按此优先级分流），内容经宿主资产解析器解析，**引用而非拷贝**。\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name load\n * @note 语言正常化后 loadFile/loadUrl/loadByKey 别名已删除（A4），统一为 `load` 一个函数。\n * @returns Shape 加载的几何，永远是 part 的第一条语句，后面可接特征链。\n * @param params.key - faicad 缓存中的资产 key（内容按 key 取）。type:string\n * @param params.path - 本地绝对路径（非 web 环境）。type:string\n * @param params.url - 网络地址。type:string\n * @param params.format - 格式提示（如 'step'/'stl'；CAD 源走 BREP 精确路径，STL 等三角化源走 mesh 路径）。type:string\n * @note key/path/url 是优先级分流（key 优先，其次 path，最后 url），三者只需其一；同时给多个时按优先级取。`format` 是提示而非强约束——CAD 源（step/stp/brep 等）与三角化源（stl 等）由 `isCadFormat` 静态判定路径。\n * @example\n * const p = await cad.load({ key: 'file_abc123' })\n * const p = await cad.load({ path: 'D:/models/box.step', format: 'step' })\n * const p = await cad.load({ url: 'https://…/box.3mf' })\n  */\nexport async function load(params: Record<string, unknown>): Promise<Shape> {\n  const assets = getBackends().assets as {\n    resolveByKey(key: string): Promise<{ bytes: ArrayBuffer }>\n    resolveFile(path: string): Promise<ArrayBuffer>\n    resolveUrl(url: string): Promise<ArrayBuffer>\n  } | undefined\n  if (!assets) {\n    throw new OpError('load', 'E_OP_FAILED', '[stdlib/load] assets is required for load op')\n  }\n\n  // 按 key/path/url 分流解析 buffer\n  let buffer: ArrayBuffer\n  if (params.key !== undefined && params.key !== null) {\n    buffer = (await assets.resolveByKey(params.key as string)).bytes\n  } else if (params.path !== undefined && params.path !== null) {\n    buffer = await assets.resolveFile(params.path as string)\n  } else if (params.url !== undefined && params.url !== null) {\n    buffer = await assets.resolveUrl(params.url as string)\n  } else {\n    throw new OpError('load', 'E_OP_FAILED', '[stdlib/load] load op requires exactly one of key/path/url')\n  }\n\n  // 静态判定路径：mesh 模式 / 无 kernel / 非 CAD 源 → mesh 路径；否则 BREP 路径\n  const { config, kernel: kernels } = getBackends()\n  const kernel = kernels.brep as BrepEngineApi | null\n  const useBrep = config.mode !== 'mesh' && !!kernel && isCadFormat(params, true)\n\n  // brep 模式且将走 mesh-only 路径 → 调用前抛错，不静默回退\n  if (!useBrep && config.mode === 'brep') {\n    throw new BrepUnsupportedError('E_BREP_UNSUPPORTED: load op has no BREP implementation for this source')\n  }\n\n  // mesh 路径\n  if (!useBrep) {\n    return solid(await cad.load(buffer, params.format as string | undefined))\n  }\n\n  // BREP 路径（直接执行，不包 try-catch！异常 = 未预期错误，冒泡上报）\n  // P2：brepChain（meshShapeCache）归引擎侧，loadBrep 不再传\n  // partIndex：多 part 文件（如多 solid STEP）逐 part 加载——宿主为每个 part\n  // 生成独立 load 语句并携带 partIndex，提取 Compound 中对应子 solid。\n  const partIndex = typeof params.partIndex === 'number' ? params.partIndex : undefined\n  const { solid: solidHandle, shape } = loadBrep(kernel!, buffer, undefined, undefined, partIndex)\n  return fromBrep(shape, { solid: solidHandle })\n}\n"]}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/api/load.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAG1C;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,MAA+B;IACxD,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAIhB,CAAA;IACb,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,8CAA8C,CAAC,CAAA;IAC1F,CAAC;IAED,6BAA6B;IAC7B,IAAI,MAAmB,CAAA;IACvB,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAa,CAAC,CAAC,CAAC,KAAK,CAAA;IAClE,CAAC;SAAM,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC7D,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAc,CAAC,CAAA;IAC1D,CAAC;SAAM,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QAC3D,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,GAAa,CAAC,CAAA;IACxD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,4DAA4D,CAAC,CAAA;IACxG,CAAC;IAED,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,IAA4B,CAAA;IACnD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAE/E,wCAAwC;IACxC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACvC,MAAM,IAAI,oBAAoB,CAAC,wEAAwE,CAAC,CAAA;IAC1G,CAAC;IAED,UAAU;IACV,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAA4B,CAAC,CAAC,CAAA;IAC3E,CAAC;IAED,6CAA6C;IAC7C,gDAAgD;IAChD,0DAA0D;IAC1D,oDAAoD;IACpD,MAAM,SAAS,GAAG,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;IACrF,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC5C,MAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CACjD,CAAA;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAA;AAChD,CAAC","sourcesContent":["/**\n * stdlib load — 加载库函数（统一 load 函数）\n *\n *\n * buffer 经宿主资产解析器解析，isCadFormat 静态判定 brep/mesh，\n * 产物经 solid()/fromBrep() 构造器创建。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { isCadFormat } from '../brep/brep-chain'\nimport { loadBrep } from '../brep/brep-ops'\nimport { OpError } from './internal/result-unwrap'\nimport { getBackends, BrepUnsupportedError } from '../runtime-state'\nimport { solid, fromBrep } from '../shape'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * 执行加载操作（统一 load 函数）\n *\n * 按 params 中存在的 key/path/url 分流解析 buffer，全部经宿主资产解析器。\n *\n * 静态分派：\n * - CAD 源 + kernel + 非 mesh 模式 → BREP 路径（loadBrep 异常 = 未预期错误，冒泡上报）\n * - 非 CAD 源 / 无 kernel / mesh 模式 → mesh 路径\n * - brep 模式且将走 mesh 路径 → 调用前抛 BrepUnsupportedError（不静默回退）\n */\n/**\n * 加载几何资产。key / path / url 三选一（按此优先级分流），内容经宿主资产解析器解析，**引用而非拷贝**。\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name load\n * @note 语言正常化后 loadFile/loadUrl/loadByKey 别名已删除（A4），统一为 `load` 一个函数。\n * @returns Shape 加载的几何，永远是 part 的第一条语句，后面可接特征链。\n * @param params.key - faicad 缓存中的资产 key（内容按 key 取）。type:string\n * @param params.path - 本地绝对路径（非 web 环境）。type:string\n * @param params.url - 网络地址。type:string\n * @param params.format - 格式提示（如 'step'/'stl'；CAD 源走 BREP 精确路径，STL 等三角化源走 mesh 路径）。type:string\n * @note key/path/url 是优先级分流（key 优先，其次 path，最后 url），三者只需其一；同时给多个时按优先级取。`format` 是提示而非强约束——CAD 源（step/stp/brep 等）与三角化源（stl 等）由 `isCadFormat` 静态判定路径。\n * @note 本 op 要求导入物含实体（历史契约）。非实体（wire/face/shell）的导入是平台 `cad.import_brep` 的一等能力，不由本 op 承担。\n * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用的「文件导入 Feature」提供——key/path/url 三键分流读的是应用侧 `FileRef`，产物语句位置、命名与 partIndex 都是画布语义。不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。平台侧导入请用 `cad.import_brep`（冻结 BREP 资产）。\n * @example\n * const p = await cad.load({ key: 'file_abc123' })\n * const p = await cad.load({ path: 'D:/models/box.step', format: 'step' })\n * const p = await cad.load({ url: 'https://…/box.3mf' })\n */\nexport async function load(params: Record<string, unknown>): Promise<Shape> {\n  const assets = getBackends().assets as {\n    resolveByKey(key: string): Promise<{ bytes: ArrayBuffer }>\n    resolveFile(path: string): Promise<ArrayBuffer>\n    resolveUrl(url: string): Promise<ArrayBuffer>\n  } | undefined\n  if (!assets) {\n    throw new OpError('load', 'E_OP_FAILED', '[stdlib/load] assets is required for load op')\n  }\n\n  // 按 key/path/url 分流解析 buffer\n  let buffer: ArrayBuffer\n  if (params.key !== undefined && params.key !== null) {\n    buffer = (await assets.resolveByKey(params.key as string)).bytes\n  } else if (params.path !== undefined && params.path !== null) {\n    buffer = await assets.resolveFile(params.path as string)\n  } else if (params.url !== undefined && params.url !== null) {\n    buffer = await assets.resolveUrl(params.url as string)\n  } else {\n    throw new OpError('load', 'E_OP_FAILED', '[stdlib/load] load op requires exactly one of key/path/url')\n  }\n\n  // 静态判定路径：mesh 模式 / 无 kernel / 非 CAD 源 → mesh 路径；否则 BREP 路径\n  const { config, kernel: kernels } = getBackends()\n  const kernel = kernels.brep as BrepEngineApi | null\n  const useBrep = config.mode !== 'mesh' && !!kernel && isCadFormat(params, true)\n\n  // brep 模式且将走 mesh-only 路径 → 调用前抛错，不静默回退\n  if (!useBrep && config.mode === 'brep') {\n    throw new BrepUnsupportedError('E_BREP_UNSUPPORTED: load op has no BREP implementation for this source')\n  }\n\n  // mesh 路径\n  if (!useBrep) {\n    return solid(await cad.load(buffer, params.format as string | undefined))\n  }\n\n  // BREP 路径（直接执行，不包 try-catch！异常 = 未预期错误，冒泡上报）\n  // P2：brepChain（meshShapeCache）归引擎侧，loadBrep 不再传\n  // partIndex：多 part 文件（如多 solid STEP）逐 part 加载——宿主为每个 part\n  // 生成独立 load 语句并携带 partIndex，提取 Compound 中对应子 solid。\n  const partIndex = typeof params.partIndex === 'number' ? params.partIndex : undefined\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel!, buffer, undefined, undefined, partIndex,\n  )\n  return fromBrep(shape, { solid: solidHandle })\n}\n"]}

package/dist/api/pattern.d.ts

@@ -0,0 +1,32 @@
+/**
+ * stdlib pattern — linearPattern（手写覆盖生成投影，Phase 3: L3 `replica[k]` 角色表）
+ *
+ * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径
+ * 用质心聚类把结果面按份数 k 分组、回投影到输入面角色，产出 `replica[k]/<inner>`。
+ *
+ * 机制（无内核历史，纯几何推理）：pattern 的每份副本都是输入的精确平移，副本面
+ * 几何相同但质心不同。结果面沿 pattern 方向投影得到份数坐标 t，四舍五入到 spacing
+ * 倍数即得 k；再按「面内坐标」（centroid − t·dir）匹配输入面对应面，回投其 inner role。
+ */
+import type { Shape, Vec3 } from '../mesh/types.js';
+/**
+ * 线性阵列：沿 direction 复制 count 份（含原位置）。
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name linearPattern
+ * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。结果面按份数 k 回投影到输入面
+ *       角色，产出 `replica[k]/<inner>`（Phase 3 L3 抗重放词汇）。
+ * @returns Shape 所有副本 fused 后的几何。
+ * @param input - 目标几何。type:Shape required:true
+ * @param direction - 阵列方向。type:[x,y,z] required:true
+ * @param count - 副本总数（含原位置）。type:number required:true
+ * @param spacing - 副本间距。type:number required:true
+ * @example
+ * const p = await cad.linearPattern(part0, [1, 0, 0], 3, 20)
+ */
+export declare const linearPattern: ((input: Shape, direction: Vec3, count: number, spacing: number) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=pattern.d.ts.map

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

@@ -0,0 +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;AAgGhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;;CAKxB,CAAA"}