@faicad/faijs 0.13.0

package/dist/api/primitives.d.ts

@@ -0,0 +1,161 @@
+/**
+ * stdlib primitives — 基本体创建库函数（box/sphere/cylinder/cone/wedge）
+ *
+ *
+ * dispatchPath 静态判定 brep/mesh，产物经 solid()/fromBrep() 构造器创建。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * Validate box parameters (brepjs contract, §4.1 A 决策): `width`, `depth` and
+ * `height` must be positive numbers. The legacy `{ size }` object form is
+ * removed — any call still passing `size` throws an explicit `E_ARGS_FORM`
+ * error pointing at the new signature (error hint ≠ compatibility).
+ * @param params - the raw box operation parameters.
+ */
+export declare function assertBoxParams(params: Record<string, unknown>): void;
+/**
+ * Validate sphere parameters: `radius` must be a positive number.
+ * @param params - the raw sphere operation parameters.
+ */
+export declare function assertSphereParams(params: Record<string, unknown>): void;
+/**
+ * Validate cylinder parameters (brepjs contract, §4.3 A 决策): `radius` and
+ * `height` must be positive. The legacy `{ center }` object key is removed — any
+ * call still passing `center` throws an explicit `E_ARGS_FORM` error pointing at
+ * the new signature (error hint ≠ compatibility, 裁决 3).
+ * @param params - the raw cylinder operation parameters.
+ */
+export declare function assertCylinderParams(params: Record<string, unknown>): void;
+/**
+ * Validate cone parameters (brepjs contract, §4.1 P 决策): `radiusBottom` and
+ * `height` must be positive, `radiusTop` must be non-negative. The legacy
+ * `{ center }` object key is removed — any call still passing `center` throws an
+ * explicit `E_ARGS_FORM` error pointing at the new signature (error hint ≠
+ * compatibility, 裁决 3).
+ * @param params - the raw cone operation parameters.
+ */
+export declare function assertConeParams(params: Record<string, unknown>): void;
+/**
+ * Validate wedge parameters: `width`, `height`, `angle`, and `length` must be
+ * positive numbers.
+ * @param params - the raw wedge operation parameters.
+ */
+export declare function assertWedgeParams(params: Record<string, unknown>): void;
+/**
+ * 创建长方体（brepjs 契约，§4.1 A 决策）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name box
+ * @returns Shape 长方体几何，可作为后续 op 的输入。
+ * @param params.width - X 方向边长（mm）。type:number required:true
+ * @param params.depth - Y 方向边长（mm）。type:number required:true
+ * @param params.height - Z 方向边长（mm）。type:number required:true
+ * @param params.at - 中心点（CENTER 语义，优先于 centered）。type:[x,y,z] 可选
+ * @param params.centered - 无 at 时是否居中到原点（type:boolean 默认 false，角点在原点）。
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const part0 = cad.box(10, 20, 30)
+ * const part1 = cad.box(30, 20, 10, { centered: true, at: [1, 2, 3], segments: 64 })
+ *
+ * 位置原生（§4.1/§6.2）：`box(width, depth, height)` 与 `box(10, 20, 30, {centered:true})`
+ * 归一到同一对象（D11 位置→对象 + 尾参 options 合并）。旧 `{ size }` 对象形态已废弃（裁决 3），
+ * 传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.1）。
+   */
+export declare const box: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 创建球体。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name sphere
+ * @returns Shape 球体几何，可作为后续 op 的输入。
+ * @param params.radius - 半径（mm）。type:number required:true
+ * @param params.segments - 细分度（影响面数）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @param params.center - 球心位置（at 的同义别名）。type:[x,y,z] 默认 [0,0,0]（原点）。
+ * @param params.at - 球心位置（center 的同义别名，brepjs 契约；裁决 4 双形态合法）。
+ * @example
+ * const r = cad.sphere({ radius: 10 })
+ * const r = cad.sphere(10, { at: [0, 0, 10], segments: 64 })
+ * const r = cad.sphere({ radius: 10, segments: 64, center: [0,0,10] })
+ */
+export declare const sphere: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 创建圆柱体（brepjs 契约，§4.3 A 决策）。
+ * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`
+ * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name cylinder
+ * @returns Shape 圆柱体几何，可作为后续 op 的输入。
+ * @param params.radius - 底面半径（mm）。type:number required:true
+ * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true
+ * @param params.at - 底面中心（BASE 语义）。type:[x,y,z] 可选
+ * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const c = cad.cylinder(5, 40)
+ * const c = cad.cylinder(5, 40, { centered: true, at: [0, 0, 20], segments: 64 })
+ *
+ * 位置原生（§4.1/§6.2）：`cylinder(5, 40)` 与 `cylinder(5, 40, {centered:true})`
+ * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }` 对象形态已废弃
+ * （裁决 3），传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.3）。
+  */
+export declare const cylinder: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 创建圆锥体（brepjs 契约，§4.1 P 决策）。radiusTop 等于 radiusBottom 时即圆柱，0 为尖锥。
+ * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`
+ * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name cone
+ * @returns Shape 圆锥体几何，可作为后续 op 的输入。
+ * @param params.radiusBottom - 底半径（mm）。type:number required:true
+ * @param params.radiusTop - 顶半径（mm），0 为尖锥，非负，等于 radiusBottom 得圆柱。type:number required:true
+ * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true
+ * @param params.at - 底面轴心（BASE 语义）。type:[x,y,z] 可选
+ * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const c = cad.cone(10, 4, 30)
+ * const c = cad.cone(10, 0, 30, { centered: true, at: [0, 0, 20], segments: 64 })
+ * 位置原生（§4.1/§6.2）：`cone(10, 4, 30)` 与 `cone(10, 4, 30, { centered: true })`
+ * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }`/`{ size }` 对象形态
+ * 已废弃（裁决 3），传入会抛 E_ARGS_FORM（错误提示 ≠ 兼容）。
+  */
+export declare const cone: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+/**
+ * 创建楔形体。唯一契约是 width/height/angle/length（width/height/angle 为正数，length 沿切割方向），
+ * 旧文档的 size 形态已废弃，传 { size } 会抛错。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name wedge
+ * @note 曾与 UI 面板的 `size` 形态并存并写入文档，但断言层确认唯一合法契约是 width/height/angle/length；传 `{ size }` 直接抛错。已按真源收敛。
+ * @returns Shape 楔形体几何，可作为后续 op 的输入。
+ * @param params.width - 底面宽度（mm）。type:number required:true
+ * @param params.height - 高度（mm）。type:number required:true
+ * @param params.angle - 楔形角度（度）。type:number required:true
+ * @param params.length - 沿切割方向的长度（mm）。type:number required:true
+ * @example
+ * const w = cad.wedge({ width: 30, height: 20, angle: 45, length: 10 })
+  */
+export declare const wedge: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=primitives.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/api/primitives.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAe1C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS1E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKvE;AAkBD;;;;;;;;;;;;;;;;;;;;;KAqBK;AACL,eAAO,MAAM,GAAG;;CAsBd,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM;;CAcjB,CAAA;AAWF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,QAAQ;;CAcnB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;IAsBI;AACJ,eAAO,MAAM,IAAI;;CAqBf,CAAA;AAEF;;;;;;;;;;;;;;;;IAgBI;AACJ,eAAO,MAAM,KAAK;;CAYhB,CAAA"}

