@faicad/faijs 0.29.5 → 0.31.1

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

@@ -1 +1 @@
-{"version":3,"file":"compat-projection.js","sourceRoot":"","sources":["../../../src/api/internal/compat-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,WAAW,GAAG,KAAK,CAAA;IACvB,IAAI,CAAC;QACH,WAAW,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAA;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;IACvE,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,qBAAqB,EAAE,KAAK,IAAI,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,gEAAgE;YAC7E,0DAA0D,IAAI,SAAS;YACvE,+CAA+C,CAClD,CAAA;IACH,CAAC;AACH,CAAC;AAKD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAAgB,EAChB,SAAoB,EACpB,IAAmC;IAEnC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;QAC5B,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACvB,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;QACjE,OAAO,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACrC,CAAC,CAAA;AACH,CAAC","sourcesContent":["/**\n * compat-projection — the single BREP-TS projection wrapper factory (P23, §4.2).\n *\n * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2\n *\n * Every symbol on the TS compat face and every generated `compatOp` op funnels\n * through {@link projectBrepOp}. That is what makes the generated face and the\n * hand-curated `api/brepjs-compat` face one mechanism rather than two:\n *\n *   1. single-kernel assert (D10) — library code never installs a kernel;\n *   2. D11 dual-form normalization — object form → positional form, in the\n *      exported function (§4.2 「归一化位置」), not in a script-side adapter;\n *   3. the vendored call itself, through `callBrepjs` (Result shape preserved).\n *\n * P21's `api/brepjs-compat` used a private copy of steps 1–3 (`wrapDual`); P23 lifts it\n * here so `gen-l3-surface.ts` can emit one `compatOp(projectBrepOp(…), …)` line\n * per symbol instead of re-expanding the template for each op.\n *\n * @module\n */\n\nimport { resolveArgs, type FormClass } from './dual-form-args'\nimport { callBrepjs } from './l3-bridge'\nimport { getActiveBrepEngineId } from '../../brep/engine/registry'\nimport { getBackends } from '../../runtime-state'\n\n/**\n * Assert that a BREP kernel is bound before invoking a compat op.\n *\n * Reads the configured backend's kernel slot, guarding against the throw that\n * `getBackends()` performs before host configuration. Falls back to the core\n * engine-registry activation flag（2026-09-25 core-decouple wrapup：brepjs\n * registry 随子包删除——此处只问「core registry 是否已有激活 brep 引擎」）\n * when nothing is configured.\n *\n * @param name - op name, used in the guiding error message.\n * @throws when no BREP kernel is bound (the message tells the host what to do,\n * because library code must never install a kernel itself — §4.2 rule 1).\n */\nexport function assertKernelBound(name: string): void {\n  let kernelBound = false\n  try {\n    kernelBound = getBackends().kernel.brep != null\n  } catch {\n    // backends not configured yet — that is not an error, just no kernel\n  }\n  if (!kernelBound && getActiveBrepEngineId() === null) {\n    throw new Error(\n      `[compat:${name}] no BREP kernel bound; run host init/inject (e.g. initOcct + ` +\n        `register the occt brep engine) before the first compat.${name} call. ` +\n        `Library code must not install kernels itself.`\n    )\n  }\n}\n\n/** Signature of a projected compat op (inputs normalized before the call). */\nexport type CompatProjection = (...args: unknown[]) => unknown\n\n/**\n * Project a vendored brepjs function onto the faijs TS compat face.\n *\n * The returned function is brepjs-shaped: positional arguments in, `Result`\n * (or whatever the vendored function returns) out — no faijs `Shape`, no\n * adoption. Adoption and the statement-boundary unwrap are `compatOp`'s job\n * (§4.3.2 steps 4/5), which is why the script face can wrap the very same\n * projection the TS face exports.\n *\n * @param name      - op name (error messages + D11 discriminant context).\n * @param params    - machine parameter-name table (object form → positional).\n * @param formClass - D11 form class (A single-name dual-form / B1 options-only /\n *                    B2 two names).\n * @param impl      - the vendored function.\n * @returns the projected compat op.\n */\nexport function projectBrepOp(\n  name: string,\n  params: string[],\n  formClass: FormClass,\n  impl: (...args: never[]) => unknown,\n): CompatProjection {\n  return (...args: unknown[]) => {\n    assertKernelBound(name)\n    const positional = resolveArgs(args, { name, params, formClass })\n    return callBrepjs(impl, positional)\n  }\n}\n"]}
+{"version":3,"file":"compat-projection.js","sourceRoot":"","sources":["../../../src/api/internal/compat-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,WAAW,GAAG,KAAK,CAAA;IACvB,IAAI,CAAC;QACH,WAAW,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAA;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;IACvE,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,qBAAqB,EAAE,KAAK,IAAI,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,gEAAgE;YAC7E,0DAA0D,IAAI,SAAS;YACvE,+CAA+C,CAClD,CAAA;IACH,CAAC;AACH,CAAC;AAKD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAAgB,EAChB,SAAoB,EACpB,IAAmC;IAEnC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;QAC5B,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACvB,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;QACjE,OAAO,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACrC,CAAC,CAAA;AACH,CAAC","sourcesContent":["/**\n * compat-projection — the single BREP-TS projection wrapper factory (P23, §4.2).\n *\n * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2\n *\n * Every symbol on the TS compat face and every generated `compatOp` op funnels\n * through {@link projectBrepOp}. That is what makes the generated face and the\n * hand-curated `api/brepjs-compat` face one mechanism rather than two:\n *\n *   1. single-kernel assert (D10) — library code never installs a kernel;\n *   2. D11 dual-form normalization — object form → positional form, in the\n *      exported function (§4.2 「归一化位置」), not in a script-side adapter;\n *   3. the brepjs call itself, through `callBrepjs` (Result shape preserved).\n *\n * P21's `api/brepjs-compat` used a private copy of steps 1–3 (`wrapDual`); P23 lifts it\n * here so `gen-l3-surface.ts` can emit one `compatOp(projectBrepOp(…), …)` line\n * per symbol instead of re-expanding the template for each op.\n *\n * @module\n */\n\nimport { resolveArgs, type FormClass } from './dual-form-args'\nimport { callBrepjs } from './l3-bridge'\nimport { getActiveBrepEngineId } from '../../brep/engine/registry'\nimport { getBackends } from '../../runtime-state'\n\n/**\n * Assert that a BREP kernel is bound before invoking a compat op.\n *\n * Reads the configured backend's kernel slot, guarding against the throw that\n * `getBackends()` performs before host configuration. Falls back to the core\n * engine-registry activation flag（2026-09-25 core-decouple wrapup：brepjs\n * registry 已内化到 core——此处只问「core registry 是否已有激活 brep 引擎」）\n * when nothing is configured.\n *\n * @param name - op name, used in the guiding error message.\n * @throws when no BREP kernel is bound (the message tells the host what to do,\n * because library code must never install a kernel itself — §4.2 rule 1).\n */\nexport function assertKernelBound(name: string): void {\n  let kernelBound = false\n  try {\n    kernelBound = getBackends().kernel.brep != null\n  } catch {\n    // backends not configured yet — that is not an error, just no kernel\n  }\n  if (!kernelBound && getActiveBrepEngineId() === null) {\n    throw new Error(\n      `[compat:${name}] no BREP kernel bound; run host init/inject (e.g. initOcct + ` +\n        `register the occt brep engine) before the first compat.${name} call. ` +\n        `Library code must not install kernels itself.`\n    )\n  }\n}\n\n/** Signature of a projected compat op (inputs normalized before the call). */\nexport type CompatProjection = (...args: unknown[]) => unknown\n\n/**\n * Project a brepjs function onto the faijs TS compat face.\n *\n * The returned function is brepjs-shaped: positional arguments in, `Result`\n * (or whatever the brepjs function returns) out — no faijs `Shape`, no\n * adoption. Adoption and the statement-boundary unwrap are `compatOp`'s job\n * (§4.3.2 steps 4/5), which is why the script face can wrap the very same\n * projection the TS face exports.\n *\n * @param name      - op name (error messages + D11 discriminant context).\n * @param params    - machine parameter-name table (object form → positional).\n * @param formClass - D11 form class (A single-name dual-form / B1 options-only /\n *                    B2 two names).\n * @param impl      - the brepjs function.\n * @returns the projected compat op.\n */\nexport function projectBrepOp(\n  name: string,\n  params: string[],\n  formClass: FormClass,\n  impl: (...args: never[]) => unknown,\n): CompatProjection {\n  return (...args: unknown[]) => {\n    assertKernelBound(name)\n    const positional = resolveArgs(args, { name, params, formClass })\n    return callBrepjs(impl, positional)\n  }\n}\n"]}

package/dist/api/internal/dual-form-args.d.ts

@@ -1,8 +1,6 @@
 /**
  * dual-form-args — D11 参数双形态归一化判别器
  *
- * 设计文档：docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2
- *
  * 本文件实现参数双形态归一化（D11）：
  * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现
  * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态

package/dist/api/internal/dual-form-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dual-form-args.d.ts","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,YAAY;AACZ,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC,YAAY;AACZ,MAAM,WAAW,OAAO;IACtB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY;IACZ,SAAS,EAAE,SAAS,CAAA;CACrB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAQrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,EAAE,CAUX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAgCrE;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,eAAe;IACf,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CA0BhF;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAoD1F"}
+{"version":3,"file":"dual-form-args.d.ts","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,YAAY;AACZ,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC,YAAY;AACZ,MAAM,WAAW,OAAO;IACtB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY;IACZ,SAAS,EAAE,SAAS,CAAA;CACrB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAQrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,EAAE,CAUX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAgCrE;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,eAAe;IACf,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CA0BhF;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAoD1F"}

package/dist/api/internal/dual-form-args.js

@@ -1,8 +1,6 @@
 /**
  * dual-form-args — D11 参数双形态归一化判别器
  *
- * 设计文档：docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2
- *
  * 本文件实现参数双形态归一化（D11）：
  * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现
  * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态
@@ -21,7 +19,7 @@
  * B2 条目不走判别器（两个名字各自固定形态）。
  */
 import { isShape } from '../../shape.js';
-/** 句柄类型守卫（vendored 句柄有 .wrapped 属性）。 */
+/** 句柄类型守卫（compat 句柄有 .wrapped 属性）。 */
 function isHandleLike(v) {
     return typeof v === 'object' && v !== null && 'wrapped' in v;
 }

package/dist/api/internal/dual-form-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"dual-form-args.js","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * dual-form-args — D11 参数双形态归一化判别器\n *\n * 设计文档：docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2\n *\n * 本文件实现参数双形态归一化（D11）：\n * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现\n * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态\n * - B2 类（人类看来不明显）：双名，brepjs 形态占正名，faijs 对象形态加描述性后缀\n *\n * 判别规则：\n * 1. 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n *    且非 Shape、非句柄、非数组 → 对象形态\n * 2. 否则 → 位置形态\n *\n * 对象形态映射：\n * - 按 params 表（机器参数名）将对象键映射为位置数组\n * - 缺省键 → undefined\n * - 对象形态含 params 外未知键 → 抛 E_ARGS_FORM\n *\n * B2 条目不走判别器（两个名字各自固定形态）。\n */\n\nimport { isShape } from '../../shape'\n\n/** 形态分类。 */\nexport type FormClass = 'A' | 'B1' | 'B2'\n\n/** 参数规格。 */\nexport interface ArgSpec {\n  /** op 名（错误信息用）。 */\n  name: string\n  /** 机器参数名表（按位置顺序），用于对象形态→位置数组映射。 */\n  params?: string[]\n  /** 形态分类。 */\n  formClass: FormClass\n}\n\n/** 句柄类型守卫（vendored 句柄有 .wrapped 属性）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && 'wrapped' in v\n}\n\n/**\n * 判定参数是否为对象形态。\n *\n * 判别式（全仓统一）：\n * - 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n * - 且非 Shape、非句柄、非数组\n *\n * @param args - 调用参数数组\n * @returns 是否为对象形态\n */\nexport function isObjectForm(args: unknown[]): boolean {\n  if (args.length === 0) return false\n  const first = args[0]\n  if (first === null || typeof first !== 'object') return false\n  if (Array.isArray(first)) return false\n  if (isShape(first)) return false\n  if (isHandleLike(first)) return false\n  return Object.getPrototypeOf(first) === Object.prototype\n}\n\n/**\n * 将对象形态参数归一化为位置数组。\n *\n * @param obj - 对象形态参数\n * @param params - 机器参数名表\n * @param opName - op 名（错误信息用）\n * @returns 位置数组（缺省键 → undefined）\n * @throws E_ARGS_FORM 对象含 params 外未知键时\n */\nexport function normalizeObjectForm(\n  obj: Record<string, unknown>,\n  params: string[],\n  opName: string,\n): unknown[] {\n  const keys = Object.keys(obj)\n  const unknownKeys = keys.filter(k => !params.includes(k))\n  if (unknownKeys.length > 0) {\n    throw new Error(\n      `[faijs/args] ${opName}: E_ARGS_FORM: unexpected parameter(s): ${unknownKeys.join(', ')}. ` +\n      `Expected: ${params.join(', ')}`\n    )\n  }\n  return params.map(k => obj[k])\n}\n\n/**\n * 参数双形态归一化判别器。\n *\n * 根据 args 和 spec 归一化参数：\n * - B2 条目：直接返回原样（两个名字各自固定形态）\n * - B1 条目：直接返回原样（brepjs options 对象即唯一对象形态，§4.2「无需判别」）\n * - 对象形态：按 params 表映射为位置数组\n * - 位置形态：直接返回原样\n *\n * B1 为何原样返回：B1 的 brepjs 位置形态首参本身就是配置对象（如\n * `thread(options: ThreadOptions)`），对象形态与它在首参上撞型，判别式失效；\n * 方案 §4.2 B1 的定义即「faijs 侧无独立对象 schema 时，直接以 brepjs options\n * 对象为唯一对象形态（单名单形态，无需判别）」。若在此处按 params 表归一，\n * 任何 options 键都会因不在 params 表里而误抛 E_ARGS_FORM。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化后的参数数组\n * @throws E_ARGS_FORM 形态无法匹配或对象含未知键时\n */\nexport function resolveArgs(args: unknown[], spec: ArgSpec): unknown[] {\n  // B2 条目不走判别器（两个名字各自固定形态）\n  if (spec.formClass === 'B2') {\n    return args\n  }\n  // B1 条目：brepjs options 对象即唯一对象形态，无需判别（§4.2）\n  if (spec.formClass === 'B1') {\n    return args\n  }\n\n  // 无 params 表时无法归一化对象形态，只能接受位置形态\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return args\n  }\n\n  // 判定形态\n  if (isObjectForm(args)) {\n    // 对象形态 → 位置数组\n    return normalizeObjectForm(\n      args[0] as Record<string, unknown>,\n      spec.params,\n      spec.name,\n    )\n  }\n\n  // 位置形态 → 原样返回\n  return args\n}\n\n/**\n * 双形态归一化结果。\n *\n * 包含归一化后的参数和是否为对象形态的标记。\n */\nexport interface ResolvedArgs {\n  /** 归一化后的参数数组。 */\n  args: unknown[]\n  /** 是否为对象形态。 */\n  isObjectForm: boolean\n}\n\n/**\n * 参数双形态归一化判别器（带形态信息）。\n *\n * 与 resolveArgs 相同，但返回形态信息。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化结果\n */\nexport function resolveArgsWithInfo(args: unknown[], spec: ArgSpec): ResolvedArgs {\n  if (spec.formClass === 'B2' || spec.formClass === 'B1') {\n    return { args, isObjectForm: false }\n  }\n\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return { args, isObjectForm: false }\n  }\n\n  if (isObjectForm(args)) {\n    return {\n      args: normalizeObjectForm(\n        args[0] as Record<string, unknown>,\n        spec.params,\n        spec.name,\n      ),\n      isObjectForm: true,\n    }\n  }\n\n  return { args, isObjectForm: false }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// 反方向：位置形态 → 对象形态（faijs 特有 dual op，impl 原生对象形态）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * 位置形态声明（D11 反方向，§4.2「归一方向 = 位置→对象」）。\n *\n * faijs 特有 dual op 的 impl 是对象形态原生（`box(width, depth, height)` 经\n * 装箱为 `{ width, depth, height, ... }`，`translate(shape, { offset })`），brepjs 生态\n * 的位置形态（`box(10, 20, 30, { centered: true })` / `translate(shape, 1, 0, 0)`）\n * 需先归一成对象形态。\n * 声明式而非 if 分支：op 作者只列「哪个键吃几个位置参数」，判别与装箱由\n * {@link positionalToObject} 统一完成。\n *\n * 与语句层的 `StatementSummary.positional`（位置实参**值**）以及投影侧的\n * `ArgSpec.params`（对象→位置**参数名表**）是三个不同概念：`SlotMap` 是\n * 位置槽→对象键的**装箱声明**（位置→对象，D11 反方向；§9 命名区分）。\n */\nexport interface SlotMap {\n  /**\n   * 对象形态键名，按位置顺序（只描述 Shape 之后的**非几何**形参）。\n   * 例：`box(10, 20, 30)` → `keys: ['size']`；`cylinder(5, 40)` →\n   * `keys: ['radius', 'height']`。\n   */\n  keys: string[]\n  /**\n   * 哪些键是 vec3 槽位（吃掉最多 3 个连续位置参数）。\n   * 1 个 → 标量（number 或数组原样）；2~3 个 → `[x, y(, z)]` 数组。\n   * 例：`box(10)` → `{ size: 10 }`；`box(10, 20, 30)` → `{ size: [10, 20, 30] }`。\n   */\n  vec3Keys?: string[]\n  /**\n   * 前置 Shape 形参个数（原样透传，不参与装箱），缺省 0。\n   * 例：`translate(shape, 1, 0, 0)` → `shapeArity: 1`。\n   */\n  shapeArity?: number\n}\n\n/** 判定值是否是可作为对象形态形参的 plain object（与 {@link isObjectForm} 同判别式）。 */\nfunction isPlainObjectValue(v: unknown): boolean {\n  if (v === null || typeof v !== 'object') return false\n  if (Array.isArray(v)) return false\n  if (isShape(v)) return false\n  if (isHandleLike(v)) return false\n  return Object.getPrototypeOf(v) === Object.prototype\n}\n\n/**\n * 位置形态 → 对象形态归一（faijs 特有 dual op 的 D11 反方向）。\n *\n * 触发条件：声明了 slotMap 且对象槽位（第 `shapeArity` 个实参）不是\n * plain object。已是对象形态或实参不足时原样返回（交由 op 自身的断言报错）。\n *\n * @param args - 调用参数数组\n * @param form - slotMap 声明（位置槽→对象键装箱表）\n * @param name - op 名（错误信息用）\n * @returns 归一后的参数数组（前置 Shape 原样 + 末尾一个对象形态参数）\n * @throws E_ARGS_FORM 位置参数个数与声明的槽位不匹配时\n */\nexport function positionalToObject(args: unknown[], form: SlotMap, name: string): unknown[] {\n  const shapeArity = form.shapeArity ?? 0\n  if (args.length <= shapeArity) return args // 无位置形参可装箱 → 原样（op 断言报错）\n  if (isPlainObjectValue(args[shapeArity])) return args // 已是对象形态\n\n  const rest = args.slice(shapeArity)\n  const obj: Record<string, unknown> = {}\n  let i = 0\n  for (const key of form.keys) {\n    if (i >= rest.length) break\n    // §6.2 尾参 options：当前实参是 plain object（候选尾参 options）→ 停止装箱\n    // 交给下方 options 合并，不让任何槽位把它吞进拓扑参数\n    // （`box(20,{centered:true})` / `cylinder(5,40,{centered:true})`）。\n    if (isPlainObjectValue(rest[i])) break\n    if (form.vec3Keys?.includes(key)) {\n      // vec3 槽位：吃掉最多 3 个连续实参（1 个 → 标量，2~3 个 → 数组）。\n      // 若剩余序列最末是 plain object（候选尾参 options），先为它留位，不让\n      // 跨槽 vec3 把 options 吞进拓扑参数（`box(10,20,30,{centered:true})`）。\n      const avail = rest.length - i\n      const reserveOptions = avail > 1 && isPlainObjectValue(rest[rest.length - 1]) ? 1 : 0\n      const take = Math.min(3, avail - reserveOptions)\n      const chunk = rest.slice(i, i + take)\n      obj[key] = take === 1 ? chunk[0] : chunk\n      i += take\n      continue\n    }\n    obj[key] = rest[i]\n    i += 1\n  }\n  // D11 尾参 options 合并（§6.2）：位置槽装箱后，若剩余实参恰好 1 个且为\n  // plain object → 作为 options 并入 args。让 `box(10,20,30,{centered:true})`、\n  // `sphere(5,{at,segments})`、`cylinder(5,40,{centered:true})` 在脚本面可用。\n  if (i < rest.length) {\n    if (rest.length - i === 1 && isPlainObjectValue(rest[i])) {\n      const opts = rest[i] as Record<string, unknown>\n      const dup = Object.keys(opts).filter((k) => form.keys.includes(k) || k in obj)\n      if (dup.length > 0) {\n        throw new Error(\n          `[faijs/args] ${name}: E_ARGS_FORM: option key(s) ${dup.join(', ')} ` +\n          `conflict with positional slot(s) (${form.keys.join(', ')})`\n        )\n      }\n      Object.assign(obj, opts)\n      return [...args.slice(0, shapeArity), obj]\n    }\n    throw new Error(\n      `[faijs/args] ${name}: E_ARGS_FORM: expected ${form.keys.join(', ')} ` +\n        `(${form.keys.length} positional slot(s)); got ${rest.length} value(s): ` +\n        rest.map((a) => (typeof a === 'object' ? '[object]' : String(a))).join(', ')\n    )\n  }\n  return [...args.slice(0, shapeArity), obj]\n}\n"]}
+{"version":3,"file":"dual-form-args.js","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * dual-form-args — D11 参数双形态归一化判别器\n *\n * 本文件实现参数双形态归一化（D11）：\n * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现\n * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态\n * - B2 类（人类看来不明显）：双名，brepjs 形态占正名，faijs 对象形态加描述性后缀\n *\n * 判别规则：\n * 1. 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n *    且非 Shape、非句柄、非数组 → 对象形态\n * 2. 否则 → 位置形态\n *\n * 对象形态映射：\n * - 按 params 表（机器参数名）将对象键映射为位置数组\n * - 缺省键 → undefined\n * - 对象形态含 params 外未知键 → 抛 E_ARGS_FORM\n *\n * B2 条目不走判别器（两个名字各自固定形态）。\n */\n\nimport { isShape } from '../../shape'\n\n/** 形态分类。 */\nexport type FormClass = 'A' | 'B1' | 'B2'\n\n/** 参数规格。 */\nexport interface ArgSpec {\n  /** op 名（错误信息用）。 */\n  name: string\n  /** 机器参数名表（按位置顺序），用于对象形态→位置数组映射。 */\n  params?: string[]\n  /** 形态分类。 */\n  formClass: FormClass\n}\n\n/** 句柄类型守卫（compat 句柄有 .wrapped 属性）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && 'wrapped' in v\n}\n\n/**\n * 判定参数是否为对象形态。\n *\n * 判别式（全仓统一）：\n * - 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n * - 且非 Shape、非句柄、非数组\n *\n * @param args - 调用参数数组\n * @returns 是否为对象形态\n */\nexport function isObjectForm(args: unknown[]): boolean {\n  if (args.length === 0) return false\n  const first = args[0]\n  if (first === null || typeof first !== 'object') return false\n  if (Array.isArray(first)) return false\n  if (isShape(first)) return false\n  if (isHandleLike(first)) return false\n  return Object.getPrototypeOf(first) === Object.prototype\n}\n\n/**\n * 将对象形态参数归一化为位置数组。\n *\n * @param obj - 对象形态参数\n * @param params - 机器参数名表\n * @param opName - op 名（错误信息用）\n * @returns 位置数组（缺省键 → undefined）\n * @throws E_ARGS_FORM 对象含 params 外未知键时\n */\nexport function normalizeObjectForm(\n  obj: Record<string, unknown>,\n  params: string[],\n  opName: string,\n): unknown[] {\n  const keys = Object.keys(obj)\n  const unknownKeys = keys.filter(k => !params.includes(k))\n  if (unknownKeys.length > 0) {\n    throw new Error(\n      `[faijs/args] ${opName}: E_ARGS_FORM: unexpected parameter(s): ${unknownKeys.join(', ')}. ` +\n      `Expected: ${params.join(', ')}`\n    )\n  }\n  return params.map(k => obj[k])\n}\n\n/**\n * 参数双形态归一化判别器。\n *\n * 根据 args 和 spec 归一化参数：\n * - B2 条目：直接返回原样（两个名字各自固定形态）\n * - B1 条目：直接返回原样（brepjs options 对象即唯一对象形态，§4.2「无需判别」）\n * - 对象形态：按 params 表映射为位置数组\n * - 位置形态：直接返回原样\n *\n * B1 为何原样返回：B1 的 brepjs 位置形态首参本身就是配置对象（如\n * `thread(options: ThreadOptions)`），对象形态与它在首参上撞型，判别式失效；\n * 方案 §4.2 B1 的定义即「faijs 侧无独立对象 schema 时，直接以 brepjs options\n * 对象为唯一对象形态（单名单形态，无需判别）」。若在此处按 params 表归一，\n * 任何 options 键都会因不在 params 表里而误抛 E_ARGS_FORM。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化后的参数数组\n * @throws E_ARGS_FORM 形态无法匹配或对象含未知键时\n */\nexport function resolveArgs(args: unknown[], spec: ArgSpec): unknown[] {\n  // B2 条目不走判别器（两个名字各自固定形态）\n  if (spec.formClass === 'B2') {\n    return args\n  }\n  // B1 条目：brepjs options 对象即唯一对象形态，无需判别（§4.2）\n  if (spec.formClass === 'B1') {\n    return args\n  }\n\n  // 无 params 表时无法归一化对象形态，只能接受位置形态\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return args\n  }\n\n  // 判定形态\n  if (isObjectForm(args)) {\n    // 对象形态 → 位置数组\n    return normalizeObjectForm(\n      args[0] as Record<string, unknown>,\n      spec.params,\n      spec.name,\n    )\n  }\n\n  // 位置形态 → 原样返回\n  return args\n}\n\n/**\n * 双形态归一化结果。\n *\n * 包含归一化后的参数和是否为对象形态的标记。\n */\nexport interface ResolvedArgs {\n  /** 归一化后的参数数组。 */\n  args: unknown[]\n  /** 是否为对象形态。 */\n  isObjectForm: boolean\n}\n\n/**\n * 参数双形态归一化判别器（带形态信息）。\n *\n * 与 resolveArgs 相同，但返回形态信息。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化结果\n */\nexport function resolveArgsWithInfo(args: unknown[], spec: ArgSpec): ResolvedArgs {\n  if (spec.formClass === 'B2' || spec.formClass === 'B1') {\n    return { args, isObjectForm: false }\n  }\n\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return { args, isObjectForm: false }\n  }\n\n  if (isObjectForm(args)) {\n    return {\n      args: normalizeObjectForm(\n        args[0] as Record<string, unknown>,\n        spec.params,\n        spec.name,\n      ),\n      isObjectForm: true,\n    }\n  }\n\n  return { args, isObjectForm: false }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// 反方向：位置形态 → 对象形态（faijs 特有 dual op，impl 原生对象形态）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * 位置形态声明（D11 反方向，§4.2「归一方向 = 位置→对象」）。\n *\n * faijs 特有 dual op 的 impl 是对象形态原生（`box(width, depth, height)` 经\n * 装箱为 `{ width, depth, height, ... }`，`translate(shape, { offset })`），brepjs 生态\n * 的位置形态（`box(10, 20, 30, { centered: true })` / `translate(shape, 1, 0, 0)`）\n * 需先归一成对象形态。\n * 声明式而非 if 分支：op 作者只列「哪个键吃几个位置参数」，判别与装箱由\n * {@link positionalToObject} 统一完成。\n *\n * 与语句层的 `StatementSummary.positional`（位置实参**值**）以及投影侧的\n * `ArgSpec.params`（对象→位置**参数名表**）是三个不同概念：`SlotMap` 是\n * 位置槽→对象键的**装箱声明**（位置→对象，D11 反方向；§9 命名区分）。\n */\nexport interface SlotMap {\n  /**\n   * 对象形态键名，按位置顺序（只描述 Shape 之后的**非几何**形参）。\n   * 例：`box(10, 20, 30)` → `keys: ['size']`；`cylinder(5, 40)` →\n   * `keys: ['radius', 'height']`。\n   */\n  keys: string[]\n  /**\n   * 哪些键是 vec3 槽位（吃掉最多 3 个连续位置参数）。\n   * 1 个 → 标量（number 或数组原样）；2~3 个 → `[x, y(, z)]` 数组。\n   * 例：`box(10)` → `{ size: 10 }`；`box(10, 20, 30)` → `{ size: [10, 20, 30] }`。\n   */\n  vec3Keys?: string[]\n  /**\n   * 前置 Shape 形参个数（原样透传，不参与装箱），缺省 0。\n   * 例：`translate(shape, 1, 0, 0)` → `shapeArity: 1`。\n   */\n  shapeArity?: number\n}\n\n/** 判定值是否是可作为对象形态形参的 plain object（与 {@link isObjectForm} 同判别式）。 */\nfunction isPlainObjectValue(v: unknown): boolean {\n  if (v === null || typeof v !== 'object') return false\n  if (Array.isArray(v)) return false\n  if (isShape(v)) return false\n  if (isHandleLike(v)) return false\n  return Object.getPrototypeOf(v) === Object.prototype\n}\n\n/**\n * 位置形态 → 对象形态归一（faijs 特有 dual op 的 D11 反方向）。\n *\n * 触发条件：声明了 slotMap 且对象槽位（第 `shapeArity` 个实参）不是\n * plain object。已是对象形态或实参不足时原样返回（交由 op 自身的断言报错）。\n *\n * @param args - 调用参数数组\n * @param form - slotMap 声明（位置槽→对象键装箱表）\n * @param name - op 名（错误信息用）\n * @returns 归一后的参数数组（前置 Shape 原样 + 末尾一个对象形态参数）\n * @throws E_ARGS_FORM 位置参数个数与声明的槽位不匹配时\n */\nexport function positionalToObject(args: unknown[], form: SlotMap, name: string): unknown[] {\n  const shapeArity = form.shapeArity ?? 0\n  if (args.length <= shapeArity) return args // 无位置形参可装箱 → 原样（op 断言报错）\n  if (isPlainObjectValue(args[shapeArity])) return args // 已是对象形态\n\n  const rest = args.slice(shapeArity)\n  const obj: Record<string, unknown> = {}\n  let i = 0\n  for (const key of form.keys) {\n    if (i >= rest.length) break\n    // §6.2 尾参 options：当前实参是 plain object（候选尾参 options）→ 停止装箱\n    // 交给下方 options 合并，不让任何槽位把它吞进拓扑参数\n    // （`box(20,{centered:true})` / `cylinder(5,40,{centered:true})`）。\n    if (isPlainObjectValue(rest[i])) break\n    if (form.vec3Keys?.includes(key)) {\n      // vec3 槽位：吃掉最多 3 个连续实参（1 个 → 标量，2~3 个 → 数组）。\n      // 若剩余序列最末是 plain object（候选尾参 options），先为它留位，不让\n      // 跨槽 vec3 把 options 吞进拓扑参数（`box(10,20,30,{centered:true})`）。\n      const avail = rest.length - i\n      const reserveOptions = avail > 1 && isPlainObjectValue(rest[rest.length - 1]) ? 1 : 0\n      const take = Math.min(3, avail - reserveOptions)\n      const chunk = rest.slice(i, i + take)\n      obj[key] = take === 1 ? chunk[0] : chunk\n      i += take\n      continue\n    }\n    obj[key] = rest[i]\n    i += 1\n  }\n  // D11 尾参 options 合并（§6.2）：位置槽装箱后，若剩余实参恰好 1 个且为\n  // plain object → 作为 options 并入 args。让 `box(10,20,30,{centered:true})`、\n  // `sphere(5,{at,segments})`、`cylinder(5,40,{centered:true})` 在脚本面可用。\n  if (i < rest.length) {\n    if (rest.length - i === 1 && isPlainObjectValue(rest[i])) {\n      const opts = rest[i] as Record<string, unknown>\n      const dup = Object.keys(opts).filter((k) => form.keys.includes(k) || k in obj)\n      if (dup.length > 0) {\n        throw new Error(\n          `[faijs/args] ${name}: E_ARGS_FORM: option key(s) ${dup.join(', ')} ` +\n          `conflict with positional slot(s) (${form.keys.join(', ')})`\n        )\n      }\n      Object.assign(obj, opts)\n      return [...args.slice(0, shapeArity), obj]\n    }\n    throw new Error(\n      `[faijs/args] ${name}: E_ARGS_FORM: expected ${form.keys.join(', ')} ` +\n        `(${form.keys.length} positional slot(s)); got ${rest.length} value(s): ` +\n        rest.map((a) => (typeof a === 'object' ? '[object]' : String(a))).join(', ')\n    )\n  }\n  return [...args.slice(0, shapeArity), obj]\n}\n"]}

