@faicad/faijs 0.14.1 → 0.16.0

package/dist/api/compound.js

@@ -1,164 +0,0 @@
-/**
- * stdlib compound — group/assembly 库函数（compound Shape + AssemblyBehavior）
- *
- *
- * 从 src/ops/assemble.ts 迁出并改写为 stdlib 形态：
- * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）
- * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）
- * - 装配求解（P1 起）委派 api/assembly/（brepjs solverAdapter 内核）：
- *   do_assemble/solve 触发求解 → 引擎应用
- *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
- *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。
- *
- * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。
- * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，
- * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
- */
-import { compound as makeCompound, ensureSlot } from '../shape.js';
-import { keep, nameOf, setPendingAssemblyTransforms, setPendingAssemblyKinematics } from '../runtime-state.js';
-import { solveAssemblyAndKinematics } from './assembly/solve.js';
-import { validateConstraints } from './assembly/validate.js';
-import { buildKinematicTree } from './assembly/joints.js';
-// ── 求解器 ──
-// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走
-// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。
-// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：
-// 引擎不得 import stdlib/compound；公共 API 经本 re-export 保持）。
-export { applyTransform } from '../mesh/rigid-transform.js';
-/**
- * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。
- * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。
- *
- * 约束形态（方案 §5）：
- * - 遗留 face_mate：规范化为 mate 后降级为 brepjs concentric + 轴编码求解（§3.7.2）；
- * - 新形态 mate/align/coincident/concentric/distance/angle/parallel/perpendicular/fixed；
- * - 面参数 `{ topoRef }` 执行期解析（BREP 现场/mesh 行快照），旧 `{ center, normal }`
- *   快照直接使用（兼容已持久化的历史脚本）；
- * - 输出为 per-member 终态（L6 修复），锚定成员不输出变换。
- */
-function solveTransforms(members, behavior) {
-    return solveAssemblyAndKinematics(members, behavior.memberNames, behavior.constraints, behavior.joints ?? [], behavior.drive, { solver: behavior.solver, name: behavior.name }).transforms;
-}
-// ── group / assembly 库函数 ──
-/**
- * 成员名推导：显式 memberNames 兼容旧手工构造 IR；否则经 keep() 反查
- * （P3 起经 keep()/nameOfShapes 反查成员名——库不再访问执行上下文，F1）。
- */
-function memberNamesOf(params, members) {
-    if (Array.isArray(params.memberNames) && params.memberNames.length > 0) {
-        return params.memberNames;
-    }
-    return members.map((m) => {
-        // 兼容字符串形态的 members（历史 IR 直传 partName）：字符串本身就是名字
-        if (typeof m === 'string')
-            return m;
-        return String(nameOf(m) ?? '');
-    });
-}
-/**
- * `cad.group({ name, members })` → compound Shape。
- * members 是成员 Shape（编译产物 ctx.<var> 引用），成员名经 keep() 反查。
- *
- * 函数体 keep 声明（keep-syntax 设计 §2.5）：group 保留其成员且可见（R6）。
- */
-/**
- * 分组：零约束，保持当前布局。结构语句，无几何输出，成员用变量名引用。
- * @group 结构
- * @inputs 1
- * @async false
- * @qual ok
- * @name group
- * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（无几何输出，服务于编辑器画布与时间线），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。**平台侧需要几何复合体请用 `cad.compound`**（内核 `makeCompound`，持 OCCT 句柄，可变换/可导出）。
- * @returns CompoundShape 复合几何（kind='compound'，children 为成员 Shape 引用）。
- * @param params.name - 组名。type:string
- * @param params.members - 成员（编译产物 ctx.<var> 引用；结构语句里是裸变量引用，非字符串数组）。type:Shape[]
- * @note members 在 .fai.js 里是裸变量引用（编译为 ctx.<var>），字符串数组形态的成员名经 keep() 反查兼容历史 IR。
- * @example
- * const part0 = cad.box(30, 20, 10, { centered: true })
- * cad.group({ name: '底板组', members: [part0] })
-  */
-export function group(params) {
-    const members = params.members ?? [];
-    if (members.length > 0)
-        keep(...members);
-    const memberNames = memberNamesOf(params, members);
-    const c = makeCompound(members);
-    // 挂最小 behavior（memberNames 供 ExecutionResult.compounds 结构输出；group 无约束）
-    ensureSlot(c).behavior = {
-        memberNames,
-        constraints: [],
-        joints: [],
-        solve: () => [],
-        solveDetailed: () => ({ transforms: [], dof: 0, converged: true, unsupported: [] }),
-    };
-    return c;
-}
-/**
- * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。
- * 求解内核复用 vendored brepjs solverAdapter.solveConstraints（链式拓扑调度 / DOF / converged /
- * unsupported 诊断）；输出为 per-member 终态变换（每成员一条，恒等位姿不输出）。
- * @group 结构
- * @inputs 1
- * @async false
- * @qual warn
- * @name assembly
- * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（成员以编辑器结构语句形态声明，服务于画布与时间线），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。
- * @returns CompoundShape + AssemblyBehavior（含 do_assemble / solve 方法）。
- * @note 约束类型（a=参考、b=从动，移动 b 去贴合 a）：`mate` 面对面贴合（法向反向+面中心重合，遗留 face_mate 的新名，求解降级为 concentric + 轴编码）；`align` 同向对齐（法向同向+面中心重合）；`coincident` 共面/共点/共线（保留面内 2 个平移 DOF）；`concentric` 轴重合（孔轴配合，圆柱/圆锥面需 hint.axis，直边/圆边需 EdgeHint.axis）；`distance` 定距（mm，带 value）；`angle` 夹角（deg，带 value）；`parallel`/`perpendicular` 平行/垂直（angle 0°/90° 语法糖）；`fixed` 锚定部件（地基）；`face_mate` 为遗留别名（规范化为 mate，新代码不再使用）。
- * @note EntityRef 四种形态：`{ part, face: { topoRef } | { surfaceType?, center, normal } }`、`{ part, edge: { topoRef } | { axis: { origin, direction } } }`、`{ part, point: [x,y,z] }`、`{ part, faceIndex }`（1 起，仅调试简写）。
- * @note 不收敛（实体类型不匹配/环/参考不可达）→ 抛错并带 unsupported 明细；成员名为空串 → 求解前抛错；mesh 快照缺 axis 的圆柱/圆锥面作轴实体 → E_TOPO_NOT_FOUND（绝不静默降级）。`mate`（中心重合）与 `coincident`（只共面）是两种不同语义，不互相映射。
- * @note 早期文档/示例曾用 `fixedPartId`/`movingPartId`/`faceRowIndex`/`faceId`/`invalid`——这些键在代码中不存在。真实契约是 `fixedPartName`/`movingPartName` + `fixedFace`/`movingFace`（遗留 face_mate）。`faceId` 字段随 §6.2 移除，不再写入。
- * @param params.name - 装配名。type:string
- * @param params.members - 成员（裸变量引用）。type:Shape[]
- * @param params.constraints - 约束数组（遗留 face_mate 形态或上述新形态 { type, a, b }）。type:AssemblyConstraint[]
- * @example
- * let asm1 = cad.assembly({ name: '主轴组件', members: [part0, part1, part2], constraints: [ { type: 'fixed', part: 'part0' }, { type: 'mate', a: { part: 'part0', face: { topoRef: { kind: 'face', origin: 'part0', role: 'box:top', hint: { kind: 'face', surfaceType: 'plane' } } } }, b: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: 'box:bottom', hint: { kind: 'face', surfaceType: 'plane' } } } } }, { type: 'concentric', a: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: '', hint: { kind: 'face', surfaceType: 'cylinder' } } } }, b: { part: 'part2', face: { topoRef: { kind: 'face', origin: 'part2', role: 'cylinder:lateral', hint: { kind: 'face', surfaceType: 'cylinder' } } } } } ] })
- * asm1.solve()
-  */
-export function assembly(params) {
-    const members = params.members ?? [];
-    const constraints = params.constraints ?? [];
-    const joints = params.joints ?? [];
-    const drive = params.drive;
-    // P2-f1：约束参数运行期校验（keep() 之前，fail-fast；规则见 api/assembly/validate.ts V1–V6）
-    const memberNames = memberNamesOf(params, members);
-    validateConstraints(constraints, memberNames);
-    // P3：运动副构造期 fail-fast——parent/child ∈ members、child 唯一驱动、多 DOF 类型
-    // 在 assembly() 构造时暴露（buildJoint/buildKinematicTree 复用同一份校验实现）
-    if (joints.length > 0)
-        buildKinematicTree(memberNames, joints);
-    if (members.length > 0)
-        keep(...members);
-    const c = makeCompound(members);
-    const behavior = {
-        name: params.name,
-        memberNames,
-        constraints,
-        joints,
-        drive,
-        memberColors: params.memberColors,
-        solver: params.solver,
-        solve: () => solveTransforms(members, behavior),
-        solveDetailed: () => solveAssemblyAndKinematics(members, behavior.memberNames, behavior.constraints, behavior.joints ?? [], behavior.drive, { solver: behavior.solver, name: behavior.name }),
-    };
-    ensureSlot(c).behavior = behavior;
-    // solve / do_assemble 完全同义（方案 §5.5 D2：solve 为新名，do_assemble 保留为别名）
-    const solveAndRegister = () => {
-        // P6：只求解并登记待应用变换；应用与下游失效由引擎做（F2：库不查询/修改 DAG）
-        // P3：约束 + 运动副在库侧一次合并（solveAssemblyAndKinematics），transforms 与
-        // kinematics 一起登记（禁止引擎侧两次求解/两次登记）
-        const result = behavior.solveDetailed();
-        if (result.transforms.length > 0)
-            setPendingAssemblyTransforms(c, result.transforms);
-        if (result.kinematics)
-            setPendingAssemblyKinematics(c, result.kinematics);
-    };
-    c.do_assemble = solveAndRegister;
-    c.solve = solveAndRegister;
-    c.add_constraint = () => {
-        // Phase 1 semantics: constraints are read from the assembly statement's args.constraints;
-        // add_constraint is intentionally a no-op (kept for ABI uniformity).
-    };
-    return c;
-}
-//# sourceMappingURL=compound.js.map