package/dist/api/primitives.js

@@ -0,0 +1,296 @@
+/**
+ * stdlib primitives — 基本体创建库函数（box/sphere/cylinder/cone/wedge）
+ *
+ *
+ * dispatchPath 静态判定 brep/mesh，产物经 solid()/fromBrep() 构造器创建。
+ */
+import { clampNRad } from '../mesh/types.js';
+import { cad } from '../mesh/index.js';
+import { primitiveToBrepSolid } from '../primitives/brep-primitives.js';
+import { solidToShape } from '../brep/brep-ops.js';
+import { getBackends, getCurrentStmt } from '../runtime-state.js';
+import { fromBrep } from '../shape.js';
+import { assignRoles } from '../topology/naming/roles.js';
+import { asPartName } from '../identity.js';
+import { defineOp } from '../sdk.js';
+import { assertPositiveNumber, assertNonNegativeNumber } from './assert.js';
+// ── per-op 参数自校验（Phase 2.2；stdlib 被直接 import 时的防御层） ──
+/**
+ * Validate box parameters (brepjs contract, §4.1 A 决策): `width`, `depth` and
+ * `height` must be positive numbers. The legacy `{ size }` object form is
+ * removed — any call still passing `size` throws an explicit `E_ARGS_FORM`
+ * error pointing at the new signature (error hint ≠ compatibility).
+ * @param params - the raw box operation parameters.
+ */
+export function assertBoxParams(params) {
+    if (params.size !== undefined) {
+        throw new Error('[faijs/args] box: E_ARGS_FORM: the `box({ size })` object form is removed. ' +
+            'box now uses `box(width, depth, height, { at?, centered?, segments? })`.');
+    }
+    assertPositiveNumber(params.width, 'box.width');
+    assertPositiveNumber(params.depth, 'box.depth');
+    assertPositiveNumber(params.height, 'box.height');
+}
+/**
+ * Validate sphere parameters: `radius` must be a positive number.
+ * @param params - the raw sphere operation parameters.
+ */
+export function assertSphereParams(params) {
+    assertPositiveNumber(params.radius, 'sphere.radius');
+}
+/**
+ * Validate cylinder parameters (brepjs contract, §4.3 A 决策): `radius` and
+ * `height` must be positive. The legacy `{ center }` object key is removed — any
+ * call still passing `center` throws an explicit `E_ARGS_FORM` error pointing at
+ * the new signature (error hint ≠ compatibility, 裁决 3).
+ * @param params - the raw cylinder operation parameters.
+ */
+export function assertCylinderParams(params) {
+    if (params.center !== undefined || params.size !== undefined) {
+        throw new Error('[faijs/args] cylinder: E_ARGS_FORM: the legacy object form is removed. ' +
+            'cylinder now uses `cylinder(radius, height, { at?, centered?, segments? })`.');
+    }
+    assertPositiveNumber(params.radius, 'cylinder.radius');
+    assertPositiveNumber(params.height, 'cylinder.height');
+}
+/**
+ * Validate cone parameters (brepjs contract, §4.1 P 决策): `radiusBottom` and
+ * `height` must be positive, `radiusTop` must be non-negative. The legacy
+ * `{ center }` object key is removed — any call still passing `center` throws an
+ * explicit `E_ARGS_FORM` error pointing at the new signature (error hint ≠
+ * compatibility, 裁决 3).
+ * @param params - the raw cone operation parameters.
+ */
+export function assertConeParams(params) {
+    if (params.center !== undefined || params.size !== undefined) {
+        throw new Error('[faijs/args] cone: E_ARGS_FORM: the legacy object form is removed. ' +
+            'cone now uses `cone(bottomRadius, topRadius, height, { at?, centered?, segments? })`.');
+    }
+    assertPositiveNumber(params.radiusBottom, 'cone.radiusBottom');
+    assertNonNegativeNumber(params.radiusTop, 'cone.radiusTop');
+    assertPositiveNumber(params.height, 'cone.height');
+}
+/**
+ * Validate wedge parameters: `width`, `height`, `angle`, and `length` must be
+ * positive numbers.
+ * @param params - the raw wedge operation parameters.
+ */
+export function assertWedgeParams(params) {
+    assertPositiveNumber(params.width, 'wedge.width');
+    assertPositiveNumber(params.height, 'wedge.height');
+    assertPositiveNumber(params.angle, 'wedge.angle');
+    assertPositiveNumber(params.length, 'wedge.length');
+}
+/** BREP 路径：OCCT 精确构造 + 三角化 + fromBrep 登记（基本体无面演化；链根建 roleTable）。 */
+function primitiveBrep(op, params) {
+    const kernel = getBackends().kernel.brep;
+    if (!kernel)
+        throw new Error('[stdlib/box] no OCCT kernel');
+    const type = op === 'box' ? 'cube' : op;
+    const result = primitiveToBrepSolid(kernel, type, params);
+    // §3.2：链根建表——语义命名器按 op 类型给面命名（'box'→box:top 等，其余位置名兜底）。
+    // origin 用链根 part 变量名（当前语句 LHS，§2.2），保证多个同类型 primitive 不撞 origin。
+    const origin = String(getCurrentStmt()?.outputs[0] ?? op);
+    const roles = assignRoles(kernel, result.solid, op);
+    return fromBrep(solidToShape(kernel, result.solid, clampNRad((params.nRad ?? params.segments))), { solid: result.solid, roleTable: new Map([[asPartName(origin), roles]]) });
+}
+/**
+ * 创建长方体（brepjs 契约，§4.1 A 决策）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name box
+ * @returns Shape 长方体几何，可作为后续 op 的输入。
+ * @param params.width - X 方向边长（mm）。type:number required:true
+ * @param params.depth - Y 方向边长（mm）。type:number required:true
+ * @param params.height - Z 方向边长（mm）。type:number required:true
+ * @param params.at - 中心点（CENTER 语义，优先于 centered）。type:[x,y,z] 可选
+ * @param params.centered - 无 at 时是否居中到原点（type:boolean 默认 false，角点在原点）。
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const part0 = cad.box(10, 20, 30)
+ * const part1 = cad.box(30, 20, 10, { centered: true, at: [1, 2, 3], segments: 64 })
+ *
+ * 位置原生（§4.1/§6.2）：`box(width, depth, height)` 与 `box(10, 20, 30, {centered:true})`
+ * 归一到同一对象（D11 位置→对象 + 尾参 options 合并）。旧 `{ size }` 对象形态已废弃（裁决 3），
+ * 传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.1）。
+   */
+export const box = defineOp({
+    name: 'box',
+    mesh: (params) => {
+        assertBoxParams(params);
+        return cad.box(params);
+    },
+    brep: (params) => {
+        assertBoxParams(params);
+        return primitiveBrep('box', params);
+    },
+    // schema feeds codegen/UI parameter panels.
+    schema: {
+        width: 'number',
+        depth: 'number',
+        height: 'number',
+        at: 'vec3?',
+        centered: 'boolean?',
+        segments: 'number?',
+    },
+    // D11 位置→对象（§4.1/§6.2）：三个标量装箱成 { width, depth, height }，尾参
+    // options 经 dual-form-args 的尾参合并（§6.2）并入。
+    slotMap: { keys: ['width', 'depth', 'height'] },
+});
+/**
+ * 创建球体。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name sphere
+ * @returns Shape 球体几何，可作为后续 op 的输入。
+ * @param params.radius - 半径（mm）。type:number required:true
+ * @param params.segments - 细分度（影响面数）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @param params.center - 球心位置（at 的同义别名）。type:[x,y,z] 默认 [0,0,0]（原点）。
+ * @param params.at - 球心位置（center 的同义别名，brepjs 契约；裁决 4 双形态合法）。
+ * @example
+ * const r = cad.sphere({ radius: 10 })
+ * const r = cad.sphere(10, { at: [0, 0, 10], segments: 64 })
+ * const r = cad.sphere({ radius: 10, segments: 64, center: [0,0,10] })
+ */
+export const sphere = defineOp({
+    name: 'sphere',
+    mesh: (params) => {
+        assertSphereParams(params);
+        return cad.sphere(centerParams(params));
+    },
+    brep: (params) => {
+        assertSphereParams(params);
+        return primitiveBrep('sphere', centerParams(params));
+    },
+    schema: { radius: 'number', segments: 'number?', center: 'vec3?', at: 'vec3?' },
+    // D11: `sphere(10)` == `sphere({ radius: 10 })`; 尾参 options（{at, segments}）
+    // 经 dual-form-args 的尾参合并规则归一（裁决 4，§6.2）。
+    slotMap: { keys: ['radius'] },
+});
+/**
+ * 位置归一：把 brepjs 契约的 `at`（= faijs 的 `center`，球心语义）归一为一个
+ * `center` 输入，mesh/brep 两条消费路径共用（裁决 1/4，§4.2）。
+ */
+function centerParams(params) {
+    if (params.at !== undefined)
+        return { ...params, center: params.at };
+    return params;
+}
+/**
+ * 创建圆柱体（brepjs 契约，§4.3 A 决策）。
+ * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`
+ * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name cylinder
+ * @returns Shape 圆柱体几何，可作为后续 op 的输入。
+ * @param params.radius - 底面半径（mm）。type:number required:true
+ * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true
+ * @param params.at - 底面中心（BASE 语义）。type:[x,y,z] 可选
+ * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const c = cad.cylinder(5, 40)
+ * const c = cad.cylinder(5, 40, { centered: true, at: [0, 0, 20], segments: 64 })
+ *
+ * 位置原生（§4.1/§6.2）：`cylinder(5, 40)` 与 `cylinder(5, 40, {centered:true})`
+ * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }` 对象形态已废弃
+ * （裁决 3），传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.3）。
+  */
+export const cylinder = defineOp({
+    name: 'cylinder',
+    mesh: (params) => {
+        assertCylinderParams(params);
+        return cad.cylinder(params);
+    },
+    brep: (params) => {
+        assertCylinderParams(params);
+        return primitiveBrep('cylinder', params);
+    },
+    schema: { radius: 'number', height: 'number', at: 'vec3?', centered: 'boolean?', segments: 'number?' },
+    // D11（§4.1/§6.2）：`cylinder(5, 40)` 两个标量装箱成 { radius, height }；尾参 options
+    // 经 dual-form-args 尾参合并并入。
+    slotMap: { keys: ['radius', 'height'] },
+});
+/**
+ * 创建圆锥体（brepjs 契约，§4.1 P 决策）。radiusTop 等于 radiusBottom 时即圆柱，0 为尖锥。
+ * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`
+ * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name cone
+ * @returns Shape 圆锥体几何，可作为后续 op 的输入。
+ * @param params.radiusBottom - 底半径（mm）。type:number required:true
+ * @param params.radiusTop - 顶半径（mm），0 为尖锥，非负，等于 radiusBottom 得圆柱。type:number required:true
+ * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true
+ * @param params.at - 底面轴心（BASE 语义）。type:[x,y,z] 可选
+ * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false
+ * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）
+ * @example
+ * const c = cad.cone(10, 4, 30)
+ * const c = cad.cone(10, 0, 30, { centered: true, at: [0, 0, 20], segments: 64 })
+ * 位置原生（§4.1/§6.2）：`cone(10, 4, 30)` 与 `cone(10, 4, 30, { centered: true })`
+ * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }`/`{ size }` 对象形态
+ * 已废弃（裁决 3），传入会抛 E_ARGS_FORM（错误提示 ≠ 兼容）。
+  */
+export const cone = defineOp({
+    name: 'cone',
+    mesh: (params) => {
+        assertConeParams(params);
+        return cad.cone(params);
+    },
+    brep: (params) => {
+        assertConeParams(params);
+        return primitiveBrep('cone', params);
+    },
+    schema: {
+        radiusBottom: 'number',
+        radiusTop: 'number',
+        height: 'number',
+        at: 'vec3?',
+        centered: 'boolean?',
+        segments: 'number?',
+    },
+    // D11（§4.1/§6.2）: `cone(10, 4, 30)` 三个标量装箱成 { radiusBottom, radiusTop, height }。
+    // 尾参 options（{at, centered, segments}）经 dual-form-args 尾参合并并入。
+    slotMap: { keys: ['radiusBottom', 'radiusTop', 'height'] },
+});
+/**
+ * 创建楔形体。唯一契约是 width/height/angle/length（width/height/angle 为正数，length 沿切割方向），
+ * 旧文档的 size 形态已废弃，传 { size } 会抛错。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name wedge
+ * @note 曾与 UI 面板的 `size` 形态并存并写入文档，但断言层确认唯一合法契约是 width/height/angle/length；传 `{ size }` 直接抛错。已按真源收敛。
+ * @returns Shape 楔形体几何，可作为后续 op 的输入。
+ * @param params.width - 底面宽度（mm）。type:number required:true
+ * @param params.height - 高度（mm）。type:number required:true
+ * @param params.angle - 楔形角度（度）。type:number required:true
+ * @param params.length - 沿切割方向的长度（mm）。type:number required:true
+ * @example
+ * const w = cad.wedge({ width: 30, height: 20, angle: 45, length: 10 })
+  */
+export const wedge = defineOp({
+    name: 'wedge',
+    mesh: (params) => {
+        assertWedgeParams(params);
+        return cad.wedge(params);
+    },
+    brep: (params) => {
+        assertWedgeParams(params);
+        return primitiveBrep('wedge', params);
+    },
+    // D11: `wedge(30, 20, 45, 10)` == `wedge({ width: 30, height: 20, angle: 45, length: 10 })`.
+    slotMap: { keys: ['width', 'height', 'angle', 'length'] },
+});
+//# sourceMappingURL=primitives.js.map

