@faicad/faijs 0.29.3 → 0.30.9

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

@@ -1 +1 @@
-{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/api/assembly/entities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/entities — EntityRef → SolverEntity 实体抽取（P1，方案 §3.6 / §5.2）\n *\n * 三要素范式（与 chamfer 同构，方案 §3.5）：\n * 1. 引用可序列化：EntityRef 进 .fai.js；\n * 2. 解析在执行期：TopoRef 复用 topo-resolve 的解析通道（BREP 现场 / mesh 行快照）；\n * 3. 句柄是瞬态：解析出的几何立即转成纯数据 SolverEntity，句柄不跨语句。\n *\n * 输出契约对齐 brepjs solverAdapter 的 SolverEntity：{ type: 'plane'|'axis'|'point',\n * origin, normal?/direction? }。dependent 侧填本地坐标（部件自身坐标系），\n * reference 侧世界变换由 solverAdapter 的 transformEntity 负责——本层不做。\n *\n * 缺轴（mesh 行快照无宿主注入的 axis、sphere 等无轴面类型）→ 抛\n * E_TOPO_NOT_FOUND（方案 R4/P0 验收③：绝不静默降级）。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { PartName } from '../../identity'\nimport type { SolverEntity } from './solvers/types'\nimport { TopoRefError, type AxisHint } from '../../topology/naming'\nimport { resolveTopoRef, captureEdgeAxis, captureFaceHint } from '../../topology/naming'\nimport {\n  buildShapeResolutionContext,\n  buildEdgeResolutionContext,\n  resolveFaceGeometry,\n  type ResolvedFaceGeometry,\n} from '../topo-resolve'\nimport type { EntityRef, AssemblyVec3 } from './types'\n\n/** 实体抽取环境：内核（null = mesh/primitive 行快照路径）+ 成员查找。 */\nexport interface EntityResolutionEnv {\n  kernel: BrepEngineApi | null\n  /** part 变量名 → 成员 Shape。 */\n  memberOf: (part: string) => Shape | undefined\n}\n\n/** 无轴可用的报错信息后缀（E_TOPO_NOT_FOUND）。 */\nfunction missingAxisReason(geom: ResolvedFaceGeometry): string {\n  return `face needs an axis (surfaceType=${geom.surfaceType ?? 'unknown'}) but none is available ` +\n    `(BREP path: captureFaceHint; mesh path: host must inject axis into the naming row)`\n}\n\n/**\n * 面几何 → SolverEntity（方案 §5.2 抽取规则表）。\n * 平面 → plane；圆柱/圆锥（有轴）→ axis；其它/缺轴 → E_TOPO_NOT_FOUND。\n *\n * @param geom - the resolved face geometry (live BREP or mesh row snapshot).\n * @returns the solver entity (plane or axis).\n * @throws TopoRefError with code E_TOPO_NOT_FOUND when the surface has no usable axis or is unsupported.\n */\nexport function faceGeometryToSolverEntity(geom: ResolvedFaceGeometry): SolverEntity {\n  const st = geom.surfaceType\n  if (st === 'cylinder' || st === 'cone') {\n    if (!geom.axis) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', missingAxisReason(geom))\n    }\n    return { type: 'axis', origin: geom.axis.origin, direction: geom.axis.direction }\n  }\n  if (!st || st === 'plane') {\n    return { type: 'plane', origin: geom.center, normal: geom.normal }\n  }\n  throw new TopoRefError(\n    'E_TOPO_NOT_FOUND',\n    'face',\n    `unsupported surface type for an assembly entity: ${st}` +\n      (geom.axis ? '' : ` (${missingAxisReason(geom)})`),\n  )\n}\n\n/** 快照形态 FaceRef → ResolvedFaceGeometry（无 axis——贴合语义只需 center+normal）。 */\nfunction snapshotFaceGeometry(face: { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 }): ResolvedFaceGeometry {\n  return { surfaceType: face.surfaceType, center: face.center, normal: face.normal }\n}\n\n/**\n * 解析一个 EntityRef 的面几何（mate/align 降级路径用：只需 center + normal，\n * 圆柱面轴不参与贴合——方案 §3.7.4 适用边界）。\n *\n * @param ref - the entity reference (must be a face reference).\n * @param env - the resolution environment.\n * @returns the resolved face geometry.\n * @throws Error when the ref is not a face reference or the part is unknown.\n */\nexport function resolveFaceGeometryOfRef(ref: EntityRef, env: EntityResolutionEnv): ResolvedFaceGeometry {\n  if (!('face' in ref)) {\n    throw new Error('[assembly] mate/align constraints require face references on both sides')\n  }\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n  const face = ref.face as { topoRef?: unknown; center?: AssemblyVec3; normal?: AssemblyVec3; surfaceType?: string }\n  if (face.topoRef) {\n    return resolveFaceGeometry(env.kernel, shape, face.topoRef as Parameters<typeof resolveFaceGeometry>[2])\n  }\n  if (!face.center || !face.normal) {\n    throw new Error('[assembly] face snapshot requires center and normal')\n  }\n  return snapshotFaceGeometry(face as { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 })\n}\n\n/** 边 TopoRef → 轴（BREP 现场；mesh 无邻接能力 → E_TOPO_NOT_FOUND）。 */\nfunction resolveEdgeAxisFromTopoRef(\n  kernel: BrepEngineApi,\n  shape: Shape,\n  edgeTopoRef: Parameters<typeof resolveTopoRef>[0],\n  part: PartName,\n): AxisHint {\n  const ctx = buildEdgeResolutionContext(kernel, shape)\n  if (!ctx) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge entity needs a BREP naming context (part=${part}); mesh parts have no edge adjacency`,\n    )\n  }\n  const resolved = resolveTopoRef(edgeTopoRef, ctx)\n  const entry = ctx.edges?.[resolved.ordinal - 1]\n  if (!entry?.handle) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `resolved edge ordinal ${resolved.ordinal} has no live handle (part=${part})`,\n    )\n  }\n  const axis = captureEdgeAxis(kernel, entry.handle)\n  if (!axis) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge ordinal ${resolved.ordinal} is not a line or circle — no axis entity available`,\n    )\n  }\n  return axis\n}\n\n/**\n * 解析一个 EntityRef → SolverEntity（coincident/concentric/distance/angle 直译路径）。\n *\n * @param ref - the entity reference.\n * @param env - the resolution environment.\n * @returns the solver entity (pure data).\n * @throws TopoRefError / Error on unresolvable or unsupported references.\n */\nexport function resolveSolverEntity(ref: EntityRef, env: EntityResolutionEnv): SolverEntity {\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n\n  if ('point' in ref) {\n    return { type: 'point', origin: ref.point }\n  }\n  if ('face' in ref) {\n    return faceGeometryToSolverEntity(resolveFaceGeometryOfRef(ref, env))\n  }\n  if ('faceIndex' in ref) {\n    // 序号简写（1 起，调试用）：直接按 ordinal 取候选面几何（不走 TopoRef 打分）\n    const ctx = buildShapeResolutionContext(env.kernel, shape)\n    if (!ctx) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} has no naming context on part ${ref.part}`,\n      )\n    }\n    const entry = ctx.faces[ref.faceIndex - 1]\n    if (!entry) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} out of range (part ${ref.part} has ${ctx.faces.length} faces)`,\n      )\n    }\n    return faceGeometryToSolverEntity(faceGeometryFromContextEntry(env, entry, ref.part))\n  }\n  // edge 引用\n  const edge = ref.edge as { topoRef?: unknown; axis?: { origin: AssemblyVec3; direction: AssemblyVec3 } }\n  if (edge.axis) {\n    return { type: 'axis', origin: edge.axis.origin, direction: edge.axis.direction }\n  }\n  if (!env.kernel) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge TopoRef needs a live kernel (part=${ref.part}); mesh path supports only axis snapshots`,\n    )\n  }\n  const axis = resolveEdgeAxisFromTopoRef(env.kernel, shape, edge.topoRef as Parameters<typeof resolveTopoRef>[0], ref.part)\n  return { type: 'axis', origin: axis.origin, direction: axis.direction }\n}\n\n/**\n * faceIndex 简写的面几何（从解析上下文候选行直接取）：\n * BREP 候选（活句柄）→ captureFaceHint 现场；行快照候选 → 行几何。\n */\nfunction faceGeometryFromContextEntry(\n  env: EntityResolutionEnv,\n  entry: { handle?: unknown; row?: unknown },\n  part: PartName,\n): ResolvedFaceGeometry {\n  if (entry.handle && env.kernel) {\n    const hint = captureFaceHint(env.kernel, entry.handle as Parameters<typeof captureFaceHint>[1])\n    return {\n      surfaceType: hint.surfaceType,\n      center: hint.center ?? [0, 0, 0],\n      normal: hint.normal ?? [0, 0, 1],\n      ...(hint.axis ? { axis: hint.axis } : {}),\n    }\n  }\n  const hint = entry.row as\n    | { surfaceType?: string; center?: AssemblyVec3; normal?: AssemblyVec3; axis?: AxisHint }\n    | undefined\n  if (!hint?.center || !hint?.normal) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex row has no geometry (part=${part})`)\n  }\n  return {\n    surfaceType: hint.surfaceType,\n    center: hint.center,\n    normal: hint.normal,\n    ...(hint.axis ? { axis: hint.axis } : {}),\n  }\n}\n"]}
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/api/assembly/entities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/entities — EntityRef → SolverEntity 实体抽取（P1，方案 §3.6 / §5.2）\n *\n * 三要素范式（与 chamfer 同构，方案 §3.5）：\n * 1. 引用可序列化：EntityRef 进 .fai.js；\n * 2. 解析在执行期：TopoRef 复用 topo-resolve 的解析通道（BREP 现场 / mesh 行快照）；\n * 3. 句柄是瞬态：解析出的几何立即转成纯数据 SolverEntity，句柄不跨语句。\n *\n * 输出契约对齐约束求解器的 SolverEntity：{ type: 'plane'|'axis'|'point',\n * origin, normal?/direction? }。dependent 侧填本地坐标（部件自身坐标系），\n * reference 侧世界变换由 solverAdapter 的 transformEntity 负责——本层不做。\n *\n * 缺轴（mesh 行快照无宿主注入的 axis、sphere 等无轴面类型）→ 抛\n * E_TOPO_NOT_FOUND（方案 R4/P0 验收③：绝不静默降级）。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { PartName } from '../../identity'\nimport type { SolverEntity } from './solvers/types'\nimport { TopoRefError, type AxisHint } from '../../topology/naming'\nimport { resolveTopoRef, captureEdgeAxis, captureFaceHint } from '../../topology/naming'\nimport {\n  buildShapeResolutionContext,\n  buildEdgeResolutionContext,\n  resolveFaceGeometry,\n  type ResolvedFaceGeometry,\n} from '../topo-resolve'\nimport type { EntityRef, AssemblyVec3 } from './types'\n\n/** 实体抽取环境：内核（null = mesh/primitive 行快照路径）+ 成员查找。 */\nexport interface EntityResolutionEnv {\n  kernel: BrepEngineApi | null\n  /** part 变量名 → 成员 Shape。 */\n  memberOf: (part: string) => Shape | undefined\n}\n\n/** 无轴可用的报错信息后缀（E_TOPO_NOT_FOUND）。 */\nfunction missingAxisReason(geom: ResolvedFaceGeometry): string {\n  return `face needs an axis (surfaceType=${geom.surfaceType ?? 'unknown'}) but none is available ` +\n    `(BREP path: captureFaceHint; mesh path: host must inject axis into the naming row)`\n}\n\n/**\n * 面几何 → SolverEntity（方案 §5.2 抽取规则表）。\n * 平面 → plane；圆柱/圆锥（有轴）→ axis；其它/缺轴 → E_TOPO_NOT_FOUND。\n *\n * @param geom - the resolved face geometry (live BREP or mesh row snapshot).\n * @returns the solver entity (plane or axis).\n * @throws TopoRefError with code E_TOPO_NOT_FOUND when the surface has no usable axis or is unsupported.\n */\nexport function faceGeometryToSolverEntity(geom: ResolvedFaceGeometry): SolverEntity {\n  const st = geom.surfaceType\n  if (st === 'cylinder' || st === 'cone') {\n    if (!geom.axis) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', missingAxisReason(geom))\n    }\n    return { type: 'axis', origin: geom.axis.origin, direction: geom.axis.direction }\n  }\n  if (!st || st === 'plane') {\n    return { type: 'plane', origin: geom.center, normal: geom.normal }\n  }\n  throw new TopoRefError(\n    'E_TOPO_NOT_FOUND',\n    'face',\n    `unsupported surface type for an assembly entity: ${st}` +\n      (geom.axis ? '' : ` (${missingAxisReason(geom)})`),\n  )\n}\n\n/** 快照形态 FaceRef → ResolvedFaceGeometry（无 axis——贴合语义只需 center+normal）。 */\nfunction snapshotFaceGeometry(face: { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 }): ResolvedFaceGeometry {\n  return { surfaceType: face.surfaceType, center: face.center, normal: face.normal }\n}\n\n/**\n * 解析一个 EntityRef 的面几何（mate/align 降级路径用：只需 center + normal，\n * 圆柱面轴不参与贴合——方案 §3.7.4 适用边界）。\n *\n * @param ref - the entity reference (must be a face reference).\n * @param env - the resolution environment.\n * @returns the resolved face geometry.\n * @throws Error when the ref is not a face reference or the part is unknown.\n */\nexport function resolveFaceGeometryOfRef(ref: EntityRef, env: EntityResolutionEnv): ResolvedFaceGeometry {\n  if (!('face' in ref)) {\n    throw new Error('[assembly] mate/align constraints require face references on both sides')\n  }\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n  const face = ref.face as { topoRef?: unknown; center?: AssemblyVec3; normal?: AssemblyVec3; surfaceType?: string }\n  if (face.topoRef) {\n    return resolveFaceGeometry(env.kernel, shape, face.topoRef as Parameters<typeof resolveFaceGeometry>[2])\n  }\n  if (!face.center || !face.normal) {\n    throw new Error('[assembly] face snapshot requires center and normal')\n  }\n  return snapshotFaceGeometry(face as { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 })\n}\n\n/** 边 TopoRef → 轴（BREP 现场；mesh 无邻接能力 → E_TOPO_NOT_FOUND）。 */\nfunction resolveEdgeAxisFromTopoRef(\n  kernel: BrepEngineApi,\n  shape: Shape,\n  edgeTopoRef: Parameters<typeof resolveTopoRef>[0],\n  part: PartName,\n): AxisHint {\n  const ctx = buildEdgeResolutionContext(kernel, shape)\n  if (!ctx) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge entity needs a BREP naming context (part=${part}); mesh parts have no edge adjacency`,\n    )\n  }\n  const resolved = resolveTopoRef(edgeTopoRef, ctx)\n  const entry = ctx.edges?.[resolved.ordinal - 1]\n  if (!entry?.handle) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `resolved edge ordinal ${resolved.ordinal} has no live handle (part=${part})`,\n    )\n  }\n  const axis = captureEdgeAxis(kernel, entry.handle)\n  if (!axis) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge ordinal ${resolved.ordinal} is not a line or circle — no axis entity available`,\n    )\n  }\n  return axis\n}\n\n/**\n * 解析一个 EntityRef → SolverEntity（coincident/concentric/distance/angle 直译路径）。\n *\n * @param ref - the entity reference.\n * @param env - the resolution environment.\n * @returns the solver entity (pure data).\n * @throws TopoRefError / Error on unresolvable or unsupported references.\n */\nexport function resolveSolverEntity(ref: EntityRef, env: EntityResolutionEnv): SolverEntity {\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n\n  if ('point' in ref) {\n    return { type: 'point', origin: ref.point }\n  }\n  if ('face' in ref) {\n    return faceGeometryToSolverEntity(resolveFaceGeometryOfRef(ref, env))\n  }\n  if ('faceIndex' in ref) {\n    // 序号简写（1 起，调试用）：直接按 ordinal 取候选面几何（不走 TopoRef 打分）\n    const ctx = buildShapeResolutionContext(env.kernel, shape)\n    if (!ctx) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} has no naming context on part ${ref.part}`,\n      )\n    }\n    const entry = ctx.faces[ref.faceIndex - 1]\n    if (!entry) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} out of range (part ${ref.part} has ${ctx.faces.length} faces)`,\n      )\n    }\n    return faceGeometryToSolverEntity(faceGeometryFromContextEntry(env, entry, ref.part))\n  }\n  // edge 引用\n  const edge = ref.edge as { topoRef?: unknown; axis?: { origin: AssemblyVec3; direction: AssemblyVec3 } }\n  if (edge.axis) {\n    return { type: 'axis', origin: edge.axis.origin, direction: edge.axis.direction }\n  }\n  if (!env.kernel) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge TopoRef needs a live kernel (part=${ref.part}); mesh path supports only axis snapshots`,\n    )\n  }\n  const axis = resolveEdgeAxisFromTopoRef(env.kernel, shape, edge.topoRef as Parameters<typeof resolveTopoRef>[0], ref.part)\n  return { type: 'axis', origin: axis.origin, direction: axis.direction }\n}\n\n/**\n * faceIndex 简写的面几何（从解析上下文候选行直接取）：\n * BREP 候选（活句柄）→ captureFaceHint 现场；行快照候选 → 行几何。\n */\nfunction faceGeometryFromContextEntry(\n  env: EntityResolutionEnv,\n  entry: { handle?: unknown; row?: unknown },\n  part: PartName,\n): ResolvedFaceGeometry {\n  if (entry.handle && env.kernel) {\n    const hint = captureFaceHint(env.kernel, entry.handle as Parameters<typeof captureFaceHint>[1])\n    return {\n      surfaceType: hint.surfaceType,\n      center: hint.center ?? [0, 0, 0],\n      normal: hint.normal ?? [0, 0, 1],\n      ...(hint.axis ? { axis: hint.axis } : {}),\n    }\n  }\n  const hint = entry.row as\n    | { surfaceType?: string; center?: AssemblyVec3; normal?: AssemblyVec3; axis?: AxisHint }\n    | undefined\n  if (!hint?.center || !hint?.normal) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex row has no geometry (part=${part})`)\n  }\n  return {\n    surfaceType: hint.surfaceType,\n    center: hint.center,\n    normal: hint.normal,\n    ...(hint.axis ? { axis: hint.axis } : {}),\n  }\n}\n"]}

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

@@ -3,7 +3,7 @@
  *
  * 分层（方案 §4.1）：normalize（规范化 + face_mate 兼容）→ lower（直译降级，
  * mate/align 寄生在 concentric 上）→ entities（TopoRef → SolverEntity，双链路）
- * → solve（委派 brepjs solveConstraints）→ pose（位姿转换契约）。
+ * → solve（core 自持 solveConstraints）→ pose（位姿转换契约）。
  */
 export * from './types.js';
 export * from './normalize.js';

package/dist/api/assembly/index.js

@@ -3,7 +3,7 @@
  *
  * 分层（方案 §4.1）：normalize（规范化 + face_mate 兼容）→ lower（直译降级，
  * mate/align 寄生在 concentric 上）→ entities（TopoRef → SolverEntity，双链路）
- * → solve（委派 brepjs solveConstraints）→ pose（位姿转换契约）。
+ * → solve（core 自持 solveConstraints）→ pose（位姿转换契约）。
  */
 export * from './types.js';
 export * from './normalize.js';

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

@@ -1 +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"]}
+{"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（core 自持 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

@@ -1,7 +1,7 @@
 /**
  * api/assembly/joints — 运动副声明与运动学解算（P3）
  *
- * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 vendored 工厂构造，
+ * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 brepjs 工厂构造，
  * 与 brepjs Joint.dofs 的组合顺序对齐：cylindrical → [rotation, translation]、
  * planar → [u, v, rotation]、spherical → [x, y, z]）。
  *
@@ -9,8 +9,8 @@
  * spherical 在 buildJoint 里显式抛错（绝不静默降级成单 DOF），待 per-DOF ranges
  * 启用（JointSpec.dofs 已按此预留）。
  *
- * 链路：JointSpec[] → buildJoint（vendored 工厂）→ buildKinematicTree（建树三步
- * + 校验）→ solveKinematics（vendored forwardKinematics）→ per-member 位姿。
+ * 链路：JointSpec[] → buildJoint（brepjs 工厂）→ buildKinematicTree（建树三步
+ * + 校验）→ solveKinematics（brepjs forwardKinematics）→ per-member 位姿。
  *
  * cad.* 查询函数（jointTrajectory / inverseKinematics / mechanismDOF）是无副作用
  * 纯函数：输入纯数据、输出纯数据，不挂在 assembly receiver 上。
@@ -33,7 +33,7 @@ export interface JointDofSpec {
 }
 /**
  * 可序列化运动副声明（.fai.js 对象字面量）。派生字段（dofs）由 buildJoint 内
- * vendored 工厂构造——脚本里只写纯数据。
+ * brepjs 工厂构造——脚本里只写纯数据。
  */
 export interface JointSpec {
     type: JointType;
@@ -74,18 +74,18 @@ export interface JointSpec {
 /**
  * 由 JointSpec 构造 brepjs Joint。
  *
- * revolute/prismatic 走 vendored 工厂（主 DOF 的 value 在工厂内 clamp 到
+ * revolute/prismatic 走 brepjs 工厂（主 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).
+ * @returns the 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
+ * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（brepjs
  * forwardKinematics 只接受单个根；多成员必须有唯一合成根）。
  *
  * 校验（求解前，绝不静默）：
@@ -119,7 +119,7 @@ export interface KinematicsSolveResult {
     kinematics: Record<string, KinematicsPose>;
 }
 /**
- * 运动学正解：buildKinematicTree → vendored forwardKinematics → per-member 位姿。
+ * 运动学正解：buildKinematicTree → brepjs forwardKinematics → per-member 位姿。
  *
  * 校验（求解前）：成员名空串 / parent-child ∈ members / child 唯一驱动（都收在
  * buildKinematicTree 内）；drive 键必须 ∈ joints 的 child 集（多余键是笔误，
@@ -160,8 +160,14 @@ export interface FaijsTrajectorySample {
  * 产出 steps+1 个采样（含两端点）；joints 缺省值在两端取存储值。
  * 无 endEffector 参数（关节空间插值，不追踪端点）。
  *
- * @param p - trajectory query parameters.
- * @returns the sampled trajectory (poses with faijs-order quaternions).
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name jointTrajectory
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns FaijsTrajectorySample[] 采样序列（steps+1 个，含两端点）。
+ * @param p - 轨迹查询参数。type:JointTrajectoryParams required:true
  */
 export declare function jointTrajectory(p: JointTrajectoryParams): FaijsTrajectorySample[];
 /** `cad.inverseKinematics({ joints, endEffector, target, options? })` 参数。 */
@@ -176,7 +182,7 @@ export interface InverseKinematicsParams {
     };
     options?: BrepjsIKOptions;
 }
-/** IK 结果（与 vendored IKResult 同构；values 键 = child 成员名）。 */
+/** IK 结果（与 brepjs IKResult 同构；values 键 = child 成员名）。 */
 export interface IKResult {
     values: Record<string, number[]>;
     converged: boolean;
@@ -188,8 +194,14 @@ export interface IKResult {
  * damped-least-squares IK：求使末端到达 target 的关节值。关节范围在每个迭代
  * clamp；不可达目标返回 converged:false 与最优配置。纯函数，无副作用。
  *
- * @param p - IK query parameters.
- * @returns the solved joint values plus convergence diagnostics.
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name inverseKinematics
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns IKResult 关节值 + 收敛诊断（converged / iterations / error）。
+ * @param p - IK 查询参数。type:InverseKinematicsParams required:true
  */
 export declare function inverseKinematics(p: InverseKinematicsParams): IKResult;
 /** `cad.mechanismDOF({ joints })` 参数。 */
@@ -200,8 +212,14 @@ export interface MechanismDOFParams {
  * `cad.mechanismDOF({ joints })` — 开链机构自由度 = 各 joint DOF 数之和
  * （revolute/prismatic 各 1；串联两 revolute = 2）。纯函数，无副作用。
  *
- * @param p - DOF query parameters.
- * @returns the mechanism's total degree of freedom.
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name mechanismDOF
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns number 机构总自由度。
+ * @param p - 自由度查询参数。type:MechanismDOFParams required:true
  */
 export declare function mechanismDOF(p: MechanismDOFParams): number;
 export type { JointPose, BrepjsIKOptions as IKOptions };

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

@@ -1 +1 @@
-{"version":3,"file":"joints.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/joints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAQL,KAAK,KAAK,EACV,KAAK,SAAS,EAEd,KAAK,SAAS,IAAI,eAAe,EAElC,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACzF,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAI3C,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEzF,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,IAAI,EAAE;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAA;IACvD,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,YAAY,EAAE,CAAA;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,YAAY,CAAA;IACzB,qEAAqE;IACrE,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;CAC3D;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAiCjD;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,YAAY,CAiC3F;AAID,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAA;IACtB,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAC3C;AAiBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,EAAE,SAAS,EAAE,EACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,qBAAqB,CA0BvB;AAID,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IACvC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IACrC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,CAAC,EAAE,MAAM,CAAA;IACT,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAChC,iBAAiB;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,qBAAqB,GAAG,qBAAqB,EAAE,CAgBjF;AAED,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,4DAA4D;IAC5D,MAAM,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;IACxD,OAAO,CAAC,EAAE,eAAe,CAAA;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAChC,SAAS,EAAE,OAAO,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,uBAAuB,GAAG,QAAQ,CActE;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAI1D;AAGD,YAAY,EAAE,SAAS,EAAE,eAAe,IAAI,SAAS,EAAE,CAAA"}
+{"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

@@ -1,7 +1,7 @@
 /**
  * api/assembly/joints — 运动副声明与运动学解算（P3）
  *
- * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 vendored 工厂构造，
+ * JointSpec 是 .fai.js 可序列化子集（派生字段 dofs 由 brepjs 工厂构造，
  * 与 brepjs Joint.dofs 的组合顺序对齐：cylindrical → [rotation, translation]、
  * planar → [u, v, rotation]、spherical → [x, y, z]）。
  *
@@ -9,8 +9,8 @@
  * spherical 在 buildJoint 里显式抛错（绝不静默降级成单 DOF），待 per-DOF ranges
  * 启用（JointSpec.dofs 已按此预留）。
  *
- * 链路：JointSpec[] → buildJoint（vendored 工厂）→ buildKinematicTree（建树三步
- * + 校验）→ solveKinematics（vendored forwardKinematics）→ per-member 位姿。
+ * 链路：JointSpec[] → buildJoint（brepjs 工厂）→ buildKinematicTree（建树三步
+ * + 校验）→ solveKinematics（brepjs forwardKinematics）→ per-member 位姿。
  *
  * cad.* 查询函数（jointTrajectory / inverseKinematics / mechanismDOF）是无副作用
  * 纯函数：输入纯数据、输出纯数据，不挂在 assembly receiver 上。
@@ -25,13 +25,13 @@ import { fromBrepjsQuat, toBrepjsQuat, jointPoseToAssemblyTransform, isIdentityP
 /**
  * 由 JointSpec 构造 brepjs Joint。
  *
- * revolute/prismatic 走 vendored 工厂（主 DOF 的 value 在工厂内 clamp 到
+ * revolute/prismatic 走 brepjs 工厂（主 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).
+ * @returns the Joint (with offset attached when declared).
  * @throws Error on multi-DOF joint types and unknown joint types.
  */
 export function buildJoint(spec) {
@@ -70,7 +70,7 @@ export function buildJoint(spec) {
 }
 // ── buildKinematicTree：建树三步 + 校验 ──
 /**
- * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（vendored
+ * 由成员名 + JointSpec[] 构建 kinematic AssemblyNode 树（brepjs
  * forwardKinematics 只接受单个根；多成员必须有唯一合成根）。
  *
  * 校验（求解前，绝不静默）：
@@ -133,7 +133,7 @@ function specMemberNames(joints) {
     return names;
 }
 /**
- * 运动学正解：buildKinematicTree → vendored forwardKinematics → per-member 位姿。
+ * 运动学正解：buildKinematicTree → brepjs forwardKinematics → per-member 位姿。
  *
  * 校验（求解前）：成员名空串 / parent-child ∈ members / child 唯一驱动（都收在
  * buildKinematicTree 内）；drive 键必须 ∈ joints 的 child 集（多余键是笔误，
@@ -184,8 +184,14 @@ export function solveKinematics(memberNames, joints, drive) {
  * 产出 steps+1 个采样（含两端点）；joints 缺省值在两端取存储值。
  * 无 endEffector 参数（关节空间插值，不追踪端点）。
  *
- * @param p - trajectory query parameters.
- * @returns the sampled trajectory (poses with faijs-order quaternions).
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name jointTrajectory
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns FaijsTrajectorySample[] 采样序列（steps+1 个，含两端点）。
+ * @param p - 轨迹查询参数。type:JointTrajectoryParams required:true
  */
 export function jointTrajectory(p) {
     const memberNames = specMemberNames(p.joints);
@@ -207,8 +213,14 @@ export function jointTrajectory(p) {
  * damped-least-squares IK：求使末端到达 target 的关节值。关节范围在每个迭代
  * clamp；不可达目标返回 converged:false 与最优配置。纯函数，无副作用。
  *
- * @param p - IK query parameters.
- * @returns the solved joint values plus convergence diagnostics.
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name inverseKinematics
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns IKResult 关节值 + 收敛诊断（converged / iterations / error）。
+ * @param p - IK 查询参数。type:InverseKinematicsParams required:true
  */
 export function inverseKinematics(p) {
     const memberNames = specMemberNames(p.joints);
@@ -229,8 +241,14 @@ export function inverseKinematics(p) {
  * `cad.mechanismDOF({ joints })` — 开链机构自由度 = 各 joint DOF 数之和
  * （revolute/prismatic 各 1；串联两 revolute = 2）。纯函数，无副作用。
  *
- * @param p - DOF query parameters.
- * @returns the mechanism's total degree of freedom.
+ * @group 查询
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name mechanismDOF
+ * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。
+ * @returns number 机构总自由度。
+ * @param p - 自由度查询参数。type:MechanismDOFParams required:true
  */
 export function mechanismDOF(p) {
     const memberNames = specMemberNames(p.joints);

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

@@ -1 +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 './solvers/joints-kinematics'\nimport { createAssemblyNode, addChild, type AssemblyNode } from './solvers/assembly-tree'\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 }"]}
+{"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 由 brepjs 工厂构造，\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（brepjs 工厂）→ buildKinematicTree（建树三步\n * + 校验）→ solveKinematics（brepjs 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 './solvers/joints-kinematics'\nimport { createAssemblyNode, addChild, type AssemblyNode } from './solvers/assembly-tree'\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 * brepjs 工厂构造——脚本里只写纯数据。\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 走 brepjs 工厂（主 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 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 树（brepjs\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 → brepjs 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 * @group 查询\n * @inputs 0\n * @async false\n * @qual ok\n * @name jointTrajectory\n * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。\n * @returns FaijsTrajectorySample[] 采样序列（steps+1 个，含两端点）。\n * @param p - 轨迹查询参数。type:JointTrajectoryParams required:true\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 结果（与 brepjs 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 * @group 查询\n * @inputs 0\n * @async false\n * @qual ok\n * @name inverseKinematics\n * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。\n * @returns IKResult 关节值 + 收敛诊断（converged / iterations / error）。\n * @param p - IK 查询参数。type:InverseKinematicsParams required:true\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 * @group 查询\n * @inputs 0\n * @async false\n * @qual ok\n * @name mechanismDOF\n * @note 纯函数：输入输出都是纯数据，不产 Shape、不依赖引擎；装配面契约见 `docs/api-contract.md` §12。\n * @returns number 机构总自由度。\n * @param p - 自由度查询参数。type:MechanismDOFParams required:true\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/preview.d.ts

@@ -4,7 +4,7 @@
  * 动机：3d_editor 预览需要**与执行同源**的轻量入口（P2-f5 已删除旧预览专用数学）；
  *
  * 同源性保证：内部复用 lowerEntities（与 lowerStructuralConstraint 同编码规则）
- * 与 vendored brepjs solveConstraints——不另写数学。
+ * 与 chain-solver solveConstraints——不另写数学。
  *
  * **输入约定**：一律是"未编码"的实体（SolverEntity，纯数据）——
  * 面 → {type:'plane', origin:center, normal}，圆柱/圆锥面与边 →

package/dist/api/assembly/preview.js

@@ -4,7 +4,7 @@
  * 动机：3d_editor 预览需要**与执行同源**的轻量入口（P2-f5 已删除旧预览专用数学）；
  *
  * 同源性保证：内部复用 lowerEntities（与 lowerStructuralConstraint 同编码规则）
- * 与 vendored brepjs solveConstraints——不另写数学。
+ * 与 chain-solver solveConstraints——不另写数学。
  *
  * **输入约定**：一律是"未编码"的实体（SolverEntity，纯数据）——
  * 面 → {type:'plane', origin:center, normal}，圆柱/圆锥面与边 →

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

@@ -1 +1 @@
-{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../src/api/assembly/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,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 './solvers/types'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { solveConstraints } from './solvers/chain-solver'\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}"]}
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../src/api/assembly/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,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 * 与 chain-solver 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 './solvers/types'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { solveConstraints } from './solvers/chain-solver'\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}"]}

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

@@ -2,7 +2,7 @@
  * api/assembly/solve — 装配求解入口（P1，方案 §4.2）
  *
  * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints
- *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 vendored 修改）→
+ *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 brepjs 修改）→
  * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。
  *
  * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。

package/dist/api/assembly/solve.js

@@ -2,7 +2,7 @@
  * api/assembly/solve — 装配求解入口（P1，方案 §4.2）
  *
  * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints
- *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 vendored 修改）→
+ *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 brepjs 修改）→
  * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。
  *
  * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。

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

@@ -1 +1 @@
-{"version":3,"file":"solve.js","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solve — 装配求解入口（P1，方案 §4.2）\n *\n * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints\n *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 vendored 修改）→\n * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。\n *\n * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。\n * 恒等位姿的成员（锚定/链根）不输出变换——引擎不做无谓的几何重算。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport { solveConstraints } from './solvers/chain-solver'\nimport { normalizeConstraint } from './normalize'\nimport { lowerStructuralConstraint } from './lower'\nimport { type EntityResolutionEnv } from './entities'\nimport { poseToAssemblyTransform, isIdentityPose, type SolverPose } from './pose'\nimport { solveKinematics, type JointSpec, type KinematicsPose } from './joints'\nimport type { AssemblyConstraint, AssemblyVec3 } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport { solveGlobal } from './solvers/global-solver'\n\n/** 求解完整结果：per-member 终态变换 + 诊断量。 */\nexport interface AssemblySolveResult {\n  /** 每个被定位成员一条终态变换（index = 成员下标；恒等位姿不输出）。 */\n  transforms: AssemblyTransform[]\n  /** unsupported 约束的自由度合计（诊断量；收敛时为 0）。 */\n  dof: number\n  /** 是否全部约束可解（不收敛时 solveAssembly 已抛错，此字段恒 true）。 */\n  converged: boolean\n  /** 无法求解的约束明细（entity 类型不匹配 / 参考不可达）。 */\n  unsupported: string[]\n  /**\n   * P3：运动副解算的全成员位姿表（键 = 成员名；含恒等链根），\n   * 只有该装配声明了 joints 时才存在——宿主从 ExecutionResult.kinematics 消费。\n   */\n  kinematics?: Record<string, KinematicsPose>\n  /**\n   * P3：合并诊断（joints 覆盖约束解时各记一条；D-P3-1，不参与 converged 统计）。\n   */\n  warnings?: string[]\n  /**\n   * P1（global 求解器）：逐约束最终残差（CQ 代价的逐约束平方和）。chain 路径不填。\n   */\n  residuals?: number[]\n}\n\n/**\n * 求解装配：members + memberNames + constraints → per-member 终态。\n *\n * @param members - member shapes (compound children, aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw before solving).\n * @param constraints - raw constraints from `cad.assembly({ constraints })`.\n * @param opts - optional solver options (e.g. `solver: 'global'` selects the global least-squares path).\n * @returns the solve result (transforms + diagnostics).\n * @throws Error on empty member names, unknown constraint parts, or non-convergence.\n */\nexport function solveAssembly(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  // P1：global 求解器分派（CadQuery 兼容全局最小二乘；零额外依赖）\n  if (opts?.solver === 'global') {\n    return solveGlobal(members, memberNames, constraints, opts)\n  }\n\n  // R7：成员名是 solver 的节点键，空串会让多成员互相覆盖——求解前断言\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 variable name in constraints`,\n      )\n    }\n  })\n\n  const memberMap = new Map<string, Shape>()\n  members.forEach((m, i) => {\n    const name = memberNames[i]\n    if (name && !memberMap.has(name)) memberMap.set(name, m)\n  })\n  // kernel 仅 TopoRef/边引用解析需要；backends 未配置（纯位姿场景/单测）→ null，\n  // 此时快照引用仍可解，TopoRef 引用按 E_TOPO_NOT_FOUND 显式报错\n  let kernel: BrepEngineApi | null = null\n  try {\n    kernel = getBrepApi()\n  } catch {\n    // backends not configured — snapshot-form constraints still solvable\n  }\n  const env: EntityResolutionEnv = { kernel, memberOf: (p: string) => memberMap.get(p) }\n\n  const lowered: ReturnType<typeof lowerStructuralConstraint>['constraint'][] = []\n  const depOrigins = new Map<string, AssemblyVec3>()\n  for (const raw of constraints) {\n    const c = normalizeConstraint(raw)\n    const { constraint, depOrigin } = lowerStructuralConstraint(c, env)\n    lowered.push(constraint)\n    if (depOrigin && constraint.entityB) depOrigins.set(constraint.entityB.node, depOrigin)\n  }\n\n  const result = solveConstraints([...memberNames], lowered)\n  if (!result.converged) {\n    throw new Error(\n      `[assembly] constraint solve did not converge (dof=${result.dof}); unsupported: ` +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  // per-member 终态（L6 修复）：恒等位姿（锚定/链根）不输出，引擎不重算\n  const transforms: AssemblyTransform[] = []\n  for (const [node, rawPose] of result.transforms) {\n    const pose: SolverPose = rawPose\n    if (isIdentityPose(pose)) continue\n    const index = memberNames.indexOf(node)\n    if (index < 0) continue\n    const pivot = depOrigins.get(node) ?? ([0, 0, 0] as AssemblyVec3)\n    transforms.push(poseToAssemblyTransform(pose, pivot, index))\n  }\n  return { transforms, dof: result.dof, converged: result.converged, unsupported: result.unsupported }\n}\n\n/**\n * 求解装配（约束 + 运动副，P3）：先跑约束求解得到 per-member 终态，再跑\n * solveKinematics 得到 joints 的 per-member 位姿，以**成员名**为键用 joints 结果\n * 覆盖同名成员的约束解，得到唯一一张表——**在库侧一次合并**，调用方一次性\n * setPendingAssemblyTransforms（禁止引擎侧两次登记）。\n *\n * 诊断不混用：joints 不参与 solveConstraints 的 converged/dof/unsupported 统计；\n * 覆盖发生时在 warnings 里各记一条（D-P3-1）。kinematics 为全成员位姿表（含\n * 恒等链根），供宿主从 ExecutionResult.kinematics 消费。\n *\n * joints 为空 → 退化为基础 solveAssembly 行为（无 kinematics/warnings 字段）。\n *\n * @param members - member shapes (aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw).\n * @param constraints - raw constraints (may be empty).\n * @param joints - raw joint declarations (may be empty).\n * @param drive - per-child DOF value overrides (may be undefined).\n * @param opts - optional solver options (forwarded to the base constraint solve).\n * @returns the merged solve result (transforms + diagnostics + kinematics/warnings).\n */\nexport function solveAssemblyAndKinematics(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  joints: JointSpec[] = [],\n  drive?: Record<string, number | number[]>,\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  const base = solveAssembly(members, memberNames, constraints, opts)\n  if (joints.length === 0) return base\n\n  const kin = solveKinematics(memberNames, joints, drive)\n  // 合并：以成员名为键，joints 结果覆盖同名成员的约束解（唯一一张表）\n  const merged = new Map<string, AssemblyTransform>()\n  for (const t of base.transforms) {\n    const name = memberNames[t.index]\n    if (name) merged.set(name, t)\n  }\n  const warnings: string[] = []\n  for (const t of kin.transforms) {\n    const name = memberNames[t.index]\n    if (!name) continue\n    if (merged.has(name)) {\n      warnings.push(`[assembly] joint '${name}' overrides the constraint solution for member '${name}'`)\n    }\n    merged.set(name, t)\n  }\n  // 按成员下标升序输出（与约束解的 Map 遍历序解耦，输出顺序确定）\n  const transforms = [...merged.entries()]\n    .map(([name, t]) => ({ name, t }))\n    .sort((a, b) => memberNames.indexOf(a.name) - memberNames.indexOf(b.name))\n    .map(({ t }) => t)\n\n  return {\n    transforms,\n    dof: base.dof,\n    converged: base.converged,\n    unsupported: base.unsupported,\n    kinematics: kin.kinematics,\n    warnings: warnings.length > 0 ? warnings : undefined,\n  }\n}\n"]}
+{"version":3,"file":"solve.js","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solve — 装配求解入口（P1，方案 §4.2）\n *\n * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints\n *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 brepjs 修改）→\n * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。\n *\n * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。\n * 恒等位姿的成员（锚定/链根）不输出变换——引擎不做无谓的几何重算。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport { solveConstraints } from './solvers/chain-solver'\nimport { normalizeConstraint } from './normalize'\nimport { lowerStructuralConstraint } from './lower'\nimport { type EntityResolutionEnv } from './entities'\nimport { poseToAssemblyTransform, isIdentityPose, type SolverPose } from './pose'\nimport { solveKinematics, type JointSpec, type KinematicsPose } from './joints'\nimport type { AssemblyConstraint, AssemblyVec3 } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport { solveGlobal } from './solvers/global-solver'\n\n/** 求解完整结果：per-member 终态变换 + 诊断量。 */\nexport interface AssemblySolveResult {\n  /** 每个被定位成员一条终态变换（index = 成员下标；恒等位姿不输出）。 */\n  transforms: AssemblyTransform[]\n  /** unsupported 约束的自由度合计（诊断量；收敛时为 0）。 */\n  dof: number\n  /** 是否全部约束可解（不收敛时 solveAssembly 已抛错，此字段恒 true）。 */\n  converged: boolean\n  /** 无法求解的约束明细（entity 类型不匹配 / 参考不可达）。 */\n  unsupported: string[]\n  /**\n   * P3：运动副解算的全成员位姿表（键 = 成员名；含恒等链根），\n   * 只有该装配声明了 joints 时才存在——宿主从 ExecutionResult.kinematics 消费。\n   */\n  kinematics?: Record<string, KinematicsPose>\n  /**\n   * P3：合并诊断（joints 覆盖约束解时各记一条；D-P3-1，不参与 converged 统计）。\n   */\n  warnings?: string[]\n  /**\n   * P1（global 求解器）：逐约束最终残差（CQ 代价的逐约束平方和）。chain 路径不填。\n   */\n  residuals?: number[]\n}\n\n/**\n * 求解装配：members + memberNames + constraints → per-member 终态。\n *\n * @param members - member shapes (compound children, aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw before solving).\n * @param constraints - raw constraints from `cad.assembly({ constraints })`.\n * @param opts - optional solver options (e.g. `solver: 'global'` selects the global least-squares path).\n * @returns the solve result (transforms + diagnostics).\n * @throws Error on empty member names, unknown constraint parts, or non-convergence.\n */\nexport function solveAssembly(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  // P1：global 求解器分派（CadQuery 兼容全局最小二乘；零额外依赖）\n  if (opts?.solver === 'global') {\n    return solveGlobal(members, memberNames, constraints, opts)\n  }\n\n  // R7：成员名是 solver 的节点键，空串会让多成员互相覆盖——求解前断言\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 variable name in constraints`,\n      )\n    }\n  })\n\n  const memberMap = new Map<string, Shape>()\n  members.forEach((m, i) => {\n    const name = memberNames[i]\n    if (name && !memberMap.has(name)) memberMap.set(name, m)\n  })\n  // kernel 仅 TopoRef/边引用解析需要；backends 未配置（纯位姿场景/单测）→ null，\n  // 此时快照引用仍可解，TopoRef 引用按 E_TOPO_NOT_FOUND 显式报错\n  let kernel: BrepEngineApi | null = null\n  try {\n    kernel = getBrepApi()\n  } catch {\n    // backends not configured — snapshot-form constraints still solvable\n  }\n  const env: EntityResolutionEnv = { kernel, memberOf: (p: string) => memberMap.get(p) }\n\n  const lowered: ReturnType<typeof lowerStructuralConstraint>['constraint'][] = []\n  const depOrigins = new Map<string, AssemblyVec3>()\n  for (const raw of constraints) {\n    const c = normalizeConstraint(raw)\n    const { constraint, depOrigin } = lowerStructuralConstraint(c, env)\n    lowered.push(constraint)\n    if (depOrigin && constraint.entityB) depOrigins.set(constraint.entityB.node, depOrigin)\n  }\n\n  const result = solveConstraints([...memberNames], lowered)\n  if (!result.converged) {\n    throw new Error(\n      `[assembly] constraint solve did not converge (dof=${result.dof}); unsupported: ` +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  // per-member 终态（L6 修复）：恒等位姿（锚定/链根）不输出，引擎不重算\n  const transforms: AssemblyTransform[] = []\n  for (const [node, rawPose] of result.transforms) {\n    const pose: SolverPose = rawPose\n    if (isIdentityPose(pose)) continue\n    const index = memberNames.indexOf(node)\n    if (index < 0) continue\n    const pivot = depOrigins.get(node) ?? ([0, 0, 0] as AssemblyVec3)\n    transforms.push(poseToAssemblyTransform(pose, pivot, index))\n  }\n  return { transforms, dof: result.dof, converged: result.converged, unsupported: result.unsupported }\n}\n\n/**\n * 求解装配（约束 + 运动副，P3）：先跑约束求解得到 per-member 终态，再跑\n * solveKinematics 得到 joints 的 per-member 位姿，以**成员名**为键用 joints 结果\n * 覆盖同名成员的约束解，得到唯一一张表——**在库侧一次合并**，调用方一次性\n * setPendingAssemblyTransforms（禁止引擎侧两次登记）。\n *\n * 诊断不混用：joints 不参与 solveConstraints 的 converged/dof/unsupported 统计；\n * 覆盖发生时在 warnings 里各记一条（D-P3-1）。kinematics 为全成员位姿表（含\n * 恒等链根），供宿主从 ExecutionResult.kinematics 消费。\n *\n * joints 为空 → 退化为基础 solveAssembly 行为（无 kinematics/warnings 字段）。\n *\n * @param members - member shapes (aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw).\n * @param constraints - raw constraints (may be empty).\n * @param joints - raw joint declarations (may be empty).\n * @param drive - per-child DOF value overrides (may be undefined).\n * @param opts - optional solver options (forwarded to the base constraint solve).\n * @returns the merged solve result (transforms + diagnostics + kinematics/warnings).\n */\nexport function solveAssemblyAndKinematics(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  joints: JointSpec[] = [],\n  drive?: Record<string, number | number[]>,\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  const base = solveAssembly(members, memberNames, constraints, opts)\n  if (joints.length === 0) return base\n\n  const kin = solveKinematics(memberNames, joints, drive)\n  // 合并：以成员名为键，joints 结果覆盖同名成员的约束解（唯一一张表）\n  const merged = new Map<string, AssemblyTransform>()\n  for (const t of base.transforms) {\n    const name = memberNames[t.index]\n    if (name) merged.set(name, t)\n  }\n  const warnings: string[] = []\n  for (const t of kin.transforms) {\n    const name = memberNames[t.index]\n    if (!name) continue\n    if (merged.has(name)) {\n      warnings.push(`[assembly] joint '${name}' overrides the constraint solution for member '${name}'`)\n    }\n    merged.set(name, t)\n  }\n  // 按成员下标升序输出（与约束解的 Map 遍历序解耦，输出顺序确定）\n  const transforms = [...merged.entries()]\n    .map(([name, t]) => ({ name, t }))\n    .sort((a, b) => memberNames.indexOf(a.name) - memberNames.indexOf(b.name))\n    .map(({ t }) => t)\n\n  return {\n    transforms,\n    dof: base.dof,\n    converged: base.converged,\n    unsupported: base.unsupported,\n    kinematics: kin.kinematics,\n    warnings: warnings.length > 0 ? warnings : undefined,\n  }\n}\n"]}

package/dist/api/assembly/solvers/assembly-tree.d.ts

@@ -1,5 +1,5 @@
 /**
- * Assembly tree — core 自有实现（§5.6 移植：vendored assemblyFns 逐字对齐，纯数据结构）。
+ * Assembly tree — core 自有实现（§5.6 移植：brepjs assemblyFns 逐字对齐，纯数据结构）。
  *
  * An assembly is a tree of nodes. Each node has an optional shape,
  * a local transform (translation + rotation), optional metadata,

package/dist/api/assembly/solvers/assembly-tree.js

@@ -1,5 +1,5 @@
 /**
- * Assembly tree — core 自有实现（§5.6 移植：vendored assemblyFns 逐字对齐，纯数据结构）。
+ * Assembly tree — core 自有实现（§5.6 移植：brepjs assemblyFns 逐字对齐，纯数据结构）。
  *
  * An assembly is a tree of nodes. Each node has an optional shape,
  * a local transform (translation + rotation), optional metadata,