package/dist/api/compound.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compound.js","sourceRoot":"","sources":["../../src/api/compound.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib compound — group/assembly 库函数（compound Shape + AssemblyBehavior）\n *\n *\n * 从 src/ops/assemble.ts 迁出并改写为 stdlib 形态：\n * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）\n * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）\n * - 装配求解（P1 起）委派 api/assembly/（brepjs solverAdapter 内核）：\n *   do_assemble/solve 触发求解 → 引擎应用\n *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。\n *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。\n *\n * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。\n * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，\n * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { compound as makeCompound, ensureSlot, type CompoundShape } from '../shape'\nimport { keep, nameOf, setPendingAssemblyTransforms, setPendingAssemblyKinematics, type AssemblyTransform } from '../runtime-state'\nimport { solveAssemblyAndKinematics, type AssemblySolveResult } from './assembly/solve'\nimport { validateConstraints } from './assembly/validate'\nimport { buildKinematicTree, type JointSpec } from './assembly/joints'\nimport type { AssemblyConstraint } from './assembly/types'\nimport type { SolverStyle } from './assembly/solvers/types'\n\n// ── 参数类型（keep-syntax 设计 §2.5：成员保留由函数体 keep() 显式声明，不再靠类型标注） ──\n\n/** Parameters for the `group` stdlib function: an optional name and ordered members. */\nexport interface GroupParams {\n  name?: string\n  /** Compound members: read-only references, never mutated by group/assembly. */\n  members?: Shape[]\n  memberNames?: string[]\n}\n\n/** Parameters for the `assembly` stdlib function: group params plus assembly constraints. */\nexport interface AssemblyParams extends GroupParams {\n  constraints?: AssemblyConstraint[]\n  /** P3：运动副声明（可选；parent/child 必须是 members 里的名字）。 */\n  joints?: JointSpec[]\n  /** P3：驱动值覆盖（键 = child 成员名；值 = 主 DOF 数值或多 DOF 数组）。 */\n  drive?: Record<string, number | number[]>\n  /** cq-compat：成员颜色（sRGB 0..1），导出 STEP 时写入 XCAF。 */\n  memberColors?: Record<string, [number, number, number]>\n  /** P1：求解风格。'chain'（默认，vendored brepjs 解析链式）| 'global'（CadQuery 兼容全局最小二乘）。 */\n  solver?: SolverStyle\n}\n\n// ── 约束类型（P1 起定义收口在 api/assembly/types，此处 re-export 保持既有导出面） ──\n\nexport type {\n  AssemblyConstraint,\n  FaceMateConstraint,\n  FaceMateFace,\n  EntityRef,\n  FaceRef,\n  EdgeRef,\n  MateConstraint,\n  AlignConstraint,\n  CoincidentConstraint,\n  ConcentricConstraint,\n  DistanceConstraint,\n  AngleConstraint,\n  ParallelConstraint,\n  PerpendicularConstraint,\n  FixedConstraint,\n  StructuralConstraint,\n  AssemblyVec3,\n} from './assembly/types'\nexport type { AssemblySolveResult } from './assembly/solve'\n\n// ── 求解器 ──\n// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走\n// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。\n\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import stdlib/compound；公共 API 经本 re-export 保持）。\nexport { applyTransform } from '../mesh/rigid-transform'\n\n// ── AssemblyBehavior ──\n\n/** Behavior attached to an assembly compound: its members, constraints, and solver. */\nexport interface AssemblyBehavior {\n  name?: string\n  memberNames: string[]\n  constraints: AssemblyConstraint[]\n  /** P3：运动副声明（无 joints 时为空数组）。 */\n  joints?: JointSpec[]\n  /** P3：驱动值覆盖（键 = child 成员名；缺省 undefined = 用 joint 存储值）。 */\n  drive?: Record<string, number | number[]>\n  /** cq-compat：成员颜色（sRGB 0..1）。 */\n  memberColors?: Record<string, [number, number, number]>\n  /** P1：求解风格。 */\n  solver?: SolverStyle\n  /** 只求解（P6）：返回\"成员下标 → 变换\"列表。不改写入参、不传播；可重复调用（幂等）。 */\n  solve(): AssemblyTransform[]\n  /** 只求解并带诊断量（P1）：transforms + dof/converged/unsupported（方案 P1⑤）；P3 增 kinematics/warnings。 */\n  solveDetailed(): AssemblySolveResult\n}\n\n/**\n * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。\n * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。\n *\n * 约束形态（方案 §5）：\n * - 遗留 face_mate：规范化为 mate 后降级为 brepjs concentric + 轴编码求解（§3.7.2）；\n * - 新形态 mate/align/coincident/concentric/distance/angle/parallel/perpendicular/fixed；\n * - 面参数 `{ topoRef }` 执行期解析（BREP 现场/mesh 行快照），旧 `{ center, normal }`\n *   快照直接使用（兼容已持久化的历史脚本）；\n * - 输出为 per-member 终态（L6 修复），锚定成员不输出变换。\n */\nfunction solveTransforms(members: Shape[], behavior: AssemblyBehavior): AssemblyTransform[] {\n  return solveAssemblyAndKinematics(\n    members,\n    behavior.memberNames,\n    behavior.constraints,\n    behavior.joints ?? [],\n    behavior.drive,\n    { solver: behavior.solver, name: behavior.name },\n  ).transforms\n}\n\n// ── group / assembly 库函数 ──\n\n/**\n * 成员名推导：显式 memberNames 兼容旧手工构造 IR；否则经 keep() 反查\n * （P3 起经 keep()/nameOfShapes 反查成员名——库不再访问执行上下文，F1）。\n */\nfunction memberNamesOf(params: { memberNames?: unknown }, members: Shape[]): string[] {\n  if (Array.isArray(params.memberNames) && params.memberNames.length > 0) {\n    return params.memberNames as string[]\n  }\n  return members.map((m) => {\n    // 兼容字符串形态的 members（历史 IR 直传 partName）：字符串本身就是名字\n    if (typeof m === 'string') return m\n    return String(nameOf(m) ?? '')\n  })\n}\n\n/**\n * `cad.group({ name, members })` → compound Shape。\n * members 是成员 Shape（编译产物 ctx.<var> 引用），成员名经 keep() 反查。\n *\n * 函数体 keep 声明（keep-syntax 设计 §2.5）：group 保留其成员且可见（R6）。\n */\n/**\n * 分组：零约束，保持当前布局。结构语句，无几何输出，成员用变量名引用。\n * @group 结构\n * @inputs 1\n * @async false\n * @qual ok\n * @name group\n * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（无几何输出，服务于编辑器画布与时间线），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。**平台侧需要几何复合体请用 `cad.compound`**（内核 `makeCompound`，持 OCCT 句柄，可变换/可导出）。\n * @returns CompoundShape 复合几何（kind='compound'，children 为成员 Shape 引用）。\n * @param params.name - 组名。type:string\n * @param params.members - 成员（编译产物 ctx.<var> 引用；结构语句里是裸变量引用，非字符串数组）。type:Shape[]\n * @note members 在 .fai.js 里是裸变量引用（编译为 ctx.<var>），字符串数组形态的成员名经 keep() 反查兼容历史 IR。\n * @example\n * const part0 = cad.box(30, 20, 10, { centered: true })\n * cad.group({ name: '底板组', members: [part0] })\n  */\nexport function group(params: GroupParams): CompoundShape {\n  const members = (params.members as Shape[] | undefined) ?? []\n  if (members.length > 0) keep(...members)\n  const memberNames = memberNamesOf(params, members)\n  const c = makeCompound(members)\n  // 挂最小 behavior（memberNames 供 ExecutionResult.compounds 结构输出；group 无约束）\n  ensureSlot(c).behavior = {\n    memberNames,\n    constraints: [],\n    joints: [],\n    solve: () => [],\n    solveDetailed: () => ({ transforms: [], dof: 0, converged: true, unsupported: [] }),\n  }\n  return c\n}\n\n/**\n * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。\n * 求解内核复用 vendored brepjs solverAdapter.solveConstraints（链式拓扑调度 / DOF / converged /\n * unsupported 诊断）；输出为 per-member 终态变换（每成员一条，恒等位姿不输出）。\n * @group 结构\n * @inputs 1\n * @async false\n * @qual warn\n * @name assembly\n * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（成员以编辑器结构语句形态声明，服务于画布与时间线），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。\n * @returns CompoundShape + AssemblyBehavior（含 do_assemble / solve 方法）。\n * @note 约束类型（a=参考、b=从动，移动 b 去贴合 a）：`mate` 面对面贴合（法向反向+面中心重合，遗留 face_mate 的新名，求解降级为 concentric + 轴编码）；`align` 同向对齐（法向同向+面中心重合）；`coincident` 共面/共点/共线（保留面内 2 个平移 DOF）；`concentric` 轴重合（孔轴配合，圆柱/圆锥面需 hint.axis，直边/圆边需 EdgeHint.axis）；`distance` 定距（mm，带 value）；`angle` 夹角（deg，带 value）；`parallel`/`perpendicular` 平行/垂直（angle 0°/90° 语法糖）；`fixed` 锚定部件（地基）；`face_mate` 为遗留别名（规范化为 mate，新代码不再使用）。\n * @note EntityRef 四种形态：`{ part, face: { topoRef } | { surfaceType?, center, normal } }`、`{ part, edge: { topoRef } | { axis: { origin, direction } } }`、`{ part, point: [x,y,z] }`、`{ part, faceIndex }`（1 起，仅调试简写）。\n * @note 不收敛（实体类型不匹配/环/参考不可达）→ 抛错并带 unsupported 明细；成员名为空串 → 求解前抛错；mesh 快照缺 axis 的圆柱/圆锥面作轴实体 → E_TOPO_NOT_FOUND（绝不静默降级）。`mate`（中心重合）与 `coincident`（只共面）是两种不同语义，不互相映射。\n * @note 早期文档/示例曾用 `fixedPartId`/`movingPartId`/`faceRowIndex`/`faceId`/`invalid`——这些键在代码中不存在。真实契约是 `fixedPartName`/`movingPartName` + `fixedFace`/`movingFace`（遗留 face_mate）。`faceId` 字段随 §6.2 移除，不再写入。\n * @param params.name - 装配名。type:string\n * @param params.members - 成员（裸变量引用）。type:Shape[]\n * @param params.constraints - 约束数组（遗留 face_mate 形态或上述新形态 { type, a, b }）。type:AssemblyConstraint[]\n * @example\n * let asm1 = cad.assembly({ name: '主轴组件', members: [part0, part1, part2], constraints: [ { type: 'fixed', part: 'part0' }, { type: 'mate', a: { part: 'part0', face: { topoRef: { kind: 'face', origin: 'part0', role: 'box:top', hint: { kind: 'face', surfaceType: 'plane' } } } }, b: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: 'box:bottom', hint: { kind: 'face', surfaceType: 'plane' } } } } }, { type: 'concentric', a: { part: 'part1', face: { topoRef: { kind: 'face', origin: 'part1', role: '', hint: { kind: 'face', surfaceType: 'cylinder' } } } }, b: { part: 'part2', face: { topoRef: { kind: 'face', origin: 'part2', role: 'cylinder:lateral', hint: { kind: 'face', surfaceType: 'cylinder' } } } } } ] })\n * asm1.solve()\n  */\nexport function assembly(params: AssemblyParams): CompoundShape {\n  const members = (params.members as Shape[] | undefined) ?? []\n  const constraints = (params.constraints as AssemblyConstraint[] | undefined) ?? []\n  const joints = (params.joints as JointSpec[] | undefined) ?? []\n  const drive = params.drive as Record<string, number | number[]> | undefined\n\n  // P2-f1：约束参数运行期校验（keep() 之前，fail-fast；规则见 api/assembly/validate.ts V1–V6）\n  const memberNames = memberNamesOf(params, members)\n  validateConstraints(constraints, memberNames)\n  // P3：运动副构造期 fail-fast——parent/child ∈ members、child 唯一驱动、多 DOF 类型\n  // 在 assembly() 构造时暴露（buildJoint/buildKinematicTree 复用同一份校验实现）\n  if (joints.length > 0) buildKinematicTree(memberNames, joints)\n\n  if (members.length > 0) keep(...members)\n  const c = makeCompound(members)\n  const behavior: AssemblyBehavior = {\n    name: params.name as string | undefined,\n    memberNames,\n    constraints,\n    joints,\n    drive,\n    memberColors: params.memberColors,\n    solver: params.solver,\n    solve: () => solveTransforms(members, behavior),\n    solveDetailed: () =>\n      solveAssemblyAndKinematics(\n        members,\n        behavior.memberNames,\n        behavior.constraints,\n        behavior.joints ?? [],\n        behavior.drive,\n        { solver: behavior.solver, name: behavior.name },\n      ),\n  }\n  ensureSlot(c).behavior = behavior\n  // solve / do_assemble 完全同义（方案 §5.5 D2：solve 为新名，do_assemble 保留为别名）\n  const solveAndRegister = (): void => {\n    // P6：只求解并登记待应用变换；应用与下游失效由引擎做（F2：库不查询/修改 DAG）\n    // P3：约束 + 运动副在库侧一次合并（solveAssemblyAndKinematics），transforms 与\n    // kinematics 一起登记（禁止引擎侧两次求解/两次登记）\n    const result = behavior.solveDetailed()\n    if (result.transforms.length > 0) setPendingAssemblyTransforms(c, result.transforms)\n    if (result.kinematics) setPendingAssemblyKinematics(c, result.kinematics)\n  }\n  ;(c as CompoundShape & { do_assemble?: () => void }).do_assemble = solveAndRegister\n  ;(c as CompoundShape & { solve?: () => void }).solve = solveAndRegister\n  // 统一成员调用 ABI：add_constraint 是 no-op（现状语义：约束由 assembly 语句 args.constraints 读取，\n  // 编译产物机械发射 `ctx.<asm>.add_constraint({...})`，调用此方法不崩）\n  ;(c as CompoundShape & { add_constraint?: () => void }).add_constraint = () => {\n    // Phase 1 semantics: constraints are read from the assembly statement's args.constraints;\n    // add_constraint is intentionally a no-op (kept for ABI uniformity).\n  }\n  return c\n}\n"]}

