@faicad/faijs 0.33.2 → 0.35.8

package/dist/extra/op-names.d.ts

@@ -0,0 +1,37 @@
+/**
+ * op-names — the editor-owned op name lists (single source).
+ *
+ * 2026-10-13 merge: these names now live in core (`packages/core/src/extra/`).
+ * `createApiNamespace()` carries the complete cad surface (platform + sketch
+ * + extra ops). The lists serve two consumers:
+ *
+ * 1. the cad-namespace membership guards (all ops are in `createApiNamespace`),
+ *    and
+ * 2. the symbol table (gen-symbol-table discovers each op from the explicit
+ *    keys in `createApiNamespace()`; no separate `registerEditorSymbols()`
+ *    call is needed).
+ *
+ * `EDITOR_OPS` is the editor-owned op group (plan §4.2 A) and `CREATOR_OPS` the
+ * svg / 3D-text creator group (plan §4.2 B). The split is not cosmetic: the A
+ * group is lightweight (no heavy deps), so the weapp worker can mount it via
+ * the `@faicad/faijs/extra/editor-ops` entry while the B group — which carries
+ * the opentype.js / SVG / text-geometry chain — stays off the end-side bundle.
+ */
+/** A group (plan §4.2): editor-owned ops, three basic API only. */
+export declare const EDITOR_OPS: readonly ["fai_drill", "fai_extrude", "fai_split", "group", "assembly", "copy", "load"];
+/** B group (plan §4.2): svg / 3D-text creators; carry the non-basic three chain. */
+export declare const CREATOR_OPS: readonly ["text", "svgExtrude"];
+/** Every op name the editor ops group carries, in assembly order. */
+export declare const ALL_EDITOR_OPS: readonly ["fai_drill", "fai_extrude", "fai_split", "group", "assembly", "copy", "load", "text", "svgExtrude"];
+/** Name of an editor-owned op (`cad.<name>`). */
+export type EditorOpName = (typeof EDITOR_OPS)[number];
+/** Name of a creator op (`cad.<name>`). */
+export type CreatorOpName = (typeof CREATOR_OPS)[number];
+/**
+ * Membership test for the editor-owned op list (A group).
+ *
+ * @param name - the `cad.<name>` candidate to test.
+ * @returns true when the name is one of `EDITOR_OPS`.
+ */
+export declare function isEditorOp(name: string): name is EditorOpName;
+//# sourceMappingURL=op-names.d.ts.map

package/dist/extra/op-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-names.d.ts","sourceRoot":"","sources":["../../src/extra/op-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mEAAmE;AACnE,eAAO,MAAM,UAAU,yFAQb,CAAA;AAEV,oFAAoF;AACpF,eAAO,MAAM,WAAW,iCAGd,CAAA;AAEV,qEAAqE;AACrE,eAAO,MAAM,cAAc,+GAA2C,CAAA;AAEtE,iDAAiD;AACjD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtD,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,YAAY,CAE7D"}

package/dist/extra/op-names.js

@@ -0,0 +1,46 @@
+/**
+ * op-names — the editor-owned op name lists (single source).
+ *
+ * 2026-10-13 merge: these names now live in core (`packages/core/src/extra/`).
+ * `createApiNamespace()` carries the complete cad surface (platform + sketch
+ * + extra ops). The lists serve two consumers:
+ *
+ * 1. the cad-namespace membership guards (all ops are in `createApiNamespace`),
+ *    and
+ * 2. the symbol table (gen-symbol-table discovers each op from the explicit
+ *    keys in `createApiNamespace()`; no separate `registerEditorSymbols()`
+ *    call is needed).
+ *
+ * `EDITOR_OPS` is the editor-owned op group (plan §4.2 A) and `CREATOR_OPS` the
+ * svg / 3D-text creator group (plan §4.2 B). The split is not cosmetic: the A
+ * group is lightweight (no heavy deps), so the weapp worker can mount it via
+ * the `@faicad/faijs/extra/editor-ops` entry while the B group — which carries
+ * the opentype.js / SVG / text-geometry chain — stays off the end-side bundle.
+ */
+/** A group (plan §4.2): editor-owned ops, three basic API only. */
+export const EDITOR_OPS = [
+    'fai_drill',
+    'fai_extrude',
+    'fai_split',
+    'group',
+    'assembly',
+    'copy',
+    'load',
+];
+/** B group (plan §4.2): svg / 3D-text creators; carry the non-basic three chain. */
+export const CREATOR_OPS = [
+    'text',
+    'svgExtrude',
+];
+/** Every op name the editor ops group carries, in assembly order. */
+export const ALL_EDITOR_OPS = [...EDITOR_OPS, ...CREATOR_OPS];
+/**
+ * Membership test for the editor-owned op list (A group).
+ *
+ * @param name - the `cad.<name>` candidate to test.
+ * @returns true when the name is one of `EDITOR_OPS`.
+ */
+export function isEditorOp(name) {
+    return EDITOR_OPS.includes(name);
+}
+//# sourceMappingURL=op-names.js.map