package/dist/api/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/api/primitives.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib primitives — 基本体创建库函数（box/sphere/cylinder/cone/wedge）\n *\n *\n * dispatchPath 静态判定 brep/mesh，产物经 solid()/fromBrep() 构造器创建。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { clampNRad } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { primitiveToBrepSolid } from '../primitives/brep-primitives'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBackends, getCurrentStmt } from '../runtime-state'\nimport { fromBrep } from '../shape'\nimport { assignRoles } from '../topology/naming/roles'\nimport { asPartName } from '../identity'\nimport { defineOp } from '../sdk'\nimport { assertPositiveNumber, assertNonNegativeNumber } from './assert'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n// ── per-op 参数自校验（Phase 2.2；stdlib 被直接 import 时的防御层） ──\n\n/**\n * Validate box parameters (brepjs contract, §4.1 A 决策): `width`, `depth` and\n * `height` must be positive numbers. The legacy `{ size }` object form is\n * removed — any call still passing `size` throws an explicit `E_ARGS_FORM`\n * error pointing at the new signature (error hint ≠ compatibility).\n * @param params - the raw box operation parameters.\n */\nexport function assertBoxParams(params: Record<string, unknown>): void {\n  if (params.size !== undefined) {\n    throw new Error(\n      '[faijs/args] box: E_ARGS_FORM: the `box({ size })` object form is removed. ' +\n      'box now uses `box(width, depth, height, { at?, centered?, segments? })`.',\n    )\n  }\n  assertPositiveNumber(params.width, 'box.width')\n  assertPositiveNumber(params.depth, 'box.depth')\n  assertPositiveNumber(params.height, 'box.height')\n}\n\n/**\n * Validate sphere parameters: `radius` must be a positive number.\n * @param params - the raw sphere operation parameters.\n */\nexport function assertSphereParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.radius, 'sphere.radius')\n}\n\n/**\n * Validate cylinder parameters (brepjs contract, §4.3 A 决策): `radius` and\n * `height` must be positive. The legacy `{ center }` object key is removed — any\n * call still passing `center` throws an explicit `E_ARGS_FORM` error pointing at\n * the new signature (error hint ≠ compatibility, 裁决 3).\n * @param params - the raw cylinder operation parameters.\n */\nexport function assertCylinderParams(params: Record<string, unknown>): void {\n  if (params.center !== undefined || params.size !== undefined) {\n    throw new Error(\n      '[faijs/args] cylinder: E_ARGS_FORM: the legacy object form is removed. ' +\n      'cylinder now uses `cylinder(radius, height, { at?, centered?, segments? })`.',\n    )\n  }\n  assertPositiveNumber(params.radius, 'cylinder.radius')\n  assertPositiveNumber(params.height, 'cylinder.height')\n}\n\n/**\n * Validate cone parameters (brepjs contract, §4.1 P 决策): `radiusBottom` and\n * `height` must be positive, `radiusTop` must be non-negative. The legacy\n * `{ center }` object key is removed — any call still passing `center` throws an\n * explicit `E_ARGS_FORM` error pointing at the new signature (error hint ≠\n * compatibility, 裁决 3).\n * @param params - the raw cone operation parameters.\n */\nexport function assertConeParams(params: Record<string, unknown>): void {\n  if (params.center !== undefined || params.size !== undefined) {\n    throw new Error(\n      '[faijs/args] cone: E_ARGS_FORM: the legacy object form is removed. ' +\n      'cone now uses `cone(bottomRadius, topRadius, height, { at?, centered?, segments? })`.',\n    )\n  }\n  assertPositiveNumber(params.radiusBottom, 'cone.radiusBottom')\n  assertNonNegativeNumber(params.radiusTop, 'cone.radiusTop')\n  assertPositiveNumber(params.height, 'cone.height')\n}\n\n/**\n * Validate wedge parameters: `width`, `height`, `angle`, and `length` must be\n * positive numbers.\n * @param params - the raw wedge operation parameters.\n */\nexport function assertWedgeParams(params: Record<string, unknown>): void {\n  assertPositiveNumber(params.width, 'wedge.width')\n  assertPositiveNumber(params.height, 'wedge.height')\n  assertPositiveNumber(params.angle, 'wedge.angle')\n  assertPositiveNumber(params.length, 'wedge.length')\n}\n\n/** BREP 路径：OCCT 精确构造 + 三角化 + fromBrep 登记（基本体无面演化；链根建 roleTable）。 */\nfunction primitiveBrep(op: string, params: Record<string, unknown>): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/box] no OCCT kernel')\n  const type = op === 'box' ? 'cube' : op\n  const result = primitiveToBrepSolid(kernel, type as 'cube' | 'sphere' | 'cylinder' | 'cone' | 'wedge', params as never)\n  // §3.2：链根建表——语义命名器按 op 类型给面命名（'box'→box:top 等，其余位置名兜底）。\n  // origin 用链根 part 变量名（当前语句 LHS，§2.2），保证多个同类型 primitive 不撞 origin。\n  const origin = String(getCurrentStmt()?.outputs[0] ?? op)\n  const roles = assignRoles(kernel, result.solid, op)\n  return fromBrep(\n    solidToShape(kernel, result.solid, clampNRad((params.nRad ?? params.segments) as number)),\n    { solid: result.solid, roleTable: new Map([[asPartName(origin), roles]]) },\n  )\n}\n\n/**\n * 创建长方体（brepjs 契约，§4.1 A 决策）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name box\n * @returns Shape 长方体几何，可作为后续 op 的输入。\n * @param params.width - X 方向边长（mm）。type:number required:true\n * @param params.depth - Y 方向边长（mm）。type:number required:true\n * @param params.height - Z 方向边长（mm）。type:number required:true\n * @param params.at - 中心点（CENTER 语义，优先于 centered）。type:[x,y,z] 可选\n * @param params.centered - 无 at 时是否居中到原点（type:boolean 默认 false，角点在原点）。\n * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）\n * @example\n * const part0 = cad.box(10, 20, 30)\n * const part1 = cad.box(30, 20, 10, { centered: true, at: [1, 2, 3], segments: 64 })\n *\n * 位置原生（§4.1/§6.2）：`box(width, depth, height)` 与 `box(10, 20, 30, {centered:true})`\n * 归一到同一对象（D11 位置→对象 + 尾参 options 合并）。旧 `{ size }` 对象形态已废弃（裁决 3），\n * 传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.1）。\n   */\nexport const box = defineOp({\n  name: 'box',\n  mesh: (params: Record<string, unknown>) => {\n    assertBoxParams(params)\n    return cad.box(params as never)\n  },\n  brep: (params: Record<string, unknown>) => {\n    assertBoxParams(params)\n    return primitiveBrep('box', params)\n  },\n  // schema feeds codegen/UI parameter panels.\n  schema: {\n    width: 'number',\n    depth: 'number',\n    height: 'number',\n    at: 'vec3?',\n    centered: 'boolean?',\n    segments: 'number?',\n  },\n  // D11 位置→对象（§4.1/§6.2）：三个标量装箱成 { width, depth, height }，尾参\n  // options 经 dual-form-args 的尾参合并（§6.2）并入。\n  slotMap: { keys: ['width', 'depth', 'height'] },\n})\n\n/**\n * 创建球体。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sphere\n * @returns Shape 球体几何，可作为后续 op 的输入。\n * @param params.radius - 半径（mm）。type:number required:true\n * @param params.segments - 细分度（影响面数）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）\n * @param params.center - 球心位置（at 的同义别名）。type:[x,y,z] 默认 [0,0,0]（原点）。\n * @param params.at - 球心位置（center 的同义别名，brepjs 契约；裁决 4 双形态合法）。\n * @example\n * const r = cad.sphere({ radius: 10 })\n * const r = cad.sphere(10, { at: [0, 0, 10], segments: 64 })\n * const r = cad.sphere({ radius: 10, segments: 64, center: [0,0,10] })\n */\nexport const sphere = defineOp({\n  name: 'sphere',\n  mesh: (params: Record<string, unknown>) => {\n    assertSphereParams(params)\n    return cad.sphere(centerParams(params) as never)\n  },\n  brep: (params: Record<string, unknown>) => {\n    assertSphereParams(params)\n    return primitiveBrep('sphere', centerParams(params))\n  },\n  schema: { radius: 'number', segments: 'number?', center: 'vec3?', at: 'vec3?' },\n  // D11: `sphere(10)` == `sphere({ radius: 10 })`; 尾参 options（{at, segments}）\n  // 经 dual-form-args 的尾参合并规则归一（裁决 4，§6.2）。\n  slotMap: { keys: ['radius'] },\n})\n\n/**\n * 位置归一：把 brepjs 契约的 `at`（= faijs 的 `center`，球心语义）归一为一个\n * `center` 输入，mesh/brep 两条消费路径共用（裁决 1/4，§4.2）。\n */\nfunction centerParams(params: Record<string, unknown>): Record<string, unknown> {\n  if (params.at !== undefined) return { ...params, center: params.at }\n  return params\n}\n\n/**\n * 创建圆柱体（brepjs 契约，§4.3 A 决策）。\n * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`\n * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name cylinder\n * @returns Shape 圆柱体几何，可作为后续 op 的输入。\n * @param params.radius - 底面半径（mm）。type:number required:true\n * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true\n * @param params.at - 底面中心（BASE 语义）。type:[x,y,z] 可选\n * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false\n * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）\n * @example\n * const c = cad.cylinder(5, 40)\n * const c = cad.cylinder(5, 40, { centered: true, at: [0, 0, 20], segments: 64 })\n *\n * 位置原生（§4.1/§6.2）：`cylinder(5, 40)` 与 `cylinder(5, 40, {centered:true})`\n * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }` 对象形态已废弃\n * （裁决 3），传入会抛 `E_ARGS_FORM`（错误提示 ≠ 兼容，§4.3）。\n  */\nexport const cylinder = defineOp({\n  name: 'cylinder',\n  mesh: (params: Record<string, unknown>) => {\n    assertCylinderParams(params)\n    return cad.cylinder(params as never)\n  },\n  brep: (params: Record<string, unknown>) => {\n    assertCylinderParams(params)\n    return primitiveBrep('cylinder', params)\n  },\n  schema: { radius: 'number', height: 'number', at: 'vec3?', centered: 'boolean?', segments: 'number?' },\n  // D11（§4.1/§6.2）：`cylinder(5, 40)` 两个标量装箱成 { radius, height }；尾参 options\n  // 经 dual-form-args 尾参合并并入。\n  slotMap: { keys: ['radius', 'height'] },\n})\n\n/**\n * 创建圆锥体（brepjs 契约，§4.1 P 决策）。radiusTop 等于 radiusBottom 时即圆柱，0 为尖锥。\n * 锚点：`at` 是**底面轴心**（BASE 语义，默认 [0,0,0]，底面在原点、+Z 延伸）；`centered:true`\n * 指底面落到 −h/2（无 at 时居中到原点；与 `at` 同给时以 `at` 为中心）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name cone\n * @returns Shape 圆锥体几何，可作为后续 op 的输入。\n * @param params.radiusBottom - 底半径（mm）。type:number required:true\n * @param params.radiusTop - 顶半径（mm），0 为尖锥，非负，等于 radiusBottom 得圆柱。type:number required:true\n * @param params.height - 高度（mm），沿 +Z 轴。type:number required:true\n * @param params.at - 底面轴心（BASE 语义）。type:[x,y,z] 可选\n * @param params.centered - 是否居中（底面 −h/2；与 at 同给时以 at 为中心）。type:boolean 默认 false\n * @param params.segments - 细分度（影响三角化）。type:number 默认 64（= brepjs standard 等效，P0 §5.0/§5.1）\n * @example\n * const c = cad.cone(10, 4, 30)\n * const c = cad.cone(10, 0, 30, { centered: true, at: [0, 0, 20], segments: 64 })\n * 位置原生（§4.1/§6.2）：`cone(10, 4, 30)` 与 `cone(10, 4, 30, { centered: true })`\n * 归一到同一对象（D11 位置→装箱 + 尾参 options 合并）。旧 `{ center }`/`{ size }` 对象形态\n * 已废弃（裁决 3），传入会抛 E_ARGS_FORM（错误提示 ≠ 兼容）。\n  */\nexport const cone = defineOp({\n  name: 'cone',\n  mesh: (params: Record<string, unknown>) => {\n    assertConeParams(params)\n    return cad.cone(params as never)\n  },\n  brep: (params: Record<string, unknown>) => {\n    assertConeParams(params)\n    return primitiveBrep('cone', params)\n  },\n  schema: {\n    radiusBottom: 'number',\n    radiusTop: 'number',\n    height: 'number',\n    at: 'vec3?',\n    centered: 'boolean?',\n    segments: 'number?',\n  },\n  // D11（§4.1/§6.2）: `cone(10, 4, 30)` 三个标量装箱成 { radiusBottom, radiusTop, height }。\n  // 尾参 options（{at, centered, segments}）经 dual-form-args 尾参合并并入。\n  slotMap: { keys: ['radiusBottom', 'radiusTop', 'height'] },\n})\n\n/**\n * 创建楔形体。唯一契约是 width/height/angle/length（width/height/angle 为正数，length 沿切割方向），\n * 旧文档的 size 形态已废弃，传 { size } 会抛错。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name wedge\n * @note 曾与 UI 面板的 `size` 形态并存并写入文档，但断言层确认唯一合法契约是 width/height/angle/length；传 `{ size }` 直接抛错。已按真源收敛。\n * @returns Shape 楔形体几何，可作为后续 op 的输入。\n * @param params.width - 底面宽度（mm）。type:number required:true\n * @param params.height - 高度（mm）。type:number required:true\n * @param params.angle - 楔形角度（度）。type:number required:true\n * @param params.length - 沿切割方向的长度（mm）。type:number required:true\n * @example\n * const w = cad.wedge({ width: 30, height: 20, angle: 45, length: 10 })\n  */\nexport const wedge = defineOp({\n  name: 'wedge',\n  mesh: (params: Record<string, unknown>) => {\n    assertWedgeParams(params)\n    return cad.wedge(params as never)\n  },\n  brep: (params: Record<string, unknown>) => {\n    assertWedgeParams(params)\n    return primitiveBrep('wedge', params)\n  },\n  // D11: `wedge(30, 20, 45, 10)` == `wedge({ width: 30, height: 20, angle: 45, length: 10 })`.\n  slotMap: { keys: ['width', 'height', 'angle', 'length'] },\n})\n"]}

