@faicad/faijs 0.13.0

package/dist/api/assembly/index.js

@@ -0,0 +1,16 @@
+/**
+ * api/assembly — 装配约束求解层（P1）
+ *
+ * 分层（方案 §4.1）：normalize（规范化 + face_mate 兼容）→ lower（直译降级，
+ * mate/align 寄生在 concentric 上）→ entities（TopoRef → SolverEntity，双链路）
+ * → solve（委派 brepjs solveConstraints）→ pose（位姿转换契约）。
+ */
+export * from './types.js';
+export * from './normalize.js';
+export * from './entities.js';
+export * from './lower.js';
+export * from './pose.js';
+export * from './solve.js';
+export * from './preview.js';
+export * from './joints.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/assembly/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA","sourcesContent":["/**\n * api/assembly — 装配约束求解层（P1）\n *\n * 分层（方案 §4.1）：normalize（规范化 + face_mate 兼容）→ lower（直译降级，\n * mate/align 寄生在 concentric 上）→ entities（TopoRef → SolverEntity，双链路）\n * → solve（委派 brepjs solveConstraints）→ pose（位姿转换契约）。\n */\n\nexport * from './types'\nexport * from './normalize'\nexport * from './entities'\nexport * from './lower'\nexport * from './pose'\nexport * from './solve'\nexport * from './preview'\nexport * from './joints'\n"]}

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

