@faicad/faijs 0.13.0

package/dist/api/assembly/validate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * api/assembly/validate — `cad.assembly({ constraints })` 约束参数运行期校验（P2-f1）
+ *
+ * 前置事实（09-07 方案 §2.1）：`assembly` 是 `api/compound.ts` 里的普通导出函数
+ * （经 api-namespace 注册进 cad 命名空间），**不是 defineOp/compatOp 声明的 op**，
+ * 没有 "params 校验惯例" 可复用；`api/assert.ts` 的 7 个助手都是标量/向量级，
+ * **没有对象/数组结构校验助手**——本模块内的结构校验逻辑是新增的，不污染通用 assert。
+ *
+ * 校验规则（逐条可判，报错文案必含：字段路径 + 期望形态 + 实际收到值）：
+ * - V1 `type` ∈ {mate, align, coincident, concentric, distance, angle, parallel,
+ *   perpendicular, fixed, face_mate}（文案列出合法类型全集）；
+ * - V2 mate/align/coincident/concentric/distance/angle/parallel/perpendicular
+ *   必须有 `a`、`b` 两个 EntityRef（face_mate 等价为 fixedFace/movingFace）；
+ * - V3 distance/angle 必须有**有限数** `value`；不设区间（angle 允许 ±360 以外）
+ *   与 brepjs solveAngle 行为对齐；
+ * - V4 EntityRef 四形态 `face`/`edge`/`point`/`faceIndex` 互斥且恰占其一；
+ *   `faceIndex` 必须为正整数；
+ * - V5 `fixed` 只需要 `part`；`part` 必须出现在 members 里（**所有约束类型统一检查**，
+ *   文案含成员名全集）；
+ * - V6 face_mate 按 normalize 语义重排（fixedPartName/fixedFace → a，
+ *   movingPartName/movingFace → b）后同样过 V2/V5。
+ *
+ * 调用点：`compound.ts` 的 `assembly(params)` 函数体开头、`keep()` 之前（fail-fast，
+ * 与 normalize.ts 的未知类型抛错互补——执行期错误不静默）。
+ */
+import type { AssemblyConstraint } from './types.js';
+/** 合法约束类型全集（V1；与 types.ts 的 AssemblyConstraint 并集约等）。 */
+export declare const ASSEMBLY_CONSTRAINT_TYPES: readonly ["mate", "align", "coincident", "concentric", "distance", "angle", "parallel", "perpendicular", "fixed", "face_mate"];
+/**
+ * 校验 `cad.assembly({ constraints })` 的 constraints 参数（V1–V6）。
+ * @param constraints - 未校验的 constraints 输入（脚本/宿主直传，可为任意值）。
+ * @param memberNames - 成员名列表（来自成员的 nameOf 反查/显式 memberNames），V5 用。
+ * @throws Error 首条违规即抛（fail-fast），文案含字段路径。
+ * @returns 断言函数，通过后收窄 constraints 为 AssemblyConstraint[]。
+ */
+export declare function validateConstraints(constraints: unknown, memberNames: string[]): asserts constraints is AssemblyConstraint[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/api/assembly/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjD,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,gIAG5B,CAAA;AA0GV;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,OAAO,EACpB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAO7C"}

package/dist/api/assembly/validate.js

@@ -0,0 +1,131 @@
+/**
+ * api/assembly/validate — `cad.assembly({ constraints })` 约束参数运行期校验（P2-f1）
+ *
+ * 前置事实（09-07 方案 §2.1）：`assembly` 是 `api/compound.ts` 里的普通导出函数
+ * （经 api-namespace 注册进 cad 命名空间），**不是 defineOp/compatOp 声明的 op**，
+ * 没有 "params 校验惯例" 可复用；`api/assert.ts` 的 7 个助手都是标量/向量级，
+ * **没有对象/数组结构校验助手**——本模块内的结构校验逻辑是新增的，不污染通用 assert。
+ *
+ * 校验规则（逐条可判，报错文案必含：字段路径 + 期望形态 + 实际收到值）：
+ * - V1 `type` ∈ {mate, align, coincident, concentric, distance, angle, parallel,
+ *   perpendicular, fixed, face_mate}（文案列出合法类型全集）；
+ * - V2 mate/align/coincident/concentric/distance/angle/parallel/perpendicular
+ *   必须有 `a`、`b` 两个 EntityRef（face_mate 等价为 fixedFace/movingFace）；
+ * - V3 distance/angle 必须有**有限数** `value`；不设区间（angle 允许 ±360 以外）
+ *   与 brepjs solveAngle 行为对齐；
+ * - V4 EntityRef 四形态 `face`/`edge`/`point`/`faceIndex` 互斥且恰占其一；
+ *   `faceIndex` 必须为正整数；
+ * - V5 `fixed` 只需要 `part`；`part` 必须出现在 members 里（**所有约束类型统一检查**，
+ *   文案含成员名全集）；
+ * - V6 face_mate 按 normalize 语义重排（fixedPartName/fixedFace → a，
+ *   movingPartName/movingFace → b）后同样过 V2/V5。
+ *
+ * 调用点：`compound.ts` 的 `assembly(params)` 函数体开头、`keep()` 之前（fail-fast，
+ * 与 normalize.ts 的未知类型抛错互补——执行期错误不静默）。
+ */
+/** 合法约束类型全集（V1；与 types.ts 的 AssemblyConstraint 并集约等）。 */
+export const ASSEMBLY_CONSTRAINT_TYPES = [
+    'mate', 'align', 'coincident', 'concentric', 'distance', 'angle',
+    'parallel', 'perpendicular', 'fixed', 'face_mate',
+];
+/** 需要 `a`/`b` 两个 EntityRef 的新形态类型（V2；distance/angle 在 types 契约里也有 a/b）。 */
+const PAIRED_TYPES = new Set([
+    'mate', 'align', 'coincident', 'concentric', 'distance', 'angle',
+    'parallel', 'perpendicular',
+]);
+function fail(path, expected, got) {
+    throw new Error(`[assembly] ${path}: expected ${expected}, got ${JSON.stringify(got)}`);
+}
+/** V4：EntityRef 四形态互斥且恰占其一；faceIndex 正整数；part 必须 ∈ members（V5）。 */
+function checkEntityRef(ref, path, memberNames) {
+    if (ref === null || typeof ref !== 'object') {
+        fail(path, 'an EntityRef object { part, face | edge | point | faceIndex }', ref);
+    }
+    const r = ref;
+    if (typeof r.part !== 'string' || r.part.length === 0) {
+        fail(`${path}.part`, 'a non-empty member name string', r.part);
+    }
+    if (!memberNames.includes(r.part)) {
+        throw new Error(`[assembly] ${path}.part: "${r.part}" is not a member; members: [${memberNames.join(', ')}]`);
+    }
+    const present = ['face', 'edge', 'point', 'faceIndex'].filter((k) => k in r && r[k] !== undefined);
+    if (present.length !== 1) {
+        fail(path, `exactly one of face/edge/point/faceIndex (mutually exclusive), got keys [${present.join(', ')}]`, r);
+    }
+    if ('faceIndex' in r) {
+        const idx = r.faceIndex;
+        if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 1) {
+            fail(`${path}.faceIndex`, 'a positive integer (1-based face ordinal)', idx);
+        }
+    }
+    if ('point' in r) {
+        const p = r.point;
+        if (!Array.isArray(p) || p.length !== 3 ||
+            p.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+            fail(`${path}.point`, 'a vec3 [x, y, z] of finite numbers', p);
+        }
+    }
+}
+/** V6：face_mate 按 normalize 语义重排后过 V2/V5（face 省略四形态检查——结构上必为面）。 */
+function checkFaceMate(c, path, memberNames) {
+    const a = { part: c.fixedPartName, face: c.fixedFace };
+    const b = { part: c.movingPartName, face: c.movingFace };
+    checkEntityRef(a, `${path} (a → fixedPartName/fixedFace)`, memberNames);
+    checkEntityRef(b, `${path} (b → movingPartName/movingFace)`, memberNames);
+}
+/** 校验单条约束（下标 i 用于报错路径）。 */
+function checkOne(raw, i, memberNames) {
+    const path = `constraints[${i}]`;
+    if (raw === null || typeof raw !== 'object') {
+        fail(path, 'an object with a "type" field', raw);
+    }
+    const c = raw;
+    // V1
+    const type = c.type;
+    if (typeof type !== 'string' || !ASSEMBLY_CONSTRAINT_TYPES.includes(type)) {
+        throw new Error(`[assembly] ${path}.type: unknown constraint type ${JSON.stringify(type)}, expected one of ${ASSEMBLY_CONSTRAINT_TYPES.join(' | ')}`);
+    }
+    // V6：face_mate 先归一化再走通用校验
+    if (type === 'face_mate') {
+        checkFaceMate(c, path, memberNames);
+        return;
+    }
+    // V5：fixed 只需要顶层 part（字符串）且 ∈ members
+    if (type === 'fixed') {
+        if (typeof c.part !== 'string' || c.part.length === 0) {
+            fail(`${path}.part`, 'a non-empty member name string', c.part);
+        }
+        if (!memberNames.includes(c.part)) {
+            throw new Error(`[assembly] ${path}.part: "${c.part}" is not a member; members: [${memberNames.join(', ')}]`);
+        }
+        return;
+    }
+    // V2 + V4（a/b 每个都是 EntityRef）
+    if (PAIRED_TYPES.has(type)) {
+        checkEntityRef(c.a, `${path}.a`, memberNames);
+        checkEntityRef(c.b, `${path}.b`, memberNames);
+    }
+    // V3：distance/angle 必须有有限数 value（不设区间，与 brepjs solveAngle 对齐）
+    if (type === 'distance' || type === 'angle') {
+        const v = c.value;
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            fail(`${path}.value`, 'a finite number', v);
+        }
+    }
+}
+/**
+ * 校验 `cad.assembly({ constraints })` 的 constraints 参数（V1–V6）。
+ * @param constraints - 未校验的 constraints 输入（脚本/宿主直传，可为任意值）。
+ * @param memberNames - 成员名列表（来自成员的 nameOf 反查/显式 memberNames），V5 用。
+ * @throws Error 首条违规即抛（fail-fast），文案含字段路径。
+ * @returns 断言函数，通过后收窄 constraints 为 AssemblyConstraint[]。
+ */
+export function validateConstraints(constraints, memberNames) {
+    if (!Array.isArray(constraints)) {
+        fail('constraints', 'an array of constraint objects', constraints);
+    }
+    for (let i = 0; i < constraints.length; i++) {
+        checkOne(constraints[i], i, memberNames);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/assembly/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/api/assembly/validate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/validate — `cad.assembly({ constraints })` 约束参数运行期校验（P2-f1）\n *\n * 前置事实（09-07 方案 §2.1）：`assembly` 是 `api/compound.ts` 里的普通导出函数\n * （经 api-namespace 注册进 cad 命名空间），**不是 defineOp/compatOp 声明的 op**，\n * 没有 \"params 校验惯例\" 可复用；`api/assert.ts` 的 7 个助手都是标量/向量级，\n * **没有对象/数组结构校验助手**——本模块内的结构校验逻辑是新增的，不污染通用 assert。\n *\n * 校验规则（逐条可判，报错文案必含：字段路径 + 期望形态 + 实际收到值）：\n * - V1 `type` ∈ {mate, align, coincident, concentric, distance, angle, parallel,\n *   perpendicular, fixed, face_mate}（文案列出合法类型全集）；\n * - V2 mate/align/coincident/concentric/distance/angle/parallel/perpendicular\n *   必须有 `a`、`b` 两个 EntityRef（face_mate 等价为 fixedFace/movingFace）；\n * - V3 distance/angle 必须有**有限数** `value`；不设区间（angle 允许 ±360 以外）\n *   与 brepjs solveAngle 行为对齐；\n * - V4 EntityRef 四形态 `face`/`edge`/`point`/`faceIndex` 互斥且恰占其一；\n *   `faceIndex` 必须为正整数；\n * - V5 `fixed` 只需要 `part`；`part` 必须出现在 members 里（**所有约束类型统一检查**，\n *   文案含成员名全集）；\n * - V6 face_mate 按 normalize 语义重排（fixedPartName/fixedFace → a，\n *   movingPartName/movingFace → b）后同样过 V2/V5。\n *\n * 调用点：`compound.ts` 的 `assembly(params)` 函数体开头、`keep()` 之前（fail-fast，\n * 与 normalize.ts 的未知类型抛错互补——执行期错误不静默）。\n */\n\nimport type { AssemblyConstraint } from './types'\n\n/** 合法约束类型全集（V1；与 types.ts 的 AssemblyConstraint 并集约等）。 */\nexport const ASSEMBLY_CONSTRAINT_TYPES = [\n  'mate', 'align', 'coincident', 'concentric', 'distance', 'angle',\n  'parallel', 'perpendicular', 'fixed', 'face_mate',\n] as const\n\n/** 需要 `a`/`b` 两个 EntityRef 的新形态类型（V2；distance/angle 在 types 契约里也有 a/b）。 */\nconst PAIRED_TYPES = new Set([\n  'mate', 'align', 'coincident', 'concentric', 'distance', 'angle',\n  'parallel', 'perpendicular',\n])\n\nfunction fail(path: string, expected: string, got: unknown): never {\n  throw new Error(`[assembly] ${path}: expected ${expected}, got ${JSON.stringify(got)}`)\n}\n\n/** V4：EntityRef 四形态互斥且恰占其一；faceIndex 正整数；part 必须 ∈ members（V5）。 */\nfunction checkEntityRef(ref: unknown, path: string, memberNames: string[]): void {\n  if (ref === null || typeof ref !== 'object') {\n    fail(path, 'an EntityRef object { part, face | edge | point | faceIndex }', ref)\n  }\n  const r = ref as Record<string, unknown>\n  if (typeof r.part !== 'string' || r.part.length === 0) {\n    fail(`${path}.part`, 'a non-empty member name string', r.part)\n  }\n  if (!memberNames.includes(r.part)) {\n    throw new Error(\n      `[assembly] ${path}.part: \"${r.part}\" is not a member; members: [${memberNames.join(', ')}]`,\n    )\n  }\n  const present = (['face', 'edge', 'point', 'faceIndex'] as const).filter(\n    (k) => k in r && r[k] !== undefined,\n  )\n  if (present.length !== 1) {\n    fail(path, `exactly one of face/edge/point/faceIndex (mutually exclusive), got keys [${present.join(', ')}]`, r)\n  }\n  if ('faceIndex' in r) {\n    const idx = r.faceIndex\n    if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 1) {\n      fail(`${path}.faceIndex`, 'a positive integer (1-based face ordinal)', idx)\n    }\n  }\n  if ('point' in r) {\n    const p = r.point\n    if (\n      !Array.isArray(p) || p.length !== 3 ||\n      p.some((n) => typeof n !== 'number' || !Number.isFinite(n))\n    ) {\n      fail(`${path}.point`, 'a vec3 [x, y, z] of finite numbers', p)\n    }\n  }\n}\n\n/** V6：face_mate 按 normalize 语义重排后过 V2/V5（face 省略四形态检查——结构上必为面）。 */\nfunction checkFaceMate(c: Record<string, unknown>, path: string, memberNames: string[]): void {\n  const a = { part: c.fixedPartName, face: c.fixedFace }\n  const b = { part: c.movingPartName, face: c.movingFace }\n  checkEntityRef(a, `${path} (a → fixedPartName/fixedFace)`, memberNames)\n  checkEntityRef(b, `${path} (b → movingPartName/movingFace)`, memberNames)\n}\n\n/** 校验单条约束（下标 i 用于报错路径）。 */\nfunction checkOne(raw: unknown, i: number, memberNames: string[]): void {\n  const path = `constraints[${i}]`\n  if (raw === null || typeof raw !== 'object') {\n    fail(path, 'an object with a \"type\" field', raw)\n  }\n  const c = raw as Record<string, unknown>\n  // V1\n  const type = c.type\n  if (typeof type !== 'string' || !(ASSEMBLY_CONSTRAINT_TYPES as readonly string[]).includes(type)) {\n    throw new Error(\n      `[assembly] ${path}.type: unknown constraint type ${JSON.stringify(type)}, expected one of ${ASSEMBLY_CONSTRAINT_TYPES.join(' | ')}`,\n    )\n  }\n\n  // V6：face_mate 先归一化再走通用校验\n  if (type === 'face_mate') {\n    checkFaceMate(c, path, memberNames)\n    return\n  }\n\n  // V5：fixed 只需要顶层 part（字符串）且 ∈ members\n  if (type === 'fixed') {\n    if (typeof c.part !== 'string' || c.part.length === 0) {\n      fail(`${path}.part`, 'a non-empty member name string', c.part)\n    }\n    if (!memberNames.includes(c.part)) {\n      throw new Error(\n        `[assembly] ${path}.part: \"${c.part}\" is not a member; members: [${memberNames.join(', ')}]`,\n      )\n    }\n    return\n  }\n\n  // V2 + V4（a/b 每个都是 EntityRef）\n  if (PAIRED_TYPES.has(type)) {\n    checkEntityRef(c.a, `${path}.a`, memberNames)\n    checkEntityRef(c.b, `${path}.b`, memberNames)\n  }\n\n  // V3：distance/angle 必须有有限数 value（不设区间，与 brepjs solveAngle 对齐）\n  if (type === 'distance' || type === 'angle') {\n    const v = c.value\n    if (typeof v !== 'number' || !Number.isFinite(v)) {\n      fail(`${path}.value`, 'a finite number', v)\n    }\n  }\n}\n\n/**\n * 校验 `cad.assembly({ constraints })` 的 constraints 参数（V1–V6）。\n * @param constraints - 未校验的 constraints 输入（脚本/宿主直传，可为任意值）。\n * @param memberNames - 成员名列表（来自成员的 nameOf 反查/显式 memberNames），V5 用。\n * @throws Error 首条违规即抛（fail-fast），文案含字段路径。\n * @returns 断言函数，通过后收窄 constraints 为 AssemblyConstraint[]。\n */\nexport function validateConstraints(\n  constraints: unknown,\n  memberNames: string[],\n): asserts constraints is AssemblyConstraint[] {\n  if (!Array.isArray(constraints)) {\n    fail('constraints', 'an array of constraint objects', constraints)\n  }\n  for (let i = 0; i < constraints.length; i++) {\n    checkOne(constraints[i], i, memberNames)\n  }\n}"]}