package/dist/extra/op-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-names.js","sourceRoot":"","sources":["../../src/extra/op-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,WAAW;IACX,aAAa;IACb,WAAW;IACX,OAAO;IACP,UAAU;IACV,MAAM;IACN,MAAM;CACE,CAAA;AAEV,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM;IACN,YAAY;CACJ,CAAA;AAEV,qEAAqE;AACrE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAU,CAAA;AAQtE;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;AACzD,CAAC","sourcesContent":["/**\n * op-names — the editor-owned op name lists (single source).\n *\n * 2026-10-13 merge: these names now live in core (`packages/core/src/extra/`).\n * `createApiNamespace()` carries the complete cad surface (platform + sketch\n * + extra ops). The lists serve two consumers:\n *\n * 1. the cad-namespace membership guards (all ops are in `createApiNamespace`),\n *    and\n * 2. the symbol table (gen-symbol-table discovers each op from the explicit\n *    keys in `createApiNamespace()`; no separate `registerEditorSymbols()`\n *    call is needed).\n *\n * `EDITOR_OPS` is the editor-owned op group (plan §4.2 A) and `CREATOR_OPS` the\n * svg / 3D-text creator group (plan §4.2 B). The split is not cosmetic: the A\n * group is lightweight (no heavy deps), so the weapp worker can mount it via\n * the `@faicad/faijs/extra/editor-ops` entry while the B group — which carries\n * the opentype.js / SVG / text-geometry chain — stays off the end-side bundle.\n */\n\n/** A group (plan §4.2): editor-owned ops, three basic API only. */\nexport const EDITOR_OPS = [\n  'fai_drill',\n  'fai_extrude',\n  'fai_split',\n  'group',\n  'assembly',\n  'copy',\n  'load',\n] as const\n\n/** B group (plan §4.2): svg / 3D-text creators; carry the non-basic three chain. */\nexport const CREATOR_OPS = [\n  'text',\n  'svgExtrude',\n] as const\n\n/** Every op name the editor ops group carries, in assembly order. */\nexport const ALL_EDITOR_OPS = [...EDITOR_OPS, ...CREATOR_OPS] as const\n\n/** Name of an editor-owned op (`cad.<name>`). */\nexport type EditorOpName = (typeof EDITOR_OPS)[number]\n\n/** Name of a creator op (`cad.<name>`). */\nexport type CreatorOpName = (typeof CREATOR_OPS)[number]\n\n/**\n * Membership test for the editor-owned op list (A group).\n *\n * @param name - the `cad.<name>` candidate to test.\n * @returns true when the name is one of `EDITOR_OPS`.\n */\nexport function isEditorOp(name: string): name is EditorOpName {\n  return (EDITOR_OPS as readonly string[]).includes(name)\n}\n"]}

package/dist/extra/ops/compound.d.ts