package/dist/api/reconcile.d.ts

@@ -0,0 +1,28 @@
+/**
+ * stdlib reconcile — 断链/混合时刻定向归约（P0-1b）
+ *
+ *
+ * 用户纠正（2026-08-29）：brep→mesh 的归约不只在"mesh 与 brep 做布尔"的时刻发生，
+ * 而是**任何 BREP 断链时刻**——BREP 输入进入 mesh-only 路径（如 knurl 滚花）即断链，
+ * 必须先转 mesh。本文件提供各 mesh 路径入口共用的定向归约：
+ *
+ * - 触发：本次 op 的输入中既有 `hasBrep(s) === true`、又有 `false`（混合），
+ *   或 mesh-only op 收到 BREP 输入（断链）。
+ * - 处理对象：**只对 BREP 侧输入**（`brepOf(s)` 有句柄者）做归约（reconcileMesh），
+ *   把 OCCT 逐面三角汤归约为合法 2-manifold 网格；mesh 侧输入**原样透传**。
+ * - 非混合场景零变化：全 BREP → 走精确布尔，不碰归约；全 mesh → 原样透传。
+ *   ⇒ 满足用户"不应该改变现有行为"的硬约束。
+ *
+ * 与红线不冲突：归约发生在 dispatchPath 静态判定为 'mesh' **之后**，是输入数据规整，
+ * 不是运行时 try-catch 回退。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * 混合/断链时刻定向归约：仅对 BREP 侧输入做归约，mesh 侧原样透传。
+ * 无 BREP 输入时返回原数组引用（零开销、零行为变化）。
+ * @param inputs - the input shapes to reconcile.
+ * @returns the input array as-is when no BREP input is present, otherwise a
+ *   new array with BREP-side inputs converted to valid 2-manifold meshes.
+ */
+export declare function reconcileBrepInputs(inputs: Shape[]): Shape[];
+//# sourceMappingURL=reconcile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/api/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAI1C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAe5D"}

