@faicad/faijs 0.29.3 → 0.30.9

package/dist/api/helix.js

@@ -19,7 +19,7 @@ import { getBrepApi } from '../brep/handle-bridge.js';
 import { fromBrepCurve } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { getOcctKernel } from '../occt-kernel/occtKernel.js';
-/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */
+/** BREP 路径：用 occt 原生 makeHelixWire / makeHelixWireHanded 构造螺旋线，登记 1D 句柄。 */
 function helixBrep(opts) {
     const { radius, pitch, turns } = opts;
     if (!(radius > 0))
@@ -28,12 +28,21 @@ function helixBrep(opts) {
         throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero');
     if (!(turns > 0))
         throw new Error('E_HELIX_BAD_TURNS: turns must be > 0');
+    const handed = opts.handed ?? 'right';
+    if (handed !== 'right' && handed !== 'left') {
+        throw new Error(`E_HELIX_BAD_HANDED: handed must be 'right' or 'left' (got '${String(handed)}')`);
+    }
     const axis = opts.axis ?? [0, 0, 1];
     const origin = opts.origin ?? [0, 0, 0];
     const height = pitch * turns;
     const kernel = getBrepApi();
     const occt = getOcctKernel();
-    const handle = occt.makeHelixWire({ x: origin[0], y: origin[1], z: origin[2] }, { x: axis[0], y: axis[1], z: axis[2] }, pitch, height, radius);
+    const o = { x: origin[0], y: origin[1], z: origin[2] };
+    const a = { x: axis[0], y: axis[1], z: axis[2] };
+    // 右手默认沿用 makeHelixWire（保持两个原生入口都可达）；左手走带手性的显式入口。
+    const handle = (handed === 'left'
+        ? occt.makeHelixWireHanded(o, a, pitch, height, radius, true)
+        : occt.makeHelixWire(o, a, pitch, height, radius));
     return fromBrepCurve(solidToShape(kernel, handle), { solid: handle });
 }
 /**
@@ -43,17 +52,24 @@ function helixBrep(opts) {
  * @async false
  * @qual ok
  * @name helix
- * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @note 平台 op：仅 occt 引擎（原生 makeHelixWire / makeHelixWireHanded）。非 occt 引擎执行前报错；brep_mock 不拦截。
  * @returns Shape 1D 螺旋线（kind:'curve'）。
  * @param options.radius - 螺旋半径（mm，>0）。type:number required:true
  * @param options.pitch - 螺距（mm，≠0）。type:number required:true
  * @param options.turns - 圈数（>0）。type:number required:true
  * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false
  * @param options.origin - 起点（默认原点）。type:Vec3 required:false
+ * @param options.handed - 手性：'right'（默认）或 'left'。type:HelixHanded required:false
  * @example
  * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })
+ * const lh = cad.helix({ radius: 5, pitch: 2, turns: 3, handed: 'left' })
  */
 export const helix = defineOp({
+    // name 必填：① 引擎门文案携带 op 名（`op 'helix' requires engine occt`，见
+    // test/api/sweep-loft.test.ts GOTCHA-3 对该形态的要求）；② occt op 覆盖率扫描器
+    // 的 op 全集只收 `export const X = defineOp({ name: '…' })`——缺 name 的 op
+    // 不可见，其直调的 occt 方法（makeHelixWireHanded）会被误判为「未接入」。
+    name: 'helix',
     brep(opts) {
         return helixBrep(opts);
     },

package/dist/api/helix.js.map

@@ -1 +1 @@
-{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAgBzD,sDAAsD;AACtD,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAC/B,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAC5C,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EACtC,KAAK,EACL,MAAM,EACN,MAAM,CACkB,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = occt.makeHelixWire(\n    { x: origin[0], y: origin[1], z: origin[2] },\n    { x: axis[0], y: axis[1], z: axis[2] },\n    pitch,\n    height,\n    radius,\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n */\nexport const helix = defineOp({\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}
+{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAwBzD,4EAA4E;AAC5E,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAA;IACrC,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,8DAA8D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnG,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACtD,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAChD,iDAAiD;IACjD,MAAM,MAAM,GAAG,CACb,MAAM,KAAK,MAAM;QACf,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAC3B,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,6DAA6D;IAC7D,iEAAiE;IACjE,oEAAoE;IACpE,mDAAmD;IACnD,IAAI,EAAE,OAAO;IACb,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** 螺旋手性：`'right'`（右手，逆时针上旋）或 `'left'`（左手，顺时针上旋）。 */\nexport type HelixHanded = 'right' | 'left'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n  /**\n   * 手性（默认 `'right'`）。同 pitch/height/radius 下左右旋互为镜像。\n   * `'right'` 走 `makeHelixWire`，`'left'` 走 `makeHelixWireHanded(..., true)`。\n   */\n  handed?: HelixHanded\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire / makeHelixWireHanded 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const handed = opts.handed ?? 'right'\n  if (handed !== 'right' && handed !== 'left') {\n    throw new Error(`E_HELIX_BAD_HANDED: handed must be 'right' or 'left' (got '${String(handed)}')`)\n  }\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const o = { x: origin[0], y: origin[1], z: origin[2] }\n  const a = { x: axis[0], y: axis[1], z: axis[2] }\n  // 右手默认沿用 makeHelixWire（保持两个原生入口都可达）；左手走带手性的显式入口。\n  const handle = (\n    handed === 'left'\n      ? occt.makeHelixWireHanded(o, a, pitch, height, radius, true)\n      : occt.makeHelixWire(o, a, pitch, height, radius)\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire / makeHelixWireHanded）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @param options.handed - 手性：'right'（默认）或 'left'。type:HelixHanded required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n * const lh = cad.helix({ radius: 5, pitch: 2, turns: 3, handed: 'left' })\n */\nexport const helix = defineOp({\n  // name 必填：① 引擎门文案携带 op 名（`op 'helix' requires engine occt`，见\n  // test/api/sweep-loft.test.ts GOTCHA-3 对该形态的要求）；② occt op 覆盖率扫描器\n  // 的 op 全集只收 `export const X = defineOp({ name: '…' })`——缺 name 的 op\n  // 不可见，其直调的 occt 方法（makeHelixWireHanded）会被误判为「未接入」。\n  name: 'helix',\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}

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

@@ -1 +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;AAU1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAuCpF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAMtB,CAAA"}
+{"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;AAwB1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAkDpF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAMtB,CAAA"}

package/dist/api/import-step.js

@@ -4,6 +4,20 @@ import { OpError } from './internal/result-unwrap.js';
 import { loadBrep } from '../brep/brep-ops.js';
 import { fromBrep } from '../shape.js';
 import { defineOp } from '../sdk.js';
+import { parseStepPartMeta } from '../step/stepMetaParser.js';
+/** 尽力把 ArrayBuffer 当 UTF-8 文本解出；非文本（如 .brp 二进制）返回 undefined。 */
+function decodeStepText(buffer) {
+    if (!(buffer?.byteLength))
+        return undefined;
+    try {
+        const s = new TextDecoder('utf-8', { fatal: false }).decode(buffer);
+        // STEP 是纯文本 ISO-10303-21；首段要出现 `ISO-10303-21;` 才算。
+        return s.includes('ISO-10303-21') ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * api import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
  *
@@ -55,6 +69,20 @@ export async function importStepImpl(params) {
     // C6：非实体一等公民（对齐 import_brep）。loadBrep 自适应：CASCADE Topology
     // 文本走 kernel.fromBREP，其余（STEP/STP）走 kernel.importStep。
     const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, { allowNonSolid: true });
+    // P2（设计文档 2026-10-05-meta §5.2 读）：从 STEP (P21) 文本捞伙伴级描述/属性
+    // 挂 `shape.meta`（name 已由 OCCT label 提供，description/UDA 由纯文本补充）。
+    // 非文本/非 STEP 内容跳过，绝不抛。
+    const stepText = decodeStepText(buffer);
+    if (stepText && shape.meta == null) {
+        const partMeta = parseStepPartMeta(stepText);
+        const shapeMeta = { ...(shape.meta ?? {}) };
+        if (partMeta.description)
+            shapeMeta.description = partMeta.description;
+        if (partMeta.metadata && Object.keys(partMeta.metadata).length > 0)
+            shapeMeta.metadata = partMeta.metadata;
+        if (Object.keys(shapeMeta).length > 0)
+            shape.meta = shapeMeta;
+    }
     // E3（H12）：链根建 roleTable——导入文件的面没有语义名，按枚举序命名
     // imported:<i>（同一文件重复导入，枚举序稳定，role 名跨次导入保持一致）。
     const stmtId = String(getCurrentStmt()?.id ?? '');

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

@@ -1 +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,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAIjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAA+B;IAClE,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,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QAAC,MAAM,GAAG,UAAU,EAAE,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,oBAAoB,CAChE,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,EAAE,aAAa,EAAE,IAAI,EAAE,CAC9D,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;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,iEAAiE;IACjE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,EAAgB;CACpH,CAAC,CAAA","sourcesContent":["import type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * api 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\n/**\n * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。\n *\n * @param params - op 参数对象；`path` 为 STEP 文件路径。\n * @returns 持 OCCT 句柄的几何（非实体亦可）。\n */\nexport async function importStepImpl(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  let kernel: BrepEngineApi\n  try { kernel = getBrepApi() } catch { 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, { 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\n/**\n * GOTCHA（2026-09-30）：与 import_brep 同——必须经 defineOp 包装进入 cad 命名空间，\n * 不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在 define-op.ts\n * 包装层的 brep 分支登记；裸 async 函数产物没有 part 键表，下游 place/edgeRef\n * 报 \"input shape has no role table (nameless shape)\"。\n */\nexport const import_step = defineOp({\n  name: 'import_step',\n  brep: importStepImpl,\n  engines: ['occt'],\n  // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`），与 import-brep 同构。\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } } as Provenance,\n})\n"]}
+{"version":3,"file":"import-step.js","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { parseStepPartMeta } from '../step/stepMetaParser'\nimport type { ShapeMeta } from './meta'\n\n/** 尽力把 ArrayBuffer 当 UTF-8 文本解出；非文本（如 .brp 二进制）返回 undefined。 */\nfunction decodeStepText(buffer: ArrayBuffer): string | undefined {\n  if (!(buffer?.byteLength)) return undefined\n  try {\n    const s = new TextDecoder('utf-8', { fatal: false }).decode(buffer)\n    // STEP 是纯文本 ISO-10303-21；首段要出现 `ISO-10303-21;` 才算。\n    return s.includes('ISO-10303-21') ? s : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * api 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\n/**\n * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。\n *\n * @param params - op 参数对象；`path` 为 STEP 文件路径。\n * @returns 持 OCCT 句柄的几何（非实体亦可）。\n */\nexport async function importStepImpl(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  let kernel: BrepEngineApi\n  try { kernel = getBrepApi() } catch { 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, { allowNonSolid: true },\n  )\n  // P2（设计文档 2026-10-05-meta §5.2 读）：从 STEP (P21) 文本捞伙伴级描述/属性\n  // 挂 `shape.meta`（name 已由 OCCT label 提供，description/UDA 由纯文本补充）。\n  // 非文本/非 STEP 内容跳过，绝不抛。\n  const stepText = decodeStepText(buffer)\n  if (stepText && shape.meta == null) {\n    const partMeta = parseStepPartMeta(stepText)\n    const shapeMeta: ShapeMeta = { ...(shape.meta ?? {}) }\n    if (partMeta.description) shapeMeta.description = partMeta.description\n    if (partMeta.metadata && Object.keys(partMeta.metadata).length > 0) shapeMeta.metadata = partMeta.metadata\n    if (Object.keys(shapeMeta).length > 0) shape.meta = shapeMeta\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\n/**\n * GOTCHA（2026-09-30）：与 import_brep 同——必须经 defineOp 包装进入 cad 命名空间，\n * 不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在 define-op.ts\n * 包装层的 brep 分支登记；裸 async 函数产物没有 part 键表，下游 place/edgeRef\n * 报 \"input shape has no role table (nameless shape)\"。\n */\nexport const import_step = defineOp({\n  name: 'import_step',\n  brep: importStepImpl,\n  engines: ['occt'],\n  // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`），与 import-brep 同构。\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } } as Provenance,\n})\n"]}

package/dist/api/index.d.ts

@@ -1,8 +1,6 @@
 /**
  * L3 API 面（api/）— faijs 库函数命名空间
  *
- * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）
- *
  * 导出全部官方库函数、Shape 构造器与 schema 表。
  * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；
  * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。
@@ -32,8 +30,19 @@ export type { SketchOnPlaneParams, PlaneSpec } from './sketch-on-plane.js';
 export { wire } from './wire.js';
 export { helix } from './helix.js';
 export { split } from './split.js';
-export { sweep } from './sweep.js';
+export { sweep, type SweepOptions, type SweepOrientation, type SweepGuideContact, type SweepLawKind } from './sweep.js';
 export { loft } from './loft.js';
+export { surface, type SurfaceOptions } from './surface.js';
+export { offset2d, type Offset2DOptions, type Offset2DJoinType } from './offset2d.js';
+export { solidFromFaces, type SolidFromFacesParams } from './solid-from-faces.js';
+export { halfSpace, type HalfSpaceParams } from './half-space.js';
+export { exportStl, type ExportStlOptions } from './export-stl.js';
+export { exportBrep } from './export-brep.js';
+export { isEdge, isFace, isShell, isVertex, isWire, isCompSolid, isEqual } from './shape-type/index.js';
+export { toSVG, toMultiviewSVG, toPNG, toMultiviewPNG } from './view-export/index.js';
+export { edge, circleArc, ellipseEdge, ellipseArc, tangentArc, approximatePoints, interpolateWithTangents, curveDegreeElevate, curveKnotInsert, curveKnotRemove, curveIsPeriodic, } from './curve-sketch/index.js';
+export { faceOnSurface, nonPlanarFace, makeSolid, reverseSurfaceU, outerWire } from './surface-face/index.js';
+export { draftPrism, pipe } from './solid-offset/index.js';
 export { knurl } from './knurl.js';
 export { sdf } from './sdf.js';
 export { applyTransform } from '../mesh/rigid-transform.js';
@@ -50,12 +59,16 @@ export { solid, isShape, isCompound } from '../shape.js';
 export { compound as structCompound } from '../shape.js';
 export type { ShapeSlot, SolidShape, CompoundShape, CurveShape, StdShape, ShapeKind } from '../shape.js';
 export type { Shape } from '../mesh/types.js';
+export type { PbrAppearance, PbrColor, PbrAlphaMode, MaterialSpec, ShapeAppearanceMethods } from './appearance.js';
+export { mergeAppearance, normalizeColor } from './appearance.js';
+export type { ShapeMeta, FileMeta, ShapeMetaMethods } from './meta.js';
+export { mergeMeta } from './meta.js';
 export * from './generated/script-face.js';
 export { extrude } from './extrude.js';
 export { revolve } from './generated/operations.js';
-export { ok, err, isOk, isErr, unwrap, unwrapOr, vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize, createPlane, createNamedPlane, resolvePlane, kernelError, validationError, DEG2RAD, RAD2DEG, } from './brepjs-compat/index.js';
-export type { Result, Ok, Err, BrepError, Plane, PlaneName, PlaneInput, Vec3, PointInput, } from './brepjs-compat/index.js';
-export { map, andThen } from './brepjs-compat/index.js';
+export { ok, err, isOk, isErr, unwrap, unwrapOr, vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize, createPlane, createNamedPlane, resolvePlane, kernelError, validationError, DEG2RAD, RAD2DEG, } from './geom-types/index.js';
+export type { Result, Ok, Err, BrepError, Plane, PlaneName, PlaneInput, Vec3, PointInput, } from './geom-types/index.js';
+export { map, andThen } from './geom-types/index.js';
 export * from './brep-topology.js';
 export * from './cadquery-selectors/index.js';
 export { measureVolume, measureArea, measureLength } from './generated/measurement.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAQjE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,mBAAmB,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACrI,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9E,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC3E,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACtG,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAG3B,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAKxD,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrD,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,UAAU,CAAA;AACrD,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACrG,YAAY,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAO1C,cAAc,yBAAyB,CAAA;AAOvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAMhD,OAAO,EACL,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EACtC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EACnE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAC3C,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,OAAO,GACjB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,MAAM,EAAE,EAAE,EAAE,GAAG,EACf,SAAS,EACT,KAAK,EAAE,SAAS,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,GACjB,MAAM,iBAAiB,CAAA;AAMxB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAM9C,cAAc,iBAAiB,CAAA;AAG/B,cAAc,sBAAsB,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}

package/dist/api/index.js

@@ -1,8 +1,6 @@
 /**
  * L3 API 面（api/）— faijs 库函数命名空间
  *
- * 设计文档：docs/plans/2026-09-01-layered-api-architecture.md §D1/D2（P6 迁入 core）
- *
  * 导出全部官方库函数、Shape 构造器与 schema 表。
  * 库函数签名 = .fai.js 源码里的调用形态（无隐式参数）；
  * 后端资源经 getBackends() 获取，保留声明经 keep() 表达。
@@ -39,6 +37,29 @@ export { helix } from './helix.js';
 export { split } from './split.js';
 export { sweep } from './sweep.js';
 export { loft } from './loft.js';
+// S3（occt-wasm op 接入）：控制点阵 → B 样条面（平台 op engines:['occt']）。
+export { surface } from './surface.js';
+// S3（occt-wasm op 接入）：2D 轮廓偏置 → 1D 轮廓（平台 op engines:['occt']）。
+export { offset2d } from './offset2d.js';
+// S3（occt-wasm op 接入）：面集一次成型为实体（平台 op engines:['occt']）。
+export { solidFromFaces } from './solid-from-faces.js';
+// S3（occt-wasm op 接入）：无限半空间实体（平台 op engines:['occt']，作无界布尔工具）。
+export { halfSpace } from './half-space.js';
+// S3（occt-wasm op 接入）：导出族——STL（中立，纯数据序列化）/ BREP 文本（平台 op engines:['occt']）。
+export { exportStl } from './export-stl.js';
+export { exportBrep } from './export-brep.js';
+// S4（occt-wasm op 接入）：类型判定谓词族（平台 op engines:['occt']，布尔返回）。
+// 仅平铺不与 ../shape 既有 TS 守卫同名者；`isCompound` 与 ../shape#isCompound 同名，
+// 只在 cad 脚本面（api-namespace）暴露，避免本桶重复导出。
+export { isEdge, isFace, isShell, isVertex, isWire, isCompSolid, isEqual } from './shape-type/index.js';
+// S4 视图与导出族（平台 op engines:['occt']，字符串/Uint8Array 返回）：平铺到 TS 桶。
+export { toSVG, toMultiviewSVG, toPNG, toMultiviewPNG } from './view-export/index.js';
+// S4（occt-wasm op 接入）：曲线与草图构造族（平台 op engines:['occt']，方案 §3.4.1）。
+export { edge, circleArc, ellipseEdge, ellipseArc, tangentArc, approximatePoints, interpolateWithTangents, curveDegreeElevate, curveKnotInsert, curveKnotRemove, curveIsPeriodic, } from './curve-sketch/index.js';
+// S4（occt-wasm op 接入）：曲面与面构造族（平台 op engines:['occt']，方案 §3.4.2）。
+export { faceOnSurface, nonPlanarFace, makeSolid, reverseSurfaceU, outerWire } from './surface-face/index.js';
+// S4（occt-wasm op 接入）：实体与偏置族剩余（平台 op engines:['occt']，方案 §3.4.4）。
+export { draftPrism, pipe } from './solid-offset/index.js';
 export { knurl } from './knurl.js';
 export { sdf } from './sdf.js';
 // 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：
@@ -60,10 +81,12 @@ export { faceRef } from './face-ref.js';
 export { asset } from './asset.js';
 export { solid, isShape, isCompound } from '../shape.js';
 export { compound as structCompound } from '../shape.js';
+export { mergeAppearance, normalizeColor } from './appearance.js';
+export { mergeMeta } from './meta.js';
 // ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──
 //
 // ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。
-//    这批 op 经 `compatOp(projectBrepOp(…))` 包装，faijs 形态（Shape 进 / Shape 出、
+//    这批 op 经 `defineOp({ brep: __own_* })` 直连 core 自有实现，faijs 形态（Shape 进 / Shape 出、
 //    布尔双形态、brep-only），TS 侧与 `.fai.js` 侧同语义。
 export * from './generated/script-face.js';
 // P25: compat extrude/revolve (brep-only, face→prism / face→lathe) share one
@@ -75,17 +98,17 @@ export * from './generated/script-face.js';
 export { extrude } from './extrude.js';
 export { revolve } from './generated/operations.js';
 //
-// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随 vendored
-//    树删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具
+// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随旧
+//    子包删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具
 //    （Result / 向量 / 平面 / 错误 / 常量），它们为 core 内联实现（§5.2），
 //    在两个面之间语义一致且无同名冲突。
-export { ok, err, isOk, isErr, unwrap, unwrapOr, vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize, createPlane, createNamedPlane, resolvePlane, kernelError, validationError, DEG2RAD, RAD2DEG, } from './brepjs-compat/index.js';
-// ── 2026-09-25 core-decouple：vendored 库建造工厂（makeExternalGear /
+export { ok, err, isOk, isErr, unwrap, unwrapOr, vecAdd, vecSub, vecScale, vecDot, vecCross, vecLength, vecNormalize, createPlane, createNamedPlane, resolvePlane, kernelError, validationError, DEG2RAD, RAD2DEG, } from './geom-types/index.js';
+// ── 2026-09-25 core-decouple：旧库建造工厂（makeExternalGear /
 //    makeInternalGear / makePlanetaryGear / thread）与其句柄类型
 //    （Vertex/Edge/…/Shape3D/ValidSolid/Bounds3D/Gear*）随裁决 9 删除；
 //    Result 组合器 map/andThen 为 core 内联（§5.2），保留平铺；
 //    brepjsCompat 命名空间整体删除（§5.5 第 3 条）。
-export { map, andThen } from './brepjs-compat/index.js';
+export { map, andThen } from './geom-types/index.js';
 // ── 2026-09-25 core-decouple wrapup §2.2：sheetmetal 拓扑查询 / 构造 / 测量
 //    出口（faijs 风格，裁决 3 补进公开导出）。isValid 不在此面——cad 脚本面
 //    已有同语义出口（见 brep-topology.ts 头部注释）。同步测量（measureVolume

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 库函数命名空间\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。\n//\n// D1（2026-09-23 扩展库拆分，选项 C）：四个 transform op **全部留 core**——\n// `translate` 是通用几何变换且是小程序端唯一在用的 transform op，同族不拆散。\nexport { translate, rotate_euler, scale, scale3d } from './transform'\nexport { union, subtract, intersect, cut } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { shell, type ShellParams } from './shell'\nexport { draft, type DraftParams } from './draft'\nexport { thicken } from './thicken'\nexport { defeature, reverseShape, unifySameDomain, sew, sewAndSolidify, removeHolesFromFace, type SewParams } from './feature-repair'\nexport { filletVariable } from './fillet-variable'\nexport { splitByPlane, type SplitByPlaneParams } from './split-by-plane'\nexport { sectionByPlane, type SectionByPlaneParams } from './section-by-plane'\nexport { screw } from './screw'\nexport { profile, buildProfileShape, assertProfileParams } from './profile'\nexport type { ProfileLineSeg, ProfileArcSeg, ProfileSeg, ProfileLoop, ProfileParams } from './profile'\nexport { sketchOnPlane, buildSketchOnPlaneWith } from './sketch-on-plane'\nexport { sketchOnFace, buildSketchOnFaceWith } from './sketch-on-face'\nexport { punchHole, buildPunchHole, punchSolidOf } from './punch-hole'\nexport type { SketchOnPlaneParams, PlaneSpec } from './sketch-on-plane'\nexport { wire } from './wire'\nexport { helix } from './helix'\nexport { split } from './split'\nexport { sweep } from './sweep'\nexport { loft } from './loft'\nexport { knurl } from './knurl'\nexport { sdf } from './sdf'\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import api/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面）。\n// A/B 组 op（fai_* / group / assembly / copy / load / text / svgExtrude）已迁出\n// core，见 @faicad/faijs-extra；装配**求解器**（solve/validate/joints/solvers）\n// 仍是平台能力，留在此处。\nexport * from './assembly'\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 { 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, CurveShape, StdShape, ShapeKind } from '../shape'\nexport type { Shape } from '../mesh/types'\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// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随 vendored\n//    树删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具\n//    （Result / 向量 / 平面 / 错误 / 常量），它们为 core 内联实现（§5.2），\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  BrepError,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n} from './brepjs-compat'\n// ── 2026-09-25 core-decouple：vendored 库建造工厂（makeExternalGear /\n//    makeInternalGear / makePlanetaryGear / thread）与其句柄类型\n//    （Vertex/Edge/…/Shape3D/ValidSolid/Bounds3D/Gear*）随裁决 9 删除；\n//    Result 组合器 map/andThen 为 core 内联（§5.2），保留平铺；\n//    brepjsCompat 命名空间整体删除（§5.5 第 3 条）。\nexport { map, andThen } from './brepjs-compat'\n// ── 2026-09-25 core-decouple wrapup §2.2：sheetmetal 拓扑查询 / 构造 / 测量\n//    出口（faijs 风格，裁决 3 补进公开导出）。isValid 不在此面——cad 脚本面\n//    已有同语义出口（见 brep-topology.ts 头部注释）。同步测量（measureVolume\n//    / measureArea / measureLength）为 api/generated/measurement.ts 第一方\n//    同步版，一并平铺（cad 面的 volume/area/length 为 async 脚本面重命名）。\nexport * from './brep-topology'\n// CadQuery 拓扑选择器子系统（独立物理边界，与 topo-resolve 隔离）：\n// 等价搬运自 cq-compat，子路径直达 @faicad/faijs/api/cadquery-selectors。\nexport * from './cadquery-selectors'\nexport { measureVolume, measureArea, measureLength } from './generated/measurement'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 API 面（api/）— faijs 库函数命名空间\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。\n//\n// D1（2026-09-23 扩展库拆分，选项 C）：四个 transform op **全部留 core**——\n// `translate` 是通用几何变换且是小程序端唯一在用的 transform op，同族不拆散。\nexport { translate, rotate_euler, scale, scale3d } from './transform'\nexport { union, subtract, intersect, cut } from './boolean'\nexport { engrave } from './engrave'\nexport { chamfer } from './chamfer'\nexport { fillet } from './fillet'\nexport { shell, type ShellParams } from './shell'\nexport { draft, type DraftParams } from './draft'\nexport { thicken } from './thicken'\nexport { defeature, reverseShape, unifySameDomain, sew, sewAndSolidify, removeHolesFromFace, type SewParams } from './feature-repair'\nexport { filletVariable } from './fillet-variable'\nexport { splitByPlane, type SplitByPlaneParams } from './split-by-plane'\nexport { sectionByPlane, type SectionByPlaneParams } from './section-by-plane'\nexport { screw } from './screw'\nexport { profile, buildProfileShape, assertProfileParams } from './profile'\nexport type { ProfileLineSeg, ProfileArcSeg, ProfileSeg, ProfileLoop, ProfileParams } from './profile'\nexport { sketchOnPlane, buildSketchOnPlaneWith } from './sketch-on-plane'\nexport { sketchOnFace, buildSketchOnFaceWith } from './sketch-on-face'\nexport { punchHole, buildPunchHole, punchSolidOf } from './punch-hole'\nexport type { SketchOnPlaneParams, PlaneSpec } from './sketch-on-plane'\nexport { wire } from './wire'\nexport { helix } from './helix'\nexport { split } from './split'\nexport { sweep, type SweepOptions, type SweepOrientation, type SweepGuideContact, type SweepLawKind } from './sweep'\nexport { loft } from './loft'\n// S3（occt-wasm op 接入）：控制点阵 → B 样条面（平台 op engines:['occt']）。\nexport { surface, type SurfaceOptions } from './surface'\n// S3（occt-wasm op 接入）：2D 轮廓偏置 → 1D 轮廓（平台 op engines:['occt']）。\nexport { offset2d, type Offset2DOptions, type Offset2DJoinType } from './offset2d'\n// S3（occt-wasm op 接入）：面集一次成型为实体（平台 op engines:['occt']）。\nexport { solidFromFaces, type SolidFromFacesParams } from './solid-from-faces'\n// S3（occt-wasm op 接入）：无限半空间实体（平台 op engines:['occt']，作无界布尔工具）。\nexport { halfSpace, type HalfSpaceParams } from './half-space'\n// S3（occt-wasm op 接入）：导出族——STL（中立，纯数据序列化）/ BREP 文本（平台 op engines:['occt']）。\nexport { exportStl, type ExportStlOptions } from './export-stl'\nexport { exportBrep } from './export-brep'\n// S4（occt-wasm op 接入）：类型判定谓词族（平台 op engines:['occt']，布尔返回）。\n// 仅平铺不与 ../shape 既有 TS 守卫同名者；`isCompound` 与 ../shape#isCompound 同名，\n// 只在 cad 脚本面（api-namespace）暴露，避免本桶重复导出。\nexport { isEdge, isFace, isShell, isVertex, isWire, isCompSolid, isEqual } from './shape-type'\n// S4 视图与导出族（平台 op engines:['occt']，字符串/Uint8Array 返回）：平铺到 TS 桶。\nexport { toSVG, toMultiviewSVG, toPNG, toMultiviewPNG } from './view-export'\n// S4（occt-wasm op 接入）：曲线与草图构造族（平台 op engines:['occt']，方案 §3.4.1）。\nexport {\n  edge, circleArc, ellipseEdge, ellipseArc, tangentArc,\n  approximatePoints, interpolateWithTangents,\n  curveDegreeElevate, curveKnotInsert, curveKnotRemove, curveIsPeriodic,\n} from './curve-sketch'\n// S4（occt-wasm op 接入）：曲面与面构造族（平台 op engines:['occt']，方案 §3.4.2）。\nexport { faceOnSurface, nonPlanarFace, makeSolid, reverseSurfaceU, outerWire } from './surface-face'\n// S4（occt-wasm op 接入）：实体与偏置族剩余（平台 op engines:['occt']，方案 §3.4.4）。\nexport { draftPrism, pipe } from './solid-offset'\nexport { knurl } from './knurl'\nexport { sdf } from './sdf'\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import api/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n// P2-f3：装配子层全量导出（solvePreview/entityFromGeometry 等经此到门面）。\n// A/B 组 op（fai_* / group / assembly / copy / load / text / svgExtrude）已迁出\n// core，见 @faicad/faijs-extra；装配**求解器**（solve/validate/joints/solvers）\n// 仍是平台能力，留在此处。\nexport * from './assembly'\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 { 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, CurveShape, StdShape, ShapeKind } from '../shape'\nexport type { Shape } from '../mesh/types'\n// PBR 外观规格（设计文档 2026-10-05 v2 §4.1）：类型供宿主/第三方消费；\n// 归一化/合并纯函数供编辑器映射（faijsAppearanceToHost）与导出复用。\nexport type { PbrAppearance, PbrColor, PbrAlphaMode, MaterialSpec, ShapeAppearanceMethods } from './appearance'\nexport { mergeAppearance, normalizeColor } from './appearance'\n// 零件/文件级说明性元数据（设计文档 2026-10-05-meta）：类型供宿主/第三方消费；\n// 合并纯函数供编辑器映射与导出复用。\nexport type { ShapeMeta, FileMeta, ShapeMetaMethods } from './meta'\nexport { mergeMeta } from './meta'\n\n// ── P23：brepjs 兼容面接线（§4.2 / B1 三源一致）──\n//\n// ① 生成脚本面 op（与 api-namespace 的 cad 面同源：api/generated/script-face.ts）。\n//    这批 op 经 `defineOp({ brep: __own_* })` 直连 core 自有实现，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// ② 2026-09-25 core-decouple：brepjsCompat 命名空间与全部 op 投影随旧\n//    子包删除（§5.5 第 3 条，裁决 9）。此处只平铺**无 op 语义**的组合器与纯工具\n//    （Result / 向量 / 平面 / 错误 / 常量），它们为 core 内联实现（§5.2），\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 './geom-types'\nexport type {\n  Result, Ok, Err,\n  BrepError,\n  Plane, PlaneName, PlaneInput,\n  Vec3, PointInput,\n} from './geom-types'\n// ── 2026-09-25 core-decouple：旧库建造工厂（makeExternalGear /\n//    makeInternalGear / makePlanetaryGear / thread）与其句柄类型\n//    （Vertex/Edge/…/Shape3D/ValidSolid/Bounds3D/Gear*）随裁决 9 删除；\n//    Result 组合器 map/andThen 为 core 内联（§5.2），保留平铺；\n//    brepjsCompat 命名空间整体删除（§5.5 第 3 条）。\nexport { map, andThen } from './geom-types'\n// ── 2026-09-25 core-decouple wrapup §2.2：sheetmetal 拓扑查询 / 构造 / 测量\n//    出口（faijs 风格，裁决 3 补进公开导出）。isValid 不在此面——cad 脚本面\n//    已有同语义出口（见 brep-topology.ts 头部注释）。同步测量（measureVolume\n//    / measureArea / measureLength）为 api/generated/measurement.ts 第一方\n//    同步版，一并平铺（cad 面的 volume/area/length 为 async 脚本面重命名）。\nexport * from './brep-topology'\n// CadQuery 拓扑选择器子系统（独立物理边界，与 topo-resolve 隔离）：\n// 等价搬运自 cq-compat，子路径直达 @faicad/faijs/api/cadquery-selectors。\nexport * from './cadquery-selectors'\nexport { measureVolume, measureArea, measureLength } from './generated/measurement'\n"]}

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

@@ -2,8 +2,6 @@
  * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement
  * op, built **on top of** defineOp (single implementation entry, v1).
  *
- * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3
- *
  * compatOp is NOT a second implementation path parallel to defineOp: every
  * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability
  * routing), the Result boundary (runImpl + unwrapResult), product wrapping
@@ -12,16 +10,13 @@
  *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of
  *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);
  *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the
- *     three bridging steps that cannot be shared (all reuse shared
+ *     two bridging steps that cannot be shared (all reuse shared
  *     infrastructure, §3.2):
- *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →
- *          borrowBrepjsShape view (zero-copy; library-private handles pass
- *          through untouched);
- *       2. call + unwrap — callBrepjs through the shared unwrapResult
+ *       1. call + unwrap — callBrepjs through the shared unwrapResult
  *          (`err` throws an OpError carrying the op name + BrepError code);
  *          async library fns are awaited first, so `Promise<Result<…>>` —
  *          the shape every kernel-awaiting library returns — unwraps too;
- *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared
+ *       2. adoptOut — outward adoption: top-level handle / `outputs`-declared
  *          fields (single handle or handle array) → adoptEntity
  *          (unregister finalizer + fromHandle).
  *
@@ -44,28 +39,7 @@ import type { Shape } from '../../mesh/types.js';
 export interface CompatSpec extends Omit<DualOpOptions, 'mesh' | 'brep'> {
     /** Op name (error messages + metadata; required, unlike defineOp's optional name). */
     name: string;
-    /**
-     * 是否按 brepjs 句柄形态借入输入（默认 true）。
-     *
-     * faijs 化库（内部直接消费 core Shape 与 core op，如 sheetmetal）必须传
-     * `borrow: false`：borrowDeep 会把嵌套的 faijs Shape 替换成 brepjs 形态的
-     * `BorrowedShapeHandle`，而 core op 只认带 BREP 槽的 Shape，替换后库内部
-     * 布尔/拓扑调用会报「input is not on the BREP chain」。真 brepjs 形态的库
-     * （消费 ShapeHandle 对象）保持默认 true。
-     */
-    borrow?: boolean;
 }
-/**
- * Inward bridging step: deep walk with faijs Shapes replaced by borrowed
- * brepjs views (zero-copy); everything else passes through.
- * Class instances are not traversed (defensive); library-private handles
- * pass through (§4.3.4 of the design).
- *
- * @param v - the value to borrow from (plain object, array, or primitive).
- * @param depth - current traversal depth (guard against deep recursion).
- * @returns the value with faijs Shapes replaced by borrowed views.
- */
-export declare function borrowDeep(v: unknown, depth: number): unknown;
 /**
  * Statement-boundary unwrap — `err` becomes an execution error carrying the op
  * name and the `BrepError` code. Delegates to the shared
@@ -87,7 +61,7 @@ type MetaCarrier = {
  * The decorated product is identical to a defineOp product: same `DUAL_OP_META`
  * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,
  * slotMap), same dispatch semantics, same Result boundary. The adapter carries
- * only the brepjs bridging (borrow / call / adopt); every other mechanism
+ * only the brepjs bridging (input pass-through / call / adopt); every other mechanism
  * belongs to defineOp.
  *
  * @param fn   the brepjs-shaped function.

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;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;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;AAgFD,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,CAiBxD"}
+{"version":3,"file":"compat-op.d.ts","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;CAEb;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AA8ED,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,CAiBxD"}

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

@@ -2,8 +2,6 @@
  * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement
  * op, built **on top of** defineOp (single implementation entry, v1).
  *
- * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3
- *
  * compatOp is NOT a second implementation path parallel to defineOp: every
  * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability
  * routing), the Result boundary (runImpl + unwrapResult), product wrapping
@@ -12,16 +10,13 @@
  *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of
  *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);
  *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the
- *     three bridging steps that cannot be shared (all reuse shared
+ *     two bridging steps that cannot be shared (all reuse shared
  *     infrastructure, §3.2):
- *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →
- *          borrowBrepjsShape view (zero-copy; library-private handles pass
- *          through untouched);
- *       2. call + unwrap — callBrepjs through the shared unwrapResult
+ *       1. call + unwrap — callBrepjs through the shared unwrapResult
  *          (`err` throws an OpError carrying the op name + BrepError code);
  *          async library fns are awaited first, so `Promise<Result<…>>` —
  *          the shape every kernel-awaiting library returns — unwraps too;
- *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared
+ *       2. adoptOut — outward adoption: top-level handle / `outputs`-declared
  *          fields (single handle or handle array) → adoptEntity
  *          (unregister finalizer + fromHandle).
  *
@@ -40,33 +35,8 @@
  */
 import { defineOp, DUAL_OP_META, } from '../../define-op.js';
 import { isShape } from '../../shape.js';
-import { borrowBrepjsShape, adoptEntity, callBrepjs } from './l3-bridge.js';
+import { adoptEntity, callBrepjs } from './l3-bridge.js';
 import { unwrapResult } from './result-unwrap.js';
-const MAX_WALK_DEPTH = 4;
-/**
- * Inward bridging step: deep walk with faijs Shapes replaced by borrowed
- * brepjs views (zero-copy); everything else passes through.
- * Class instances are not traversed (defensive); library-private handles
- * pass through (§4.3.4 of the design).
- *
- * @param v - the value to borrow from (plain object, array, or primitive).
- * @param depth - current traversal depth (guard against deep recursion).
- * @returns the value with faijs Shapes replaced by borrowed views.
- */
-export function borrowDeep(v, depth) {
-    if (depth > MAX_WALK_DEPTH || v === null || typeof v !== 'object')
-        return v;
-    if (isShape(v))
-        return borrowBrepjsShape(v);
-    if (Array.isArray(v))
-        return v.map((x) => borrowDeep(x, depth + 1));
-    if (Object.getPrototypeOf(v) !== Object.prototype)
-        return v;
-    const out = {};
-    for (const [k, x] of Object.entries(v))
-        out[k] = borrowDeep(x, depth + 1);
-    return out;
-}
 /**
  * Statement-boundary unwrap — `err` becomes an execution error carrying the op
  * name and the `BrepError` code. Delegates to the shared
@@ -131,8 +101,8 @@ function readSegmentsFromArgs(args) {
     return undefined;
 }
 /**
- * Build the brep-only adapter: borrow inputs → call the vendor function through
- * the shared unwrap → adopt the product (with the caller's `segments`,
+ * Build the brep-only adapter: pass inputs through → call the vendor function
+ * through the shared unwrap → adopt the product (with the caller's `segments`,
  * 裁决 1/§5.2). The adapter never dispatches and never mounts metadata —
  * those are defineOp's.
  *
@@ -142,10 +112,8 @@ function readSegmentsFromArgs(args) {
  */
 function buildAdapter(fn, spec) {
     return async (...args) => {
-        // borrow: false（faijs 化库）时输入原样直传——嵌套的 core Shape 保留其
-        // BREP 槽，库内部调 core op 才能取到 OCCT 句柄（否则报 input not on the
-        // BREP chain）。默认 true 保持 brepjs 形态库的借入语义。
-        const effective = spec.borrow === false ? args : args.map((a) => borrowDeep(a, 0));
+        // faijs-native 库消费 core Shape：输入原样直传，保留 BREP 槽。
+        const effective = args;
         // Async library fns are supported: a library that awaits its kernel (every
         // `@faicad/faijs-gears` factory does — `await getGearKernel()`) returns
         // `Promise<Result<…>>`, and the shared unwrap is a sync leaf that only
@@ -161,7 +129,7 @@ function buildAdapter(fn, spec) {
  * The decorated product is identical to a defineOp product: same `DUAL_OP_META`
  * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,
  * slotMap), same dispatch semantics, same Result boundary. The adapter carries
- * only the brepjs bridging (borrow / call / adopt); every other mechanism
+ * only the brepjs bridging (input pass-through / call / adopt); every other mechanism
  * belongs to defineOp.
  *
  * @param fn   the brepjs-shaped function.
@@ -178,7 +146,7 @@ export function compatOp(fn, spec) {
         brep: buildAdapter(fn, spec),
         name: spec.name,
         capabilities,
-        // D11 透传：平台 op（vendored 实现调 occt-only 方法）在生成物里声明 engines。
+        // D11 透传：平台 op（compat 实现调 occt-only 方法）在生成物里声明 engines。
         // engines 与 capabilities 可并存（2026-09-24 撤销 D11-7 互斥），此处两条独立透传。
         engines,
         outputs,