@@ -0,0 +1,140 @@
+/**
+ * faijs-extra compound — group/assembly 库函数（compound Shape + AssemblyBehavior）
+ *
+ *
+ * 从 src/ops/assemble.ts 迁出并改写为 op 形态：
+ * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）
+ * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）
+ * - 装配求解（P1 起）委派 api/assembly/（chain-solver 内核）：
+ *   do_assemble/solve 触发求解 → 引擎应用
+ *   （mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ *   P2-f5：旧装配算法与自有四元数实现已删除，求解全链路走 api/assembly。
+ *
+ * compound 自身无独立 mesh——几何由 children 承载，意义是结构（层级）。
+ * do_assemble 编译为 `await ctx.<asm>.do_assemble()`：调用 compound 的求解方法，
+ * 对约束定位的成员施加装配变换（mesh 顶点烘焙 + BREP 刚体变换 + 下游传播）。
+ */
+import type { Shape } from '../../mesh/types.js';
+import { type CompoundShape } from '../../shape.js';
+import { type AssemblyTransform } from '../../runtime-state.js';
+import { type AssemblySolveResult } from '../../api/assembly/solve.js';
+import { type JointSpec } from '../../api/assembly/joints.js';
+import type { AssemblyConstraint } from '../../api/assembly/types.js';
+import type { SolverStyle } from '../../api/assembly/solvers/types.js';
+/** Parameters for the `group` op function: an optional name and ordered members. */
+export interface GroupParams {
+    name?: string;
+    /** Compound members: read-only references, never mutated by group/assembly. */
+    members?: Shape[];
+    memberNames?: string[];
+}
+/** Parameters for the `assembly` op function: group params plus assembly constraints. */
+export interface AssemblyParams extends GroupParams {
+    constraints?: AssemblyConstraint[];
+    /** P3：运动副声明（可选；parent/child 必须是 members 里的名字）。 */
+    joints?: JointSpec[];
+    /** P3：驱动值覆盖（键 = child 成员名；值 = 主 DOF 数值或多 DOF 数组）。 */
+    drive?: Record<string, number | number[]>;
+    /** cq-compat：成员颜色（sRGB 0..1），导出 STEP 时写入 XCAF。 */
+    memberColors?: Record<string, [number, number, number]>;
+    /** P1：求解风格。'chain'（默认，链式拓扑解析）| 'global'（CadQuery 兼容全局最小二乘）。 */
+    solver?: SolverStyle;
+}
+export type { AssemblyConstraint, FaceMateConstraint, FaceMateFace, EntityRef, FaceRef, EdgeRef, MateConstraint, AlignConstraint, CoincidentConstraint, ConcentricConstraint, DistanceConstraint, AngleConstraint, ParallelConstraint, PerpendicularConstraint, FixedConstraint, FixedPointConstraint, FixedAxisConstraint, FixedRotationConstraint, StructuralConstraint, AssemblyVec3, } from '../../api/assembly/types.js';
+export type { AssemblySolveResult } from '../../api/assembly/solve.js';
+export { applyTransform } from '../../mesh/rigid-transform.js';
+/** Behavior attached to an assembly compound: its members, constraints, and solver. */
+export interface AssemblyBehavior {
+    /**
+     * F3：声明来源判别符（`group` → 'group'，`assembly` → 'assembly'）。
+     * `ExecutionResult.assemblies` 只收 'assembly'——group 无约束/关节，进装配声明面
+     * 会让消费方（animation 宿主）对空约束集求解并撞欠定诊断。历史 behavior 无此字段
+     * （旧持久化 compound）→ 视为非 assembly 声明。
+     */
+    kind?: 'group' | 'assembly';
+    name?: string;
+    memberNames: string[];
+    constraints: AssemblyConstraint[];
+    /** P3：运动副声明（无 joints 时为空数组）。 */
+    joints?: JointSpec[];
+    /** P3：驱动值覆盖（键 = child 成员名；缺省 undefined = 用 joint 存储值）。 */
+    drive?: Record<string, number | number[]>;
+    /** cq-compat：成员颜色（sRGB 0..1）。 */
+    memberColors?: Record<string, [number, number, number]>;
+    /** P1：求解风格。 */
+    solver?: SolverStyle;
+    /** 只求解（P6）：返回"成员下标 → 变换"列表。不改写入参、不传播；可重复调用（幂等）。 */
+    solve(): AssemblyTransform[];
+    /** 只求解并带诊断量（P1）：transforms + dof/converged/unsupported（方案 P1⑤）；P3 增 kinematics/warnings。 */
+    solveDetailed(): AssemblySolveResult;
+}
+/**
+ * F3：装配声明的**宿主消费形态**（`ExecutionResult.assemblies` 的元素，2026-10-15）。
+ *
+ * = AssemblyBehavior 的声明字段（去掉 solve/solveDetailed 方法）+ CompoundShape 引用。
+ * 存在的理由：约束/关节声明此前只活在 compound 的 behavior 槽里，而 `getSlot` 未公开
+ * 导出——宿主持不到声明，只能在 outputs 里逆结构。本类型把声明面提到 ExecutionResult
+ * 一级字段，宿主据此在**自己的侧**做纯求解（禁烘焙：不调 asm.solve()/do_assemble()，
+ * 不触发 applyPendingAssemblyTransforms），位姿只以 transform 数据在宿主侧流动。
+ */
+export interface AssemblyDecl {
+    /** 装配名（cad.assembly 的 name 参数；未给则 undefined）。 */
+    name?: string;
+    /** 成员变量名（声明序，与 compound children 同序）。 */
+    memberNames: string[];
+    /** 约束声明（原样携带，未经求解）。 */
+    constraints: AssemblyConstraint[];
+    /** 运动副声明（无 joints 时为空数组）。 */
+    joints: JointSpec[];
+    /** 求解风格（'chain' 缺省 | 'global'）。 */
+    solver?: SolverStyle;
+    /** 装配 compound 本体（成员 Shape 经其 children 取用；也出现在 outputs 里）。 */
+    compound: CompoundShape;
+}
+/**
+ * `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`**。**平台侧需要几何复合体请用 `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 declare function group(params: GroupParams): CompoundShape;
+/**
+ * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。
+ * 求解内核复用 chain-solver 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`**。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` 锚定部件（地基）；`fixedPoint`/`fixedAxis`/`fixedRotation` 世界锚定 unary（把成员子实体钉到世界字面点/方向、锁朝向，平移其余 DOF 仍自由，仅 `solver:'global'` 支持）；`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 declare function assembly(params: AssemblyParams): CompoundShape;
+//# sourceMappingURL=compound.d.ts.map

package/dist/extra/ops/compound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compound.d.ts","sourceRoot":"","sources":["../../../src/extra/ops/compound.ts"],"names":[],"mappings":"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"}

package/dist/extra/ops/compound.js

@@ -0,0 +1,167 @@
+/**
+ * faijs-extra compound — group/assembly 库函数（compound Shape + AssemblyBehavior）
+ *
+ *
+ * 从 src/ops/assemble.ts 迁出并改写为 op 形态：
+ * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）
+ * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）
+ * - 装配求解（P1 起）委派 api/assembly/（chain-solver 内核）：
+ *   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 '../../api/assembly/solve.js';
+import { validateConstraints } from '../../api/assembly/validate.js';
+import { buildKinematicTree } from '../../api/assembly/joints.js';
+// ── 求解器 ──
+// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走
+// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。
+// （utils/quaternion.ts 已内化为第一方代码，函数名保留历史来源标识。）
+// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：
+// 引擎不得 import api/compound；公共 API 经本 re-export 保持）。
+export { applyTransform } from '../../mesh/rigid-transform.js';
+/**
+ * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。
+ * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。
+ *
+ * 约束形态（方案 §5）：
+ * - 遗留 face_mate：规范化为 mate 后降级为 chain-solver 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`**。**平台侧需要几何复合体请用 `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 = {
+        kind: 'group',
+        memberNames,
+        constraints: [],
+        joints: [],
+        solve: () => [],
+        solveDetailed: () => ({ transforms: [], dof: 0, converged: true, unsupported: [] }),
+    };
+    return c;
+}
+/**
+ * 装配：成员 + 约束。结构语句，无几何输出，成员用变量名引用、实体用 EntityRef / 拓扑引用。
+ * 求解内核复用 chain-solver 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`**。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` 锚定部件（地基）；`fixedPoint`/`fixedAxis`/`fixedRotation` 世界锚定 unary（把成员子实体钉到世界字面点/方向、锁朝向，平移其余 DOF 仍自由，仅 `solver:'global'` 支持）；`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 = {
+        kind: 'assembly',
+        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/extra/ops/compound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compound.js","sourceRoot":"","sources":["../../../src/extra/ops/compound.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * faijs-extra compound — group/assembly 库函数（compound Shape + AssemblyBehavior）\n *\n *\n * 从 src/ops/assemble.ts 迁出并改写为 op 形态：\n * - `group(params)` → compound Shape（kind='compound'，children 为成员 Shape 引用）\n * - `assembly(params)` → compound Shape + AssemblyBehavior（约束列表 + solve 方法）\n * - 装配求解（P1 起）委派 api/assembly/（chain-solver 内核）：\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 '../../api/assembly/solve'\nimport { validateConstraints } from '../../api/assembly/validate'\nimport { buildKinematicTree, type JointSpec } from '../../api/assembly/joints'\nimport type { AssemblyConstraint } from '../../api/assembly/types'\nimport type { SolverStyle } from '../../api/assembly/solvers/types'\n\n// ── 参数类型（keep-syntax 设计 §2.5：成员保留由函数体 keep() 显式声明，不再靠类型标注） ──\n\n/** Parameters for the `group` op 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` op 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'（默认，链式拓扑解析）| '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  FixedPointConstraint,\n  FixedAxisConstraint,\n  FixedRotationConstraint,\n  StructuralConstraint,\n  AssemblyVec3,\n} from '../../api/assembly/types'\nexport type { AssemblySolveResult } from '../../api/assembly/solve'\n\n// ── 求解器 ──\n// P2-f5：旧装配算法与自有四元数实现已整体删除——旋转计算一律走\n// brepjs utils/quaternion.ts，输出经 api/assembly/pose.ts fromBrepjsQuat 重排。\n// （utils/quaternion.ts 已内化为第一方代码，函数名保留历史来源标识。）\n\n// 应用变换（mesh 顶点烘焙）下沉到引擎侧 src/mesh/rigid-transform.ts（E-b：\n// 引擎不得 import api/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  /**\n   * F3：声明来源判别符（`group` → 'group'，`assembly` → 'assembly'）。\n   * `ExecutionResult.assemblies` 只收 'assembly'——group 无约束/关节，进装配声明面\n   * 会让消费方（animation 宿主）对空约束集求解并撞欠定诊断。历史 behavior 无此字段\n   * （旧持久化 compound）→ 视为非 assembly 声明。\n   */\n  kind?: 'group' | 'assembly'\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 * F3：装配声明的**宿主消费形态**（`ExecutionResult.assemblies` 的元素，2026-10-15）。\n *\n * = AssemblyBehavior 的声明字段（去掉 solve/solveDetailed 方法）+ CompoundShape 引用。\n * 存在的理由：约束/关节声明此前只活在 compound 的 behavior 槽里，而 `getSlot` 未公开\n * 导出——宿主持不到声明，只能在 outputs 里逆结构。本类型把声明面提到 ExecutionResult\n * 一级字段，宿主据此在**自己的侧**做纯求解（禁烘焙：不调 asm.solve()/do_assemble()，\n * 不触发 applyPendingAssemblyTransforms），位姿只以 transform 数据在宿主侧流动。\n */\nexport interface AssemblyDecl {\n  /** 装配名（cad.assembly 的 name 参数；未给则 undefined）。 */\n  name?: string\n  /** 成员变量名（声明序，与 compound children 同序）。 */\n  memberNames: string[]\n  /** 约束声明（原样携带，未经求解）。 */\n  constraints: AssemblyConstraint[]\n  /** 运动副声明（无 joints 时为空数组）。 */\n  joints: JointSpec[]\n  /** 求解风格（'chain' 缺省 | 'global'）。 */\n  solver?: SolverStyle\n  /** 装配 compound 本体（成员 Shape 经其 children 取用；也出现在 outputs 里）。 */\n  compound: CompoundShape\n}\n\n/**\n * 纯求解（P6：求解 ≠ 传播）：委派 api/assembly/solveAssembly（P1 起）。\n * 不修改任何输入、不触碰引擎状态——引擎负责应用变换并让下游失效重算（F2）。\n *\n * 约束形态（方案 §5）：\n * - 遗留 face_mate：规范化为 mate 后降级为 chain-solver 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`**。**平台侧需要几何复合体请用 `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    kind: 'group',\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 * 求解内核复用 chain-solver 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`**。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` 锚定部件（地基）；`fixedPoint`/`fixedAxis`/`fixedRotation` 世界锚定 unary（把成员子实体钉到世界字面点/方向、锁朝向，平移其余 DOF 仍自由，仅 `solver:'global'` 支持）；`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    kind: 'assembly',\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/extra/ops/copy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * faijs-extra 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`**。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/extra/ops/copy.d.ts.map

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

package/dist/extra/ops/copy.js

@@ -0,0 +1,83 @@
+/**
+ * faijs-extra 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 { getBrepApi } from '../../brep/handle-bridge.js';
+import { 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 = getBrepApi();
+    const inputSolid = brepOf(input);
+    if (inputSolid === undefined)
+        throw new Error('[extra/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`**。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('[extra/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('[extra/copy] no input geometry');
+        keep(input);
+        return copyBrep(input);
+    },
+    naming: { kind: 'identity' },
+    paramDims: {},
+});
+//# sourceMappingURL=copy.js.map

package/dist/extra/ops/copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.js","sourceRoot":"","sources":["../../../src/extra/ops/copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAGjE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGpC,2EAA2E;AAC3E,SAAS,QAAQ,CAAC,KAAY;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IAC1D,IAAI,UAAU,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IAE/E,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,gCAAgC,CAAC,CAAA;QAC7D,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,gCAAgC,CAAC,CAAA;QAC7D,IAAI,CAAC,KAAK,CAAC,CAAA;QACX,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAgB;IAE1C,SAAS,EAAE,EAAE;CACd,CAAC,CAAA","sourcesContent":["/**\n * faijs-extra 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 { getBrepApi } from '../../brep/handle-bridge'\nimport { 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'\n\n/** BREP 路径：kernel.copy 深拷贝实体 + 恒等面演化 + 恒等 roleTable 传播 + fromBrep 一次登记。 */\nfunction copyBrep(input: Shape): Shape {\n  const kernel = getBrepApi()\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (inputSolid === undefined) throw new Error('[extra/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`**。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('[extra/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('[extra/copy] no input geometry')\n    keep(input)\n    return copyBrep(input)\n  },\n  naming: { kind: 'identity' } as Provenance,\n\n  paramDims: {},\n})\n"]}