package/dist/api/internal/export-members.d.ts

@@ -0,0 +1,80 @@
+/**
+ * export-members — 导出命令的「入参 Shape → 成员表」（方案 §2.6 定式 3 的共用件）
+ *
+ * `cad.exportStep`（`api/export-step.ts`）与 `cad.export3mf`（`api/export-3mf.ts`）
+ * 是同一个库面序列化器（`brep/export/export-model.ts#exportModelSync`）的两个脚本面
+ * 薄壳。两者的差别只有「一个成员交给写出器的载荷是 `solid` 还是 `mesh`」；把入参拆
+ * 成成员表这一步完全一致，故收在本文件——两份拷贝各自漂移会让脚本面与库面同源
+ * （矩阵 B12 / B14）失去保障。
+ *
+ * 拆解口径对齐现成先例 `node-host/cli.ts#writeAssemblyStep`：
+ * - 成员 = `CompoundShape.children`（同序；嵌套 compound 不递归展开，与先例一致）；
+ * - 成员名 = `behavior.memberNames[i]`（装配 op 写入的短名，`memberColors` 亦以它为
+ *   键），无装配 behavior 时回落 `nameOf(child)`；
+ * - 成员色 = `behavior.memberColors[成员名]`（sRGB 0–1，STEP 写 XCAF COLOUR_RGB、
+ *   3MF 写 basematerials）；
+ * - 非 compound 入参 = 单成员、不带名与色，与 `cli.ts#writeOutput`（`:744-758`）同
+ *   口径——单件导出不写名。
+ *
+ * 判定用**结构**判定 `isCompoundLike` 而非 SDK 的 `isShape`/`isCompound`：本 op 吃
+ * 的是脚本文本传进来的值，可能是跨库产物，不能对它提「必须由本库构造器创建」的要求
+ * （同 `keep-syntax §5.3 D5` 的既有取舍）。
+ *
+ * 成员几何一律由调用方**现场**读（`brepOf(child)`），不取创建期快照：装配变换在语句
+ * 之后才烘进 `slot.solid`，快照对已变换成员是陈旧的（`cli.ts#writeAssemblyStep` 的
+ * 同款注释）。
+ */
+import type { Shape, Vec3 } from '../../mesh/types.js';
+import type { CompoundShape } from '../../shape.js';
+/** 导出成员：一个待导出的几何 + 其身份（名 / 色）。 */
+export interface ExportMember {
+    /** 成员几何：compound 的成员，或单件入参本身。 */
+    shape: Shape;
+    /** 成员名（写 STEP PRODUCT 名 / 3MF `<object name>`）；无名时缺省。 */
+    name?: string;
+    /** sRGB 0–1 成员色（来自装配 behavior 的 `memberColors`）。 */
+    color?: readonly [number, number, number];
+}
+/**
+ * 把导出命令的入参拆成成员表。
+ *
+ * @param input - 单件 Shape 或装配 compound（结构判定）。
+ * @returns 成员表；空 compound 返回空数组——调用方必须显式报错，不得落空文件。
+ */
+export declare function exportMembersOf(input: Shape | CompoundShape): ExportMember[];
+/** 装配节点位姿（与 `Shape.transform` 同形态，见 mesh/types.ts）。 */
+export interface ExportTransform {
+    translate?: Vec3;
+    rotate?: {
+        angle: number;
+        axis?: Vec3;
+    };
+    matrix?: number[];
+}
+/** 导出成员树节点：结构（名 / 色 / 位姿 / 子节点）与几何（shape）分离。 */
+export interface ExportMemberNode {
+    /** 成员几何：compound 的成员，或单件入参本身。 */
+    shape: Shape;
+    /** 成员名（写 3MF `<object name>` / STEP PRODUCT 名）；无名时缺省。 */
+    name?: string;
+    /** sRGB 0–1 成员色（来自装配 behavior 的 `memberColors`）。 */
+    color?: readonly [number, number, number];
+    /** 本节点相对父的位姿（来自 `shape.transform`）。 */
+    transform?: ExportTransform;
+    /** 子节点（嵌套装配）；非 compound 叶节点缺省。 */
+    children?: ExportMemberNode[];
+}
+/**
+ * 导出命令入参 → 成员树（方案 §2.1「装配模型 = 节点属性，单一真源」的脚本面投影）。
+ * 与 `exportMembersOf`（平铺）不同，本函数**保留嵌套**：compound 的成员若自身是
+ * compound 则递归展开为子树（同序），叶节点携带其 `shape.transform` 作为相对父位姿。
+ *
+ * 名称 / 颜色取自各层 compound 的 behavior（`memberNames` / `memberColors`，装配 op
+ * 写入；core 只读不写，不 import extra）。本层只管结构，几何载荷由调用方（各 op）
+ * 现场读取——避免创建期快照陈旧（同 `exportMembersOf` 注释）。
+ *
+ * @param input - 脚本面导出命令的入参形状（叶或 compound 装配）。
+ * @returns 保留嵌套结构的成员树；叶节点携带 `shape.transform` 作为相对父位姿。
+ */
+export declare function exportTreeOf(input: Shape | CompoundShape): ExportMemberNode[];
+//# sourceMappingURL=export-members.d.ts.map

