@faicad/faijs 0.13.0

package/dist/vendored/brepjs/operations/ikFns.js

@@ -0,0 +1,320 @@
+/**
+ * Inverse kinematics and motion trajectories for joint chains.
+ *
+ * `inverseKinematics` solves for the joint values that place an end-effector at
+ * a target pose, using a damped-least-squares (Levenberg-Marquardt) update over
+ * a numerically-differentiated Jacobian. Differentiating through
+ * `forwardKinematics` keeps the solver agnostic to joint type — revolute,
+ * prismatic, and the multi-DOF cylindrical/planar/spherical joints all
+ * contribute their `dofs` uniformly — and respects each DOF's range by clamping
+ * every iterate.
+ *
+ * `jointTrajectory` samples a straight-line path in joint space between two
+ * configurations, returning the posed assembly (via forward kinematics) at each
+ * step — the building block for animation and reachable-workspace sweeps.
+ */
+import { quatMultiply, quatRotate } from '../utils/quaternion.js';
+import { walkAssembly } from './assemblyFns.js';
+import { forwardKinematics } from './jointFns.js';
+// ---------------------------------------------------------------------------
+// Small vector / quaternion helpers
+// ---------------------------------------------------------------------------
+const IDENTITY_POSE = { position: [0, 0, 0], rotation: [1, 0, 0, 0] };
+function applyPose(pose, p) {
+    const r = quatRotate(pose.rotation, p);
+    return [r[0] + pose.position[0], r[1] + pose.position[1], r[2] + pose.position[2]];
+}
+function quatConjugate(q) {
+    return [q[0], -q[1], -q[2], -q[3]];
+}
+/**
+ * The rotation vector (axis · angle) taking orientation `from` to `to`, i.e. the
+ * angular error that drives `from` toward `to`. Returns the zero vector when the
+ * orientations coincide.
+ */
+function rotationError(from, to) {
+    const d = quatMultiply(to, quatConjugate(from));
+    let [w, x, y, z] = d;
+    const norm = Math.hypot(w, x, y, z) || 1;
+    w /= norm;
+    x /= norm;
+    y /= norm;
+    z /= norm;
+    if (w < 0) {
+        // Shortest path: q and -q represent the same rotation.
+        w = -w;
+        x = -x;
+        y = -y;
+        z = -z;
+    }
+    const s = Math.hypot(x, y, z);
+    if (s < 1e-12)
+        return [0, 0, 0];
+    const angle = 2 * Math.atan2(s, w);
+    const k = angle / s;
+    return [x * k, y * k, z * k];
+}
+// ---------------------------------------------------------------------------
+// Chain extraction
+// ---------------------------------------------------------------------------
+/** Joints from the root down to `endEffector`, in root→leaf order. */
+function chainTo(assembly, endEffector) {
+    const joints = [];
+    walkAssembly(assembly, (n) => {
+        if (n.joints)
+            joints.push(...n.joints);
+    });
+    const byChild = new Map();
+    for (const j of joints)
+        byChild.set(j.child, j);
+    const chain = [];
+    const seen = new Set();
+    let cur = endEffector;
+    while (cur && byChild.has(cur) && !seen.has(cur)) {
+        seen.add(cur);
+        const j = byChild.get(cur);
+        if (!j)
+            break;
+        chain.push(j);
+        cur = j.parent;
+    }
+    return chain.reverse();
+}
+// ---------------------------------------------------------------------------
+// Linear algebra (small dense systems, Float64Array to avoid index-undefined)
+// ---------------------------------------------------------------------------
+/** Read a Float64Array element as a definite number (dense matrices are full). */
+function el(a, i) {
+    return a[i] ?? 0;
+}
+/** Solve `A x = b` for an `n×n` system by Gauss-Jordan with partial pivoting. */
+function solveLinear(A, b, n) {
+    const w = n + 1;
+    const M = new Float64Array(n * w);
+    for (let r = 0; r < n; r++) {
+        for (let c = 0; c < n; c++)
+            M[r * w + c] = el(A, r * n + c);
+        M[r * w + n] = el(b, r);
+    }
+    for (let col = 0; col < n; col++) {
+        let piv = col;
+        for (let r = col + 1; r < n; r++) {
+            if (Math.abs(el(M, r * w + col)) > Math.abs(el(M, piv * w + col)))
+                piv = r;
+        }
+        if (Math.abs(el(M, piv * w + col)) < 1e-12)
+            return null;
+        if (piv !== col) {
+            for (let k = col; k < w; k++) {
+                const tmp = el(M, col * w + k);
+                M[col * w + k] = el(M, piv * w + k);
+                M[piv * w + k] = tmp;
+            }
+        }
+        const d = el(M, col * w + col);
+        for (let k = col; k < w; k++)
+            M[col * w + k] = el(M, col * w + k) / d;
+        for (let r = 0; r < n; r++) {
+            if (r === col)
+                continue;
+            const f = el(M, r * w + col);
+            if (f === 0)
+                continue;
+            for (let k = col; k < w; k++)
+                M[r * w + k] = el(M, r * w + k) - f * el(M, col * w + k);
+        }
+    }
+    const x = new Float64Array(n);
+    for (let r = 0; r < n; r++)
+        x[r] = el(M, r * w + n);
+    return x;
+}
+/** Flatten a chain's DOFs into a parameter vector with bounds, applying the seed. */
+function flattenChain(chain, seed) {
+    const segments = [];
+    const q = [];
+    const lo = [];
+    const hi = [];
+    for (const j of chain) {
+        const s = seed?.[j.child];
+        segments.push({ child: j.child, count: j.dofs.length });
+        j.dofs.forEach((dof, i) => {
+            const seeded = Array.isArray(s) ? s[i] : i === 0 ? s : undefined;
+            const v = seeded ?? dof.value;
+            q.push(Math.min(dof.max, Math.max(dof.min, v)));
+            lo.push(dof.min);
+            hi.push(dof.max);
+        });
+    }
+    return {
+        segments,
+        q: Float64Array.from(q),
+        lo: Float64Array.from(lo),
+        hi: Float64Array.from(hi),
+    };
+}
+/** Slice a parameter vector back into per-joint value arrays keyed by child. */
+function overridesOf(segments, q) {
+    const out = {};
+    let i = 0;
+    for (const seg of segments) {
+        const vals = [];
+        for (let k = 0; k < seg.count; k++)
+            vals.push(el(q, i++));
+        out[seg.child] = vals;
+    }
+    return out;
+}
+/** Residual twist `e` (target − current) for a pose; returns its norm. */
+function residualTwist(out, pose, target, tip, m) {
+    const pos = applyPose(pose, tip);
+    out[0] = target.position[0] - pos[0];
+    out[1] = target.position[1] - pos[1];
+    out[2] = target.position[2] - pos[2];
+    if (m === 6 && target.rotation) {
+        const r = rotationError(pose.rotation, target.rotation);
+        out[3] = r[0];
+        out[4] = r[1];
+        out[5] = r[2];
+    }
+    let s = 0;
+    for (let i = 0; i < m; i++)
+        s += el(out, i) ** 2;
+    return Math.sqrt(s);
+}
+/**
+ * Finite-difference Jacobian: column `j` is the end-effector twist from δq[j].
+ * The probe steps *inward* from a bound — `forwardKinematics` clamps each DOF to
+ * its range, so a forward `+eps` at the upper limit would yield a zero column and
+ * trap the solver at the ceiling. Stepping `-eps` there (and dividing by the
+ * signed step) keeps every column a true one-sided derivative.
+ */
+function fillJacobian(J, q, n, m, lo, hi, base, tip, eps, tipPose) {
+    const basePos = applyPose(base, tip);
+    for (let j = 0; j < n; j++) {
+        const saved = el(q, j);
+        // Step away from whichever bound we're against so the perturbation isn't
+        // clamped to a no-op; default forward.
+        const h = saved + eps > el(hi, j) && saved - eps >= el(lo, j) ? -eps : eps;
+        q[j] = saved + h;
+        const p2 = tipPose(q);
+        q[j] = saved;
+        const pos2 = applyPose(p2, tip);
+        J[j] = (pos2[0] - basePos[0]) / h;
+        J[n + j] = (pos2[1] - basePos[1]) / h;
+        J[2 * n + j] = (pos2[2] - basePos[2]) / h;
+        if (m === 6) {
+            const dr = rotationError(base.rotation, p2.rotation);
+            J[3 * n + j] = dr[0] / h;
+            J[4 * n + j] = dr[1] / h;
+            J[5 * n + j] = dr[2] / h;
+        }
+    }
+}
+/** One damped-least-squares step: `Δq = Jᵀ(JJᵀ + λ²I)⁻¹ e`. */
+function dlsStep(J, e, n, m, lambda) {
+    const A = new Float64Array(m * m);
+    const lam2 = lambda * lambda;
+    for (let r = 0; r < m; r++) {
+        for (let c = 0; c < m; c++) {
+            let s = 0;
+            for (let k = 0; k < n; k++)
+                s += el(J, r * n + k) * el(J, c * n + k);
+            A[r * m + c] = s + (r === c ? lam2 : 0);
+        }
+    }
+    const y = solveLinear(A, e, m);
+    if (!y)
+        return null;
+    const dq = new Float64Array(n);
+    for (let j = 0; j < n; j++) {
+        let v = 0;
+        for (let r = 0; r < m; r++)
+            v += el(J, r * n + j) * el(y, r);
+        dq[j] = v;
+    }
+    return dq;
+}
+/**
+ * Solve for the joint values that place `endEffector` (offset by `tip`) at
+ * `target`, by damped-least-squares descent on a numerical Jacobian. Joint
+ * ranges are honored: every iterate is clamped to each DOF's `[min, max]`.
+ *
+ * Returns the solved per-DOF values keyed by child node (ready to pass to
+ * `forwardKinematics`), whether it converged, the iteration count, and the final
+ * residual norm. An end-effector with no driving joints, or an unreachable
+ * target, returns `converged: false` with the best configuration found.
+ */
+export function inverseKinematics(assembly, endEffector, target, options = {}) {
+    const maxIterations = options.maxIterations ?? 200;
+    const tolerance = options.tolerance ?? 1e-5;
+    const lambda = options.damping ?? 0.05;
+    const tip = options.tip ?? [0, 0, 0];
+    const m = target.rotation !== undefined ? 6 : 3;
+    const eps = 1e-6;
+    const { segments, q, lo, hi } = flattenChain(chainTo(assembly, endEffector), options.seed);
+    const n = q.length;
+    const tipPose = (state) => forwardKinematics(assembly, overridesOf(segments, state)).get(endEffector) ?? IDENTITY_POSE;
+    const e = new Float64Array(m);
+    const J = new Float64Array(m * n);
+    let pose = tipPose(q);
+    let err = residualTwist(e, pose, target, tip, m);
+    let iter = 0;
+    for (; iter < maxIterations && n > 0 && err > tolerance; iter++) {
+        fillJacobian(J, q, n, m, lo, hi, pose, tip, eps, tipPose);
+        const dq = dlsStep(J, e, n, m, lambda);
+        if (!dq)
+            break;
+        for (let j = 0; j < n; j++) {
+            const next = el(q, j) + el(dq, j);
+            q[j] = Math.min(el(hi, j), Math.max(el(lo, j), next));
+        }
+        pose = tipPose(q);
+        err = residualTwist(e, pose, target, tip, m);
+    }
+    return {
+        values: overridesOf(segments, q),
+        converged: err <= tolerance,
+        iterations: iter,
+        error: err,
+    };
+}
+/** Resolve a value spec (number, array, or absent) to a per-DOF array. */
+function valuesOf(joint, spec) {
+    return joint.dofs.map((dof, i) => {
+        const raw = Array.isArray(spec) ? spec[i] : i === 0 ? spec : undefined;
+        const v = raw ?? dof.value;
+        return Math.min(dof.max, Math.max(dof.min, v));
+    });
+}
+/**
+ * Sample a straight-line path in joint space from `from` to `to` over `steps`
+ * segments, yielding `steps + 1` samples (inclusive of both endpoints). Each
+ * sample carries the interpolated per-DOF values (clamped to range) and the
+ * forward-kinematics poses of every node. Joints absent from `from`/`to` hold
+ * their stored value at both ends.
+ */
+export function jointTrajectory(assembly, from, to, steps) {
+    const joints = [];
+    walkAssembly(assembly, (n) => {
+        if (n.joints)
+            joints.push(...n.joints);
+    });
+    const ends = joints.map((j) => ({
+        child: j.child,
+        a: valuesOf(j, from[j.child]),
+        b: valuesOf(j, to[j.child]),
+    }));
+    const count = Math.max(1, Math.floor(steps));
+    const samples = [];
+    for (let s = 0; s <= count; s++) {
+        const t = s / count;
+        const values = {};
+        for (const end of ends) {
+            values[end.child] = end.a.map((a, i) => a + ((end.b[i] ?? a) - a) * t);
+        }
+        samples.push({ t, values, poses: forwardKinematics(assembly, values) });
+    }
+    return samples;
+}
+//# sourceMappingURL=ikFns.js.map