@@ -0,0 +1,208 @@
+/**
+ * api/assembly/joints — 运动副声明与运动学解算（P3）
+ *
+ * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 vendored 工厂构造，
+ * 与 brepjs Joint.dofs 的组合顺序对齐：cylindrical → [rotation, translation]、
+ * planar → [u, v, rotation]、spherical → [x, y, z]）。
+ *
+ * P3 首期只实现 revolute / prismatic 两种单 DOF 运动副；cylindrical / planar /
+ * spherical 在 buildJoint 里显式抛错（绝不静默降级成单 DOF），待 per-DOF ranges
+ * 启用（JointSpec.dofs 已按此预留）。
+ *
+ * 链路：JointSpec[] → buildJoint（vendored 工厂）→ buildKinematicTree（建树三步
+ * + 校验）→ solveKinematics（vendored forwardKinematics）→ per-member 位姿。
+ *
+ * cad.* 查询函数（jointTrajectory / inverseKinematics / mechanismDOF）是无副作用
+ * 纯函数：输入纯数据、输出纯数据，不挂在 assembly receiver 上。
+ *
+ * 四元数顺序：faijs 对外 [x,y,z,w]，brepjs [w,x,y,z]——只经 ./pose 的转换函数
+ * 换序，禁止在本模块手写分量重排。
+ */
+import { type Joint, type JointPose, type IKOptions as BrepjsIKOptions } from '../../vendored/brepjs/index.js';
+import { type AssemblyNode } from '../../vendored/brepjs/index.js';
+import { type FaijsQuat } from './pose.js';
+import type { AssemblyTransform } from '../../runtime-state.js';
+import type { AssemblyVec3 } from './types.js';
+/** 运动副类型：P3 首期只实现 revolute / prismatic。 */
+export type JointType = 'revolute' | 'prismatic' | 'cylindrical' | 'planar' | 'spherical';
+/** 单 DOF 范围（主 DOF 镜像字段 min/max/value）。 */
+export interface JointDofSpec {
+    min: number;
+    max: number;
+    value: number;
+}
+/**
+ * 可序列化运动副声明（.fai.js 对象字面量）。派生字段（dofs）由 buildJoint 内
+ * vendored 工厂构造——脚本里只写纯数据。
+ */
+export interface JointSpec {
+    type: JointType;
+    /**
+     * 参考体（不动）；child 相对它运动。必须是 members 里的**变量名**（字符串——
+     * `.fai.js` 可序列化子集；members 也是字符串名数组）。buildKinematicTree
+     * 校验二者 ∈ members。
+     */
+    parent: string;
+    /** 从动体（同样是 members 里的变量名）。 */
+    child: string;
+    /** 主轴：origin 是所有旋转 DOF 的枢轴锚点。 */
+    axis: {
+        origin: AssemblyVec3;
+        direction: AssemblyVec3;
+    };
+    /** 主 DOF 范围与当前值（revolute 单位 deg / prismatic 单位 mm；由 type 决定）。 */
+    min: number;
+    max: number;
+    value: number;
+    /**
+     * 多 DOF 运动副（cylindrical 2 / planar 3 / spherical 3）的逐 DOF 范围，
+     * **长度必须与 type 的 DOF 数一致，顺序 = brepjs `Joint.dofs` 的组合顺序**：
+     *   cylindrical → [rotation, translation]
+     *   planar      → [u, v, rotation]
+     *   spherical   → [x, y, z]
+     * P3 首期只实现 revolute/prismatic，此字段随多 DOF 类型一起启用。
+     */
+    dofs?: JointDofSpec[];
+    /** planar 专用：面内 u 参考方向（brepjs 会投影到平面并归一化）。 */
+    uDirection?: AssemblyVec3;
+    /** 静态连杆偏置（childWorld = parentWorld ∘ jointTransform ∘ offset），可选。 */
+    offset?: {
+        position?: AssemblyVec3;
+        rotation?: FaijsQuat;
+    };
+}
+/**
+ * 由 JointSpec 构造 brepjs Joint。
+ *
+ * revolute/prismatic 走 vendored 工厂（主 DOF 的 value 在工厂内 clamp 到
+ * [min,max]）；cylindrical/planar/spherical 显式抛错（多 DOF 未启用，绝不
+ * 静默降级）。offset 的四元数经 toBrepjsQuat 换序（faijs [x,y,z,w] → brepjs
+ * [w,x,y,z]）。
+ *
+ * @param spec - the serializable joint declaration.
+ * @returns the vendored brepjs Joint (with offset attached when declared).
+ * @throws Error on multi-DOF joint types and unknown joint types.
+ */
+export declare function buildJoint(spec: JointSpec): Joint;
+/**
+ * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（vendored
+ * forwardKinematics 只接受单个根；多成员必须有唯一合成根）。
+ *
+ * 校验（求解前，绝不静默）：
+ * - 成员名空串 → 抛错（与约束求解 R7 同源）；
+ * - parent/child 必须在 members 里 → 抛错并附成员名全集；
+ * - 同一 child 不得被两个 joint 驱动（brepjs forwardKinematics 对重复 child
+ *   静默跳过——faijs 侧必须在求解前显式失败）。
+ *
+ * 建树三步：
+ * ① 合成根 '__asm_root'（不带 shape）；② 全部成员挂成子节点（未被 joint 驱动
+ * 的成员靠这一步拿到 identity 位姿；addChild 返回新节点必须重新赋值）；③ 每个
+ * joint 经 addJoint 挂到树上（FK 用 walkAssembly 收集 node.joints，位姿按
+ * joint.parent/child 的名字图传播，与树边无关）。
+ *
+ * @param memberNames - member variable names (the tree covers every member).
+ * @param joints - raw joint declarations.
+ * @returns the assembled kinematic tree root.
+ * @throws Error on empty member names, unknown joint parts, or duplicate child drive.
+ */
+export declare function buildKinematicTree(memberNames: string[], joints: JointSpec[]): AssemblyNode;
+/** per-member 运动学位姿（rotation 为 faijs [x,y,z,w]）。 */
+export interface KinematicsPose {
+    position: AssemblyVec3;
+    rotation: FaijsQuat;
+}
+/** 运动学解算结果：装配变换（被驱动成员）+ 全成员位姿表。 */
+export interface KinematicsSolveResult {
+    /** 被 joints 定位（非恒等）的成员装配变换；index = 成员下标。 */
+    transforms: AssemblyTransform[];
+    /** 全部成员的终态位姿（含恒等，链根也在此）；键 = 成员名。 */
+    kinematics: Record<string, KinematicsPose>;
+}
+/**
+ * 运动学正解：buildKinematicTree → vendored forwardKinematics → per-member 位姿。
+ *
+ * 校验（求解前）：成员名空串 / parent-child ∈ members / child 唯一驱动（都收在
+ * buildKinematicTree 内）；drive 键必须 ∈ joints 的 child 集（多余键是笔误，
+ * 显式失败而非静默忽略）。
+ *
+ * forwards 返回的 Map 含合成根 '__asm_root'——本函数按 memberNames 过滤掉，
+ * 只输出成员位姿。transforms 只含非恒等（被驱动）成员，恒等成员不输出（引擎
+ * 不做无谓重算，与约束求解语义一致）；kinematics 则覆盖全部成员（含恒等），
+ * 供宿主动画/导出读取完整骨架。
+ *
+ * @param memberNames - member variable names.
+ * @param joints - raw joint declarations.
+ * @param drive - per-child DOF value overrides (number for the primary DOF, or
+ *   a per-DOF array); keyed by child member name.
+ * @returns the per-member kinematics result.
+ * @throws Error on empty member names, unknown joint parts, duplicate child drive,
+ *   or a drive key that is not a joint child.
+ */
+export declare function solveKinematics(memberNames: string[], joints: JointSpec[], drive?: Record<string, number | number[]>): KinematicsSolveResult;
+/** `cad.jointTrajectory({ joints, from, to, steps })` 参数。 */
+export interface JointTrajectoryParams {
+    joints: JointSpec[];
+    from: Record<string, number | number[]>;
+    to: Record<string, number | number[]>;
+    steps: number;
+}
+/** 轨迹采样（poses 的 rotation 已换序为 faijs [x,y,z,w]）。 */
+export interface FaijsTrajectorySample {
+    /** 归一化路径参数 ∈ [0,1]。 */
+    t: number;
+    /** 该步的逐 DOF 值（键 = child 成员名）。 */
+    values: Record<string, number[]>;
+    /** 该步全成员世界位姿。 */
+    poses: Map<string, KinematicsPose>;
+}
+/**
+ * `cad.jointTrajectory({ joints, from, to, steps })` — 关节空间直线路径采样。
+ * 产出 steps+1 个采样（含两端点）；joints 缺省值在两端取存储值。
+ * 无 endEffector 参数（关节空间插值，不追踪端点）。
+ *
+ * @param p - trajectory query parameters.
+ * @returns the sampled trajectory (poses with faijs-order quaternions).
+ */
+export declare function jointTrajectory(p: JointTrajectoryParams): FaijsTrajectorySample[];
+/** `cad.inverseKinematics({ joints, endEffector, target, options? })` 参数。 */
+export interface InverseKinematicsParams {
+    joints: JointSpec[];
+    /** 末端执行器 = child 成员名。 */
+    endEffector: string;
+    /** 目标位姿（rotation 对外 faijs [x,y,z,w]，内部 toBrepjsQuat 换序）。 */
+    target: {
+        position: AssemblyVec3;
+        rotation?: FaijsQuat;
+    };
+    options?: BrepjsIKOptions;
+}
+/** IK 结果（与 vendored IKResult 同构；values 键 = child 成员名）。 */
+export interface IKResult {
+    values: Record<string, number[]>;
+    converged: boolean;
+    iterations: number;
+    error: number;
+}
+/**
+ * `cad.inverseKinematics({ joints, endEffector, target, options? })` —
+ * damped-least-squares IK：求使末端到达 target 的关节值。关节范围在每个迭代
+ * clamp；不可达目标返回 converged:false 与最优配置。纯函数，无副作用。
+ *
+ * @param p - IK query parameters.
+ * @returns the solved joint values plus convergence diagnostics.
+ */
+export declare function inverseKinematics(p: InverseKinematicsParams): IKResult;
+/** `cad.mechanismDOF({ joints })` 参数。 */
+export interface MechanismDOFParams {
+    joints: JointSpec[];
+}
+/**
+ * `cad.mechanismDOF({ joints })` — 开链机构自由度 = 各 joint DOF 数之和
+ * （revolute/prismatic 各 1；串联两 revolute = 2）。纯函数，无副作用。
+ *
+ * @param p - DOF query parameters.
+ * @returns the mechanism's total degree of freedom.
+ */
+export declare function mechanismDOF(p: MechanismDOFParams): number;
+export type { JointPose, BrepjsIKOptions as IKOptions };
+//# sourceMappingURL=joints.d.ts.map

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

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