package/dist/api/internal/export-members.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-members.d.ts","sourceRoot":"","sources":["../../../src/api/internal/export-members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAIhD,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,KAAK,EAAE,KAAK,CAAA;IACZ,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAC1C;AAWD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,YAAY,EAAE,CAiB5E;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,CAAA;KAAE,CAAA;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,KAAK,EAAE,KAAK,CAAA;IACZ,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,uCAAuC;IACvC,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,EAAE,CAgC7E"}

package/dist/api/internal/export-members.js

@@ -0,0 +1,104 @@
+/**
+ * export-members — 导出命令的「入参 Shape → 成员表」（方案 §2.6 定式 3 的共用件）
+ *
+ * `cad.exportStep`（`api/export-step.ts`）与 `cad.export3mf`（`api/export-3mf.ts`）
+ * 是同一个库面序列化器（`brep/export/export-model.ts#exportModelSync`）的两个脚本面
+ * 薄壳。两者的差别只有「一个成员交给写出器的载荷是 `solid` 还是 `mesh`」；把入参拆
+ * 成成员表这一步完全一致，故收在本文件——两份拷贝各自漂移会让脚本面与库面同源
+ * （矩阵 B12 / B14）失去保障。
+ *
+ * 拆解口径对齐现成先例 `node-host/cli.ts#writeAssemblyStep`：
+ * - 成员 = `CompoundShape.children`（同序；嵌套 compound 不递归展开，与先例一致）；
+ * - 成员名 = `behavior.memberNames[i]`（装配 op 写入的短名，`memberColors` 亦以它为
+ *   键），无装配 behavior 时回落 `nameOf(child)`；
+ * - 成员色 = `behavior.memberColors[成员名]`（sRGB 0–1，STEP 写 XCAF COLOUR_RGB、
+ *   3MF 写 basematerials）；
+ * - 非 compound 入参 = 单成员、不带名与色，与 `cli.ts#writeOutput`（`:744-758`）同
+ *   口径——单件导出不写名。
+ *
+ * 判定用**结构**判定 `isCompoundLike` 而非 SDK 的 `isShape`/`isCompound`：本 op 吃
+ * 的是脚本文本传进来的值，可能是跨库产物，不能对它提「必须由本库构造器创建」的要求
+ * （同 `keep-syntax §5.3 D5` 的既有取舍）。
+ *
+ * 成员几何一律由调用方**现场**读（`brepOf(child)`），不取创建期快照：装配变换在语句
+ * 之后才烘进 `slot.solid`，快照对已变换成员是陈旧的（`cli.ts#writeAssemblyStep` 的
+ * 同款注释）。
+ */
+import { getSlot, isCompoundLike } from '../../shape.js';
+import { nameOf } from '../../runtime-state.js';
+/**
+ * 把导出命令的入参拆成成员表。
+ *
+ * @param input - 单件 Shape 或装配 compound（结构判定）。
+ * @returns 成员表；空 compound 返回空数组——调用方必须显式报错，不得落空文件。
+ */
+export function exportMembersOf(input) {
+    if (!isCompoundLike(input))
+        return [{ shape: input }];
+    const behavior = getSlot(input)?.behavior;
+    const names = behavior?.memberNames;
+    const members = [];
+    for (let i = 0; i < input.children.length; i++) {
+        const child = input.children[i];
+        const raw = names?.[i] ?? nameOf(child);
+        const name = raw === undefined || raw === '' ? undefined : String(raw);
+        const color = name === undefined ? undefined : behavior?.memberColors?.[name];
+        members.push({
+            shape: child,
+            ...(name === undefined ? {} : { name }),
+            ...(color === undefined ? {} : { color }),
+        });
+    }
+    return members;
+}
+/**
+ * 导出命令入参 → 成员树（方案 §2.1「装配模型 = 节点属性，单一真源」的脚本面投影）。
+ * 与 `exportMembersOf`（平铺）不同，本函数**保留嵌套**：compound 的成员若自身是
+ * compound 则递归展开为子树（同序），叶节点携带其 `shape.transform` 作为相对父位姿。
+ *
+ * 名称 / 颜色取自各层 compound 的 behavior（`memberNames` / `memberColors`，装配 op
+ * 写入；core 只读不写，不 import extra）。本层只管结构，几何载荷由调用方（各 op）
+ * 现场读取——避免创建期快照陈旧（同 `exportMembersOf` 注释）。
+ *
+ * @param input - 脚本面导出命令的入参形状（叶或 compound 装配）。
+ * @returns 保留嵌套结构的成员树；叶节点携带 `shape.transform` 作为相对父位姿。
+ */
+export function exportTreeOf(input) {
+    const leaf = (s, name, color) => {
+        const node = { shape: s };
+        const t = s.transform;
+        if (t)
+            node.transform = t;
+        if (name !== undefined)
+            node.name = name;
+        if (color !== undefined)
+            node.color = color;
+        return node;
+    };
+    const build = (s) => {
+        if (!isCompoundLike(s))
+            return leaf(s);
+        const behavior = getSlot(s)?.behavior;
+        const names = behavior?.memberNames;
+        const children = [];
+        for (let i = 0; i < s.children.length; i++) {
+            const child = s.children[i];
+            if (isCompoundLike(child)) {
+                children.push(build(child));
+            }
+            else {
+                const raw = names?.[i] ?? nameOf(child);
+                const name = raw === undefined || raw === '' ? undefined : String(raw);
+                const color = name === undefined ? undefined : behavior?.memberColors?.[name];
+                children.push(leaf(child, name, color));
+            }
+        }
+        // compound 也是 Shape 的鸭子形态（有 children 槽），但类型面与叶 Shape 不重叠——
+        // 结构判定后这里的 cast 只对类型系统成立，运行时直接透传。
+        const node = leaf(s);
+        node.children = children;
+        return node;
+    };
+    return isCompoundLike(input) ? [build(input)] : [leaf(input)];
+}
+//# sourceMappingURL=export-members.js.map

