@faicad/faijs 0.13.0

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

@@ -0,0 +1,72 @@
+/**
+ * api/assembly/solve — 装配求解入口（P1，方案 §4.2）
+ *
+ * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints
+ *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 vendored 修改）→
+ * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。
+ *
+ * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。
+ * 恒等位姿的成员（锚定/链根）不输出变换——引擎不做无谓的几何重算。
+ */
+import type { Shape } from '../../mesh/types.js';
+import type { AssemblyTransform } from '../../runtime-state.js';
+import { type JointSpec, type KinematicsPose } from './joints.js';
+import type { AssemblyConstraint } from './types.js';
+import type { SolveOptions } from './solvers/types.js';
+/** 求解完整结果：per-member 终态变换 + 诊断量。 */
+export interface AssemblySolveResult {
+    /** 每个被定位成员一条终态变换（index = 成员下标；恒等位姿不输出）。 */
+    transforms: AssemblyTransform[];
+    /** unsupported 约束的自由度合计（诊断量；收敛时为 0）。 */
+    dof: number;
+    /** 是否全部约束可解（不收敛时 solveAssembly 已抛错，此字段恒 true）。 */
+    converged: boolean;
+    /** 无法求解的约束明细（entity 类型不匹配 / 参考不可达）。 */
+    unsupported: string[];
+    /**
+     * P3：运动副解算的全成员位姿表（键 = 成员名；含恒等链根），
+     * 只有该装配声明了 joints 时才存在——宿主从 ExecutionResult.kinematics 消费。
+     */
+    kinematics?: Record<string, KinematicsPose>;
+    /**
+     * P3：合并诊断（joints 覆盖约束解时各记一条；D-P3-1，不参与 converged 统计）。
+     */
+    warnings?: string[];
+    /**
+     * P1（global 求解器）：逐约束最终残差（CQ 代价的逐约束平方和）。chain 路径不填。
+     */
+    residuals?: number[];
+}
+/**
+ * 求解装配：members + memberNames + constraints → per-member 终态。
+ *
+ * @param members - member shapes (compound children, aligned with memberNames).
+ * @param memberNames - member variable names (R7: empty names throw before solving).
+ * @param constraints - raw constraints from `cad.assembly({ constraints })`.
+ * @param opts - optional solver options (e.g. `solver: 'global'` selects the global least-squares path).
+ * @returns the solve result (transforms + diagnostics).
+ * @throws Error on empty member names, unknown constraint parts, or non-convergence.
+ */
+export declare function solveAssembly(members: Shape[], memberNames: string[], constraints: AssemblyConstraint[], opts?: SolveOptions): AssemblySolveResult;
+/**
+ * 求解装配（约束 + 运动副，P3）：先跑约束求解得到 per-member 终态，再跑
+ * solveKinematics 得到 joints 的 per-member 位姿，以**成员名**为键用 joints 结果
+ * 覆盖同名成员的约束解，得到唯一一张表——**在库侧一次合并**，调用方一次性
+ * setPendingAssemblyTransforms（禁止引擎侧两次登记）。
+ *
+ * 诊断不混用：joints 不参与 solveConstraints 的 converged/dof/unsupported 统计；
+ * 覆盖发生时在 warnings 里各记一条（D-P3-1）。kinematics 为全成员位姿表（含
+ * 恒等链根），供宿主从 ExecutionResult.kinematics 消费。
+ *
+ * joints 为空 → 退化为基础 solveAssembly 行为（无 kinematics/warnings 字段）。
+ *
+ * @param members - member shapes (aligned with memberNames).
+ * @param memberNames - member variable names (R7: empty names throw).
+ * @param constraints - raw constraints (may be empty).
+ * @param joints - raw joint declarations (may be empty).
+ * @param drive - per-child DOF value overrides (may be undefined).
+ * @param opts - optional solver options (forwarded to the base constraint solve).
+ * @returns the merged solve result (transforms + diagnostics + kinematics/warnings).
+ */
+export declare function solveAssemblyAndKinematics(members: Shape[], memberNames: string[], constraints: AssemblyConstraint[], joints?: JointSpec[], drive?: Record<string, number | number[]>, opts?: SolveOptions): AssemblySolveResult;
+//# sourceMappingURL=solve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"solve.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAG7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAM5D,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,SAAS,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CA0DrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,GAAE,SAAS,EAAO,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EACzC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CAkCrB"}

package/dist/api/assembly/solve.js

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

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

@@ -0,0 +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 { getBackends } from '../../runtime-state'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { solveConstraints } from '../../vendored/brepjs/kernel/solverAdapter'\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 = getBackends().kernel.brep as BrepEngineApi | null\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/global-solver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * api/assembly/solvers/global-solver — 纯 TS global 装配求解器（P1）
+ *
+ * 复刻 CadQuery `cadquery/occ_impl/solver.py` 的**语义**（全局 NLP、模长参数化旋转、
+ * 9 类代价、Axis 缺省反平行、Plane=Axis(π)+Point(0)、包围盒对角长缩放），
+ * 以 Levenberg-Marquardt 替代 IPOPT，**零原生/WASM 依赖**（裁定 1–6，详见
+ * `docs/plans/2026-09-08-assembly-dual-solver.md`）。
+ *
+ * 关键裁定（写进代码，不在别处手算）：
+ * - 裁定 1/2：faijs Shape 不携带 placement → 初值 T0=R0=0，world 系==本地系；
+ *   两侧 marker 经 `resolveFaceGeometryOfRef`/`resolveSolverEntity` 直接取本地系，无不对称。
+ * - 裁定 3：残差取 CQ 代价的「平方前内层量」（非对代价开方）。
+ * - 裁定 4：线性求解自实现（linalg.ts）。
+ * - 裁定 5：旋转 pivot 恒 [0,0,0]（CQ 的 Rotate(v,R)+T 绕世界原点）。
+ * - 裁定 6：锚定用 CQ B4（assembly.py:455-490）：Fixed / name==self.name 锁定；
+ *   否则第一个不在 unary 里的 binary object；否则实体 0。锁定成员冻结为 identity。
+ *
+ * 失败模式（§4.6）：唯一抛错路径 = 约束类型无法映射为代价；其余以 warnings 透明化，
+ * 不抛错（LM 终止即 converged=true）。
+ */
+import type { Shape } from '../../../mesh/types.js';
+import type { AssemblyConstraint } from '../types.js';
+import { type SolveOptions, type GlobalSolveResult } from './types.js';
+/**
+ * 纯 TS global 求解器入口。
+ *
+ * @param members - member shapes（与 memberNames 对齐）。
+ * @param memberNames - 成员变量名（约束以名引用，空名会抛错）。
+ * @param constraints - 规范化前的原始约束。
+ * @param opts - 求解选项（solver 已在外层判定为 'global'，此处 name 用于 B4 锚定）。
+ * @returns 与 `AssemblySolveResult` 对齐的结果。
+ */
+export declare function solveGlobal(members: Shape[], memberNames: string[], constraints: AssemblyConstraint[], opts?: SolveOptions): GlobalSolveResult;
+//# sourceMappingURL=global-solver.d.ts.map

package/dist/api/assembly/solvers/global-solver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-solver.d.ts","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/global-solver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAIhD,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,UAAU,CAAA;AAQ7D,OAAO,EAAE,KAAK,YAAY,EAAqB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAA;AA8HtF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,iBAAiB,CAoQnB"}