@faicad/faijs 0.13.0

package/dist/api/assembly/lower.js

@@ -0,0 +1,145 @@
+/**
+ * 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 { resolveFaceGeometryOfRef, resolveSolverEntity } 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 function axisFromFace(f, flip) {
+    const n = f.normal;
+    return {
+        type: 'axis',
+        origin: f.center,
+        direction: flip ? [-n[0], -n[1], -n[2]] : n,
+    };
+}
+/**
+ * 纯实体降级（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 function lowerEntities(type, a, b, value) {
+    switch (type) {
+        case 'mate':
+        case 'align': {
+            const kindA = a.entity.type;
+            const kindB = b.entity.type;
+            if (kindA !== 'plane' || kindB !== 'plane') {
+                throw new Error(`[assembly:lower] ${type} requires plane entities on both sides, got ${kindA}/${kindB}`);
+            }
+            // SolverEntity.origin/normal 是 readonly Vec3；拷贝成可变 AssemblyVec3 再传给
+            // axisFromFace（避免类型断言覆盖 readonly→mutable 的契约警告）。
+            // SolverEntity 是扁平 interface（type 联合非 tagged union），kind 检查后字段必然存在。
+            const normalA = a.entity.normal;
+            const normalB = b.entity.normal;
+            const pa = { origin: [...a.entity.origin], normal: [...normalA] };
+            const pb = { origin: [...b.entity.origin], normal: [...normalB] };
+            const flip = type === 'mate';
+            return {
+                constraint: {
+                    type: 'concentric',
+                    entityA: { node: a.node, entity: axisFromFace({ center: pa.origin, normal: pa.normal }, false) },
+                    entityB: { node: b.node, entity: axisFromFace({ center: pb.origin, normal: pb.normal }, flip) },
+                },
+                depOrigin: pb.origin,
+            };
+        }
+        case 'coincident':
+        case 'concentric':
+        case 'distance':
+        case 'angle': {
+            const constraint = {
+                type,
+                entityA: { node: a.node, entity: a.entity },
+                entityB: { node: b.node, entity: b.entity },
+            };
+            if (value !== undefined)
+                constraint.value = value;
+            return { constraint, depOrigin: [b.entity.origin[0], b.entity.origin[1], b.entity.origin[2]] };
+        }
+        default:
+            // TS 穷尽分支防御：JS 调用方可能传越界字符串（fixed/parallel/perpendicular/其他）
+            throw new Error(`[assembly:lower] unsupported constraint type for lowerEntities: ${String(type)} ` +
+                `(fixed has no displacement semantics; parallel/perpendicular use 'angle' 0/90)`);
+    }
+}
+/** 直译定位约束：解析两侧实体后原样翻译。 */
+function lowerPair(c, env) {
+    const entityA = resolveSolverEntity(c.a, env);
+    const entityB = resolveSolverEntity(c.b, env);
+    const constraint = {
+        type: c.type,
+        entityA: { node: c.a.part, entity: entityA },
+        entityB: { node: c.b.part, entity: entityB },
+    };
+    if (c.value !== undefined)
+        constraint.value = c.value;
+    return { constraint, depOrigin: [entityB.origin[0], entityB.origin[1], entityB.origin[2]] };
+}
+/**
+ * 把一条规范化约束降级为 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 function lowerStructuralConstraint(c, env) {
+    switch (c.type) {
+        case 'mate':
+        case 'align': {
+            // 贴合/对齐：两侧都必须是面引用；轴编码进 concentric（§3.7.2）
+            const geomA = resolveFaceGeometryOfRef(c.a, env);
+            const geomB = resolveFaceGeometryOfRef(c.b, env);
+            const flip = c.type === 'mate';
+            return {
+                constraint: {
+                    type: 'concentric',
+                    entityA: { node: c.a.part, entity: axisFromFace(geomA, false) },
+                    entityB: { node: c.b.part, entity: axisFromFace(geomB, flip) },
+                },
+                depOrigin: geomB.center,
+            };
+        }
+        case 'parallel':
+            return lowerPair({ type: 'angle', value: 0, a: c.a, b: c.b }, env);
+        case 'perpendicular':
+            return lowerPair({ type: 'angle', value: 90, a: c.a, b: c.b }, env);
+        case 'fixed':
+            // solver 对 fixed 只读 entityA.node；entity 占位满足 SolverConstraint 形状
+            return {
+                constraint: {
+                    type: 'fixed',
+                    entityA: { node: c.part, entity: { type: 'point', origin: [0, 0, 0] } },
+                },
+            };
+        case 'coincident':
+        case 'concentric':
+        case 'distance':
+        case 'angle':
+            return lowerPair(c, env);
+    }
+}
+//# sourceMappingURL=lower.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lower.js","sourceRoot":"","sources":["../../../src/api/assembly/lower.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/lower — faijs 约束 → brepjs SolverConstraint 降级（P1，方案 §3.7.2 / §4.2）\n *\n * 关键简化（方案 §3.7.3）：不自写合成器、不自写拓扑调度——\n * - mate  → concentric + dep 侧 axis 编码取反法向（flip 是贴合语义的正解：\n *           A 的外法向 = B 的内法向）；\n * - align → concentric + 两侧 axis 编码不取反；\n * - coincident/concentric/distance/angle → 直译；\n * - parallel/perpendicular → angle 0°/90° 语法糖。\n *\n * 禁止把复合语义拆成多条 SolverConstraint——每节点只被定位一次（方案 §3.7.1）。\n */\n\nimport type { SolverConstraint, SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter'\nimport type { ResolvedFaceGeometry } from '../topo-resolve'\nimport type { AssemblyVec3, EntityRef, StructuralConstraint } from './types'\nimport { resolveFaceGeometryOfRef, resolveSolverEntity, type EntityResolutionEnv } from './entities'\n\n/**\n * 面 → 有向轴实体（§3.7.2 轴编码）。flip=true 取内法向（贴合语义）。\n * origin = 面中心：dep 侧是本地坐标，ref 侧由 brepjs transformEntity 转世界。\n *\n * @param f - the resolved face geometry (center + normal).\n * @param flip - when true, negate the normal (mate encoding on the dependent side).\n * @returns the directed axis entity.\n */\nexport function axisFromFace(f: ResolvedFaceGeometry, flip: boolean): SolverEntity {\n  const n = f.normal\n  return {\n    type: 'axis',\n    origin: f.center,\n    direction: flip ? ([-n[0], -n[1], -n[2]] as AssemblyVec3) : n,\n  }\n}\n\n/** 降级产物：SolverConstraint + dependent 实体 origin（作 AssemblyTransform 的 pivot）。 */\nexport interface LoweredConstraint {\n  constraint: SolverConstraint\n  /** dependent 侧实体 origin（本地坐标）；fixed 约束无。 */\n  depOrigin?: AssemblyVec3\n}\n\n/** 直译定位约束的形状（a/b 必有，value 可选）。 */\ninterface PairSpec {\n  type: 'coincident' | 'concentric' | 'distance' | 'angle'\n  value?: number\n  a: EntityRef\n  b: EntityRef\n}\n\n/**\n * 纯实体降级（P2-f3）：两侧 SolverEntity 已知（预览路径 / 宿主已持有几何）。\n * 与 lowerStructuralConstraint 共用 axisFromFace 的编码规则，不另写数学。\n *\n * mate/align 要求两侧都是 `plane` 实体（贴合语义只接受平面）——把 plane 还原成\n * {center, normal} 再走 axisFromFace 编码；与执行路径（lowerStructuralConstraint\n * 的 mate/align 分支）逐位一致。非 plane 输入直接抛错（绝不静默）。\n *\n * @param type - the constraint type（parallel/perpendicular 请显式用 angle 0/90）。\n * @param a - the reference-side entity (node + solver entity).\n * @param b - the dependent-side entity (node + solver entity).\n * @param value - distance/angle 用（其它类型忽略）。\n * @returns the lowered solver constraint with the dependent origin.\n */\nexport function lowerEntities(\n  type: 'mate' | 'align' | 'coincident' | 'concentric' | 'distance' | 'angle',\n  a: { node: string; entity: SolverEntity },\n  b: { node: string; entity: SolverEntity },\n  value?: number,\n): LoweredConstraint {\n  switch (type) {\n    case 'mate':\n    case 'align': {\n      const kindA = a.entity.type\n      const kindB = b.entity.type\n      if (kindA !== 'plane' || kindB !== 'plane') {\n        throw new Error(\n          `[assembly:lower] ${type} requires plane entities on both sides, got ${kindA}/${kindB}`,\n        )\n      }\n      // SolverEntity.origin/normal 是 readonly Vec3；拷贝成可变 AssemblyVec3 再传给\n      // axisFromFace（避免类型断言覆盖 readonly→mutable 的契约警告）。\n      // SolverEntity 是扁平 interface（type 联合非 tagged union），kind 检查后字段必然存在。\n      const normalA = a.entity.normal as readonly [number, number, number]\n      const normalB = b.entity.normal as readonly [number, number, number]\n      const pa = { origin: [...a.entity.origin] as AssemblyVec3, normal: [...normalA] as AssemblyVec3 }\n      const pb = { origin: [...b.entity.origin] as AssemblyVec3, normal: [...normalB] as AssemblyVec3 }\n      const flip = type === 'mate'\n      return {\n        constraint: {\n          type: 'concentric',\n          entityA: { node: a.node, entity: axisFromFace({ center: pa.origin, normal: pa.normal }, false) },\n          entityB: { node: b.node, entity: axisFromFace({ center: pb.origin, normal: pb.normal }, flip) },\n        },\n        depOrigin: pb.origin,\n      }\n    }\n    case 'coincident':\n    case 'concentric':\n    case 'distance':\n    case 'angle': {\n      const constraint: SolverConstraint = {\n        type,\n        entityA: { node: a.node, entity: a.entity },\n        entityB: { node: b.node, entity: b.entity },\n      }\n      if (value !== undefined) constraint.value = value\n      return { constraint, depOrigin: [b.entity.origin[0], b.entity.origin[1], b.entity.origin[2]] }\n    }\n    default:\n      // TS 穷尽分支防御：JS 调用方可能传越界字符串（fixed/parallel/perpendicular/其他）\n      throw new Error(\n        `[assembly:lower] unsupported constraint type for lowerEntities: ${String(type)} ` +\n          `(fixed has no displacement semantics; parallel/perpendicular use 'angle' 0/90)`,\n      )\n  }\n}\n\n/** 直译定位约束：解析两侧实体后原样翻译。 */\nfunction lowerPair(c: PairSpec, env: EntityResolutionEnv): LoweredConstraint {\n  const entityA = resolveSolverEntity(c.a, env)\n  const entityB = resolveSolverEntity(c.b, env)\n  const constraint: SolverConstraint = {\n    type: c.type,\n    entityA: { node: c.a.part, entity: entityA },\n    entityB: { node: c.b.part, entity: entityB },\n  }\n  if (c.value !== undefined) constraint.value = c.value\n  return { constraint, depOrigin: [entityB.origin[0], entityB.origin[1], entityB.origin[2]] }\n}\n\n/**\n * 把一条规范化约束降级为 brepjs SolverConstraint（§4.2 步骤 3）。\n *\n * @param c - the normalized structural constraint.\n * @param env - the entity resolution environment (kernel + member lookup).\n * @returns the lowered solver constraint with the dependent origin.\n */\nexport function lowerStructuralConstraint(c: StructuralConstraint, env: EntityResolutionEnv): LoweredConstraint {\n  switch (c.type) {\n    case 'mate':\n    case 'align': {\n      // 贴合/对齐：两侧都必须是面引用；轴编码进 concentric（§3.7.2）\n      const geomA = resolveFaceGeometryOfRef(c.a, env)\n      const geomB = resolveFaceGeometryOfRef(c.b, env)\n      const flip = c.type === 'mate'\n      return {\n        constraint: {\n          type: 'concentric',\n          entityA: { node: c.a.part, entity: axisFromFace(geomA, false) },\n          entityB: { node: c.b.part, entity: axisFromFace(geomB, flip) },\n        },\n        depOrigin: geomB.center,\n      }\n    }\n    case 'parallel':\n      return lowerPair({ type: 'angle', value: 0, a: c.a, b: c.b }, env)\n    case 'perpendicular':\n      return lowerPair({ type: 'angle', value: 90, a: c.a, b: c.b }, env)\n    case 'fixed':\n      // solver 对 fixed 只读 entityA.node；entity 占位满足 SolverConstraint 形状\n      return {\n        constraint: {\n          type: 'fixed',\n          entityA: { node: c.part, entity: { type: 'point', origin: [0, 0, 0] } },\n        },\n      }\n    case 'coincident':\n    case 'concentric':\n    case 'distance':\n    case 'angle':\n      return lowerPair(c, env)\n  }\n}\n"]}

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

@@ -0,0 +1,19 @@
+/**
+ * api/assembly/normalize — 约束规范化（P1，方案 §4.1 / §5.3）
+ *
+ * 唯一职责：把 `cad.assembly({ constraints })` 的各种输入形态归一为
+ * {@link StructuralConstraint}：
+ * - 遗留 `face_mate` → `mate`（字段重排：fixedPartName/fixedFace → a，movingPartName/movingFace → b）；
+ * - 新形态直通（引用同一对象，不拷贝）。
+ *
+ * 未知类型在此抛错（fail-fast），不在求解深处静默跳过。
+ */
+import type { AssemblyConstraint, StructuralConstraint } from './types.js';
+/**
+ * Normalize one assembly constraint to the structural form.
+ * @param c - the raw constraint from script args.
+ * @returns the normalized structural constraint.
+ * @throws Error when the constraint type is unknown.
+ */
+export declare function normalizeConstraint(c: AssemblyConstraint): StructuralConstraint;
+//# sourceMappingURL=normalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEvE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,kBAAkB,GAAG,oBAAoB,CAgB/E"}

package/dist/api/assembly/normalize.js

@@ -0,0 +1,32 @@
+/**
+ * api/assembly/normalize — 约束规范化（P1，方案 §4.1 / §5.3）
+ *
+ * 唯一职责：把 `cad.assembly({ constraints })` 的各种输入形态归一为
+ * {@link StructuralConstraint}：
+ * - 遗留 `face_mate` → `mate`（字段重排：fixedPartName/fixedFace → a，movingPartName/movingFace → b）；
+ * - 新形态直通（引用同一对象，不拷贝）。
+ *
+ * 未知类型在此抛错（fail-fast），不在求解深处静默跳过。
+ */
+/**
+ * Normalize one assembly constraint to the structural form.
+ * @param c - the raw constraint from script args.
+ * @returns the normalized structural constraint.
+ * @throws Error when the constraint type is unknown.
+ */
+export function normalizeConstraint(c) {
+    if (c.type === 'face_mate') {
+        return {
+            type: 'mate',
+            a: { part: c.fixedPartName, face: c.fixedFace },
+            b: { part: c.movingPartName, face: c.movingFace },
+        };
+    }
+    if (c.type === 'mate' || c.type === 'align' || c.type === 'coincident' ||
+        c.type === 'concentric' || c.type === 'distance' || c.type === 'angle' ||
+        c.type === 'parallel' || c.type === 'perpendicular' || c.type === 'fixed') {
+        return c;
+    }
+    throw new Error(`[assembly] unknown constraint type: ${c.type}`);
+}
+//# sourceMappingURL=normalize.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/api/assembly/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAqB;IACvD,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE;YAC/C,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,EAAE;SAClD,CAAA;IACH,CAAC;IACD,IACE,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;QAClE,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;QACtE,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,EACzE,CAAC;QACD,OAAO,CAAC,CAAA;IACV,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uCAAwC,CAAwB,CAAC,IAAI,EAAE,CAAC,CAAA;AAC1F,CAAC","sourcesContent":["/**\n * api/assembly/normalize — 约束规范化（P1，方案 §4.1 / §5.3）\n *\n * 唯一职责：把 `cad.assembly({ constraints })` 的各种输入形态归一为\n * {@link StructuralConstraint}：\n * - 遗留 `face_mate` → `mate`（字段重排：fixedPartName/fixedFace → a，movingPartName/movingFace → b）；\n * - 新形态直通（引用同一对象，不拷贝）。\n *\n * 未知类型在此抛错（fail-fast），不在求解深处静默跳过。\n */\n\nimport type { AssemblyConstraint, StructuralConstraint } from './types'\n\n/**\n * Normalize one assembly constraint to the structural form.\n * @param c - the raw constraint from script args.\n * @returns the normalized structural constraint.\n * @throws Error when the constraint type is unknown.\n */\nexport function normalizeConstraint(c: AssemblyConstraint): StructuralConstraint {\n  if (c.type === 'face_mate') {\n    return {\n      type: 'mate',\n      a: { part: c.fixedPartName, face: c.fixedFace },\n      b: { part: c.movingPartName, face: c.movingFace },\n    }\n  }\n  if (\n    c.type === 'mate' || c.type === 'align' || c.type === 'coincident' ||\n    c.type === 'concentric' || c.type === 'distance' || c.type === 'angle' ||\n    c.type === 'parallel' || c.type === 'perpendicular' || c.type === 'fixed'\n  ) {\n    return c\n  }\n  throw new Error(`[assembly] unknown constraint type: ${(c as { type?: unknown }).type}`)\n}\n"]}

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

@@ -0,0 +1,78 @@
+/**
+ * api/assembly/pose — 位姿转换契约（P1，方案 §4.3）
+ *
+ * brepjs 与 faijs 的位姿模型两处不一致，转换收口在本模块（禁止别处手写 q[0]/q[3]）：
+ * (a) 四元数分量顺序：brepjs [w,x,y,z] ↔ faijs [x,y,z,w]；
+ * (b) pivot 语义：brepjs `p' = R·p + position`（绕原点）↔
+ *     faijs `p' = R·(p − pivot) + pivot + translation`。
+ *     令 pivot = dependent 实体 origin（单约束场景），二者等价：
+ *     translation = position − pivot + R·pivot。
+ */
+import type { SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter.js';
+import { quatRotate } from '../../vendored/brepjs/utils/quaternion.js';
+import type { JointPose } from '../../vendored/brepjs/operations/jointFns.js';
+import type { AssemblyTransform } from '../../runtime-state.js';
+import type { AssemblyVec3 } from './types.js';
+/** brepjs 四元数 [w,x,y,z]。 */
+export type BrepjsQuat = readonly [number, number, number, number];
+/** faijs 四元数 [x,y,z,w]。 */
+export type FaijsQuat = [number, number, number, number];
+/**
+ * brepjs [w,x,y,z] → faijs [x,y,z,w]（分量换序，不改变旋转本身）。
+ * @param q - the brepjs-order quaternion.
+ * @returns the faijs-order quaternion.
+ */
+export declare function fromBrepjsQuat(q: BrepjsQuat): FaijsQuat;
+/**
+ * faijs [x,y,z,w] → brepjs [w,x,y,z]。
+ * @param q - the faijs-order quaternion.
+ * @returns the brepjs-order quaternion.
+ */
+export declare function toBrepjsQuat(q: FaijsQuat): BrepjsQuat;
+/**
+ * 四元数 → 旋转矩阵（3x3, row-major；brepjs 位姿换算唯一入口）。
+ * @param q - the faijs-order quaternion.
+ * @returns the 9-component row-major rotation matrix.
+ */
+export declare function quaternionToMatrix3(q: FaijsQuat): number[];
+/** brepjs 单节点位姿（position + [w,x,y,z] 旋转）。 */
+export interface SolverPose {
+    position: readonly [number, number, number];
+    rotation: readonly [number, number, number, number];
+}
+/**
+ * brepjs 位姿 → faijs AssemblyTransform（§4.3(b) 换算；T2 锁定）。
+ *
+ * @param pose - the solver pose (p' = R·p + position).
+ * @param pivot - rotation pivot in faijs model (convention: the dependent entity's origin).
+ * @param index - member index (filled by the caller).
+ * @returns the AssemblyTransform with quaternion/pivot/translation/rotationMatrix.
+ */
+export declare function poseToAssemblyTransform(pose: SolverPose, pivot: AssemblyVec3, index: number): AssemblyTransform;
+/**
+ * brepjs FK 位姿（JointPose = { position, rotation: [w,x,y,z] }）→ faijs AssemblyTransform。
+ *
+ * brepjs 前向运动学的位姿是「绕原点整体模型」（p' = R·p + position），与约束求解的
+ * pivot 换算同式——故 pivot = [0,0,0]、translation = pose.position。旋转经
+ * fromBrepjsQuat 换序为 faijs [x,y,z,w]；rotationMatrix 与其它变换同源。
+ *
+ * @param pose - the forward-kinematics pose (p' = R·p + position).
+ * @param index - member index (filled by the caller).
+ * @returns the AssemblyTransform with zero pivot and the FK position as translation.
+ */
+export declare function jointPoseToAssemblyTransform(pose: JointPose, index: number): AssemblyTransform;
+/**
+ * 判定一个位姿是否为恒等（锚定/链根成员：跳过输出，引擎不做无谓重算）。
+ * @param pose - the solver pose.
+ * @returns true when the pose is exactly identity.
+ */
+export declare function isIdentityPose(pose: SolverPose): boolean;
+/**
+ * 供 solve.ts 记录 pivot 用的 dependent 实体 origin 读取。
+ * @param e - the solver entity.
+ * @returns a copy of the entity origin.
+ */
+export declare function entityOrigin(e: SolverEntity): AssemblyVec3;
+/** brepjs quatRotate 的再导出（rotate by [w,x,y,z] quat）——测试与换算共用。 */
+export { quatRotate };
+//# sourceMappingURL=pose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pose.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/pose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,4BAA4B;AAC5B,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAClE,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,UAAU,CAErD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,EAAE,CAU1D;AAUD,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CACpD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAe/G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAU9F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAKxD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAE1D;AAED,iEAAiE;AACjE,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/api/assembly/pose.js

@@ -0,0 +1,116 @@
+/**
+ * api/assembly/pose — 位姿转换契约（P1，方案 §4.3）
+ *
+ * brepjs 与 faijs 的位姿模型两处不一致，转换收口在本模块（禁止别处手写 q[0]/q[3]）：
+ * (a) 四元数分量顺序：brepjs [w,x,y,z] ↔ faijs [x,y,z,w]；
+ * (b) pivot 语义：brepjs `p' = R·p + position`（绕原点）↔
+ *     faijs `p' = R·(p − pivot) + pivot + translation`。
+ *     令 pivot = dependent 实体 origin（单约束场景），二者等价：
+ *     translation = position − pivot + R·pivot。
+ */
+import { quatRotate } from '../../vendored/brepjs/utils/quaternion.js';
+/**
+ * brepjs [w,x,y,z] → faijs [x,y,z,w]（分量换序，不改变旋转本身）。
+ * @param q - the brepjs-order quaternion.
+ * @returns the faijs-order quaternion.
+ */
+export function fromBrepjsQuat(q) {
+    return [q[1], q[2], q[3], q[0]];
+}
+/**
+ * faijs [x,y,z,w] → brepjs [w,x,y,z]。
+ * @param q - the faijs-order quaternion.
+ * @returns the brepjs-order quaternion.
+ */
+export function toBrepjsQuat(q) {
+    return [q[3], q[0], q[1], q[2]];
+}
+/**
+ * 四元数 → 旋转矩阵（3x3, row-major；brepjs 位姿换算唯一入口）。
+ * @param q - the faijs-order quaternion.
+ * @returns the 9-component row-major rotation matrix.
+ */
+export function quaternionToMatrix3(q) {
+    const [x, y, z, w] = q;
+    const xx = x * x, yy = y * y, zz = z * z;
+    const xy = x * y, xz = x * z, yz = y * z;
+    const wx = w * x, wy = w * y, wz = w * z;
+    return [
+        1 - 2 * (yy + zz), 2 * (xy - wz), 2 * (xz + wy),
+        2 * (xy + wz), 1 - 2 * (xx + zz), 2 * (yz - wx),
+        2 * (xz - wy), 2 * (yz + wx), 1 - 2 * (xx + yy),
+    ];
+}
+function mat3MulVec(m, v) {
+    return [
+        m[0] * v[0] + m[1] * v[1] + m[2] * v[2],
+        m[3] * v[0] + m[4] * v[1] + m[5] * v[2],
+        m[6] * v[0] + m[7] * v[1] + m[8] * v[2],
+    ];
+}
+/**
+ * brepjs 位姿 → faijs AssemblyTransform（§4.3(b) 换算；T2 锁定）。
+ *
+ * @param pose - the solver pose (p' = R·p + position).
+ * @param pivot - rotation pivot in faijs model (convention: the dependent entity's origin).
+ * @param index - member index (filled by the caller).
+ * @returns the AssemblyTransform with quaternion/pivot/translation/rotationMatrix.
+ */
+export function poseToAssemblyTransform(pose, pivot, index) {
+    const q = fromBrepjsQuat(pose.rotation);
+    const m = quaternionToMatrix3(q);
+    const rp = mat3MulVec(m, pivot);
+    return {
+        index,
+        quaternion: q,
+        pivot,
+        translation: [
+            pose.position[0] - pivot[0] + rp[0],
+            pose.position[1] - pivot[1] + rp[1],
+            pose.position[2] - pivot[2] + rp[2],
+        ],
+        rotationMatrix: m,
+    };
+}
+/**
+ * brepjs FK 位姿（JointPose = { position, rotation: [w,x,y,z] }）→ faijs AssemblyTransform。
+ *
+ * brepjs 前向运动学的位姿是「绕原点整体模型」（p' = R·p + position），与约束求解的
+ * pivot 换算同式——故 pivot = [0,0,0]、translation = pose.position。旋转经
+ * fromBrepjsQuat 换序为 faijs [x,y,z,w]；rotationMatrix 与其它变换同源。
+ *
+ * @param pose - the forward-kinematics pose (p' = R·p + position).
+ * @param index - member index (filled by the caller).
+ * @returns the AssemblyTransform with zero pivot and the FK position as translation.
+ */
+export function jointPoseToAssemblyTransform(pose, index) {
+    const q = fromBrepjsQuat(pose.rotation);
+    const m = quaternionToMatrix3(q);
+    return {
+        index,
+        quaternion: q,
+        pivot: [0, 0, 0],
+        translation: [pose.position[0], pose.position[1], pose.position[2]],
+        rotationMatrix: m,
+    };
+}
+/**
+ * 判定一个位姿是否为恒等（锚定/链根成员：跳过输出，引擎不做无谓重算）。
+ * @param pose - the solver pose.
+ * @returns true when the pose is exactly identity.
+ */
+export function isIdentityPose(pose) {
+    return (pose.position[0] === 0 && pose.position[1] === 0 && pose.position[2] === 0 &&
+        pose.rotation[0] === 1 && pose.rotation[1] === 0 && pose.rotation[2] === 0 && pose.rotation[3] === 0);
+}
+/**
+ * 供 solve.ts 记录 pivot 用的 dependent 实体 origin 读取。
+ * @param e - the solver entity.
+ * @returns a copy of the entity origin.
+ */
+export function entityOrigin(e) {
+    return [e.origin[0], e.origin[1], e.origin[2]];
+}
+/** brepjs quatRotate 的再导出（rotate by [w,x,y,z] quat）——测试与换算共用。 */
+export { quatRotate };
+//# sourceMappingURL=pose.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pose.js","sourceRoot":"","sources":["../../../src/api/assembly/pose.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/pose — 位姿转换契约（P1，方案 §4.3）\n *\n * brepjs 与 faijs 的位姿模型两处不一致，转换收口在本模块（禁止别处手写 q[0]/q[3]）：\n * (a) 四元数分量顺序：brepjs [w,x,y,z] ↔ faijs [x,y,z,w]；\n * (b) pivot 语义：brepjs `p' = R·p + position`（绕原点）↔\n *     faijs `p' = R·(p − pivot) + pivot + translation`。\n *     令 pivot = dependent 实体 origin（单约束场景），二者等价：\n *     translation = position − pivot + R·pivot。\n */\n\nimport type { SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter'\nimport { quatRotate } from '../../vendored/brepjs/utils/quaternion'\nimport type { JointPose } from '../../vendored/brepjs/operations/jointFns'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport type { AssemblyVec3 } from './types'\n\n/** brepjs 四元数 [w,x,y,z]。 */\nexport type BrepjsQuat = readonly [number, number, number, number]\n/** faijs 四元数 [x,y,z,w]。 */\nexport type FaijsQuat = [number, number, number, number]\n\n/**\n * brepjs [w,x,y,z] → faijs [x,y,z,w]（分量换序，不改变旋转本身）。\n * @param q - the brepjs-order quaternion.\n * @returns the faijs-order quaternion.\n */\nexport function fromBrepjsQuat(q: BrepjsQuat): FaijsQuat {\n  return [q[1], q[2], q[3], q[0]]\n}\n\n/**\n * faijs [x,y,z,w] → brepjs [w,x,y,z]。\n * @param q - the faijs-order quaternion.\n * @returns the brepjs-order quaternion.\n */\nexport function toBrepjsQuat(q: FaijsQuat): BrepjsQuat {\n  return [q[3], q[0], q[1], q[2]]\n}\n\n/**\n * 四元数 → 旋转矩阵（3x3, row-major；brepjs 位姿换算唯一入口）。\n * @param q - the faijs-order quaternion.\n * @returns the 9-component row-major rotation matrix.\n */\nexport function quaternionToMatrix3(q: FaijsQuat): number[] {\n  const [x, y, z, w] = q\n  const xx = x * x, yy = y * y, zz = z * z\n  const xy = x * y, xz = x * z, yz = y * z\n  const wx = w * x, wy = w * y, wz = w * z\n  return [\n    1 - 2 * (yy + zz), 2 * (xy - wz), 2 * (xz + wy),\n    2 * (xy + wz), 1 - 2 * (xx + zz), 2 * (yz - wx),\n    2 * (xz - wy), 2 * (yz + wx), 1 - 2 * (xx + yy),\n  ]\n}\n\nfunction mat3MulVec(m: number[], v: AssemblyVec3): AssemblyVec3 {\n  return [\n    m[0] * v[0] + m[1] * v[1] + m[2] * v[2],\n    m[3] * v[0] + m[4] * v[1] + m[5] * v[2],\n    m[6] * v[0] + m[7] * v[1] + m[8] * v[2],\n  ]\n}\n\n/** brepjs 单节点位姿（position + [w,x,y,z] 旋转）。 */\nexport interface SolverPose {\n  position: readonly [number, number, number]\n  rotation: readonly [number, number, number, number]\n}\n\n/**\n * brepjs 位姿 → faijs AssemblyTransform（§4.3(b) 换算；T2 锁定）。\n *\n * @param pose - the solver pose (p' = R·p + position).\n * @param pivot - rotation pivot in faijs model (convention: the dependent entity's origin).\n * @param index - member index (filled by the caller).\n * @returns the AssemblyTransform with quaternion/pivot/translation/rotationMatrix.\n */\nexport function poseToAssemblyTransform(pose: SolverPose, pivot: AssemblyVec3, index: number): AssemblyTransform {\n  const q = fromBrepjsQuat(pose.rotation)\n  const m = quaternionToMatrix3(q)\n  const rp = mat3MulVec(m, pivot)\n  return {\n    index,\n    quaternion: q,\n    pivot,\n    translation: [\n      pose.position[0] - pivot[0] + rp[0],\n      pose.position[1] - pivot[1] + rp[1],\n      pose.position[2] - pivot[2] + rp[2],\n    ],\n    rotationMatrix: m,\n  }\n}\n\n/**\n * brepjs FK 位姿（JointPose = { position, rotation: [w,x,y,z] }）→ faijs AssemblyTransform。\n *\n * brepjs 前向运动学的位姿是「绕原点整体模型」（p' = R·p + position），与约束求解的\n * pivot 换算同式——故 pivot = [0,0,0]、translation = pose.position。旋转经\n * fromBrepjsQuat 换序为 faijs [x,y,z,w]；rotationMatrix 与其它变换同源。\n *\n * @param pose - the forward-kinematics pose (p' = R·p + position).\n * @param index - member index (filled by the caller).\n * @returns the AssemblyTransform with zero pivot and the FK position as translation.\n */\nexport function jointPoseToAssemblyTransform(pose: JointPose, index: number): AssemblyTransform {\n  const q = fromBrepjsQuat(pose.rotation)\n  const m = quaternionToMatrix3(q)\n  return {\n    index,\n    quaternion: q,\n    pivot: [0, 0, 0],\n    translation: [pose.position[0], pose.position[1], pose.position[2]],\n    rotationMatrix: m,\n  }\n}\n\n/**\n * 判定一个位姿是否为恒等（锚定/链根成员：跳过输出，引擎不做无谓重算）。\n * @param pose - the solver pose.\n * @returns true when the pose is exactly identity.\n */\nexport function isIdentityPose(pose: SolverPose): boolean {\n  return (\n    pose.position[0] === 0 && pose.position[1] === 0 && pose.position[2] === 0 &&\n    pose.rotation[0] === 1 && pose.rotation[1] === 0 && pose.rotation[2] === 0 && pose.rotation[3] === 0\n  )\n}\n\n/**\n * 供 solve.ts 记录 pivot 用的 dependent 实体 origin 读取。\n * @param e - the solver entity.\n * @returns a copy of the entity origin.\n */\nexport function entityOrigin(e: SolverEntity): AssemblyVec3 {\n  return [e.origin[0], e.origin[1], e.origin[2]]\n}\n\n/** brepjs quatRotate 的再导出（rotate by [w,x,y,z] quat）——测试与换算共用。 */\nexport { quatRotate }\n"]}

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

@@ -0,0 +1,55 @@
+/**
+ * api/assembly/preview — 装配约束预览纯函数入口（P2-f3，方案 §2.3）
+ *
+ * 动机：3d_editor 预览需要**与执行同源**的轻量入口（P2-f5 已删除旧预览专用数学）；
+ *
+ * 同源性保证：内部复用 lowerEntities（与 lowerStructuralConstraint 同编码规则）
+ * 与 vendored brepjs solveConstraints——不另写数学。
+ *
+ * **输入约定**：一律是"未编码"的实体（SolverEntity，纯数据）——
+ * 面 → {type:'plane', origin:center, normal}，圆柱/圆锥面与边 →
+ * {type:'axis', origin, direction}，点 → {type:'point', origin}；
+ * `mate`/`align` 的 flip 由 solvePreview 内部负责（mate：dep 侧法向取反；
+ * align：不取反），宿主不需要知道自己该不该 flip。
+ *
+ * 仅支持"恰好定位一个 dependent"的单条约束；`fixed`（无位移语义）与
+ * `parallel`/`perpendicular`（请用 `angle` 0/90 显式表达）不支持，报错。
+ */
+import type { SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter.js';
+import type { AssemblyTransform } from '../../runtime-state.js';
+import type { AssemblyVec3 } from './types.js';
+/** 预览支持的约束类型（fixed 无位移语义 → 抛错；parallel/perpendicular → angle 糖）。 */
+export type PreviewConstraintType = 'mate' | 'align' | 'coincident' | 'concentric' | 'distance' | 'angle';
+/**
+ * 单约束预览：给定两条实体的几何（SolverEntity，纯数据），
+ * 走与 solveAssembly 完全相同的 lower → solveConstraints 链路，
+ * 返回 dependent 侧成员的位姿（AssemblyTransform，index 固定 -1，
+ * pivot = dep 实体 origin）。
+ *
+ * @param type - the constraint type.
+ * @param refEntity - the reference-side solver entity.
+ * @param depEntity - the dependent-side solver entity.
+ * @param value - distance/angle 用（定距 mm / 夹角 deg）。
+ * @returns the dependent-side AssemblyTransform (index = -1).
+ * @throws Error on entity type mismatch / non-convergence / dep not positioned.
+ */
+export declare function solvePreview(type: PreviewConstraintType, refEntity: SolverEntity, depEntity: SolverEntity, value?: number): AssemblyTransform;
+/**
+ * 宿主拾取数据 → SolverEntity（预览时几何就在手上，不经过 TopoRef 解析）。
+ *
+ * @param g - 宿主拾取的几何数据（plane/axis/point，带 kind 判别）。
+ * @returns 可供求解器消解的 SolverEntity（plane/axis/point）。
+ */
+export declare function entityFromGeometry(g: {
+    kind: 'plane';
+    center: AssemblyVec3;
+    normal: AssemblyVec3;
+} | {
+    kind: 'axis';
+    origin: AssemblyVec3;
+    direction: AssemblyVec3;
+} | {
+    kind: 'point';
+    origin: AssemblyVec3;
+}): SolverEntity;
+//# sourceMappingURL=preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAI5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAA;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,qBAAqB,EAC3B,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,YAAY,EACvB,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB,CAgBnB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EACG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAC1C,YAAY,CASd"}

package/dist/api/assembly/preview.js

@@ -0,0 +1,61 @@
+/**
+ * api/assembly/preview — 装配约束预览纯函数入口（P2-f3，方案 §2.3）
+ *
+ * 动机：3d_editor 预览需要**与执行同源**的轻量入口（P2-f5 已删除旧预览专用数学）；
+ *
+ * 同源性保证：内部复用 lowerEntities（与 lowerStructuralConstraint 同编码规则）
+ * 与 vendored brepjs solveConstraints——不另写数学。
+ *
+ * **输入约定**：一律是"未编码"的实体（SolverEntity，纯数据）——
+ * 面 → {type:'plane', origin:center, normal}，圆柱/圆锥面与边 →
+ * {type:'axis', origin, direction}，点 → {type:'point', origin}；
+ * `mate`/`align` 的 flip 由 solvePreview 内部负责（mate：dep 侧法向取反；
+ * align：不取反），宿主不需要知道自己该不该 flip。
+ *
+ * 仅支持"恰好定位一个 dependent"的单条约束；`fixed`（无位移语义）与
+ * `parallel`/`perpendicular`（请用 `angle` 0/90 显式表达）不支持，报错。
+ */
+import { solveConstraints } from '../../vendored/brepjs/kernel/solverAdapter.js';
+import { lowerEntities } from './lower.js';
+import { poseToAssemblyTransform } from './pose.js';
+/**
+ * 单约束预览：给定两条实体的几何（SolverEntity，纯数据），
+ * 走与 solveAssembly 完全相同的 lower → solveConstraints 链路，
+ * 返回 dependent 侧成员的位姿（AssemblyTransform，index 固定 -1，
+ * pivot = dep 实体 origin）。
+ *
+ * @param type - the constraint type.
+ * @param refEntity - the reference-side solver entity.
+ * @param depEntity - the dependent-side solver entity.
+ * @param value - distance/angle 用（定距 mm / 夹角 deg）。
+ * @returns the dependent-side AssemblyTransform (index = -1).
+ * @throws Error on entity type mismatch / non-convergence / dep not positioned.
+ */
+export function solvePreview(type, refEntity, depEntity, value) {
+    const { constraint, depOrigin } = lowerEntities(type, { node: '__ref', entity: refEntity }, { node: '__dep', entity: depEntity }, value);
+    const r = solveConstraints(['__ref', '__dep'], [constraint]);
+    if (!r.converged) {
+        throw new Error(`[assembly:preview] constraint did not converge; unsupported: ${r.unsupported.join(', ') || '(no detail)'}`);
+    }
+    const pose = r.transforms.get('__dep');
+    if (!pose)
+        throw new Error('[assembly:preview] dependent was not positioned');
+    return poseToAssemblyTransform(pose, depOrigin ?? [0, 0, 0], -1);
+}
+/**
+ * 宿主拾取数据 → SolverEntity（预览时几何就在手上，不经过 TopoRef 解析）。
+ *
+ * @param g - 宿主拾取的几何数据（plane/axis/point，带 kind 判别）。
+ * @returns 可供求解器消解的 SolverEntity（plane/axis/point）。
+ */
+export function entityFromGeometry(g) {
+    switch (g.kind) {
+        case 'plane':
+            return { type: 'plane', origin: g.center, normal: g.normal };
+        case 'axis':
+            return { type: 'axis', origin: g.origin, direction: g.direction };
+        case 'point':
+            return { type: 'point', origin: g.origin };
+    }
+}
+//# sourceMappingURL=preview.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../src/api/assembly/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAA;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA;AAOhD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,IAA2B,EAC3B,SAAuB,EACvB,SAAuB,EACvB,KAAc;IAEd,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,aAAa,CAC7C,IAAI,EACJ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EACpC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EACpC,KAAK,CACN,CAAA;IACD,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,UAA8B,CAAC,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,gEAAgE,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,aAAa,EAAE,CAC5G,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACtC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IAC7E,OAAO,uBAAuB,CAAC,IAAI,EAAE,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,CAG2C;IAE3C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;QAC9D,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAA;QACnE,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;IAC9C,CAAC;AACH,CAAC","sourcesContent":["/**\n * api/assembly/preview — 装配约束预览纯函数入口（P2-f3，方案 §2.3）\n *\n * 动机：3d_editor 预览需要**与执行同源**的轻量入口（P2-f5 已删除旧预览专用数学）；\n *\n * 同源性保证：内部复用 lowerEntities（与 lowerStructuralConstraint 同编码规则）\n * 与 vendored brepjs solveConstraints——不另写数学。\n *\n * **输入约定**：一律是\"未编码\"的实体（SolverEntity，纯数据）——\n * 面 → {type:'plane', origin:center, normal}，圆柱/圆锥面与边 →\n * {type:'axis', origin, direction}，点 → {type:'point', origin}；\n * `mate`/`align` 的 flip 由 solvePreview 内部负责（mate：dep 侧法向取反；\n * align：不取反），宿主不需要知道自己该不该 flip。\n *\n * 仅支持\"恰好定位一个 dependent\"的单条约束；`fixed`（无位移语义）与\n * `parallel`/`perpendicular`（请用 `angle` 0/90 显式表达）不支持，报错。\n */\n\nimport type { SolverConstraint, SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { solveConstraints } from '../../vendored/brepjs/kernel/solverAdapter'\nimport { lowerEntities } from './lower'\nimport { poseToAssemblyTransform } from './pose'\nimport type { AssemblyVec3 } from './types'\n\n/** 预览支持的约束类型（fixed 无位移语义 → 抛错；parallel/perpendicular → angle 糖）。 */\nexport type PreviewConstraintType =\n  | 'mate' | 'align' | 'coincident' | 'concentric' | 'distance' | 'angle'\n\n/**\n * 单约束预览：给定两条实体的几何（SolverEntity，纯数据），\n * 走与 solveAssembly 完全相同的 lower → solveConstraints 链路，\n * 返回 dependent 侧成员的位姿（AssemblyTransform，index 固定 -1，\n * pivot = dep 实体 origin）。\n *\n * @param type - the constraint type.\n * @param refEntity - the reference-side solver entity.\n * @param depEntity - the dependent-side solver entity.\n * @param value - distance/angle 用（定距 mm / 夹角 deg）。\n * @returns the dependent-side AssemblyTransform (index = -1).\n * @throws Error on entity type mismatch / non-convergence / dep not positioned.\n */\nexport function solvePreview(\n  type: PreviewConstraintType,\n  refEntity: SolverEntity,\n  depEntity: SolverEntity,\n  value?: number,\n): AssemblyTransform {\n  const { constraint, depOrigin } = lowerEntities(\n    type,\n    { node: '__ref', entity: refEntity },\n    { node: '__dep', entity: depEntity },\n    value,\n  )\n  const r = solveConstraints(['__ref', '__dep'], [constraint as SolverConstraint])\n  if (!r.converged) {\n    throw new Error(\n      `[assembly:preview] constraint did not converge; unsupported: ${r.unsupported.join(', ') || '(no detail)'}`,\n    )\n  }\n  const pose = r.transforms.get('__dep')\n  if (!pose) throw new Error('[assembly:preview] dependent was not positioned')\n  return poseToAssemblyTransform(pose, depOrigin ?? [0, 0, 0], -1)\n}\n\n/**\n * 宿主拾取数据 → SolverEntity（预览时几何就在手上，不经过 TopoRef 解析）。\n *\n * @param g - 宿主拾取的几何数据（plane/axis/point，带 kind 判别）。\n * @returns 可供求解器消解的 SolverEntity（plane/axis/point）。\n */\nexport function entityFromGeometry(\n  g:\n    | { kind: 'plane'; center: AssemblyVec3; normal: AssemblyVec3 }\n    | { kind: 'axis'; origin: AssemblyVec3; direction: AssemblyVec3 }\n    | { kind: 'point'; origin: AssemblyVec3 },\n): SolverEntity {\n  switch (g.kind) {\n    case 'plane':\n      return { type: 'plane', origin: g.center, normal: g.normal }\n    case 'axis':\n      return { type: 'axis', origin: g.origin, direction: g.direction }\n    case 'point':\n      return { type: 'point', origin: g.origin }\n  }\n}"]}