package/dist/api/internal/export-members.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-members.js","sourceRoot":"","sources":["../../../src/api/internal/export-members.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * export-members — 导出命令的「入参 Shape → 成员表」（方案 §2.6 定式 3 的共用件）\n *\n * `cad.exportStep`（`api/export-step.ts`）与 `cad.export3mf`（`api/export-3mf.ts`）\n * 是同一个库面序列化器（`brep/export/export-model.ts#exportModelSync`）的两个脚本面\n * 薄壳。两者的差别只有「一个成员交给写出器的载荷是 `solid` 还是 `mesh`」；把入参拆\n * 成成员表这一步完全一致，故收在本文件——两份拷贝各自漂移会让脚本面与库面同源\n * （矩阵 B12 / B14）失去保障。\n *\n * 拆解口径对齐现成先例 `node-host/cli.ts#writeAssemblyStep`：\n * - 成员 = `CompoundShape.children`（同序；嵌套 compound 不递归展开，与先例一致）；\n * - 成员名 = `behavior.memberNames[i]`（装配 op 写入的短名，`memberColors` 亦以它为\n *   键），无装配 behavior 时回落 `nameOf(child)`；\n * - 成员色 = `behavior.memberColors[成员名]`（sRGB 0–1，STEP 写 XCAF COLOUR_RGB、\n *   3MF 写 basematerials）；\n * - 非 compound 入参 = 单成员、不带名与色，与 `cli.ts#writeOutput`（`:744-758`）同\n *   口径——单件导出不写名。\n *\n * 判定用**结构**判定 `isCompoundLike` 而非 SDK 的 `isShape`/`isCompound`：本 op 吃\n * 的是脚本文本传进来的值，可能是跨库产物，不能对它提「必须由本库构造器创建」的要求\n * （同 `keep-syntax §5.3 D5` 的既有取舍）。\n *\n * 成员几何一律由调用方**现场**读（`brepOf(child)`），不取创建期快照：装配变换在语句\n * 之后才烘进 `slot.solid`，快照对已变换成员是陈旧的（`cli.ts#writeAssemblyStep` 的\n * 同款注释）。\n */\n\nimport type { Shape, Vec3 } from '../../mesh/types'\nimport type { CompoundShape } from '../../shape'\nimport { getSlot, isCompoundLike } from '../../shape'\nimport { nameOf } from '../../runtime-state'\n\n/** 导出成员：一个待导出的几何 + 其身份（名 / 色）。 */\nexport interface ExportMember {\n  /** 成员几何：compound 的成员，或单件入参本身。 */\n  shape: Shape\n  /** 成员名（写 STEP PRODUCT 名 / 3MF `<object name>`）；无名时缺省。 */\n  name?: string\n  /** sRGB 0–1 成员色（来自装配 behavior 的 `memberColors`）。 */\n  color?: readonly [number, number, number]\n}\n\n/**\n * 装配 behavior 里与导出相关的两个字段（`@faicad/faijs-extra` 的 `assembly` op 写入；\n * 本文件只读不写，也不 import 扩展库——core 不得依赖 extra）。\n */\ninterface ExportBehavior {\n  memberNames?: string[]\n  memberColors?: Record<string, [number, number, number]>\n}\n\n/**\n * 把导出命令的入参拆成成员表。\n *\n * @param input - 单件 Shape 或装配 compound（结构判定）。\n * @returns 成员表；空 compound 返回空数组——调用方必须显式报错，不得落空文件。\n */\nexport function exportMembersOf(input: Shape | CompoundShape): ExportMember[] {\n  if (!isCompoundLike(input)) return [{ shape: input }]\n  const behavior = getSlot(input)?.behavior as ExportBehavior | undefined\n  const names = behavior?.memberNames\n  const members: ExportMember[] = []\n  for (let i = 0; i < input.children.length; i++) {\n    const child = input.children[i]!\n    const raw = names?.[i] ?? nameOf(child)\n    const name = raw === undefined || raw === '' ? undefined : String(raw)\n    const color = name === undefined ? undefined : behavior?.memberColors?.[name]\n    members.push({\n      shape: child,\n      ...(name === undefined ? {} : { name }),\n      ...(color === undefined ? {} : { color }),\n    })\n  }\n  return members\n}\n\n/** 装配节点位姿（与 `Shape.transform` 同形态，见 mesh/types.ts）。 */\nexport interface ExportTransform {\n  translate?: Vec3\n  rotate?: { angle: number; axis?: Vec3 }\n  matrix?: number[]\n}\n\n/** 导出成员树节点：结构（名 / 色 / 位姿 / 子节点）与几何（shape）分离。 */\nexport interface ExportMemberNode {\n  /** 成员几何：compound 的成员，或单件入参本身。 */\n  shape: Shape\n  /** 成员名（写 3MF `<object name>` / STEP PRODUCT 名）；无名时缺省。 */\n  name?: string\n  /** sRGB 0–1 成员色（来自装配 behavior 的 `memberColors`）。 */\n  color?: readonly [number, number, number]\n  /** 本节点相对父的位姿（来自 `shape.transform`）。 */\n  transform?: ExportTransform\n  /** 子节点（嵌套装配）；非 compound 叶节点缺省。 */\n  children?: ExportMemberNode[]\n}\n\n/**\n * 导出命令入参 → 成员树（方案 §2.1「装配模型 = 节点属性，单一真源」的脚本面投影）。\n * 与 `exportMembersOf`（平铺）不同，本函数**保留嵌套**：compound 的成员若自身是\n * compound 则递归展开为子树（同序），叶节点携带其 `shape.transform` 作为相对父位姿。\n *\n * 名称 / 颜色取自各层 compound 的 behavior（`memberNames` / `memberColors`，装配 op\n * 写入；core 只读不写，不 import extra）。本层只管结构，几何载荷由调用方（各 op）\n * 现场读取——避免创建期快照陈旧（同 `exportMembersOf` 注释）。\n *\n * @param input - 脚本面导出命令的入参形状（叶或 compound 装配）。\n * @returns 保留嵌套结构的成员树；叶节点携带 `shape.transform` 作为相对父位姿。\n */\nexport function exportTreeOf(input: Shape | CompoundShape): ExportMemberNode[] {\n  const leaf = (s: Shape, name?: string, color?: readonly [number, number, number]): ExportMemberNode => {\n    const node: ExportMemberNode = { shape: s }\n    const t = s.transform as ExportTransform | undefined\n    if (t) node.transform = t\n    if (name !== undefined) node.name = name\n    if (color !== undefined) node.color = color\n    return node\n  }\n  const build = (s: Shape | CompoundShape): ExportMemberNode => {\n    if (!isCompoundLike(s)) return leaf(s as Shape)\n    const behavior = getSlot(s)?.behavior as ExportBehavior | undefined\n    const names = behavior?.memberNames\n    const children: ExportMemberNode[] = []\n    for (let i = 0; i < s.children.length; i++) {\n      const child = s.children[i]!\n      if (isCompoundLike(child)) {\n        children.push(build(child))\n      } else {\n        const raw = names?.[i] ?? nameOf(child)\n        const name = raw === undefined || raw === '' ? undefined : String(raw)\n        const color = name === undefined ? undefined : behavior?.memberColors?.[name]\n        children.push(leaf(child, name, color))\n      }\n    }\n    // compound 也是 Shape 的鸭子形态（有 children 槽），但类型面与叶 Shape 不重叠——\n    // 结构判定后这里的 cast 只对类型系统成立，运行时直接透传。\n    const node = leaf(s as unknown as Shape)\n    node.children = children\n    return node\n  }\n  return isCompoundLike(input) ? [build(input)] : [leaf(input as Shape)]\n}\n"]}

package/dist/api/internal/l3-bridge.d.ts

@@ -1,8 +1,6 @@
 /**
  * L3 bridge — faijs Shape ⇄ 库侧 brepjs-shaped shape（生成层共用，E5 模板）
  *
- * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5
- *
  * 桥接事实（2026-09-02 实测，2026-09-25 core-decouple wrapup 自有化）：
  * - faijs 的 brep slot（`brepOf(shape)` → `slot.solid`）运行时是 occt-wasm 的
  *   shape 句柄（number，见 `brep/engine/types.ts` 的 `BrepHandle` 注释）；
@@ -10,10 +8,10 @@
  *   （`{ wrapped, disposed, delete, onDispose }`），其 `wrapped` 运行时也是
  *   同一 occt-wasm 实例的 shape 句柄 —— D10 单实例保证两者共享同一 wasm，
  *   句柄空间一致，**零拷贝互操作**。brepjs 子包删除后（裁决 9），本文件
- *   自带最小实现：borrow 视图 / 句柄类型视图 / disposal 解除（no-op）。
+ *   自带最小实现：句柄类型视图 / disposal 解除（no-op）。
  *
  * 因此投影一个库函数只需三件事：
- *   1. faijs Shape → 库输入：`createBorrowedHandle(brepOf(s))`（借入，不转移所有权）；
+ *   1. faijs Shape → 库输入：原样直传（faijs-native 库消费 core Shape）；
  *   2. 调库函数（Result 语义由各 op 处理：`ok` 取值 / `err` 抛错）；
  *   3. 库产物 → faijs Shape：取 `.wrapped`（owned handle）→ `fromHandle()`
  *      （meshHandle + 身份槽登记，所有权转入 faijs）。
@@ -36,36 +34,6 @@ export interface BorrowedShapeHandle {
     /** Borrowed views never dispose, so callbacks never fire（no-op）。 */
     onDispose(callback: () => void): void;
 }
-/** occt-wasm 句柄对象视图（type + id，delete no-op）。 */
-export interface OcctWasmHandleView {
-    __occtWasm: true;
-    type: string;
-    id: number;
-    delete(): void;
-    HashCode(upperBound: number): number;
-    IsNull(): boolean;
-}
-/**
- * Borrow a faijs Shape's OCCT handle as a library-side shape handle.
- *
- * No ownership transfer: the borrowed view is a no-op-dispose wrapper of the
- * same occt-wasm shape, valid while the faijs Shape owns it. Pass the result to
- * compatOp-projected functions that take `Shapeable<T>` / `AnyShape`.
- *
- * `brepOf` is a numeric arena id at runtime (occt-wasm's own `ShapeHandle` is a
- * branded number), but library code consumes shapes as *objects* (the
- * shapeTypeCache WeakMap key, `isOcctWasmHandle` discriminant, direct
- * `shape.type` reads) — a raw number crashes there ("Invalid value used as weak
- * map key"). The id is therefore wrapped into a structurally valid
- * `OcctWasmHandleView`: the type is queried from the bound occt kernel through
- * `getOcctKernel().getShapeType`, and the `delete` is a no-op (non-owning view —
- * the arena slot and its ownership are untouched).
- *
- * @param s - the faijs Shape whose brep slot is borrowed.
- * @returns a library-side ShapeHandle view of the same occt shape.
- * @throws when the Shape has no live BREP slot (mesh-only input on a brep op).
- */
-export declare function borrowBrepjsShape(s: Shape): BorrowedShapeHandle;
 /**
  * Adopt a library-side product into a faijs Shape.
  *
@@ -82,14 +50,14 @@ export declare function adoptBrepjsProduct(product: unknown, segments?: number):
 /**
  * Call a library function with a rebuilt positional argument list.
  *
- * Generated wrappers build `__args` positionally (borrowing geometry inputs,
- * passing value params through); a plain `fn(...args: unknown[])` spread fails
+ * Generated wrappers build `__args` positionally (geometry inputs pass through
+ * untouched, value params pass through as-is); a plain `fn(...args: unknown[])` spread fails
  * TS2556 against fixed-arity signatures, so the call goes through this
  * rest-typed bridge that preserves the function's own `ReturnType` (so a
  * `Result` return keeps `.ok`/`.value` for the generated unwrap code).
  *
  * @param fn   the library function.
- * @param args the rebuilt positional argument list (borrowed handles + value params).
+ * @param args the rebuilt positional argument list (geometry inputs + value params).
  * @returns whatever the function returns (typed via ReturnType).
  */
 export declare function callBrepjs<F extends (...a: never[]) => unknown>(fn: F, args: unknown[]): ReturnType<F>;
@@ -106,6 +74,23 @@ export declare function callBrepjs<F extends (...a: never[]) => unknown>(fn: F,
  * @throws BrepUnsupportedError 当当前引擎不在 `engines` 内。
  */
 export declare function assertEngineFor(opName: string, engines: readonly string[]): void;
+/**
+ * 导出命令的宿主环境断言（与 {@link assertEngineFor} 并列同构，正交轴）。
+ *
+ * 脚本可由 AI 生成任意代码、属不受信输入，而出把「往哪写、写几份、写什么」的
+ * 决定权交给脚本文本；因此脚本面导出命令只在 `'node'` 宿主开放，browser / weapp
+ * 一律在执行前拒绝（`HostPorts.hostEnv` 未声明 = 非 node，不兜底放行）。
+ *
+ * 断言只在 API 函数体第一行执行（普通函数不走 dispatchPath），所以既覆盖脚本面
+ * `cad.*`，也覆盖 TS 直连同一函数的旁路——不存在「脚本被拒、库面直连却放行」。
+ * 判据只读 `config.hostEnv`，与安全扫描档位（`securityPolicy`）解耦：放宽档位
+ * （含 `off`）不解除本门禁。
+ *
+ * @param opName - op 名（报错文案）。
+ * @param hosts - 允许执行的宿主值集合。
+ * @throws HostUnsupportedError 当当前宿主不在 `hosts` 内（含未声明）。
+ */
+export declare function assertHostFor(opName: string, hosts: readonly string[]): void;
 /**
  * Adopt a library handle as a faijs Shape (compatOp step 5's only adoption
  * entry point).

package/dist/api/internal/l3-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"l3-bridge.d.ts","sourceRoot":"","sources":["../../../src/api/internal/l3-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAY7C,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,yCAAyC;IACzC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;IACxB,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAAA;IACd,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CACtC;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,IAAI,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,IAAI,IAAI,CAAA;IACd,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAA;IACpC,MAAM,IAAI,OAAO,CAAA;CAClB;AA8CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,GAAG,mBAAmB,CAY/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAa7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAEtG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAShF;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAkBxF"}
+{"version":3,"file":"l3-bridge.d.ts","sourceRoot":"","sources":["../../../src/api/internal/l3-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAU7C,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,yCAAyC;IACzC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;IACxB,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAAA;IACd,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,oEAAoE;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CACtC;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAa7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAEtG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAShF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAO5E;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAkBxF"}

package/dist/api/internal/l3-bridge.js

@@ -1,8 +1,6 @@
 /**
  * L3 bridge — faijs Shape ⇄ 库侧 brepjs-shaped shape（生成层共用，E5 模板）
  *
- * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5
- *
  * 桥接事实（2026-09-02 实测，2026-09-25 core-decouple wrapup 自有化）：
  * - faijs 的 brep slot（`brepOf(shape)` → `slot.solid`）运行时是 occt-wasm 的
  *   shape 句柄（number，见 `brep/engine/types.ts` 的 `BrepHandle` 注释）；
@@ -10,10 +8,10 @@
  *   （`{ wrapped, disposed, delete, onDispose }`），其 `wrapped` 运行时也是
  *   同一 occt-wasm 实例的 shape 句柄 —— D10 单实例保证两者共享同一 wasm，
  *   句柄空间一致，**零拷贝互操作**。brepjs 子包删除后（裁决 9），本文件
- *   自带最小实现：borrow 视图 / 句柄类型视图 / disposal 解除（no-op）。
+ *   自带最小实现：句柄类型视图 / disposal 解除（no-op）。
  *
  * 因此投影一个库函数只需三件事：
- *   1. faijs Shape → 库输入：`createBorrowedHandle(brepOf(s))`（借入，不转移所有权）；
+ *   1. faijs Shape → 库输入：原样直传（faijs-native 库消费 core Shape）；
  *   2. 调库函数（Result 语义由各 op 处理：`ok` 取值 / `err` 抛错）；
  *   3. 库产物 → faijs Shape：取 `.wrapped`（owned handle）→ `fromHandle()`
  *      （meshHandle + 身份槽登记，所有权转入 faijs）。
@@ -22,80 +20,13 @@
  * handle-bridge / occt-kernel 的类型与工具，保持 dist/sdk.js 零 heavy 依赖
  * （occt-kernel 的 getOcctKernel 为惰性访问，引擎装配前不触碰 wasm）。
  */
-import { brepOf } from '../../shape.js';
-import { fromHandle, getBrepApi } from '../../brep/handle-bridge.js';
-import { getBackends } from '../../runtime-state.js';
+import { fromHandle } from '../../brep/handle-bridge.js';
+import { getBackends, HostUnsupportedError } from '../../runtime-state.js';
 import { OpError } from './result-unwrap.js';
-const noopFn = () => { };
-/** Build an opaque kernel handle for an arena-allocated WASM shape. */
-function occtWasmHandleView(type, id) {
-    return {
-        __occtWasm: true,
-        type,
-        id,
-        delete: noopFn,
-        HashCode(upperBound) {
-            return id % upperBound;
-        },
-        IsNull() {
-            return false;
-        },
-    };
-}
-function isOcctWasmHandle(shape) {
-    return typeof shape === 'object' && shape !== null && shape.__occtWasm === true;
-}
-/** Borrow view：不转移所有权、dispose 为 no-op（与 brepjs createBorrowedHandle 同语义）。 */
-function createBorrowedHandle(ocShape) {
-    return {
-        get wrapped() {
-            return ocShape;
-        },
-        get disposed() {
-            return false;
-        },
-        [Symbol.dispose]: noopFn,
-        delete: noopFn,
-        // Intentionally a no-op: a borrowed view never disposes, so a callback would
-        // never fire. Tie dependent lifetimes to the owning parent's handle instead.
-        onDispose: noopFn,
-    };
-}
 /** brepjs 的 finalizer registry 已随子包删除——解除登记为 no-op。 */
 function unregisterFromCleanup(_deletable) {
     // no-op（原 brepjs core/disposal.ts#unregisterFromCleanup；registry 已不存在）
 }
-/**
- * Borrow a faijs Shape's OCCT handle as a library-side shape handle.
- *
- * No ownership transfer: the borrowed view is a no-op-dispose wrapper of the
- * same occt-wasm shape, valid while the faijs Shape owns it. Pass the result to
- * compatOp-projected functions that take `Shapeable<T>` / `AnyShape`.
- *
- * `brepOf` is a numeric arena id at runtime (occt-wasm's own `ShapeHandle` is a
- * branded number), but library code consumes shapes as *objects* (the
- * shapeTypeCache WeakMap key, `isOcctWasmHandle` discriminant, direct
- * `shape.type` reads) — a raw number crashes there ("Invalid value used as weak
- * map key"). The id is therefore wrapped into a structurally valid
- * `OcctWasmHandleView`: the type is queried from the bound occt kernel through
- * `getOcctKernel().getShapeType`, and the `delete` is a no-op (non-owning view —
- * the arena slot and its ownership are untouched).
- *
- * @param s - the faijs Shape whose brep slot is borrowed.
- * @returns a library-side ShapeHandle view of the same occt shape.
- * @throws when the Shape has no live BREP slot (mesh-only input on a brep op).
- */
-export function borrowBrepjsShape(s) {
-    const solid = brepOf(s);
-    if (solid === undefined) {
-        throw new Error('[faijs/l3-bridge] E_BREP_ONLY_INPUT: operation requires a BREP-backed shape ' +
-            '(mesh-only input cannot run on the brep path)');
-    }
-    const kernelShape = isOcctWasmHandle(solid)
-        ? solid
-        : occtWasmHandleView(getBrepApi().shapeType(solid), solid);
-    return createBorrowedHandle(kernelShape);
-}
 /**
  * Adopt a library-side product into a faijs Shape.
  *
@@ -124,14 +55,14 @@ export function adoptBrepjsProduct(product, segments) {
 /**
  * Call a library function with a rebuilt positional argument list.
  *
- * Generated wrappers build `__args` positionally (borrowing geometry inputs,
- * passing value params through); a plain `fn(...args: unknown[])` spread fails
+ * Generated wrappers build `__args` positionally (geometry inputs pass through
+ * untouched, value params pass through as-is); a plain `fn(...args: unknown[])` spread fails
  * TS2556 against fixed-arity signatures, so the call goes through this
  * rest-typed bridge that preserves the function's own `ReturnType` (so a
  * `Result` return keeps `.ok`/`.value` for the generated unwrap code).
  *
  * @param fn   the library function.
- * @param args the rebuilt positional argument list (borrowed handles + value params).
+ * @param args the rebuilt positional argument list (geometry inputs + value params).
  * @returns whatever the function returns (typed via ReturnType).
  */
 export function callBrepjs(fn, args) {
@@ -157,6 +88,28 @@ export function assertEngineFor(opName, engines) {
         throw e;
     }
 }
+/**
+ * 导出命令的宿主环境断言（与 {@link assertEngineFor} 并列同构，正交轴）。
+ *
+ * 脚本可由 AI 生成任意代码、属不受信输入，而出把「往哪写、写几份、写什么」的
+ * 决定权交给脚本文本；因此脚本面导出命令只在 `'node'` 宿主开放，browser / weapp
+ * 一律在执行前拒绝（`HostPorts.hostEnv` 未声明 = 非 node，不兜底放行）。
+ *
+ * 断言只在 API 函数体第一行执行（普通函数不走 dispatchPath），所以既覆盖脚本面
+ * `cad.*`，也覆盖 TS 直连同一函数的旁路——不存在「脚本被拒、库面直连却放行」。
+ * 判据只读 `config.hostEnv`，与安全扫描档位（`securityPolicy`）解耦：放宽档位
+ * （含 `off`）不解除本门禁。
+ *
+ * @param opName - op 名（报错文案）。
+ * @param hosts - 允许执行的宿主值集合。
+ * @throws HostUnsupportedError 当当前宿主不在 `hosts` 内（含未声明）。
+ */
+export function assertHostFor(opName, hosts) {
+    const current = getBackends().config.hostEnv;
+    if (current === null || current === undefined || !hosts.some((h) => h === current)) {
+        throw new HostUnsupportedError(`E_HOST_UNSUPPORTED: op '${opName}' requires host ${hosts.join(' or ')} (current=${current ?? '<none>'})`);
+    }
+}
 // ─── adoption (compatOp step 5; R1 fix) ──────────────────────────────────────
 /** Already-adopted handle dedup table: the same library handle adopted twice →
  *  the same faijs Shape (prevents double ownership / double dispose, R6). */
@@ -187,7 +140,7 @@ export function adoptEntity(product, opName, segments) {
         return prev;
     const type = h.wrapped.type;
     if (type !== undefined && type !== 'solid' && type !== 'compound') {
-        throw new OpError(opName, 'E_SUBSHAPE_BOUNDARY', `[faijs/brepjs-compat] ${opName}: E_SUBSHAPE_BOUNDARY: sub-shape handle ('${type}') ` +
+        throw new OpError(opName, 'E_SUBSHAPE_BOUNDARY', `[faijs/op] ${opName}: E_SUBSHAPE_BOUNDARY: sub-shape handle ('${type}') ` +
             'must not cross the library boundary; return entity solids or plain data');
     }
     unregisterFromCleanup(h); // ★ R1: no-op（brepjs registry 已删除）