package/dist/api/assert.d.ts

@@ -0,0 +1,54 @@
+/**
+ * stdlib assert — per-op 参数自校验助手（Phase 2.2）
+ *
+ *
+ * 阶段 4 起（args-schema/SCHEMAS 已删除），参数校验全部由本模块的 assert 助手
+ * 承担（各 stdlib 函数在 dispatchPath 之前调用）；非法即抛 Error（不静默）。
+ */
+/**
+ * Assert that a parameter is a finite number, narrowing the type to `number`.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ * @returns asserts that `value` is a number.
+ */
+export declare function assertNumber(value: unknown, name: string): asserts value is number;
+/**
+ * Assert that a parameter is a number greater than zero.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export declare function assertPositiveNumber(value: unknown, name: string): void;
+/**
+ * Assert that a parameter is a number greater than or equal to zero.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export declare function assertNonNegativeNumber(value: unknown, name: string): void;
+/**
+ * Assert that a parameter is a vec3 `[x, y, z]` of finite numbers.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export declare function assertVec3(value: unknown, name: string): void;
+/**
+ * Assert that a parameter is a non-zero vec3 (a zero vector would degenerate
+ * operations such as split/faceNormal, so it is rejected).
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export declare function assertNonZeroVec3(value: unknown, name: string): void;
+/**
+ * Assert that a parameter is either a positive number or a vec3.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export declare function assertNumberOrVec3(value: unknown, name: string): void;
+/**
+ * Assert that a parameter is one of the given allowed values (skipped when
+ * `value` is absent).
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ * @param allowed - the list of permitted string values.
+ */
+export declare function assertOneOf(value: unknown, name: string, allowed: readonly string[]): void;
+//# sourceMappingURL=assert.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/api/assert.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAIlF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAMrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAI1F"}