package/dist/vendored/brepjs/operations/ikFns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ikFns.js","sourceRoot":"","sources":["../../../../src/vendored/brepjs/operations/ikFns.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Inverse kinematics and motion trajectories for joint chains.\n *\n * `inverseKinematics` solves for the joint values that place an end-effector at\n * a target pose, using a damped-least-squares (Levenberg-Marquardt) update over\n * a numerically-differentiated Jacobian. Differentiating through\n * `forwardKinematics` keeps the solver agnostic to joint type — revolute,\n * prismatic, and the multi-DOF cylindrical/planar/spherical joints all\n * contribute their `dofs` uniformly — and respects each DOF's range by clamping\n * every iterate.\n *\n * `jointTrajectory` samples a straight-line path in joint space between two\n * configurations, returning the posed assembly (via forward kinematics) at each\n * step — the building block for animation and reachable-workspace sweeps.\n */\n\nimport type { Vec3 } from '../core/types.js';\nimport { quatMultiply, quatRotate } from '../utils/quaternion.js';\nimport type { AssemblyNode } from './assemblyFns.js';\nimport { walkAssembly } from './assemblyFns.js';\nimport { forwardKinematics, type Joint, type JointPose } from './jointFns.js';\n\ntype Quat = readonly [number, number, number, number];\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** A target for the end-effector: a world position, optionally an orientation. */\nexport interface IKTarget {\n  readonly position: Vec3;\n  /** Target orientation `[w, x, y, z]`. Omit for position-only IK. */\n  readonly rotation?: Quat;\n}\n\nexport interface IKOptions {\n  /** Maximum solver iterations. Default 200. */\n  maxIterations?: number;\n  /** Convergence threshold on the residual norm. Default 1e-5. */\n  tolerance?: number;\n  /** Damping factor λ for the least-squares step. Default 0.05. */\n  damping?: number;\n  /** Initial joint values, keyed by child node (number or per-DOF array). */\n  seed?: Readonly<Record<string, number | readonly number[]>>;\n  /** Local point on the end-effector node to drive to the target. Default origin. */\n  tip?: Vec3;\n}\n\nexport interface IKResult {\n  /** Solved joint values, keyed by child node, one entry per DOF. */\n  readonly values: Record<string, number[]>;\n  readonly converged: boolean;\n  readonly iterations: number;\n  /** Final residual norm (position, plus orientation when targeted). */\n  readonly error: number;\n}\n\n// ---------------------------------------------------------------------------\n// Small vector / quaternion helpers\n// ---------------------------------------------------------------------------\n\nconst IDENTITY_POSE: JointPose = { position: [0, 0, 0], rotation: [1, 0, 0, 0] };\n\nfunction applyPose(pose: JointPose, p: Vec3): Vec3 {\n  const r = quatRotate(pose.rotation, p);\n  return [r[0] + pose.position[0], r[1] + pose.position[1], r[2] + pose.position[2]];\n}\n\nfunction quatConjugate(q: Quat): Quat {\n  return [q[0], -q[1], -q[2], -q[3]];\n}\n\n/**\n * The rotation vector (axis · angle) taking orientation `from` to `to`, i.e. the\n * angular error that drives `from` toward `to`. Returns the zero vector when the\n * orientations coincide.\n */\nfunction rotationError(from: Quat, to: Quat): Vec3 {\n  const d = quatMultiply(to, quatConjugate(from));\n  let [w, x, y, z] = d;\n  const norm = Math.hypot(w, x, y, z) || 1;\n  w /= norm;\n  x /= norm;\n  y /= norm;\n  z /= norm;\n  if (w < 0) {\n    // Shortest path: q and -q represent the same rotation.\n    w = -w;\n    x = -x;\n    y = -y;\n    z = -z;\n  }\n  const s = Math.hypot(x, y, z);\n  if (s < 1e-12) return [0, 0, 0];\n  const angle = 2 * Math.atan2(s, w);\n  const k = angle / s;\n  return [x * k, y * k, z * k];\n}\n\n// ---------------------------------------------------------------------------\n// Chain extraction\n// ---------------------------------------------------------------------------\n\n/** Joints from the root down to `endEffector`, in root→leaf order. */\nfunction chainTo(assembly: AssemblyNode, endEffector: string): Joint[] {\n  const joints: Joint[] = [];\n  walkAssembly(assembly, (n) => {\n    if (n.joints) joints.push(...(n.joints as readonly Joint[]));\n  });\n  const byChild = new Map<string, Joint>();\n  for (const j of joints) byChild.set(j.child, j);\n\n  const chain: Joint[] = [];\n  const seen = new Set<string>();\n  let cur: string | undefined = endEffector;\n  while (cur && byChild.has(cur) && !seen.has(cur)) {\n    seen.add(cur);\n    const j = byChild.get(cur);\n    if (!j) break;\n    chain.push(j);\n    cur = j.parent;\n  }\n  return chain.reverse();\n}\n\n// ---------------------------------------------------------------------------\n// Linear algebra (small dense systems, Float64Array to avoid index-undefined)\n// ---------------------------------------------------------------------------\n\n/** Read a Float64Array element as a definite number (dense matrices are full). */\nfunction el(a: Float64Array, i: number): number {\n  return a[i] ?? 0;\n}\n\n/** Solve `A x = b` for an `n×n` system by Gauss-Jordan with partial pivoting. */\nfunction solveLinear(A: Float64Array, b: Float64Array, n: number): Float64Array | null {\n  const w = n + 1;\n  const M = new Float64Array(n * w);\n  for (let r = 0; r < n; r++) {\n    for (let c = 0; c < n; c++) M[r * w + c] = el(A, r * n + c);\n    M[r * w + n] = el(b, r);\n  }\n  for (let col = 0; col < n; col++) {\n    let piv = col;\n    for (let r = col + 1; r < n; r++) {\n      if (Math.abs(el(M, r * w + col)) > Math.abs(el(M, piv * w + col))) piv = r;\n    }\n    if (Math.abs(el(M, piv * w + col)) < 1e-12) return null;\n    if (piv !== col) {\n      for (let k = col; k < w; k++) {\n        const tmp = el(M, col * w + k);\n        M[col * w + k] = el(M, piv * w + k);\n        M[piv * w + k] = tmp;\n      }\n    }\n    const d = el(M, col * w + col);\n    for (let k = col; k < w; k++) M[col * w + k] = el(M, col * w + k) / d;\n    for (let r = 0; r < n; r++) {\n      if (r === col) continue;\n      const f = el(M, r * w + col);\n      if (f === 0) continue;\n      for (let k = col; k < w; k++) M[r * w + k] = el(M, r * w + k) - f * el(M, col * w + k);\n    }\n  }\n  const x = new Float64Array(n);\n  for (let r = 0; r < n; r++) x[r] = el(M, r * w + n);\n  return x;\n}\n\n// ---------------------------------------------------------------------------\n// Inverse kinematics\n// ---------------------------------------------------------------------------\n\ninterface FlatChain {\n  /** Joint segments in root→leaf order, each owning `count` consecutive DOFs. */\n  readonly segments: ReadonlyArray<{ child: string; count: number }>;\n  /** Current parameter vector (one entry per DOF). */\n  readonly q: Float64Array;\n  /** Per-DOF lower and upper bounds. */\n  readonly lo: Float64Array;\n  readonly hi: Float64Array;\n}\n\n/** Flatten a chain's DOFs into a parameter vector with bounds, applying the seed. */\nfunction flattenChain(\n  chain: readonly Joint[],\n  seed?: Readonly<Record<string, number | readonly number[]>>\n): FlatChain {\n  const segments: Array<{ child: string; count: number }> = [];\n  const q: number[] = [];\n  const lo: number[] = [];\n  const hi: number[] = [];\n  for (const j of chain) {\n    const s = seed?.[j.child];\n    segments.push({ child: j.child, count: j.dofs.length });\n    j.dofs.forEach((dof, i) => {\n      const seeded = Array.isArray(s) ? s[i] : i === 0 ? (s as number | undefined) : undefined;\n      const v = seeded ?? dof.value;\n      q.push(Math.min(dof.max, Math.max(dof.min, v)));\n      lo.push(dof.min);\n      hi.push(dof.max);\n    });\n  }\n  return {\n    segments,\n    q: Float64Array.from(q),\n    lo: Float64Array.from(lo),\n    hi: Float64Array.from(hi),\n  };\n}\n\n/** Slice a parameter vector back into per-joint value arrays keyed by child. */\nfunction overridesOf(segments: FlatChain['segments'], q: Float64Array): Record<string, number[]> {\n  const out: Record<string, number[]> = {};\n  let i = 0;\n  for (const seg of segments) {\n    const vals: number[] = [];\n    for (let k = 0; k < seg.count; k++) vals.push(el(q, i++));\n    out[seg.child] = vals;\n  }\n  return out;\n}\n\n/** Residual twist `e` (target − current) for a pose; returns its norm. */\nfunction residualTwist(\n  out: Float64Array,\n  pose: JointPose,\n  target: IKTarget,\n  tip: Vec3,\n  m: number\n): number {\n  const pos = applyPose(pose, tip);\n  out[0] = target.position[0] - pos[0];\n  out[1] = target.position[1] - pos[1];\n  out[2] = target.position[2] - pos[2];\n  if (m === 6 && target.rotation) {\n    const r = rotationError(pose.rotation, target.rotation);\n    out[3] = r[0];\n    out[4] = r[1];\n    out[5] = r[2];\n  }\n  let s = 0;\n  for (let i = 0; i < m; i++) s += el(out, i) ** 2;\n  return Math.sqrt(s);\n}\n\n/**\n * Finite-difference Jacobian: column `j` is the end-effector twist from δq[j].\n * The probe steps *inward* from a bound — `forwardKinematics` clamps each DOF to\n * its range, so a forward `+eps` at the upper limit would yield a zero column and\n * trap the solver at the ceiling. Stepping `-eps` there (and dividing by the\n * signed step) keeps every column a true one-sided derivative.\n */\nfunction fillJacobian(\n  J: Float64Array,\n  q: Float64Array,\n  n: number,\n  m: number,\n  lo: Float64Array,\n  hi: Float64Array,\n  base: JointPose,\n  tip: Vec3,\n  eps: number,\n  tipPose: (s: Float64Array) => JointPose\n): void {\n  const basePos = applyPose(base, tip);\n  for (let j = 0; j < n; j++) {\n    const saved = el(q, j);\n    // Step away from whichever bound we're against so the perturbation isn't\n    // clamped to a no-op; default forward.\n    const h = saved + eps > el(hi, j) && saved - eps >= el(lo, j) ? -eps : eps;\n    q[j] = saved + h;\n    const p2 = tipPose(q);\n    q[j] = saved;\n    const pos2 = applyPose(p2, tip);\n    J[j] = (pos2[0] - basePos[0]) / h;\n    J[n + j] = (pos2[1] - basePos[1]) / h;\n    J[2 * n + j] = (pos2[2] - basePos[2]) / h;\n    if (m === 6) {\n      const dr = rotationError(base.rotation, p2.rotation);\n      J[3 * n + j] = dr[0] / h;\n      J[4 * n + j] = dr[1] / h;\n      J[5 * n + j] = dr[2] / h;\n    }\n  }\n}\n\n/** One damped-least-squares step: `Δq = Jᵀ(JJᵀ + λ²I)⁻¹ e`. */\nfunction dlsStep(\n  J: Float64Array,\n  e: Float64Array,\n  n: number,\n  m: number,\n  lambda: number\n): Float64Array | null {\n  const A = new Float64Array(m * m);\n  const lam2 = lambda * lambda;\n  for (let r = 0; r < m; r++) {\n    for (let c = 0; c < m; c++) {\n      let s = 0;\n      for (let k = 0; k < n; k++) s += el(J, r * n + k) * el(J, c * n + k);\n      A[r * m + c] = s + (r === c ? lam2 : 0);\n    }\n  }\n  const y = solveLinear(A, e, m);\n  if (!y) return null;\n  const dq = new Float64Array(n);\n  for (let j = 0; j < n; j++) {\n    let v = 0;\n    for (let r = 0; r < m; r++) v += el(J, r * n + j) * el(y, r);\n    dq[j] = v;\n  }\n  return dq;\n}\n\n/**\n * Solve for the joint values that place `endEffector` (offset by `tip`) at\n * `target`, by damped-least-squares descent on a numerical Jacobian. Joint\n * ranges are honored: every iterate is clamped to each DOF's `[min, max]`.\n *\n * Returns the solved per-DOF values keyed by child node (ready to pass to\n * `forwardKinematics`), whether it converged, the iteration count, and the final\n * residual norm. An end-effector with no driving joints, or an unreachable\n * target, returns `converged: false` with the best configuration found.\n */\nexport function inverseKinematics(\n  assembly: AssemblyNode,\n  endEffector: string,\n  target: IKTarget,\n  options: IKOptions = {}\n): IKResult {\n  const maxIterations = options.maxIterations ?? 200;\n  const tolerance = options.tolerance ?? 1e-5;\n  const lambda = options.damping ?? 0.05;\n  const tip: Vec3 = options.tip ?? [0, 0, 0];\n  const m = target.rotation !== undefined ? 6 : 3;\n  const eps = 1e-6;\n\n  const { segments, q, lo, hi } = flattenChain(chainTo(assembly, endEffector), options.seed);\n  const n = q.length;\n\n  const tipPose = (state: Float64Array): JointPose =>\n    forwardKinematics(assembly, overridesOf(segments, state)).get(endEffector) ?? IDENTITY_POSE;\n\n  const e = new Float64Array(m);\n  const J = new Float64Array(m * n);\n\n  let pose = tipPose(q);\n  let err = residualTwist(e, pose, target, tip, m);\n  let iter = 0;\n\n  for (; iter < maxIterations && n > 0 && err > tolerance; iter++) {\n    fillJacobian(J, q, n, m, lo, hi, pose, tip, eps, tipPose);\n    const dq = dlsStep(J, e, n, m, lambda);\n    if (!dq) break;\n    for (let j = 0; j < n; j++) {\n      const next = el(q, j) + el(dq, j);\n      q[j] = Math.min(el(hi, j), Math.max(el(lo, j), next));\n    }\n    pose = tipPose(q);\n    err = residualTwist(e, pose, target, tip, m);\n  }\n\n  return {\n    values: overridesOf(segments, q),\n    converged: err <= tolerance,\n    iterations: iter,\n    error: err,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Trajectories\n// ---------------------------------------------------------------------------\n\nexport interface TrajectorySample {\n  /** Normalized path parameter in `[0, 1]`. */\n  readonly t: number;\n  /** Interpolated joint values at this step, keyed by child node. */\n  readonly values: Record<string, number[]>;\n  /** Forward-kinematics world poses for every node at this step. */\n  readonly poses: Map<string, JointPose>;\n}\n\n/** Resolve a value spec (number, array, or absent) to a per-DOF array. */\nfunction valuesOf(joint: Joint, spec: number | readonly number[] | undefined): number[] {\n  return joint.dofs.map((dof, i) => {\n    const raw = Array.isArray(spec) ? spec[i] : i === 0 ? (spec as number | undefined) : undefined;\n    const v = raw ?? dof.value;\n    return Math.min(dof.max, Math.max(dof.min, v));\n  });\n}\n\n/**\n * Sample a straight-line path in joint space from `from` to `to` over `steps`\n * segments, yielding `steps + 1` samples (inclusive of both endpoints). Each\n * sample carries the interpolated per-DOF values (clamped to range) and the\n * forward-kinematics poses of every node. Joints absent from `from`/`to` hold\n * their stored value at both ends.\n */\nexport function jointTrajectory(\n  assembly: AssemblyNode,\n  from: Readonly<Record<string, number | readonly number[]>>,\n  to: Readonly<Record<string, number | readonly number[]>>,\n  steps: number\n): TrajectorySample[] {\n  const joints: Joint[] = [];\n  walkAssembly(assembly, (n) => {\n    if (n.joints) joints.push(...(n.joints as readonly Joint[]));\n  });\n\n  const ends = joints.map((j) => ({\n    child: j.child,\n    a: valuesOf(j, from[j.child]),\n    b: valuesOf(j, to[j.child]),\n  }));\n\n  const count = Math.max(1, Math.floor(steps));\n  const samples: TrajectorySample[] = [];\n  for (let s = 0; s <= count; s++) {\n    const t = s / count;\n    const values: Record<string, number[]> = {};\n    for (const end of ends) {\n      values[end.child] = end.a.map((a, i) => a + ((end.b[i] ?? a) - a) * t);\n    }\n    samples.push({ t, values, poses: forwardKinematics(assembly, values) });\n  }\n  return samples;\n}\n"]}

package/dist/vendored/brepjs/operations/instanceFns.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transform-only instancing — hold ONE source shape + N placements without
+ * copying the kernel shape. Real geometry (a Compound, or a fused solid) or a
+ * render payload (one mesh + N matrices) is produced only on demand.
+ *
+ * A 10x10 grid is 1 solid + 100 transforms, not 100 booleans. Materialize-on-
+ * export keeps the kernel work deferred; `instancedMesh` meshes the source once
+ * for an instanced (e.g. three.js InstancedMesh) preview.
+ */
+import { type Result } from '../core/result.js';
+import type { AnyShape, Dimension } from '../core/shapeTypes.js';
+import type { Matrix4x4, Vec3 } from '../core/types.js';
+import { type ShapeMesh, type MeshOptions } from '../topology/meshFns.js';
+/** Grid provenance, set by `instanceGrid`, lets `materialize({fuse})` route
+ *  through the faster kernel `gridPattern` path instead of fusing N copies. */
+interface GridSpec {
+    readonly cols: number;
+    readonly rows: number;
+    readonly pitchX: number;
+    readonly pitchY: number;
+}
+/**
+ * One source shape replicated across N placements. Not a kernel-backed shape
+ * (no `.wrapped`) — an app-level container that owns the single source handle.
+ */
+export interface InstancedShape<D extends Dimension = '3D'> extends Disposable {
+    readonly __instanced: true;
+    /** The single shared source shape (owned — disposed with this container). */
+    readonly source: AnyShape<D>;
+    /** Per-instance world transforms (row-major 4x4). */
+    readonly placements: ReadonlyArray<Matrix4x4>;
+    /** Present when built by `instanceGrid` — enables the gridPattern fuse path. */
+    readonly grid?: GridSpec | undefined;
+    [Symbol.dispose](): void;
+}
+/** Type guard for an InstancedShape. */
+export declare function isInstanced(x: unknown): x is InstancedShape<Dimension>;
+/**
+ * Instance a shape across explicit placements. `Vec3[]` is translate-only sugar
+ * for `Matrix4x4[]`. The source is owned by the returned container.
+ */
+export declare function instance<D extends Dimension>(source: AnyShape<D>, placements: readonly Matrix4x4[] | readonly Vec3[]): InstancedShape<D>;
+export interface InstanceGridOptions {
+    readonly cols: number;
+    readonly rows: number;
+    readonly pitchX: number;
+    readonly pitchY: number;
+}
+/** Instance a shape across a cols x rows grid in the XY plane. */
+export declare function instanceGrid<D extends Dimension>(source: AnyShape<D>, opts: InstanceGridOptions): InstancedShape<D>;
+/** Number of placements. */
+export declare function instanceCount(inst: InstancedShape<Dimension>): number;
+export interface MaterializeOptions {
+    /** Fuse the placed copies into a single solid (3D only). Default: false —
+     *  returns a Compound of separate placed parts. */
+    readonly fuse?: boolean;
+}
+/**
+ * Produce real geometry: a Compound of N placed copies (default), or a single
+ * fused solid (`fuse: true`, 3D only). This is where the N kernel transforms
+ * happen. A grid-built instance fuses via the faster kernel `gridPattern`.
+ */
+export declare function materialize<D extends Dimension>(inst: InstancedShape<D>, opts?: MaterializeOptions): Result<AnyShape<Dimension>>;
+export interface InstancedMesh {
+    /** The source shape meshed ONCE. */
+    readonly geometry: ShapeMesh;
+    /** Per-instance transforms — feed to e.g. three.js InstancedMesh. */
+    readonly instances: ReadonlyArray<Matrix4x4>;
+}
+/**
+ * Mesh the source once and return it alongside the placements — the
+ * "one tessellation, N placements" render payload for an instanced draw.
+ */
+export declare function instancedMesh(inst: InstancedShape<Dimension>, opts?: MeshOptions): InstancedMesh;
+export {};
+//# sourceMappingURL=instanceFns.d.ts.map

package/dist/vendored/brepjs/operations/instanceFns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instanceFns.d.ts","sourceRoot":"","sources":["../../../../src/vendored/brepjs/operations/instanceFns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAW,MAAM,uBAAuB,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAKxD,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGhF;+EAC+E;AAC/E,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,IAAI,CAAE,SAAQ,UAAU;IAC5E,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC9C,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAgCD,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,CAItE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,EAC1C,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,IAAI,EAAE,GACjD,cAAc,CAAC,CAAC,CAAC,CAMnB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC9C,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,IAAI,EAAE,mBAAmB,GACxB,cAAc,CAAC,CAAC,CAAC,CAcnB;AAED,4BAA4B;AAC5B,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,MAAM,CAErE;AAED,MAAM,WAAW,kBAAkB;IACjC;uDACmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7C,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,GAAE,kBAAuB,GAC5B,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CA8B7B;AA6BD,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAEhG"}

package/dist/vendored/brepjs/operations/instanceFns.js

@@ -0,0 +1,128 @@
+/**
+ * Transform-only instancing — hold ONE source shape + N placements without
+ * copying the kernel shape. Real geometry (a Compound, or a fused solid) or a
+ * render payload (one mesh + N matrices) is produced only on demand.
+ *
+ * A 10x10 grid is 1 solid + 100 transforms, not 100 booleans. Materialize-on-
+ * export keeps the kernel work deferred; `instancedMesh` meshes the source once
+ * for an instanced (e.g. three.js InstancedMesh) preview.
+ */
+import { ok, err } from '../core/result.js';
+import { isShape3D } from '../core/shapeTypes.js';
+import { validationError } from '../core/errors.js';
+import { applyMatrix } from '../topology/transformFns.js';
+import { makeCompound } from '../topology/solidBuilders.js';
+import { fuseAll } from '../topology/booleanFns.js';
+import { mesh } from '../topology/meshFns.js';
+import { gridPattern } from './patternFns.js';
+function translation(v) {
+    return [
+        [1, 0, 0, v[0]],
+        [0, 1, 0, v[1]],
+        [0, 0, 1, v[2]],
+        [0, 0, 0, 1],
+    ];
+}
+function isVec3Array(p) {
+    const first = p[0];
+    return first !== undefined && typeof first[0] === 'number';
+}
+function make(source, placements, grid) {
+    return {
+        __instanced: true,
+        source,
+        placements,
+        grid,
+        [Symbol.dispose]() {
+            source[Symbol.dispose]();
+        },
+    };
+}
+/** Type guard for an InstancedShape. */
+export function isInstanced(x) {
+    return (typeof x === 'object' && x !== null && x.__instanced === true);
+}
+/**
+ * Instance a shape across explicit placements. `Vec3[]` is translate-only sugar
+ * for `Matrix4x4[]`. The source is owned by the returned container.
+ */
+export function instance(source, placements) {
+    // Deep-copy matrices so later caller mutation can't change our placements.
+    const mats = isVec3Array(placements)
+        ? placements.map(translation)
+        : placements.map((m) => m.map((row) => [...row]));
+    return make(source, mats);
+}
+/** Instance a shape across a cols x rows grid in the XY plane. */
+export function instanceGrid(source, opts) {
+    const { cols, rows, pitchX, pitchY } = opts;
+    if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 1 || rows < 1) {
+        throw new RangeError(`instanceGrid: cols and rows must be positive integers, got ${cols}x${rows}`);
+    }
+    const placements = [];
+    for (let i = 0; i < cols; i++) {
+        for (let j = 0; j < rows; j++) {
+            placements.push(translation([i * pitchX, j * pitchY, 0]));
+        }
+    }
+    return make(source, placements, { cols, rows, pitchX, pitchY });
+}
+/** Number of placements. */
+export function instanceCount(inst) {
+    return inst.placements.length;
+}
+/**
+ * Produce real geometry: a Compound of N placed copies (default), or a single
+ * fused solid (`fuse: true`, 3D only). This is where the N kernel transforms
+ * happen. A grid-built instance fuses via the faster kernel `gridPattern`.
+ */
+export function materialize(inst, opts = {}) {
+    const { source, placements, grid } = inst;
+    if (placements.length === 0) {
+        return err(validationError('INSTANCE_EMPTY', 'materialize: instance has no placements'));
+    }
+    if (opts.fuse) {
+        if (!isShape3D(source)) {
+            return err(validationError('MATERIALIZE_NOT_3D', 'materialize({fuse:true}) requires a 3D source shape'));
+        }
+        // Grid provenance → kernel bulk-copy + nested fuse (≈20% faster than
+        // fusing N app-space copies; see benchmarks/gridPattern.bench.test.ts).
+        if (grid) {
+            return gridPattern(source, [1, 0, 0], [0, 1, 0], grid.cols, grid.rows, grid.pitchX, grid.pitchY);
+        }
+        return combine(source, placements, true);
+    }
+    return combine(source, placements, false);
+}
+// Place the source at each matrix, then combine into a Compound or fused solid.
+// Transient copies are disposed once the result is built (and on a failed
+// placement) — except one the result aliases, since fuseAll of a single shape
+// returns that shape itself. makeCompound/fuseAll keep their own refcounted
+// references, so disposing the inputs can't corrupt the result.
+function combine(source, placements, fuse) {
+    const copies = [];
+    for (const m of placements) {
+        const placed = applyMatrix(source, m);
+        if (!placed.ok) {
+            for (const c of copies)
+                c[Symbol.dispose]();
+            return placed;
+        }
+        copies.push(placed.value);
+    }
+    // Arbitrary placements needn't share faces, so no sameFace glue here.
+    const result = fuse ? fuseAll(copies, { unsafe: true }) : ok(makeCompound(copies));
+    for (const c of copies) {
+        if (!result.ok || c !== result.value)
+            c[Symbol.dispose]();
+    }
+    return result;
+}
+/**
+ * Mesh the source once and return it alongside the placements — the
+ * "one tessellation, N placements" render payload for an instanced draw.
+ */
+export function instancedMesh(inst, opts) {
+    return { geometry: mesh(inst.source, opts), instances: inst.placements };
+}
+//# sourceMappingURL=instanceFns.js.map

package/dist/vendored/brepjs/operations/instanceFns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instanceFns.js","sourceRoot":"","sources":["../../../../src/vendored/brepjs/operations/instanceFns.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Transform-only instancing — hold ONE source shape + N placements without\n * copying the kernel shape. Real geometry (a Compound, or a fused solid) or a\n * render payload (one mesh + N matrices) is produced only on demand.\n *\n * A 10x10 grid is 1 solid + 100 transforms, not 100 booleans. Materialize-on-\n * export keeps the kernel work deferred; `instancedMesh` meshes the source once\n * for an instanced (e.g. three.js InstancedMesh) preview.\n */\n\nimport { ok, err, type Result } from '../core/result.js';\nimport type { AnyShape, Dimension, Shape3D } from '../core/shapeTypes.js';\nimport { isShape3D } from '../core/shapeTypes.js';\nimport type { Matrix4x4, Vec3 } from '../core/types.js';\nimport { validationError } from '../core/errors.js';\nimport { applyMatrix } from '../topology/transformFns.js';\nimport { makeCompound } from '../topology/solidBuilders.js';\nimport { fuseAll } from '../topology/booleanFns.js';\nimport { mesh, type ShapeMesh, type MeshOptions } from '../topology/meshFns.js';\nimport { gridPattern } from './patternFns.js';\n\n/** Grid provenance, set by `instanceGrid`, lets `materialize({fuse})` route\n *  through the faster kernel `gridPattern` path instead of fusing N copies. */\ninterface GridSpec {\n  readonly cols: number;\n  readonly rows: number;\n  readonly pitchX: number;\n  readonly pitchY: number;\n}\n\n/**\n * One source shape replicated across N placements. Not a kernel-backed shape\n * (no `.wrapped`) — an app-level container that owns the single source handle.\n */\nexport interface InstancedShape<D extends Dimension = '3D'> extends Disposable {\n  readonly __instanced: true;\n  /** The single shared source shape (owned — disposed with this container). */\n  readonly source: AnyShape<D>;\n  /** Per-instance world transforms (row-major 4x4). */\n  readonly placements: ReadonlyArray<Matrix4x4>;\n  /** Present when built by `instanceGrid` — enables the gridPattern fuse path. */\n  readonly grid?: GridSpec | undefined;\n  [Symbol.dispose](): void;\n}\n\nfunction translation(v: Vec3): Matrix4x4 {\n  return [\n    [1, 0, 0, v[0]],\n    [0, 1, 0, v[1]],\n    [0, 0, 1, v[2]],\n    [0, 0, 0, 1],\n  ];\n}\n\nfunction isVec3Array(p: readonly Matrix4x4[] | readonly Vec3[]): p is readonly Vec3[] {\n  const first = p[0];\n  return first !== undefined && typeof first[0] === 'number';\n}\n\nfunction make<D extends Dimension>(\n  source: AnyShape<D>,\n  placements: ReadonlyArray<Matrix4x4>,\n  grid?: GridSpec\n): InstancedShape<D> {\n  return {\n    __instanced: true,\n    source,\n    placements,\n    grid,\n    [Symbol.dispose]() {\n      source[Symbol.dispose]();\n    },\n  };\n}\n\n/** Type guard for an InstancedShape. */\nexport function isInstanced(x: unknown): x is InstancedShape<Dimension> {\n  return (\n    typeof x === 'object' && x !== null && (x as { __instanced?: unknown }).__instanced === true\n  );\n}\n\n/**\n * Instance a shape across explicit placements. `Vec3[]` is translate-only sugar\n * for `Matrix4x4[]`. The source is owned by the returned container.\n */\nexport function instance<D extends Dimension>(\n  source: AnyShape<D>,\n  placements: readonly Matrix4x4[] | readonly Vec3[]\n): InstancedShape<D> {\n  // Deep-copy matrices so later caller mutation can't change our placements.\n  const mats = isVec3Array(placements)\n    ? placements.map(translation)\n    : placements.map((m) => m.map((row) => [...row]) as Matrix4x4);\n  return make(source, mats);\n}\n\nexport interface InstanceGridOptions {\n  readonly cols: number;\n  readonly rows: number;\n  readonly pitchX: number;\n  readonly pitchY: number;\n}\n\n/** Instance a shape across a cols x rows grid in the XY plane. */\nexport function instanceGrid<D extends Dimension>(\n  source: AnyShape<D>,\n  opts: InstanceGridOptions\n): InstancedShape<D> {\n  const { cols, rows, pitchX, pitchY } = opts;\n  if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 1 || rows < 1) {\n    throw new RangeError(\n      `instanceGrid: cols and rows must be positive integers, got ${cols}x${rows}`\n    );\n  }\n  const placements: Matrix4x4[] = [];\n  for (let i = 0; i < cols; i++) {\n    for (let j = 0; j < rows; j++) {\n      placements.push(translation([i * pitchX, j * pitchY, 0]));\n    }\n  }\n  return make(source, placements, { cols, rows, pitchX, pitchY });\n}\n\n/** Number of placements. */\nexport function instanceCount(inst: InstancedShape<Dimension>): number {\n  return inst.placements.length;\n}\n\nexport interface MaterializeOptions {\n  /** Fuse the placed copies into a single solid (3D only). Default: false —\n   *  returns a Compound of separate placed parts. */\n  readonly fuse?: boolean;\n}\n\n/**\n * Produce real geometry: a Compound of N placed copies (default), or a single\n * fused solid (`fuse: true`, 3D only). This is where the N kernel transforms\n * happen. A grid-built instance fuses via the faster kernel `gridPattern`.\n */\nexport function materialize<D extends Dimension>(\n  inst: InstancedShape<D>,\n  opts: MaterializeOptions = {}\n): Result<AnyShape<Dimension>> {\n  const { source, placements, grid } = inst;\n\n  if (placements.length === 0) {\n    return err(validationError('INSTANCE_EMPTY', 'materialize: instance has no placements'));\n  }\n\n  if (opts.fuse) {\n    if (!isShape3D(source)) {\n      return err(\n        validationError('MATERIALIZE_NOT_3D', 'materialize({fuse:true}) requires a 3D source shape')\n      );\n    }\n    // Grid provenance → kernel bulk-copy + nested fuse (≈20% faster than\n    // fusing N app-space copies; see benchmarks/gridPattern.bench.test.ts).\n    if (grid) {\n      return gridPattern(\n        source,\n        [1, 0, 0],\n        [0, 1, 0],\n        grid.cols,\n        grid.rows,\n        grid.pitchX,\n        grid.pitchY\n      );\n    }\n    return combine(source, placements, true);\n  }\n\n  return combine(source, placements, false);\n}\n\n// Place the source at each matrix, then combine into a Compound or fused solid.\n// Transient copies are disposed once the result is built (and on a failed\n// placement) — except one the result aliases, since fuseAll of a single shape\n// returns that shape itself. makeCompound/fuseAll keep their own refcounted\n// references, so disposing the inputs can't corrupt the result.\nfunction combine<D extends Dimension>(\n  source: AnyShape<D>,\n  placements: ReadonlyArray<Matrix4x4>,\n  fuse: boolean\n): Result<AnyShape<Dimension>> {\n  const copies: AnyShape<D>[] = [];\n  for (const m of placements) {\n    const placed = applyMatrix(source, m);\n    if (!placed.ok) {\n      for (const c of copies) c[Symbol.dispose]();\n      return placed;\n    }\n    copies.push(placed.value);\n  }\n  // Arbitrary placements needn't share faces, so no sameFace glue here.\n  const result = fuse ? fuseAll(copies as Shape3D[], { unsafe: true }) : ok(makeCompound(copies));\n  for (const c of copies) {\n    if (!result.ok || c !== result.value) c[Symbol.dispose]();\n  }\n  return result;\n}\n\nexport interface InstancedMesh {\n  /** The source shape meshed ONCE. */\n  readonly geometry: ShapeMesh;\n  /** Per-instance transforms — feed to e.g. three.js InstancedMesh. */\n  readonly instances: ReadonlyArray<Matrix4x4>;\n}\n\n/**\n * Mesh the source once and return it alongside the placements — the\n * \"one tessellation, N placements\" render payload for an instanced draw.\n */\nexport function instancedMesh(inst: InstancedShape<Dimension>, opts?: MeshOptions): InstancedMesh {\n  return { geometry: mesh(inst.source, opts), instances: inst.placements };\n}\n"]}