package/dist/api/assembly/joints.js

@@ -0,0 +1,240 @@
+/**
+ * api/assembly/joints — 运动副声明与运动学解算（P3）
+ *
+ * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 vendored 工厂构造，
+ * 与 brepjs Joint.dofs 的组合顺序对齐：cylindrical → [rotation, translation]、
+ * planar → [u, v, rotation]、spherical → [x, y, z]）。
+ *
+ * P3 首期只实现 revolute / prismatic 两种单 DOF 运动副；cylindrical / planar /
+ * spherical 在 buildJoint 里显式抛错（绝不静默降级成单 DOF），待 per-DOF ranges
+ * 启用（JointSpec.dofs 已按此预留）。
+ *
+ * 链路：JointSpec[] → buildJoint（vendored 工厂）→ buildKinematicTree（建树三步
+ * + 校验）→ solveKinematics（vendored forwardKinematics）→ per-member 位姿。
+ *
+ * cad.* 查询函数（jointTrajectory / inverseKinematics / mechanismDOF）是无副作用
+ * 纯函数：输入纯数据、输出纯数据，不挂在 assembly receiver 上。
+ *
+ * 四元数顺序：faijs 对外 [x,y,z,w]，brepjs [w,x,y,z]——只经 ./pose 的转换函数
+ * 换序，禁止在本模块手写分量重排。
+ */
+import { revoluteJoint, prismaticJoint, forwardKinematics as brepjsForwardKinematics, mechanismDOF as brepjsMechanismDOF, jointTrajectory as brepjsJointTrajectory, inverseKinematics as brepjsInverseKinematics, addJoint, } from '../../vendored/brepjs/index.js';
+import { createAssemblyNode, addChild } from '../../vendored/brepjs/index.js';
+import { fromBrepjsQuat, toBrepjsQuat, jointPoseToAssemblyTransform, isIdentityPose, } from './pose.js';
+// ── buildJoint：JointSpec → brepjs Joint ──
+/**
+ * 由 JointSpec 构造 brepjs Joint。
+ *
+ * revolute/prismatic 走 vendored 工厂（主 DOF 的 value 在工厂内 clamp 到
+ * [min,max]）；cylindrical/planar/spherical 显式抛错（多 DOF 未启用，绝不
+ * 静默降级）。offset 的四元数经 toBrepjsQuat 换序（faijs [x,y,z,w] → brepjs
+ * [w,x,y,z]）。
+ *
+ * @param spec - the serializable joint declaration.
+ * @returns the vendored brepjs Joint (with offset attached when declared).
+ * @throws Error on multi-DOF joint types and unknown joint types.
+ */
+export function buildJoint(spec) {
+    const axis = { origin: spec.axis.origin, direction: spec.axis.direction };
+    const options = { min: spec.min, max: spec.max, value: spec.value };
+    let joint;
+    switch (spec.type) {
+        case 'revolute':
+            joint = revoluteJoint(String(spec.parent), String(spec.child), axis, options);
+            break;
+        case 'prismatic':
+            joint = prismaticJoint(String(spec.parent), String(spec.child), axis, options);
+            break;
+        case 'cylindrical':
+        case 'planar':
+        case 'spherical':
+            throw new Error(`[assembly] joint type '${spec.type}' is not supported yet; per-DOF ranges pending`);
+        default: {
+            const exhaustive = spec.type;
+            throw new Error(`[assembly] unknown joint type '${String(exhaustive)}'`);
+        }
+    }
+    if (spec.offset) {
+        const rotation = spec.offset.rotation
+            ? [...toBrepjsQuat(spec.offset.rotation)]
+            : [1, 0, 0, 0];
+        joint = {
+            ...joint,
+            offset: {
+                position: spec.offset.position ?? [0, 0, 0],
+                rotation,
+            },
+        };
+    }
+    return joint;
+}
+// ── buildKinematicTree：建树三步 + 校验 ──
+/**
+ * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（vendored
+ * forwardKinematics 只接受单个根；多成员必须有唯一合成根）。
+ *
+ * 校验（求解前，绝不静默）：
+ * - 成员名空串 → 抛错（与约束求解 R7 同源）；
+ * - parent/child 必须在 members 里 → 抛错并附成员名全集；
+ * - 同一 child 不得被两个 joint 驱动（brepjs forwardKinematics 对重复 child
+ *   静默跳过——faijs 侧必须在求解前显式失败）。
+ *
+ * 建树三步：
+ * ① 合成根 '__asm_root'（不带 shape）；② 全部成员挂成子节点（未被 joint 驱动
+ * 的成员靠这一步拿到 identity 位姿；addChild 返回新节点必须重新赋值）；③ 每个
+ * joint 经 addJoint 挂到树上（FK 用 walkAssembly 收集 node.joints，位姿按
+ * joint.parent/child 的名字图传播，与树边无关）。
+ *
+ * @param memberNames - member variable names (the tree covers every member).
+ * @param joints - raw joint declarations.
+ * @returns the assembled kinematic tree root.
+ * @throws Error on empty member names, unknown joint parts, or duplicate child drive.
+ */
+export function buildKinematicTree(memberNames, joints) {
+    memberNames.forEach((name, i) => {
+        if (!name) {
+            throw new Error(`[assembly] member at index ${i} has an empty name — members are referenced by name in joints`);
+        }
+    });
+    const memberSet = new Set(memberNames);
+    const driven = new Set();
+    for (const j of joints) {
+        if (!memberSet.has(String(j.parent))) {
+            throw new Error(`[assembly] joint parent '${String(j.parent)}' is not a member — members: ${memberNames.join(', ')}`);
+        }
+        if (!memberSet.has(String(j.child))) {
+            throw new Error(`[assembly] joint child '${String(j.child)}' is not a member — members: ${memberNames.join(', ')}`);
+        }
+        if (driven.has(String(j.child))) {
+            throw new Error(`[assembly] joint child '${String(j.child)}' is driven by more than one joint — each child must be driven by exactly one joint`);
+        }
+        driven.add(String(j.child));
+    }
+    // 建树三步（见函数头注释）
+    let root = createAssemblyNode('__asm_root');
+    for (const m of memberNames)
+        root = addChild(root, createAssemblyNode(m));
+    for (const j of joints)
+        root = addJoint(root, buildJoint(j));
+    return root;
+}
+/** 从 joints 推导查询场景的成员名全集（parent ∪ child，保序去重）。 */
+function specMemberNames(joints) {
+    const names = [];
+    const seen = new Set();
+    for (const j of joints) {
+        for (const n of [String(j.parent), String(j.child)]) {
+            if (!seen.has(n)) {
+                seen.add(n);
+                names.push(n);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * 运动学正解：buildKinematicTree → vendored forwardKinematics → per-member 位姿。
+ *
+ * 校验（求解前）：成员名空串 / parent-child ∈ members / child 唯一驱动（都收在
+ * buildKinematicTree 内）；drive 键必须 ∈ joints 的 child 集（多余键是笔误，
+ * 显式失败而非静默忽略）。
+ *
+ * forwards 返回的 Map 含合成根 '__asm_root'——本函数按 memberNames 过滤掉，
+ * 只输出成员位姿。transforms 只含非恒等（被驱动）成员，恒等成员不输出（引擎
+ * 不做无谓重算，与约束求解语义一致）；kinematics 则覆盖全部成员（含恒等），
+ * 供宿主动画/导出读取完整骨架。
+ *
+ * @param memberNames - member variable names.
+ * @param joints - raw joint declarations.
+ * @param drive - per-child DOF value overrides (number for the primary DOF, or
+ *   a per-DOF array); keyed by child member name.
+ * @returns the per-member kinematics result.
+ * @throws Error on empty member names, unknown joint parts, duplicate child drive,
+ *   or a drive key that is not a joint child.
+ */
+export function solveKinematics(memberNames, joints, drive) {
+    if (drive) {
+        const jointChildren = new Set(joints.map((j) => String(j.child)));
+        for (const key of Object.keys(drive)) {
+            if (!jointChildren.has(key)) {
+                throw new Error(`[assembly] drive key '${key}' does not name a joint child — joint children: ${[...jointChildren].join(', ')}`);
+            }
+        }
+    }
+    const tree = buildKinematicTree(memberNames, joints);
+    const poses = brepjsForwardKinematics(tree, drive);
+    const transforms = [];
+    const kinematics = {};
+    memberNames.forEach((name, index) => {
+        const pose = poses.get(name);
+        if (!pose)
+            return;
+        const rotation = fromBrepjsQuat(pose.rotation);
+        kinematics[name] = {
+            position: [pose.position[0], pose.position[1], pose.position[2]],
+            rotation,
+        };
+        if (!isIdentityPose(pose))
+            transforms.push(jointPoseToAssemblyTransform(pose, index));
+    });
+    return { transforms, kinematics };
+}
+/**
+ * `cad.jointTrajectory({ joints, from, to, steps })` — 关节空间直线路径采样。
+ * 产出 steps+1 个采样（含两端点）；joints 缺省值在两端取存储值。
+ * 无 endEffector 参数（关节空间插值，不追踪端点）。
+ *
+ * @param p - trajectory query parameters.
+ * @returns the sampled trajectory (poses with faijs-order quaternions).
+ */
+export function jointTrajectory(p) {
+    const memberNames = specMemberNames(p.joints);
+    const tree = buildKinematicTree(memberNames, p.joints);
+    return brepjsJointTrajectory(tree, p.from, p.to, p.steps).map((s) => ({
+        t: s.t,
+        values: s.values,
+        poses: new Map([...s.poses.entries()].map(([name, pose]) => [
+            name,
+            {
+                position: [pose.position[0], pose.position[1], pose.position[2]],
+                rotation: fromBrepjsQuat(pose.rotation),
+            },
+        ])),
+    }));
+}
+/**
+ * `cad.inverseKinematics({ joints, endEffector, target, options? })` —
+ * damped-least-squares IK：求使末端到达 target 的关节值。关节范围在每个迭代
+ * clamp；不可达目标返回 converged:false 与最优配置。纯函数，无副作用。
+ *
+ * @param p - IK query parameters.
+ * @returns the solved joint values plus convergence diagnostics.
+ */
+export function inverseKinematics(p) {
+    const memberNames = specMemberNames(p.joints);
+    const tree = buildKinematicTree(memberNames, p.joints);
+    const target = {
+        position: p.target.position,
+        ...(p.target.rotation ? { rotation: toBrepjsQuat(p.target.rotation) } : {}),
+    };
+    const result = brepjsInverseKinematics(tree, p.endEffector, target, p.options);
+    return {
+        values: result.values,
+        converged: result.converged,
+        iterations: result.iterations,
+        error: result.error,
+    };
+}
+/**
+ * `cad.mechanismDOF({ joints })` — 开链机构自由度 = 各 joint DOF 数之和
+ * （revolute/prismatic 各 1；串联两 revolute = 2）。纯函数，无副作用。
+ *
+ * @param p - DOF query parameters.
+ * @returns the mechanism's total degree of freedom.
+ */
+export function mechanismDOF(p) {
+    const memberNames = specMemberNames(p.joints);
+    const tree = buildKinematicTree(memberNames, p.joints);
+    return brepjsMechanismDOF(tree);
+}
+//# sourceMappingURL=joints.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"joints.js","sourceRoot":"","sources":["../../../src/api/assembly/joints.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/joints — 运动副声明与运动学解算（P3）\n *\n * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 vendored 工厂构造，\n * 与 brepjs Joint.dofs 的组合顺序对齐：cylindrical → [rotation, translation]、\n * planar → [u, v, rotation]、spherical → [x, y, z]）。\n *\n * P3 首期只实现 revolute / prismatic 两种单 DOF 运动副；cylindrical / planar /\n * spherical 在 buildJoint 里显式抛错（绝不静默降级成单 DOF），待 per-DOF ranges\n * 启用（JointSpec.dofs 已按此预留）。\n *\n * 链路：JointSpec[] → buildJoint（vendored 工厂）→ buildKinematicTree（建树三步\n * + 校验）→ solveKinematics（vendored forwardKinematics）→ per-member 位姿。\n *\n * cad.* 查询函数（jointTrajectory / inverseKinematics / mechanismDOF）是无副作用\n * 纯函数：输入纯数据、输出纯数据，不挂在 assembly receiver 上。\n *\n * 四元数顺序：faijs 对外 [x,y,z,w]，brepjs [w,x,y,z]——只经 ./pose 的转换函数\n * 换序，禁止在本模块手写分量重排。\n */\n\nimport {\n  revoluteJoint,\n  prismaticJoint,\n  forwardKinematics as brepjsForwardKinematics,\n  mechanismDOF as brepjsMechanismDOF,\n  jointTrajectory as brepjsJointTrajectory,\n  inverseKinematics as brepjsInverseKinematics,\n  addJoint,\n  type Joint,\n  type JointPose,\n  type IKResult as BrepjsIKResult,\n  type IKOptions as BrepjsIKOptions,\n  type IKTarget as BrepjsIKTarget,\n} from '../../vendored/brepjs/index'\nimport { createAssemblyNode, addChild, type AssemblyNode } from '../../vendored/brepjs/index'\nimport {\n  fromBrepjsQuat,\n  toBrepjsQuat,\n  jointPoseToAssemblyTransform,\n  isIdentityPose,\n  type FaijsQuat,\n} from './pose'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport type { AssemblyVec3 } from './types'\n\n// ── JointSpec（.fai.js 可序列化子集）──\n\n/** 运动副类型：P3 首期只实现 revolute / prismatic。 */\nexport type JointType = 'revolute' | 'prismatic' | 'cylindrical' | 'planar' | 'spherical'\n\n/** 单 DOF 范围（主 DOF 镜像字段 min/max/value）。 */\nexport interface JointDofSpec {\n  min: number\n  max: number\n  value: number\n}\n\n/**\n * 可序列化运动副声明（.fai.js 对象字面量）。派生字段（dofs）由 buildJoint 内\n * vendored 工厂构造——脚本里只写纯数据。\n */\nexport interface JointSpec {\n  type: JointType\n  /**\n   * 参考体（不动）；child 相对它运动。必须是 members 里的**变量名**（字符串——\n   * `.fai.js` 可序列化子集；members 也是字符串名数组）。buildKinematicTree\n   * 校验二者 ∈ members。\n   */\n  parent: string\n  /** 从动体（同样是 members 里的变量名）。 */\n  child: string\n  /** 主轴：origin 是所有旋转 DOF 的枢轴锚点。 */\n  axis: { origin: AssemblyVec3; direction: AssemblyVec3 }\n  /** 主 DOF 范围与当前值（revolute 单位 deg / prismatic 单位 mm；由 type 决定）。 */\n  min: number\n  max: number\n  value: number\n  /**\n   * 多 DOF 运动副（cylindrical 2 / planar 3 / spherical 3）的逐 DOF 范围，\n   * **长度必须与 type 的 DOF 数一致，顺序 = brepjs `Joint.dofs` 的组合顺序**：\n   *   cylindrical → [rotation, translation]\n   *   planar      → [u, v, rotation]\n   *   spherical   → [x, y, z]\n   * P3 首期只实现 revolute/prismatic，此字段随多 DOF 类型一起启用。\n   */\n  dofs?: JointDofSpec[]\n  /** planar 专用：面内 u 参考方向（brepjs 会投影到平面并归一化）。 */\n  uDirection?: AssemblyVec3\n  /** 静态连杆偏置（childWorld = parentWorld ∘ jointTransform ∘ offset），可选。 */\n  offset?: { position?: AssemblyVec3; rotation?: FaijsQuat }\n}\n\n// ── buildJoint：JointSpec → brepjs Joint ──\n\n/**\n * 由 JointSpec 构造 brepjs Joint。\n *\n * revolute/prismatic 走 vendored 工厂（主 DOF 的 value 在工厂内 clamp 到\n * [min,max]）；cylindrical/planar/spherical 显式抛错（多 DOF 未启用，绝不\n * 静默降级）。offset 的四元数经 toBrepjsQuat 换序（faijs [x,y,z,w] → brepjs\n * [w,x,y,z]）。\n *\n * @param spec - the serializable joint declaration.\n * @returns the vendored brepjs Joint (with offset attached when declared).\n * @throws Error on multi-DOF joint types and unknown joint types.\n */\nexport function buildJoint(spec: JointSpec): Joint {\n  const axis = { origin: spec.axis.origin, direction: spec.axis.direction }\n  const options = { min: spec.min, max: spec.max, value: spec.value }\n  let joint: Joint\n  switch (spec.type) {\n    case 'revolute':\n      joint = revoluteJoint(String(spec.parent), String(spec.child), axis, options)\n      break\n    case 'prismatic':\n      joint = prismaticJoint(String(spec.parent), String(spec.child), axis, options)\n      break\n    case 'cylindrical':\n    case 'planar':\n    case 'spherical':\n      throw new Error(`[assembly] joint type '${spec.type}' is not supported yet; per-DOF ranges pending`)\n    default: {\n      const exhaustive: never = spec.type\n      throw new Error(`[assembly] unknown joint type '${String(exhaustive)}'`)\n    }\n  }\n  if (spec.offset) {\n    const rotation = spec.offset.rotation\n      ? ([...toBrepjsQuat(spec.offset.rotation)] as [number, number, number, number])\n      : ([1, 0, 0, 0] as [number, number, number, number])\n    joint = {\n      ...joint,\n      offset: {\n        position: spec.offset.position ?? ([0, 0, 0] as [number, number, number]),\n        rotation,\n      },\n    }\n  }\n  return joint\n}\n\n// ── buildKinematicTree：建树三步 + 校验 ──\n\n/**\n * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（vendored\n * forwardKinematics 只接受单个根；多成员必须有唯一合成根）。\n *\n * 校验（求解前，绝不静默）：\n * - 成员名空串 → 抛错（与约束求解 R7 同源）；\n * - parent/child 必须在 members 里 → 抛错并附成员名全集；\n * - 同一 child 不得被两个 joint 驱动（brepjs forwardKinematics 对重复 child\n *   静默跳过——faijs 侧必须在求解前显式失败）。\n *\n * 建树三步：\n * ① 合成根 '__asm_root'（不带 shape）；② 全部成员挂成子节点（未被 joint 驱动\n * 的成员靠这一步拿到 identity 位姿；addChild 返回新节点必须重新赋值）；③ 每个\n * joint 经 addJoint 挂到树上（FK 用 walkAssembly 收集 node.joints，位姿按\n * joint.parent/child 的名字图传播，与树边无关）。\n *\n * @param memberNames - member variable names (the tree covers every member).\n * @param joints - raw joint declarations.\n * @returns the assembled kinematic tree root.\n * @throws Error on empty member names, unknown joint parts, or duplicate child drive.\n */\nexport function buildKinematicTree(memberNames: string[], joints: JointSpec[]): AssemblyNode {\n  memberNames.forEach((name, i) => {\n    if (!name) {\n      throw new Error(\n        `[assembly] member at index ${i} has an empty name — members are referenced by name in joints`,\n      )\n    }\n  })\n  const memberSet = new Set(memberNames)\n  const driven = new Set<string>()\n  for (const j of joints) {\n    if (!memberSet.has(String(j.parent))) {\n      throw new Error(\n        `[assembly] joint parent '${String(j.parent)}' is not a member — members: ${memberNames.join(', ')}`,\n      )\n    }\n    if (!memberSet.has(String(j.child))) {\n      throw new Error(\n        `[assembly] joint child '${String(j.child)}' is not a member — members: ${memberNames.join(', ')}`,\n      )\n    }\n    if (driven.has(String(j.child))) {\n      throw new Error(\n        `[assembly] joint child '${String(j.child)}' is driven by more than one joint — each child must be driven by exactly one joint`,\n      )\n    }\n    driven.add(String(j.child))\n  }\n  // 建树三步（见函数头注释）\n  let root = createAssemblyNode('__asm_root')\n  for (const m of memberNames) root = addChild(root, createAssemblyNode(m))\n  for (const j of joints) root = addJoint(root, buildJoint(j))\n  return root\n}\n\n// ── solveKinematics：正解 ──\n\n/** per-member 运动学位姿（rotation 为 faijs [x,y,z,w]）。 */\nexport interface KinematicsPose {\n  position: AssemblyVec3\n  rotation: FaijsQuat\n}\n\n/** 运动学解算结果：装配变换（被驱动成员）+ 全成员位姿表。 */\nexport interface KinematicsSolveResult {\n  /** 被 joints 定位（非恒等）的成员装配变换；index = 成员下标。 */\n  transforms: AssemblyTransform[]\n  /** 全部成员的终态位姿（含恒等，链根也在此）；键 = 成员名。 */\n  kinematics: Record<string, KinematicsPose>\n}\n\n/** 从 joints 推导查询场景的成员名全集（parent ∪ child，保序去重）。 */\nfunction specMemberNames(joints: JointSpec[]): string[] {\n  const names: string[] = []\n  const seen = new Set<string>()\n  for (const j of joints) {\n    for (const n of [String(j.parent), String(j.child)]) {\n      if (!seen.has(n)) {\n        seen.add(n)\n        names.push(n)\n      }\n    }\n  }\n  return names\n}\n\n/**\n * 运动学正解：buildKinematicTree → vendored forwardKinematics → per-member 位姿。\n *\n * 校验（求解前）：成员名空串 / parent-child ∈ members / child 唯一驱动（都收在\n * buildKinematicTree 内）；drive 键必须 ∈ joints 的 child 集（多余键是笔误，\n * 显式失败而非静默忽略）。\n *\n * forwards 返回的 Map 含合成根 '__asm_root'——本函数按 memberNames 过滤掉，\n * 只输出成员位姿。transforms 只含非恒等（被驱动）成员，恒等成员不输出（引擎\n * 不做无谓重算，与约束求解语义一致）；kinematics 则覆盖全部成员（含恒等），\n * 供宿主动画/导出读取完整骨架。\n *\n * @param memberNames - member variable names.\n * @param joints - raw joint declarations.\n * @param drive - per-child DOF value overrides (number for the primary DOF, or\n *   a per-DOF array); keyed by child member name.\n * @returns the per-member kinematics result.\n * @throws Error on empty member names, unknown joint parts, duplicate child drive,\n *   or a drive key that is not a joint child.\n */\nexport function solveKinematics(\n  memberNames: string[],\n  joints: JointSpec[],\n  drive?: Record<string, number | number[]>,\n): KinematicsSolveResult {\n  if (drive) {\n    const jointChildren = new Set(joints.map((j) => String(j.child)))\n    for (const key of Object.keys(drive)) {\n      if (!jointChildren.has(key)) {\n        throw new Error(\n          `[assembly] drive key '${key}' does not name a joint child — joint children: ${[...jointChildren].join(', ')}`,\n        )\n      }\n    }\n  }\n  const tree = buildKinematicTree(memberNames, joints)\n  const poses = brepjsForwardKinematics(tree, drive)\n  const transforms: AssemblyTransform[] = []\n  const kinematics: Record<string, KinematicsPose> = {}\n  memberNames.forEach((name, index) => {\n    const pose = poses.get(name)\n    if (!pose) return\n    const rotation = fromBrepjsQuat(pose.rotation)\n    kinematics[name] = {\n      position: [pose.position[0], pose.position[1], pose.position[2]],\n      rotation,\n    }\n    if (!isIdentityPose(pose)) transforms.push(jointPoseToAssemblyTransform(pose, index))\n  })\n  return { transforms, kinematics }\n}\n\n// ── cad.* 查询函数（纯函数，无副作用；输入输出都是纯数据）──\n\n/** `cad.jointTrajectory({ joints, from, to, steps })` 参数。 */\nexport interface JointTrajectoryParams {\n  joints: JointSpec[]\n  from: Record<string, number | number[]>\n  to: Record<string, number | number[]>\n  steps: number\n}\n\n/** 轨迹采样（poses 的 rotation 已换序为 faijs [x,y,z,w]）。 */\nexport interface FaijsTrajectorySample {\n  /** 归一化路径参数 ∈ [0,1]。 */\n  t: number\n  /** 该步的逐 DOF 值（键 = child 成员名）。 */\n  values: Record<string, number[]>\n  /** 该步全成员世界位姿。 */\n  poses: Map<string, KinematicsPose>\n}\n\n/**\n * `cad.jointTrajectory({ joints, from, to, steps })` — 关节空间直线路径采样。\n * 产出 steps+1 个采样（含两端点）；joints 缺省值在两端取存储值。\n * 无 endEffector 参数（关节空间插值，不追踪端点）。\n *\n * @param p - trajectory query parameters.\n * @returns the sampled trajectory (poses with faijs-order quaternions).\n */\nexport function jointTrajectory(p: JointTrajectoryParams): FaijsTrajectorySample[] {\n  const memberNames = specMemberNames(p.joints)\n  const tree = buildKinematicTree(memberNames, p.joints)\n  return brepjsJointTrajectory(tree, p.from, p.to, p.steps).map((s) => ({\n    t: s.t,\n    values: s.values,\n    poses: new Map(\n      [...s.poses.entries()].map(([name, pose]) => [\n        name,\n        {\n          position: [pose.position[0], pose.position[1], pose.position[2]],\n          rotation: fromBrepjsQuat(pose.rotation),\n        },\n      ]),\n    ),\n  }))\n}\n\n/** `cad.inverseKinematics({ joints, endEffector, target, options? })` 参数。 */\nexport interface InverseKinematicsParams {\n  joints: JointSpec[]\n  /** 末端执行器 = child 成员名。 */\n  endEffector: string\n  /** 目标位姿（rotation 对外 faijs [x,y,z,w]，内部 toBrepjsQuat 换序）。 */\n  target: { position: AssemblyVec3; rotation?: FaijsQuat }\n  options?: BrepjsIKOptions\n}\n\n/** IK 结果（与 vendored IKResult 同构；values 键 = child 成员名）。 */\nexport interface IKResult {\n  values: Record<string, number[]>\n  converged: boolean\n  iterations: number\n  error: number\n}\n\n/**\n * `cad.inverseKinematics({ joints, endEffector, target, options? })` —\n * damped-least-squares IK：求使末端到达 target 的关节值。关节范围在每个迭代\n * clamp；不可达目标返回 converged:false 与最优配置。纯函数，无副作用。\n *\n * @param p - IK query parameters.\n * @returns the solved joint values plus convergence diagnostics.\n */\nexport function inverseKinematics(p: InverseKinematicsParams): IKResult {\n  const memberNames = specMemberNames(p.joints)\n  const tree = buildKinematicTree(memberNames, p.joints)\n  const target: BrepjsIKTarget = {\n    position: p.target.position,\n    ...(p.target.rotation ? { rotation: toBrepjsQuat(p.target.rotation) } : {}),\n  }\n  const result: BrepjsIKResult = brepjsInverseKinematics(tree, p.endEffector, target, p.options)\n  return {\n    values: result.values,\n    converged: result.converged,\n    iterations: result.iterations,\n    error: result.error,\n  }\n}\n\n/** `cad.mechanismDOF({ joints })` 参数。 */\nexport interface MechanismDOFParams {\n  joints: JointSpec[]\n}\n\n/**\n * `cad.mechanismDOF({ joints })` — 开链机构自由度 = 各 joint DOF 数之和\n * （revolute/prismatic 各 1；串联两 revolute = 2）。纯函数，无副作用。\n *\n * @param p - DOF query parameters.\n * @returns the mechanism's total degree of freedom.\n */\nexport function mechanismDOF(p: MechanismDOFParams): number {\n  const memberNames = specMemberNames(p.joints)\n  const tree = buildKinematicTree(memberNames, p.joints)\n  return brepjsMechanismDOF(tree)\n}\n\n// re-export：查询函数对外的类型面（IKOptions 透传给宿主）。\nexport type { JointPose, BrepjsIKOptions as IKOptions }"]}

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

@@ -0,0 +1,61 @@
+/**
+ * api/assembly/lower — faijs 约束 → brepjs SolverConstraint 降级（P1，方案 §3.7.2 / §4.2）
+ *
+ * 关键简化（方案 §3.7.3）：不自写合成器、不自写拓扑调度——
+ * - mate  → concentric + dep 侧 axis 编码取反法向（flip 是贴合语义的正解：
+ *           A 的外法向 = B 的内法向）；
+ * - align → concentric + 两侧 axis 编码不取反；
+ * - coincident/concentric/distance/angle → 直译；
+ * - parallel/perpendicular → angle 0°/90° 语法糖。
+ *
+ * 禁止把复合语义拆成多条 SolverConstraint——每节点只被定位一次（方案 §3.7.1）。
+ */
+import type { SolverConstraint, SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter.js';
+import type { ResolvedFaceGeometry } from '../topo-resolve.js';
+import type { AssemblyVec3, StructuralConstraint } from './types.js';
+import { type EntityResolutionEnv } from './entities.js';
+/**
+ * 面 → 有向轴实体（§3.7.2 轴编码）。flip=true 取内法向（贴合语义）。
+ * origin = 面中心：dep 侧是本地坐标，ref 侧由 brepjs transformEntity 转世界。
+ *
+ * @param f - the resolved face geometry (center + normal).
+ * @param flip - when true, negate the normal (mate encoding on the dependent side).
+ * @returns the directed axis entity.
+ */
+export declare function axisFromFace(f: ResolvedFaceGeometry, flip: boolean): SolverEntity;
+/** 降级产物：SolverConstraint + dependent 实体 origin（作 AssemblyTransform 的 pivot）。 */
+export interface LoweredConstraint {
+    constraint: SolverConstraint;
+    /** dependent 侧实体 origin（本地坐标）；fixed 约束无。 */
+    depOrigin?: AssemblyVec3;
+}
+/**
+ * 纯实体降级（P2-f3）：两侧 SolverEntity 已知（预览路径 / 宿主已持有几何）。
+ * 与 lowerStructuralConstraint 共用 axisFromFace 的编码规则，不另写数学。
+ *
+ * mate/align 要求两侧都是 `plane` 实体（贴合语义只接受平面）——把 plane 还原成
+ * {center, normal} 再走 axisFromFace 编码；与执行路径（lowerStructuralConstraint
+ * 的 mate/align 分支）逐位一致。非 plane 输入直接抛错（绝不静默）。
+ *
+ * @param type - the constraint type（parallel/perpendicular 请显式用 angle 0/90）。
+ * @param a - the reference-side entity (node + solver entity).
+ * @param b - the dependent-side entity (node + solver entity).
+ * @param value - distance/angle 用（其它类型忽略）。
+ * @returns the lowered solver constraint with the dependent origin.
+ */
+export declare function lowerEntities(type: 'mate' | 'align' | 'coincident' | 'concentric' | 'distance' | 'angle', a: {
+    node: string;
+    entity: SolverEntity;
+}, b: {
+    node: string;
+    entity: SolverEntity;
+}, value?: number): LoweredConstraint;
+/**
+ * 把一条规范化约束降级为 brepjs SolverConstraint（§4.2 步骤 3）。
+ *
+ * @param c - the normalized structural constraint.
+ * @param env - the entity resolution environment (kernel + member lookup).
+ * @returns the lowered solver constraint with the dependent origin.
+ */
+export declare function lowerStructuralConstraint(c: StructuralConstraint, env: EntityResolutionEnv): LoweredConstraint;
+//# sourceMappingURL=lower.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lower.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/lower.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAChG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAa,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAiD,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAEpG;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAOjF;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,gBAAgB,CAAA;IAC5B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,YAAY,CAAA;CACzB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,EAC3E,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EACzC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EACzC,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB,CA+CnB;AAeD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,oBAAoB,EAAE,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,CAmC9G"}