package/dist/api/assert.js

@@ -0,0 +1,90 @@
+/**
+ * stdlib assert — per-op 参数自校验助手（Phase 2.2）
+ *
+ *
+ * 阶段 4 起（args-schema/SCHEMAS 已删除），参数校验全部由本模块的 assert 助手
+ * 承担（各 stdlib 函数在 dispatchPath 之前调用）；非法即抛 Error（不静默）。
+ */
+/**
+ * Assert that a parameter is a finite number, narrowing the type to `number`.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ * @returns asserts that `value` is a number.
+ */
+export function assertNumber(value, name) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`[stdlib] ${name} must be a finite number, got ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * Assert that a parameter is a number greater than zero.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export function assertPositiveNumber(value, name) {
+    assertNumber(value, name);
+    if (value <= 0) {
+        throw new Error(`[stdlib] ${name} must be > 0, got ${value}`);
+    }
+}
+/**
+ * Assert that a parameter is a number greater than or equal to zero.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export function assertNonNegativeNumber(value, name) {
+    assertNumber(value, name);
+    if (value < 0) {
+        throw new Error(`[stdlib] ${name} must be >= 0, got ${value}`);
+    }
+}
+/**
+ * Assert that a parameter is a vec3 `[x, y, z]` of finite numbers.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export function assertVec3(value, name) {
+    if (!Array.isArray(value) ||
+        value.length !== 3 ||
+        value.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        throw new Error(`[stdlib] ${name} must be a vec3 [x, y, z], got ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * Assert that a parameter is a non-zero vec3 (a zero vector would degenerate
+ * operations such as split/faceNormal, so it is rejected).
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export function assertNonZeroVec3(value, name) {
+    assertVec3(value, name);
+    const v = value;
+    if (v[0] === 0 && v[1] === 0 && v[2] === 0) {
+        throw new Error(`[stdlib] ${name} must be a non-zero vec3, got ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * Assert that a parameter is either a positive number or a vec3.
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ */
+export function assertNumberOrVec3(value, name) {
+    if (typeof value === 'number') {
+        assertPositiveNumber(value, name);
+        return;
+    }
+    assertVec3(value, name);
+}
+/**
+ * Assert that a parameter is one of the given allowed values (skipped when
+ * `value` is absent).
+ * @param value - the value to check.
+ * @param name - the parameter name used in the thrown error message.
+ * @param allowed - the list of permitted string values.
+ */
+export function assertOneOf(value, name, allowed) {
+    if (value !== undefined && value !== null && !allowed.includes(value)) {
+        throw new Error(`[stdlib] ${name} must be one of ${allowed.join(' | ')}, got ${JSON.stringify(value)}`);
+    }
+}
+//# sourceMappingURL=assert.js.map

package/dist/api/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../src/api/assert.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,IAAY;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,iCAAiC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC3F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,IAAY;IAC/D,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACzB,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,qBAAqB,KAAK,EAAE,CAAC,CAAA;IAC/D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc,EAAE,IAAY;IAClE,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACzB,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,sBAAsB,KAAK,EAAE,CAAC,CAAA;IAChE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,IAAY;IACrD,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC/D,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,kCAAkC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC5F,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,IAAY;IAC5D,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACvB,MAAM,CAAC,GAAG,KAAiC,CAAA;IAC3C,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,iCAAiC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC3F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc,EAAE,IAAY;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QACjC,OAAM;IACR,CAAC;IACD,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAAY,EAAE,OAA0B;IAClF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,mBAAmB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACzG,CAAC;AACH,CAAC","sourcesContent":["/**\n * stdlib assert — per-op 参数自校验助手（Phase 2.2）\n *\n *\n * 阶段 4 起（args-schema/SCHEMAS 已删除），参数校验全部由本模块的 assert 助手\n * 承担（各 stdlib 函数在 dispatchPath 之前调用）；非法即抛 Error（不静默）。\n */\n\n/**\n * Assert that a parameter is a finite number, narrowing the type to `number`.\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n * @returns asserts that `value` is a number.\n */\nexport function assertNumber(value: unknown, name: string): asserts value is number {\n  if (typeof value !== 'number' || !Number.isFinite(value)) {\n    throw new Error(`[stdlib] ${name} must be a finite number, got ${JSON.stringify(value)}`)\n  }\n}\n\n/**\n * Assert that a parameter is a number greater than zero.\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n */\nexport function assertPositiveNumber(value: unknown, name: string): void {\n  assertNumber(value, name)\n  if (value <= 0) {\n    throw new Error(`[stdlib] ${name} must be > 0, got ${value}`)\n  }\n}\n\n/**\n * Assert that a parameter is a number greater than or equal to zero.\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n */\nexport function assertNonNegativeNumber(value: unknown, name: string): void {\n  assertNumber(value, name)\n  if (value < 0) {\n    throw new Error(`[stdlib] ${name} must be >= 0, got ${value}`)\n  }\n}\n\n/**\n * Assert that a parameter is a vec3 `[x, y, z]` of finite numbers.\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n */\nexport function assertVec3(value: unknown, name: string): void {\n  if (\n    !Array.isArray(value) ||\n    value.length !== 3 ||\n    value.some((n) => typeof n !== 'number' || !Number.isFinite(n))\n  ) {\n    throw new Error(`[stdlib] ${name} must be a vec3 [x, y, z], got ${JSON.stringify(value)}`)\n  }\n}\n\n/**\n * Assert that a parameter is a non-zero vec3 (a zero vector would degenerate\n * operations such as split/faceNormal, so it is rejected).\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n */\nexport function assertNonZeroVec3(value: unknown, name: string): void {\n  assertVec3(value, name)\n  const v = value as [number, number, number]\n  if (v[0] === 0 && v[1] === 0 && v[2] === 0) {\n    throw new Error(`[stdlib] ${name} must be a non-zero vec3, got ${JSON.stringify(value)}`)\n  }\n}\n\n/**\n * Assert that a parameter is either a positive number or a vec3.\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n */\nexport function assertNumberOrVec3(value: unknown, name: string): void {\n  if (typeof value === 'number') {\n    assertPositiveNumber(value, name)\n    return\n  }\n  assertVec3(value, name)\n}\n\n/**\n * Assert that a parameter is one of the given allowed values (skipped when\n * `value` is absent).\n * @param value - the value to check.\n * @param name - the parameter name used in the thrown error message.\n * @param allowed - the list of permitted string values.\n */\nexport function assertOneOf(value: unknown, name: string, allowed: readonly string[]): void {\n  if (value !== undefined && value !== null && !allowed.includes(value as string)) {\n    throw new Error(`[stdlib] ${name} must be one of ${allowed.join(' | ')}, got ${JSON.stringify(value)}`)\n  }\n}\n"]}

package/dist/api/asset.d.ts

@@ -0,0 +1,20 @@
+/**
+ * stdlib asset — `cad.asset(key)` 库函数（A7 消灭后 asset 走 CallRefIR）
+ *
+ *
+ * 嵌套调用 `cad.asset('cfg')` 返回 UTF-8 字符串（SVG 等文本资产）。
+ */
+/**
+ * 查询资产 key 内容为 UTF-8 字符串（SVG 等文本资产）。嵌套调用，供 text/svg 类 op 作资产引用。
+ * @group 查询
+ * @inputs 0
+ * @async true
+ * @qual ok
+ * @name asset
+ * @returns Promise<string> 资产内容字符串（UTF-8 解码）。`cad.asset('cfg')` 返回 SVG 等文本资产，可作 svgExtrude/engrave 的 svg 参数。
+ * @param key - 资产 key。type:string required:true
+ * @example
+ * const svg = await cad.asset('logo_cfg')
+ */
+export declare function asset(key: string): Promise<string>;
+//# sourceMappingURL=asset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../../src/api/asset.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOxD"}

package/dist/api/asset.js

@@ -0,0 +1,28 @@
+/**
+ * stdlib asset — `cad.asset(key)` 库函数（A7 消灭后 asset 走 CallRefIR）
+ *
+ *
+ * 嵌套调用 `cad.asset('cfg')` 返回 UTF-8 字符串（SVG 等文本资产）。
+ */
+import { getBackends } from '../runtime-state.js';
+/**
+ * 查询资产 key 内容为 UTF-8 字符串（SVG 等文本资产）。嵌套调用，供 text/svg 类 op 作资产引用。
+ * @group 查询
+ * @inputs 0
+ * @async true
+ * @qual ok
+ * @name asset
+ * @returns Promise<string> 资产内容字符串（UTF-8 解码）。`cad.asset('cfg')` 返回 SVG 等文本资产，可作 svgExtrude/engrave 的 svg 参数。
+ * @param key - 资产 key。type:string required:true
+ * @example
+ * const svg = await cad.asset('logo_cfg')
+ */
+export async function asset(key) {
+    const assets = getBackends().assets;
+    if (!assets) {
+        throw new Error(`[stdlib/asset] asset "${key}" cannot be resolved: assets not available`);
+    }
+    const result = await assets.resolveByKey(key);
+    return new TextDecoder('utf-8').decode(new Uint8Array(result.bytes));
+}
+//# sourceMappingURL=asset.js.map

package/dist/api/asset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset.js","sourceRoot":"","sources":["../../src/api/asset.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAW;IACrC,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAoF,CAAA;IACjH,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,4CAA4C,CAAC,CAAA;IAC3F,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;IAC7C,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;AACtE,CAAC","sourcesContent":["/**\n * stdlib asset — `cad.asset(key)` 库函数（A7 消灭后 asset 走 CallRefIR）\n *\n *\n * 嵌套调用 `cad.asset('cfg')` 返回 UTF-8 字符串（SVG 等文本资产）。\n */\n\nimport { getBackends } from '../runtime-state'\n\n/**\n * 查询资产 key 内容为 UTF-8 字符串（SVG 等文本资产）。嵌套调用，供 text/svg 类 op 作资产引用。\n * @group 查询\n * @inputs 0\n * @async true\n * @qual ok\n * @name asset\n * @returns Promise<string> 资产内容字符串（UTF-8 解码）。`cad.asset('cfg')` 返回 SVG 等文本资产，可作 svgExtrude/engrave 的 svg 参数。\n * @param key - 资产 key。type:string required:true\n * @example\n * const svg = await cad.asset('logo_cfg')\n */\nexport async function asset(key: string): Promise<string> {\n  const assets = getBackends().assets as { resolveByKey(key: string): Promise<{ bytes: ArrayBuffer }> } | undefined\n  if (!assets) {\n    throw new Error(`[stdlib/asset] asset \"${key}\" cannot be resolved: assets not available`)\n  }\n  const result = await assets.resolveByKey(key)\n  return new TextDecoder('utf-8').decode(new Uint8Array(result.bytes))\n}\n"]}

package/dist/api/boolean.d.ts

@@ -0,0 +1,56 @@
+/**
+ * stdlib boolean — 布尔库函数（union/subtract/intersect，多输入）
+ *
+ *
+ * dispatchPath 静态判定 brep/mesh，BREP 路径用 *WithHistory 收集面演化。
+ *
+ * 阶段 1：拆为三个薄函数 union/subtract/intersect + 兼容 boolean 导出（过渡）。
+ * 阶段 3 将删除 boolean 兼容导出。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * 布尔并集：合并所有输入几何（≥2 个输入）。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name union
+ * @param shapes - 参与运算的几何（变量引用，≥2 个）。type:Shape[] required:true
+ * @returns Shape 所有输入的并集。函数名即操作，输入全是变量引用，可用 `cad.union(a, b, c)` 多输入。
+ * @example
+ * const a = await cad.union(part0, part1)
+  */
+export declare const union: ((...args: Shape[]) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 布尔差集：第一个为主体，减去其余输入。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name subtract
+ * @param shapes - 参与运算的几何（变量引用，第一个为主体）。type:Shape[] required:true
+ * @returns Shape part0 减 part1 的差集（第一个为主体）。
+ * @example
+ * const b = await cad.subtract(part0, part1)
+  */
+export declare const subtract: ((...args: Shape[]) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 布尔交集：所有输入的重叠部分。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name intersect
+ * @param shapes - 参与运算的几何（变量引用）。type:Shape[] required:true
+ * @returns Shape 所有输入的交集。
+ * @example
+ * const c = await cad.intersect(part0, part1)
+  */
+export declare const intersect: ((...args: Shape[]) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=boolean.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../src/api/boolean.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AA0F1C;;;;;;;;;;;IAWI;AACJ,eAAO,MAAM,KAAK;;CAWhB,CAAA;AAEF;;;;;;;;;;;IAWI;AACJ,eAAO,MAAM,QAAQ;;CAUnB,CAAA;AAEF;;;;;;;;;;;IAWI;AACJ,eAAO,MAAM,SAAS;;CAUpB,CAAA"}

package/dist/api/boolean.js

@@ -0,0 +1,151 @@
+/**
+ * stdlib boolean — 布尔库函数（union/subtract/intersect，多输入）
+ *
+ *
+ * dispatchPath 静态判定 brep/mesh，BREP 路径用 *WithHistory 收集面演化。
+ *
+ * 阶段 1：拆为三个薄函数 union/subtract/intersect + 兼容 boolean 导出（过渡）。
+ * 阶段 3 将删除 boolean 兼容导出。
+ */
+import { cad } from '../mesh/index.js';
+import { solidToShape } from '../brep/brep-ops.js';
+import { booleanWithRoleTable, } from '../brep/face-evolution.js';
+import { getBackends, getCurrentStmt, keepHidden } from '../runtime-state.js';
+import { fromBrep, brepOf, getSlot } from '../shape.js';
+import { reconcileBrepInputs } from './reconcile.js';
+import { defineOp } from '../sdk.js';
+// ── 共享内部实现 ──
+/** BREP 路径：fuse/cut/common（*WithHistory 封装，收集面演化 + roleTable 合流 §3.4）。 */
+function booleanBrep(inputs, operation) {
+    const kernel = getBackends().kernel.brep;
+    if (!kernel)
+        throw new Error('[stdlib/boolean] no OCCT kernel');
+    const inputSolids = inputs.map((s) => brepOf(s));
+    if (inputSolids.some((s) => !s)) {
+        throw new Error('[stdlib/boolean] input is not BREP');
+    }
+    let resultSolid;
+    let lastEvolution;
+    let roleTable;
+    // 链式布尔：每步 target（累积结果）与下一个 tool 合流
+    const op = operation === 'union' ? 'fuse' : operation === 'subtract' ? 'cut' : 'intersect';
+    // 首个输入作为 target 起点
+    resultSolid = inputSolids[0];
+    roleTable = getSlot(inputs[0])?.roleTable;
+    for (let i = 1; i < inputSolids.length; i++) {
+        const prev = resultSolid;
+        const prevTable = roleTable;
+        const toolTable = getSlot(inputs[i])?.roleTable;
+        const outPart = String(getCurrentStmt()?.outputs[0] ?? '');
+        // §3.4：一次内核调用，A/B 拆流各自传播后合表（缝面以本次语句 LHS 为新 origin）
+        const r = booleanWithRoleTable(kernel, op, prev, inputSolids[i], prevTable ?? new Map(), toolTable ?? new Map(), outPart);
+        resultSolid = r.result;
+        lastEvolution = r.faceEvolution;
+        roleTable = r.roleTable;
+        if (i > 1)
+            kernel.release(prev);
+    }
+    return fromBrep(solidToShape(kernel, resultSolid), lastEvolution ? { solid: resultSolid, faceEvolution: lastEvolution, roleTable } : { solid: resultSolid, roleTable });
+}
+/** mesh 路径：manifold-3d mesh-CSG。 */
+async function booleanMesh(inputs, operation) {
+    if (inputs.length < 2) {
+        if (inputs.length === 1)
+            return inputs[0];
+        throw new Error('[stdlib/boolean] boolean needs at least 1 input');
+    }
+    if (operation === 'union')
+        return cad.union(inputs[0], inputs[1], ...inputs.slice(2));
+    if (operation === 'subtract') {
+        let result = await cad.subtract(inputs[0], inputs[1]);
+        for (let i = 2; i < inputs.length; i++)
+            result = await cad.subtract(result, inputs[i]);
+        return result;
+    }
+    let result = await cad.intersect(inputs[0], inputs[1]);
+    for (let i = 2; i < inputs.length; i++)
+        result = await cad.intersect(result, inputs[i]);
+    return result;
+}
+// ── 三个薄导出（多输入 variadic，defineOp 声明双路径 + evolution 能力） ──
+// 函数体 keep 声明（keep-syntax 设计 §2.5）：union/subtract/intersect 保留其
+// 输入且隐藏（R5：3d_editor 现状）——keepHidden 使源变量保持终端但 canvas
+// 不渲染，只有布尔结果正常显示。混合/断链时刻：BREP 侧输入先归约为合法
+// 2-manifold 网格（reconcileBrepInputs），mesh 侧原样透传。
+/**
+ * 布尔并集：合并所有输入几何（≥2 个输入）。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name union
+ * @param shapes - 参与运算的几何（变量引用，≥2 个）。type:Shape[] required:true
+ * @returns Shape 所有输入的并集。函数名即操作，输入全是变量引用，可用 `cad.union(a, b, c)` 多输入。
+ * @example
+ * const a = await cad.union(part0, part1)
+  */
+export const union = defineOp({
+    mesh: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanMesh(reconcileBrepInputs(shapes), 'union');
+    },
+    brep: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanBrep(shapes, 'union');
+    },
+    capabilities: ['evolution'],
+    schema: { shapes: 'Shape*' },
+});
+/**
+ * 布尔差集：第一个为主体，减去其余输入。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name subtract
+ * @param shapes - 参与运算的几何（变量引用，第一个为主体）。type:Shape[] required:true
+ * @returns Shape part0 减 part1 的差集（第一个为主体）。
+ * @example
+ * const b = await cad.subtract(part0, part1)
+  */
+export const subtract = defineOp({
+    mesh: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanMesh(reconcileBrepInputs(shapes), 'subtract');
+    },
+    brep: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanBrep(shapes, 'subtract');
+    },
+    capabilities: ['evolution'],
+});
+/**
+ * 布尔交集：所有输入的重叠部分。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name intersect
+ * @param shapes - 参与运算的几何（变量引用）。type:Shape[] required:true
+ * @returns Shape 所有输入的交集。
+ * @example
+ * const c = await cad.intersect(part0, part1)
+  */
+export const intersect = defineOp({
+    mesh: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanMesh(reconcileBrepInputs(shapes), 'intersect');
+    },
+    brep: (...shapes) => {
+        if (shapes.length > 0)
+            keepHidden(...shapes);
+        return booleanBrep(shapes, 'intersect');
+    },
+    capabilities: ['evolution'],
+});
+//# sourceMappingURL=boolean.js.map