package/dist/api/copy.d.ts

@@ -1,40 +0,0 @@
-/**
- * stdlib copy — 深拷贝几何（方案 B：独立新对象，源不变）
- *
- *
- * copy 是"共享读取"（克隆出新对象，源不变），与 drill/transform 的"独占改写"本质不同：
- * - **copy 不消费其源**（从消费方排除，与 group/assembly 同级）
- * - copy 输出是独立新对象 → 归"新名"类（allocate-id.ts 不保名）
- * - **源显示**（part0=box; part1=copy(part0) → 画布显示 box 和副本两份）
- *
- * 双链路：
- * - mesh 路径：深拷贝 positions/indices 到新数组
- * - BREP 路径：kernel.copy(inputSolid) → solidToShape → fromBrep 登记
- */
-import type { Shape } from '../mesh/types.js';
-/**
- * `cad.copy(input)` → 深拷贝 Shape。
- *
- * 函数体 keep 声明（keep-syntax 设计 §2.5）：copy 保留其源（可见）——
- * keep(input) 使源变量保持终端（画布显示 box 和副本两份）。
- *
- * mesh 路径：positions/indices 复制到新数组（改副本不影响源）。
- * BREP 路径：kernel.copy 产出独立 ShapeHandle。
- */
-/**
- * 深拷贝几何为独立新对象（源不变，源与副本都显示）。
- * @group 特征
- * @inputs 1
- * @async false
- * @qual ok
- * @name copy
- * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（语义含编辑器画布显示——源与副本各显示一份），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。
- * @param input - 源几何。type:Shape required:true
- * @returns Shape 源几何的深拷贝。copy 不消费其源（画布显示 box 和副本两份），改副本不影响源。
- * @example
- * const part1 = cad.copy(part0)
-  */
-export declare const copy: ((input: Shape) => Promise<Shape>) & {
-    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
-};
-//# sourceMappingURL=copy.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../../src/api/copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAoC1C;;;;;;;;GAQG;AACH;;;;;;;;;;;;IAYI;AACJ,eAAO,MAAM,IAAI;;CAgBf,CAAA"}