package/dist/api/reconcile.js

@@ -0,0 +1,45 @@
+/**
+ * stdlib reconcile — 断链/混合时刻定向归约（P0-1b）
+ *
+ *
+ * 用户纠正（2026-08-29）：brep→mesh 的归约不只在"mesh 与 brep 做布尔"的时刻发生，
+ * 而是**任何 BREP 断链时刻**——BREP 输入进入 mesh-only 路径（如 knurl 滚花）即断链，
+ * 必须先转 mesh。本文件提供各 mesh 路径入口共用的定向归约：
+ *
+ * - 触发：本次 op 的输入中既有 `hasBrep(s) === true`、又有 `false`（混合），
+ *   或 mesh-only op 收到 BREP 输入（断链）。
+ * - 处理对象：**只对 BREP 侧输入**（`brepOf(s)` 有句柄者）做归约（reconcileMesh），
+ *   把 OCCT 逐面三角汤归约为合法 2-manifold 网格；mesh 侧输入**原样透传**。
+ * - 非混合场景零变化：全 BREP → 走精确布尔，不碰归约；全 mesh → 原样透传。
+ *   ⇒ 满足用户"不应该改变现有行为"的硬约束。
+ *
+ * 与红线不冲突：归约发生在 dispatchPath 静态判定为 'mesh' **之后**，是输入数据规整，
+ * 不是运行时 try-catch 回退。
+ */
+import { reconcileMesh } from '../mesh/reconcile.js';
+import { hasBrep } from '../shape.js';
+/**
+ * 混合/断链时刻定向归约：仅对 BREP 侧输入做归约，mesh 侧原样透传。
+ * 无 BREP 输入时返回原数组引用（零开销、零行为变化）。
+ * @param inputs - the input shapes to reconcile.
+ * @returns the input array as-is when no BREP input is present, otherwise a
+ *   new array with BREP-side inputs converted to valid 2-manifold meshes.
+ */
+export function reconcileBrepInputs(inputs) {
+    let hasBrepSide = false;
+    for (const s of inputs) {
+        if (hasBrep(s)) {
+            hasBrepSide = true;
+            break;
+        }
+    }
+    if (!hasBrepSide)
+        return inputs;
+    return inputs.map((s) => {
+        if (!hasBrep(s))
+            return s;
+        const r = reconcileMesh(s.positions, s.indices);
+        return { positions: r.positions, indices: r.indices };
+    });
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/api/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../src/api/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,IAAI,WAAW,GAAG,KAAK,CAAA;IACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACf,WAAW,GAAG,IAAI,CAAA;YAClB,MAAK;QACP,CAAC;IACH,CAAC;IACD,IAAI,CAAC,WAAW;QAAE,OAAO,MAAM,CAAA;IAE/B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAA;QACzB,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAA;QAC/C,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAA;IACvD,CAAC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * stdlib reconcile — 断链/混合时刻定向归约（P0-1b）\n *\n *\n * 用户纠正（2026-08-29）：brep→mesh 的归约不只在\"mesh 与 brep 做布尔\"的时刻发生，\n * 而是**任何 BREP 断链时刻**——BREP 输入进入 mesh-only 路径（如 knurl 滚花）即断链，\n * 必须先转 mesh。本文件提供各 mesh 路径入口共用的定向归约：\n *\n * - 触发：本次 op 的输入中既有 `hasBrep(s) === true`、又有 `false`（混合），\n *   或 mesh-only op 收到 BREP 输入（断链）。\n * - 处理对象：**只对 BREP 侧输入**（`brepOf(s)` 有句柄者）做归约（reconcileMesh），\n *   把 OCCT 逐面三角汤归约为合法 2-manifold 网格；mesh 侧输入**原样透传**。\n * - 非混合场景零变化：全 BREP → 走精确布尔，不碰归约；全 mesh → 原样透传。\n *   ⇒ 满足用户\"不应该改变现有行为\"的硬约束。\n *\n * 与红线不冲突：归约发生在 dispatchPath 静态判定为 'mesh' **之后**，是输入数据规整，\n * 不是运行时 try-catch 回退。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { reconcileMesh } from '../mesh/reconcile'\nimport { hasBrep } from '../shape'\n\n/**\n * 混合/断链时刻定向归约：仅对 BREP 侧输入做归约，mesh 侧原样透传。\n * 无 BREP 输入时返回原数组引用（零开销、零行为变化）。\n * @param inputs - the input shapes to reconcile.\n * @returns the input array as-is when no BREP input is present, otherwise a\n *   new array with BREP-side inputs converted to valid 2-manifold meshes.\n */\nexport function reconcileBrepInputs(inputs: Shape[]): Shape[] {\n  let hasBrepSide = false\n  for (const s of inputs) {\n    if (hasBrep(s)) {\n      hasBrepSide = true\n      break\n    }\n  }\n  if (!hasBrepSide) return inputs\n\n  return inputs.map((s) => {\n    if (!hasBrep(s)) return s\n    const r = reconcileMesh(s.positions, s.indices)\n    return { positions: r.positions, indices: r.indices }\n  })\n}\n"]}