package/dist/api/copy.js

@@ -1,83 +0,0 @@
-/**
- * stdlib copy — 深拷贝几何（方案 B：独立新对象，源不变）
- *
- *
- * copy 是"共享读取"（克隆出新对象，源不变），与 drill/transform 的"独占改写"本质不同：
- * - **copy 不消费其源**（从消费方排除，与 group/assembly 同级）
- * - copy 输出是独立新对象 → 归"新名"类（allocate-id.ts 不保名）
- * - **源显示**（part0=box; part1=copy(part0) → 画布显示 box 和副本两份）
- *
- * 双链路：
- * - mesh 路径：深拷贝 positions/indices 到新数组
- * - BREP 路径：kernel.copy(inputSolid) → solidToShape → fromBrep 登记
- */
-import { solidToShape } from '../brep/brep-ops.js';
-import { identityEvolution, identityHashEvolution } from '../brep/face-evolution.js';
-import { getBackends, keep } from '../runtime-state.js';
-import { fromBrep, brepOf, inputRoleTable } from '../shape.js';
-import { propagateAllOrigins } from '../topology/naming/roles.js';
-import { defineOp } from '../sdk.js';
-/** BREP 路径：kernel.copy 深拷贝实体 + 恒等面演化 + 恒等 roleTable 传播 + fromBrep 一次登记。 */
-function copyBrep(input) {
-    const kernel = getBackends().kernel.brep;
-    if (!kernel)
-        throw new Error('[stdlib/copy] no OCCT kernel');
-    const inputSolid = brepOf(input);
-    if (!inputSolid)
-        throw new Error('[stdlib/copy] input is not BREP');
-    const copiedSolid = kernel.copy(inputSolid);
-    // §2.4/§3.3：copy 面 1:1 保留——hash 恒等传播 roleTable（所有 origin）
-    const inputTable = inputRoleTable(input);
-    let roleTable;
-    if (inputTable && inputTable.size > 0) {
-        roleTable = propagateAllOrigins(inputTable, identityHashEvolution(kernel, inputSolid, copiedSolid));
-    }
-    return fromBrep(solidToShape(kernel, copiedSolid), {
-        solid: copiedSolid,
-        // copy 不改变拓扑，面 ordinal 不变
-        faceEvolution: identityEvolution(kernel, copiedSolid),
-        roleTable,
-    });
-}
-/**
- * `cad.copy(input)` → 深拷贝 Shape。
- *
- * 函数体 keep 声明（keep-syntax 设计 §2.5）：copy 保留其源（可见）——
- * keep(input) 使源变量保持终端（画布显示 box 和副本两份）。
- *
- * mesh 路径：positions/indices 复制到新数组（改副本不影响源）。
- * BREP 路径：kernel.copy 产出独立 ShapeHandle。
- */
-/**
- * 深拷贝几何为独立新对象（源不变，源与副本都显示）。
- * @group 特征
- * @inputs 1
- * @async false
- * @qual ok
- * @name copy
- * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（语义含编辑器画布显示——源与副本各显示一份），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。
- * @param input - 源几何。type:Shape required:true
- * @returns Shape 源几何的深拷贝。copy 不消费其源（画布显示 box 和副本两份），改副本不影响源。
- * @example
- * const part1 = cad.copy(part0)
-  */
-export const copy = defineOp({
-    mesh: (input) => {
-        if (!input)
-            throw new Error('[stdlib/copy] no input geometry');
-        keep(input);
-        // mesh 路径：深拷贝到新 TypedArray（改副本不影响源）
-        return {
-            positions: new Float32Array(input.positions),
-            indices: new Uint32Array(input.indices),
-        };
-    },
-    brep: (input) => {
-        if (!input)
-            throw new Error('[stdlib/copy] no input geometry');
-        keep(input);
-        return copyBrep(input);
-    },
-    naming: { kind: 'identity' },
-});
-//# sourceMappingURL=copy.js.map

package/dist/api/copy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"copy.js","sourceRoot":"","sources":["../../src/api/copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACjF,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAG9D,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAIjC,2EAA2E;AAC3E,SAAS,QAAQ,CAAC,KAAY;IAC5B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAA4B,CAAA;IAChE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;IAC5D,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IAC1D,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;IAEnE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAE3C,0DAA0D;IAC1D,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAA0B,CAAA;IACjE,IAAI,SAAgC,CAAA;IACpC,IAAI,UAAU,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACtC,SAAS,GAAG,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAA;IACrG,CAAC;IAED,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE;QACjD,KAAK,EAAE,WAAW;QAClB,0BAA0B;QAC1B,aAAa,EAAE,iBAAiB,CAAC,MAAM,EAAE,WAAW,CAAC;QACrD,SAAS;KACV,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;IAYI;AACJ,MAAM,CAAC,MAAM,IAAI,GAAG,QAAQ,CAAC;IAC3B,IAAI,EAAE,CAAC,KAAY,EAAE,EAAE;QACrB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QAC9D,IAAI,CAAC,KAAK,CAAC,CAAA;QACX,oCAAoC;QACpC,OAAO;YACL,SAAS,EAAE,IAAI,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC;YAC5C,OAAO,EAAE,IAAI,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC;SACxC,CAAA;IACH,CAAC;IACD,IAAI,EAAE,CAAC,KAAY,EAAE,EAAE;QACrB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QAC9D,IAAI,CAAC,KAAK,CAAC,CAAA;QACX,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAgB;CAC3C,CAAC,CAAA","sourcesContent":["/**\n * stdlib copy — 深拷贝几何（方案 B：独立新对象，源不变）\n *\n *\n * copy 是\"共享读取\"（克隆出新对象，源不变），与 drill/transform 的\"独占改写\"本质不同：\n * - **copy 不消费其源**（从消费方排除，与 group/assembly 同级）\n * - copy 输出是独立新对象 → 归\"新名\"类（allocate-id.ts 不保名）\n * - **源显示**（part0=box; part1=copy(part0) → 画布显示 box 和副本两份）\n *\n * 双链路：\n * - mesh 路径：深拷贝 positions/indices 到新数组\n * - BREP 路径：kernel.copy(inputSolid) → solidToShape → fromBrep 登记\n */\n\nimport type { Shape } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { identityEvolution, identityHashEvolution } from '../brep/face-evolution'\nimport { getBackends, keep } from '../runtime-state'\nimport { fromBrep, brepOf, inputRoleTable } from '../shape'\nimport { propagateAllOrigins } from '../topology/naming/roles'\nimport type { RoleTable } from '../topology/naming/types'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/** BREP 路径：kernel.copy 深拷贝实体 + 恒等面演化 + 恒等 roleTable 传播 + fromBrep 一次登记。 */\nfunction copyBrep(input: Shape): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/copy] no OCCT kernel')\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[stdlib/copy] input is not BREP')\n\n  const copiedSolid = kernel.copy(inputSolid)\n\n  // §2.4/§3.3：copy 面 1:1 保留——hash 恒等传播 roleTable（所有 origin）\n  const inputTable = inputRoleTable(input) as RoleTable | undefined\n  let roleTable: RoleTable | undefined\n  if (inputTable && inputTable.size > 0) {\n    roleTable = propagateAllOrigins(inputTable, identityHashEvolution(kernel, inputSolid, copiedSolid))\n  }\n\n  return fromBrep(solidToShape(kernel, copiedSolid), {\n    solid: copiedSolid,\n    // copy 不改变拓扑，面 ordinal 不变\n    faceEvolution: identityEvolution(kernel, copiedSolid),\n    roleTable,\n  })\n}\n\n/**\n * `cad.copy(input)` → 深拷贝 Shape。\n *\n * 函数体 keep 声明（keep-syntax 设计 §2.5）：copy 保留其源（可见）——\n * keep(input) 使源变量保持终端（画布显示 box 和副本两份）。\n *\n * mesh 路径：positions/indices 复制到新数组（改副本不影响源）。\n * BREP 路径：kernel.copy 产出独立 ShapeHandle。\n */\n/**\n * 深拷贝几何为独立新对象（源不变，源与副本都显示）。\n * @group 特征\n * @inputs 1\n * @async false\n * @qual ok\n * @name copy\n * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：该 op 为编辑器应用提供（语义含编辑器画布显示——源与副本各显示一份），不属 faijs 平台面，但**不是废弃项**——它服务真实负载。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。\n * @param input - 源几何。type:Shape required:true\n * @returns Shape 源几何的深拷贝。copy 不消费其源（画布显示 box 和副本两份），改副本不影响源。\n * @example\n * const part1 = cad.copy(part0)\n  */\nexport const copy = defineOp({\n  mesh: (input: Shape) => {\n    if (!input) throw new Error('[stdlib/copy] no input geometry')\n    keep(input)\n    // mesh 路径：深拷贝到新 TypedArray（改副本不影响源）\n    return {\n      positions: new Float32Array(input.positions),\n      indices: new Uint32Array(input.indices),\n    }\n  },\n  brep: (input: Shape) => {\n    if (!input) throw new Error('[stdlib/copy] no input geometry')\n    keep(input)\n    return copyBrep(input)\n  },\n  naming: { kind: 'identity' } as Provenance,\n})\n"]}