package/dist/api/result.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Platform Result face (L3 bridge) — the only legal way for non-`api/` core
+ * code to reach the vendored `Result` implementation.
+ *
+ * D8 (docs/plans/2026-09-01-layered-api-architecture.md) forbids importing the
+ * vendored tree from anywhere outside `src/api/`, while `src/fcstd/*` needs
+ * `ok` / `err` / `isOk` / `Result`. Routing that need through this projection
+ * keeps the bridge explicit instead of reaching into
+ * `../vendored/brepjs/core/result.js` directly.
+ *
+ * Projection only — no reimplementation: the vendored module stays the single
+ * source of truth for the Result semantics shared with the compat face.
+ */
+export * from '../vendored/brepjs/core/result.js';
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/api/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,mCAAmC,CAAA"}

package/dist/api/result.js

@@ -0,0 +1,15 @@
+/**
+ * Platform Result face (L3 bridge) — the only legal way for non-`api/` core
+ * code to reach the vendored `Result` implementation.
+ *
+ * D8 (docs/plans/2026-09-01-layered-api-architecture.md) forbids importing the
+ * vendored tree from anywhere outside `src/api/`, while `src/fcstd/*` needs
+ * `ok` / `err` / `isOk` / `Result`. Routing that need through this projection
+ * keeps the bridge explicit instead of reaching into
+ * `../vendored/brepjs/core/result.js` directly.
+ *
+ * Projection only — no reimplementation: the vendored module stays the single
+ * source of truth for the Result semantics shared with the compat face.
+ */
+export * from '../vendored/brepjs/core/result.js';
+//# sourceMappingURL=result.js.map

package/dist/api/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/api/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,mCAAmC,CAAA","sourcesContent":["/**\n * Platform Result face (L3 bridge) — the only legal way for non-`api/` core\n * code to reach the vendored `Result` implementation.\n *\n * D8 (docs/plans/2026-09-01-layered-api-architecture.md) forbids importing the\n * vendored tree from anywhere outside `src/api/`, while `src/fcstd/*` needs\n * `ok` / `err` / `isOk` / `Result`. Routing that need through this projection\n * keeps the bridge explicit instead of reaching into\n * `../vendored/brepjs/core/result.js` directly.\n *\n * Projection only — no reimplementation: the vendored module stays the single\n * source of truth for the Result semantics shared with the compat face.\n */\nexport * from '../vendored/brepjs/core/result.js'\n"]}