package/dist/api/fai_drill.d.ts

@@ -1,46 +0,0 @@
-/**
- * stdlib drill — 钻孔库函数
- *
- *
- * dispatchPath 静态判定 brep/mesh。
- * BREP 路径：OCCT cut（简单孔）或 threadBrep + cut（螺丝孔）。
- */
-import type { Shape } from '../mesh/types.js';
-/**
- * Validate drill parameters: `diameter` must be a positive number, `position`
- * (if provided) a vec3, and `depth` (if provided) a number (<= 0 means a through hole).
- * @param params - the raw drill operation parameters.
- */
-export declare function assertDrillParams(params: Record<string, unknown>): void;
-/**
- * 在几何体上钻孔（CSG 减除）。depth=0 为通孔，>0 为盲孔。
- * @group 特征
- * @inputs 1
- * @async true
- * @qual ok
- * @name fai_drill
- * @deprecated **`../3d_editor` 消费面**（原 `@deprecated` 措辞已于 2026-09-22 校正）：`fai_` 前缀 op 为编辑器应用提供，不属 faijs 平台面，但**不是废弃项**——它服务真实负载（3d_editor 38 个文件在用）。**变更其 API 形态必须同步更新 `../3d_editor`**（见 `docs/plans/2026-09-22-topology-identity-development-plan.md` §2）。faijs 平台面不提供等价 op（需要时须按平台需求另行设计，不得直接搬用本 op）。
- * @note 键名以本表为准：`type: 'through'|'blind'` 与 `direction` 为向量的旧素材是无效写法——孔型由 `depth`（0=通孔）推导，`direction` 是 'normal'|'x'|'y'|'z' 枚举。
- * @returns Shape 钻孔后的几何。
- * @param input - 目标几何。type:Shape required:true
- * @param params.diameter - 孔径（mm）。type:number required:true
- * @param params.depth - 孔深（mm）；0 = 通孔，> 0 = 盲孔。type:number 默认 0
- * @param params.holeType - 孔类型：simple 简单孔 / screw 螺丝孔。type:'simple' | 'screw' 默认 'simple'
- * @param params.direction - 钻孔轴向（normal 表示沿面法向）。type:'normal' | 'x' | 'y' | 'z' 默认 'normal'
- * @param params.position - 孔心位置。type:[x,y,z] 默认 原点
- * @param params.face - 面引用（§6.2 新形态：`FaceTopoRef`，执行期按输入 Shape 解析派生法向；优先于 `faceNormal`）。type:FaceTopoRef
- * @param params.faceNormal - 面法向（决定朝向；历史兜底，§6.2 起宿主不再写，改由 `face` 解析）。type:[x,y,z] 默认 [0,0,1]
- * @param params.tolerance - 公差（mm）。type:number 默认 0.3
- * @param params.screwSystem - 螺丝孔制式（holeType='screw' 时用）。type:'metric' | 'imperial' 默认 'metric'
- * @param params.screwSpecIdx - 螺丝规格索引（holeType='screw' 时用；4 → M5）。type:number 默认 4
- * @param params.screwThread - 螺丝螺纹类型。type:'coarse' | 'fine' | 'custom' 默认 'coarse'
- * @param params.screwHead - 螺丝头型。type:'hex' | 'chc' | 'none' 默认 'none'
- * @example
- * const p = await cad.fai_drill(part0, { diameter: 5 })
- * const p = await cad.fai_drill(part0, { diameter: 5, depth: 3 })
- * const p = await cad.fai_drill(part0, { diameter: 5.2, depth: 8, holeType: 'screw', screwSystem: 'metric', screwSpecIdx: 4, screwThread: 'coarse', screwHead: 'none' })
-  */
-export declare const fai_drill: ((input: Shape, params: Record<string, unknown>) => Promise<Shape>) & {
-    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
-};
-//# sourceMappingURL=fai_drill.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"fai_drill.d.ts","sourceRoot":"","sources":["../../src/api/fai_drill.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,eAAe,CAAA;AAwBhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQvE;AAiMD;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2BI;AACJ,eAAO,MAAM,SAAS;;CAYpB,CAAA"}