bireactive 0.2.0

package/dist/constraints/index.js

@@ -0,0 +1,39 @@
+// constraints/ — reactive constraint engine.
+//
+// AVBD-based primal-dual solver integrated with the signals layer via
+// `network`. Scales from "make two values equal" to sketchpad scenes
+// and full rigid-body physics.
+//
+// Layered as:
+//
+//   Numerical kernel (signal-free):
+//     solver.ts     `Solver`, SOA cell state + AVBD inner loop.
+//     term.ts       `Term` base class (residual + Jacobian + dual λ).
+//     terms.ts      `*Term` subclasses + `Strength` constants.
+//     linalg.ts     SPD solve helpers.
+//
+//   Reactive integration:
+//     cluster.ts    `Constraints`: a `Solver` + a phase `pipeline`
+//                   run on each `step(dt)`.
+//     factories.ts  Constraint factories returning Relations.
+//     phases.ts     `Phase` type + built-in phases.
+//     drivers.ts    Generators wrapping `c.step(dt)`.
+//     physics.ts    `physics(opts)` — velocity + gravity (cloth, particles).
+//     world.ts      `world(opts)` — physics + broadphase + contacts.
+//     rigid.ts      Body, Joint, BodyAnchor relations + BoxContact.
+//
+// Reference: Giles, Diaz, Yuksel (2025). Augmented Vertex Block
+// Descent. ACM TOG 44(4) — SIGGRAPH 2025. Extends Chen et al.
+// (2024) "Vertex Block Descent". 2D demo at
+// https://github.com/savant117/avbd-demo2d.
+export { Constraints, constraints } from "./cluster.js";
+export { animate, dilated, fixedStep, } from "./drivers.js";
+export { angle, bend, clamp, collinear, distance, eq, equalDist, gap, generic, geq, inside, lensNum, leq, midpoint, onCircle, parallel, perpendicular, pin, repel, rightAngle, softTarget, spring, } from "./factories.js";
+export { dragBody, dragBodyAnchored } from "./interaction.js";
+export { prepare, snapshot, solve, writeback } from "./phases.js";
+export { physics } from "./physics.js";
+export { Body, BodyAnchor, BodyAnchorTerm, BoxContact, body, bodyAnchor, Joint, JointTerm, joint, weld, } from "./rigid.js";
+export { Solver } from "./solver.js";
+export { LAMBDA_MAX, PENALTY_MAX, PENALTY_MIN, Term } from "./term.js";
+export { BoundsTerm, DistanceTerm, EqTerm, GenericTerm, LensNumTerm, SoftTargetTerm, Strength, } from "./terms.js";
+export { world } from "./world.js";

package/dist/constraints/interaction.d.ts

@@ -0,0 +1,21 @@
+import { type Cell } from "../core/index.js";
+import type { AnyShape } from "../shapes/index.js";
+import { type Body } from "./rigid.js";
+import type { World } from "./world.js";
+interface DragHandle {
+    /** True while mid-drag; for wiring animator `rate` / cluster gating. */
+    readonly dragging: Cell<boolean>;
+    /** Tear down listeners (and the soft anchor, if any). Idempotent. */
+    dispose(): void;
+}
+/** Hard-pin drag: while down, `body` goes kinematic (`body.pin()`)
+ *  and tracks the cursor exactly; release restores its mass. Use when
+ *  the body should lead absolutely; for contact-reactive drag use
+ *  `dragBodyAnchored`. Defaults `shape.el.style.cursor = "grab"`. */
+export declare function dragBody(shape: AnyShape, world: World, body: Body): DragHandle;
+/** Soft-pin drag via `BodyAnchor`: the body keeps its mass while a
+ *  finite-`stiffness` anchor (default `5e4`) pulls it toward the
+ *  cursor, so blocked bodies lag instead of punching through.
+ *  Defaults `shape.el.style.cursor = "grab"`. */
+export declare function dragBodyAnchored(shape: AnyShape, world: World, body: Body, stiffness?: number): DragHandle;
+export {};

package/dist/constraints/interaction.js

@@ -0,0 +1,148 @@
+// Pointer-drag helpers for rigid bodies.
+//
+// These read the cursor in world space (via `shape.toWorld`) rather
+// than the shape's local frame, which would track a rotating frame
+// for bodies whose render rect rotates with `body.angle`.
+//
+// Two flavours:
+//   `dragBody`         — hard-pin (kinematic, teleports to cursor);
+//                        the body leads absolutely.
+//   `dragBodyAnchored` — soft-pin via `BodyAnchor`; the body keeps
+//                        its mass so contacts push back on the drag.
+import { cell } from "../core/index.js";
+import { bodyAnchor } from "./rigid.js";
+/** Shared pointer wiring: `onStart`/`onMove`/`onStop` with cursor in
+ *  world coords (via `shape.toWorld`, stable under rotation). */
+function bindPointerDrag(core) {
+    const dragging = cell(false);
+    let pointerId = -1;
+    let unblock = null;
+    // Own the touch gesture so a drag doesn't scroll/zoom the page.
+    core.shape.el.style.touchAction = "none";
+    if (core.shape.intrinsic)
+        core.shape.intrinsic.style.touchAction = "none";
+    // iOS ignores `touch-action` on inner SVG nodes; block scroll for the
+    // drag's lifetime via a non-passive document `touchmove`.
+    const blockScroll = () => {
+        const onMove = (e) => e.preventDefault();
+        document.addEventListener("touchmove", onMove, { passive: false });
+        return () => document.removeEventListener("touchmove", onMove);
+    };
+    const offDown = core.shape.on("pointerdown", e => {
+        const pe = e;
+        pointerId = pe.pointerId;
+        core.shape.el.setPointerCapture(pointerId);
+        unblock = blockScroll();
+        core.onStart(core.shape.toWorld(pe));
+        dragging.value = true;
+    });
+    const offMove = core.shape.on("pointermove", e => {
+        if (pointerId === -1)
+            return;
+        core.onMove(core.shape.toWorld(e));
+    });
+    const stop = () => {
+        if (pointerId !== -1) {
+            try {
+                core.shape.el.releasePointerCapture(pointerId);
+            }
+            catch {
+                /* fine */
+            }
+            pointerId = -1;
+        }
+        unblock?.();
+        unblock = null;
+        if (dragging.peek()) {
+            core.onStop();
+            dragging.value = false;
+        }
+    };
+    const offUp = core.shape.on("pointerup", stop);
+    const offCancel = core.shape.on("pointercancel", stop);
+    return {
+        dragging,
+        dispose() {
+            stop();
+            offDown();
+            offMove();
+            offUp();
+            offCancel();
+        },
+    };
+}
+/** Hard-pin drag: while down, `body` goes kinematic (`body.pin()`)
+ *  and tracks the cursor exactly; release restores its mass. Use when
+ *  the body should lead absolutely; for contact-reactive drag use
+ *  `dragBodyAnchored`. Defaults `shape.el.style.cursor = "grab"`. */
+export function dragBody(shape, world, body) {
+    if (!shape.el.style.cursor)
+        shape.el.style.cursor = "grab";
+    let grabDx = 0;
+    let grabDy = 0;
+    const wired = bindPointerDrag({
+        shape,
+        onStart(w) {
+            const p = body.position.value;
+            grabDx = w.x - p.x;
+            grabDy = w.y - p.y;
+        },
+        onMove(w) {
+            body.position.value = { x: w.x - grabDx, y: w.y - grabDy };
+        },
+        onStop() {
+            /* lifecycle below removes the pin */
+        },
+    });
+    const lc = world.addWhile(wired.dragging, body.pin());
+    return {
+        dragging: wired.dragging,
+        dispose() {
+            lc.dispose();
+            wired.dispose();
+        },
+    };
+}
+/** Soft-pin drag via `BodyAnchor`: the body keeps its mass while a
+ *  finite-`stiffness` anchor (default `5e4`) pulls it toward the
+ *  cursor, so blocked bodies lag instead of punching through.
+ *  Defaults `shape.el.style.cursor = "grab"`. */
+export function dragBodyAnchored(shape, world, body, stiffness = 5e4) {
+    if (!shape.el.style.cursor)
+        shape.el.style.cursor = "grab";
+    let grabDx = 0;
+    let grabDy = 0;
+    let anchor;
+    const wired = bindPointerDrag({
+        shape,
+        onStart(w) {
+            const p = body.position.value;
+            grabDx = w.x - p.x;
+            grabDy = w.y - p.y;
+            anchor = bodyAnchor(body, { x: p.x, y: p.y }, stiffness);
+            world.add(anchor);
+        },
+        onMove(w) {
+            if (!anchor)
+                return;
+            // Drive the anchor target — body translation chases it under load.
+            anchor.target.value = { x: w.x - grabDx, y: w.y - grabDy };
+        },
+        onStop() {
+            if (anchor) {
+                world.remove(anchor);
+                anchor = undefined;
+            }
+        },
+    });
+    return {
+        dragging: wired.dragging,
+        dispose() {
+            wired.dispose();
+            if (anchor) {
+                world.remove(anchor);
+                anchor = undefined;
+            }
+        },
+    };
+}

package/dist/constraints/linalg.d.ts

@@ -0,0 +1,18 @@
+/** Solve an SPD (or semi-definite) system `A·x = b` in place via
+ *  LDLᵀ. Returns `false` if too singular to solve safely (leaving
+ *  `b` undefined — callers typically leave the cell unchanged). */
+export declare function solveSPD(A: Float64Array, b: Float64Array, n: number): boolean;
+/** 2×2 SPD direct solve. A is row-major; we use the symmetry. */
+export declare function solve2(A: Float64Array, b: Float64Array): boolean;
+/** 3×3 SPD direct solve via cofactor expansion. */
+export declare function solve3(A: Float64Array, b: Float64Array): boolean;
+/** Add `α · v · vᵀ` to a square matrix `A` in row-major form.
+ *  Used to accumulate Jᵀ J terms in the local Newton system. */
+export declare function addOuterProduct(A: Float64Array, v: Float64Array, alpha: number, n: number): void;
+/** Add `α · I` to the diagonal of `A`. */
+export declare function addScaledIdentity(A: Float64Array, alpha: number, n: number): void;
+/** Add `α · diag(d)` to the diagonal of `A`. */
+export declare function addDiag(A: Float64Array, d: Float64Array, alpha: number, n: number): void;
+export declare function zeroMatrix(A: Float64Array, n: number): void;
+export declare function zeroVector(v: Float64Array, n: number): void;
+export declare function clamp(x: number, lo: number, hi: number): number;

package/dist/constraints/linalg.js

@@ -0,0 +1,141 @@
+// linalg.ts — small dense linear algebra for AVBD's per-cell local
+// Newton solves. Systems are `n × n` with n = cell DOF (small, ≤ 6),
+// where unrolled direct solves / LDLᵀ beat anything general-purpose.
+//
+// Convention: matrices are row-major Float64Array of length n*n.
+// Solves are in place: `A` is destroyed, `x` is written into `b`.
+const TINY = 1e-14;
+/** Solve an SPD (or semi-definite) system `A·x = b` in place via
+ *  LDLᵀ. Returns `false` if too singular to solve safely (leaving
+ *  `b` undefined — callers typically leave the cell unchanged). */
+export function solveSPD(A, b, n) {
+    if (n === 1) {
+        const a = A[0];
+        if (Math.abs(a) < TINY)
+            return false;
+        b[0] = b[0] / a;
+        return true;
+    }
+    if (n === 2)
+        return solve2(A, b);
+    if (n === 3)
+        return solve3(A, b);
+    // General LDLᵀ.
+    return ldltGeneric(A, b, n);
+}
+/** 2×2 SPD direct solve. A is row-major; we use the symmetry. */
+export function solve2(A, b) {
+    const a = A[0];
+    const c = A[1]; // = A[2] by symmetry
+    const d = A[3];
+    const det = a * d - c * c;
+    if (Math.abs(det) < TINY)
+        return false;
+    const inv = 1 / det;
+    const x0 = (d * b[0] - c * b[1]) * inv;
+    const x1 = (-c * b[0] + a * b[1]) * inv;
+    b[0] = x0;
+    b[1] = x1;
+    return true;
+}
+/** 3×3 SPD direct solve via cofactor expansion. */
+export function solve3(A, b) {
+    const a00 = A[0], a01 = A[1], a02 = A[2];
+    const a10 = A[3], a11 = A[4], a12 = A[5];
+    const a20 = A[6], a21 = A[7], a22 = A[8];
+    const c00 = a11 * a22 - a12 * a21;
+    const c01 = -(a10 * a22 - a12 * a20);
+    const c02 = a10 * a21 - a11 * a20;
+    const det = a00 * c00 + a01 * c01 + a02 * c02;
+    if (Math.abs(det) < TINY)
+        return false;
+    const c10 = -(a01 * a22 - a02 * a21);
+    const c11 = a00 * a22 - a02 * a20;
+    const c12 = -(a00 * a21 - a01 * a20);
+    const c20 = a01 * a12 - a02 * a11;
+    const c21 = -(a00 * a12 - a02 * a10);
+    const c22 = a00 * a11 - a01 * a10;
+    const inv = 1 / det;
+    const b0 = b[0], b1 = b[1], b2 = b[2];
+    // Inverse is transpose of cofactor / det. For SPD it equals the
+    // adjugate / det. We multiply by b directly.
+    b[0] = (c00 * b0 + c10 * b1 + c20 * b2) * inv;
+    b[1] = (c01 * b0 + c11 * b1 + c21 * b2) * inv;
+    b[2] = (c02 * b0 + c12 * b1 + c22 * b2) * inv;
+    return true;
+}
+/** General LDLᵀ for `n ≥ 4`. In-place: `A` is overwritten with the
+ *  factor, `b` is overwritten with the solution. */
+function ldltGeneric(A, b, n) {
+    // Factor: A = L D Lᵀ where L is unit lower-triangular and D is
+    // diagonal. We store L in the strictly-lower part of A and D on
+    // the diagonal.
+    for (let j = 0; j < n; j++) {
+        // D[j] = A[j,j] - Σ_{k<j} L[j,k]² · D[k]
+        let djj = A[j * n + j];
+        for (let k = 0; k < j; k++) {
+            const ljk = A[j * n + k];
+            djj -= ljk * ljk * A[k * n + k];
+        }
+        if (Math.abs(djj) < TINY)
+            return false;
+        A[j * n + j] = djj;
+        // L[i,j] = (A[i,j] - Σ_{k<j} L[i,k] L[j,k] D[k]) / D[j]
+        for (let i = j + 1; i < n; i++) {
+            let lij = A[i * n + j];
+            for (let k = 0; k < j; k++) {
+                lij -= A[i * n + k] * A[j * n + k] * A[k * n + k];
+            }
+            A[i * n + j] = lij / djj;
+        }
+    }
+    // Forward solve L y = b → y in b.
+    for (let i = 0; i < n; i++) {
+        let yi = b[i];
+        for (let k = 0; k < i; k++)
+            yi -= A[i * n + k] * b[k];
+        b[i] = yi;
+    }
+    // D solve: y_i ← y_i / D[i].
+    for (let i = 0; i < n; i++)
+        b[i] /= A[i * n + i];
+    // Backward solve Lᵀ x = y → x in b.
+    for (let i = n - 1; i >= 0; i--) {
+        let xi = b[i];
+        for (let k = i + 1; k < n; k++)
+            xi -= A[k * n + i] * b[k];
+        b[i] = xi;
+    }
+    return true;
+}
+/** Add `α · v · vᵀ` to a square matrix `A` in row-major form.
+ *  Used to accumulate Jᵀ J terms in the local Newton system. */
+export function addOuterProduct(A, v, alpha, n) {
+    for (let i = 0; i < n; i++) {
+        const vi = v[i] * alpha;
+        for (let j = 0; j < n; j++) {
+            A[i * n + j] += vi * v[j];
+        }
+    }
+}
+/** Add `α · I` to the diagonal of `A`. */
+export function addScaledIdentity(A, alpha, n) {
+    for (let i = 0; i < n; i++)
+        A[i * n + i] += alpha;
+}
+/** Add `α · diag(d)` to the diagonal of `A`. */
+export function addDiag(A, d, alpha, n) {
+    for (let i = 0; i < n; i++)
+        A[i * n + i] += alpha * d[i];
+}
+export function zeroMatrix(A, n) {
+    for (let i = 0; i < n * n; i++)
+        A[i] = 0;
+}
+export function zeroVector(v, n) {
+    for (let i = 0; i < n; i++)
+        v[i] = 0;
+}
+export function clamp(x, lo, hi) {
+    return x < lo ? lo : x > hi ? hi : x;
+}

package/dist/constraints/phases.d.ts

@@ -0,0 +1,21 @@
+import type { Constraints } from "./cluster.js";
+/** A single step in the `Constraints` pipeline. */
+export type Phase = (c: Constraints, dt: number) => void;
+/** Read each bound signal into the solver's `positions` buffer. The
+ *  `.value` reads subscribe the network when run inside its body. */
+export declare const snapshot: Phase;
+/** `solver.prepare()` — warm-start λ/penalty, snapshot `initials`,
+ *  reset `anchors = positions`. Integrating factories overwrite
+ *  `anchors` after this phase but before `solve`. */
+export declare const prepare: Phase;
+/** `solver.solve(dt)` — the iteration loop. */
+export declare const solve: Phase;
+/** Write solved positions back into bound signals. The network's
+ *  self-exclusion stops these writes from re-firing the body; the
+ *  auto-batch keeps them atomic for observers. */
+export declare const writeback: Phase;
+/** Default pipeline: snapshot → prepare → solve → writeback. No time
+ *  integration. Sketchpad / IK / Cassowary scenes use it as-is. */
+export declare const reactivePipeline: readonly Phase[];
+/** Grow a Float64Array to at least `n` slots, preserving contents. */
+export declare function ensureCapacity(buf: Float64Array<ArrayBuffer>, n: number): Float64Array<ArrayBuffer>;

package/dist/constraints/phases.js

@@ -0,0 +1,60 @@
+// phases.ts — pipeline phases for the `Constraints` step.
+//
+// A `Phase` is a plain `(c, dt) => void` doing one piece of work
+// between a signal write (or frame tick) and downstream observers
+// seeing the new state. `step(dt)` runs the pipeline in order.
+//
+// The four built-ins below form the reactive sketchpad pipeline.
+// Specialised factories (`physics`, `world`, …) declare their own
+// pipelines, interleaving these with integration / contact phases.
+/** Read each bound signal into the solver's `positions` buffer. The
+ *  `.value` reads subscribe the network when run inside its body. */
+export const snapshot = c => {
+    const solver = c.solver;
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous binding registry
+    const bindings = c._bindings;
+    const N = solver.cellCount;
+    for (let id = 0; id < N; id++) {
+        const b = bindings[id];
+        if (!b)
+            continue;
+        b.pack.read(b.sig.value, solver.positions, solver.offsets[id]);
+    }
+};
+/** `solver.prepare()` — warm-start λ/penalty, snapshot `initials`,
+ *  reset `anchors = positions`. Integrating factories overwrite
+ *  `anchors` after this phase but before `solve`. */
+export const prepare = c => {
+    c.solver.prepare();
+};
+/** `solver.solve(dt)` — the iteration loop. */
+export const solve = (c, dt) => {
+    c.solver.solve(dt);
+};
+/** Write solved positions back into bound signals. The network's
+ *  self-exclusion stops these writes from re-firing the body; the
+ *  auto-batch keeps them atomic for observers. */
+export const writeback = c => {
+    const solver = c.solver;
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous binding registry
+    const bindings = c._bindings;
+    const N = solver.cellCount;
+    for (let id = 0; id < N; id++) {
+        const b = bindings[id];
+        if (!b)
+            continue;
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic pack
+        b.sig.value = b.pack.write(solver.positions, solver.offsets[id]);
+    }
+};
+/** Default pipeline: snapshot → prepare → solve → writeback. No time
+ *  integration. Sketchpad / IK / Cassowary scenes use it as-is. */
+export const reactivePipeline = [snapshot, prepare, solve, writeback];
+/** Grow a Float64Array to at least `n` slots, preserving contents. */
+export function ensureCapacity(buf, n) {
+    if (buf.length >= n)
+        return buf;
+    const next = new Float64Array(Math.max(n, buf.length * 2));
+    next.set(buf);
+    return next;
+}

package/dist/constraints/physics.d.ts

@@ -0,0 +1,34 @@
+import { Constraints } from "./cluster.js";
+import type { SolverOpts } from "./solver.js";
+export interface PhysicsOpts extends SolverOpts {
+    /** External acceleration (e.g. gravity); length ≥ largest cell dim.
+     *  Default zero. */
+    gravity?: ArrayLike<number>;
+    /** Multiplicative per-tick velocity damping. `1` conserves energy,
+     *  `<1` bleeds it (cloth/rope want `0.97`–`0.995`). Default `1`. */
+    damping?: number;
+    /** Adaptive warm-start (AVBD §3.7): scale the warm-start gravity
+     *  term by how much of last tick's acceleration was in the gravity
+     *  direction — kills jitter under supported bodies. Default `true`
+     *  when gravity is non-zero. */
+    adaptiveWarmstart?: boolean;
+}
+export interface Physics extends Constraints {
+    /** External acceleration vector (read-write Float64Array). */
+    readonly aExt: Float64Array;
+    /** Read velocity for cell `id` into `out` (or a fresh array). */
+    velocity(id: number, out?: number[]): number[];
+    /** Write velocity for cell `id`. */
+    setVelocity(id: number, value: ArrayLike<number>): void;
+    /** Per-tick velocity damping. Mutable post-construction. */
+    damping: number;
+}
+/** Build a physics `Constraints` (`[snapshot, prepare, integrate,
+ *  solveWithVelocity, writeback]`). The reactive driver is disposed —
+ *  drive explicitly via `c.step(dt)` / `animate(c)` / `fixedStep(c)`.
+ *
+ *    const c = physics({ gravity: [0, 90], damping: 0.997 });
+ *    c.add(...springs, pin(grid[0][0]));
+ *    this.anim.start(animate(c));
+ */
+export declare function physics(opts?: PhysicsOpts): Physics;

package/dist/constraints/physics.js

@@ -0,0 +1,128 @@
+// physics.ts — `physics(opts)` factory.
+//
+// A `Constraints` with a velocity + gravity pipeline and the reactive
+// driver disposed. For cloth / chain / particle scenes that need time
+// integration but not rigid-body contacts (use `world(opts)` for those).
+import { Constraints } from "./cluster.js";
+import { ensureCapacity, prepare, snapshot, writeback } from "./phases.js";
+/** Build a physics `Constraints` (`[snapshot, prepare, integrate,
+ *  solveWithVelocity, writeback]`). The reactive driver is disposed —
+ *  drive explicitly via `c.step(dt)` / `animate(c)` / `fixedStep(c)`.
+ *
+ *    const c = physics({ gravity: [0, 90], damping: 0.997 });
+ *    c.add(...springs, pin(grid[0][0]));
+ *    this.anim.start(animate(c));
+ */
+export function physics(opts = {}) {
+    const c = new Constraints(opts);
+    const solver = c.solver;
+    let velocities = new Float64Array(solver.positions.length);
+    let prevVelocities = new Float64Array(velocities.length);
+    const aExt = opts.gravity ? Float64Array.from(opts.gravity) : new Float64Array(0);
+    let aExtNormSq = 0;
+    for (let i = 0; i < aExt.length; i++)
+        aExtNormSq += aExt[i] * aExt[i];
+    let damping = opts.damping ?? 1;
+    const adaptive = (opts.adaptiveWarmstart ?? aExtNormSq > 0) && aExtNormSq > 0;
+    // Integrate phase: between `prepare()` and `solve(dt)`, overwrite
+    // anchors with the inertial extrapolation y = x + dt·v + dt²·g.
+    // Adaptive warm-start gates gravity in the position seed but not in
+    // the inertia anchor.
+    const integrate = (c, dt) => {
+        if (dt <= 0)
+            return;
+        velocities = ensureCapacity(velocities, c.solver.positions.length);
+        prevVelocities = ensureCapacity(prevVelocities, c.solver.positions.length);
+        const dt2 = dt * dt;
+        const aExtLen = aExt.length;
+        const positions = c.solver.positions;
+        const initials = c.solver.initials;
+        const anchors = c.solver.anchors;
+        const masses = c.solver.masses;
+        const dims = c.solver.dims;
+        const offsets = c.solver.offsets;
+        const N = c.solver.cellCount;
+        for (let id = 0; id < N; id++) {
+            const off = offsets[id];
+            if (masses[off] <= 0)
+                continue;
+            const dim = dims[id];
+            let accelWeight = 1;
+            if (adaptive) {
+                let dot = 0;
+                for (let k = 0; k < dim && k < aExtLen; k++) {
+                    const accelK = (velocities[off + k] - prevVelocities[off + k]) / dt;
+                    dot += accelK * aExt[k];
+                }
+                const w = dot / aExtNormSq;
+                accelWeight = w < 0 ? 0 : w > 1 ? 1 : w;
+                if (!Number.isFinite(accelWeight))
+                    accelWeight = 0;
+            }
+            for (let k = 0; k < dim; k++) {
+                const a = k < aExtLen ? aExt[k] : 0;
+                const linTerm = initials[off + k] + dt * velocities[off + k];
+                // Inertial anchor: full gravity (unchanged AVBD inertia term).
+                anchors[off + k] = linTerm + dt2 * a;
+                // Position warm-start: adaptive gravity (smaller for supported bodies).
+                positions[off + k] = linTerm + dt2 * a * accelWeight;
+            }
+        }
+    };
+    // Solve + velocity update. Read velocity in the `beforePostStab`
+    // hook (`(positions − initials) / dt`), before the post-stab
+    // projection — folding that projection into velocity would
+    // re-introduce the drift it removed.
+    const solveWithVelocity = (c, dt) => {
+        c.solver.solve(dt, () => {
+            if (dt <= 0)
+                return;
+            const positions = c.solver.positions;
+            const initials = c.solver.initials;
+            const masses = c.solver.masses;
+            const dims = c.solver.dims;
+            const offsets = c.solver.offsets;
+            const N = c.solver.cellCount;
+            for (let id = 0; id < N; id++) {
+                const off = offsets[id];
+                if (masses[off] <= 0)
+                    continue;
+                const dim = dims[id];
+                for (let k = 0; k < dim; k++) {
+                    prevVelocities[off + k] = velocities[off + k];
+                    velocities[off + k] = ((positions[off + k] - initials[off + k]) / dt) * damping;
+                }
+            }
+        });
+    };
+    c.pipeline = [snapshot, prepare, integrate, solveWithVelocity, writeback];
+    // Take over the time loop — reactive solving would conflict with
+    // per-tick velocity integration.
+    c.dispose();
+    Object.defineProperty(c, "aExt", { value: aExt, writable: false, enumerable: true });
+    Object.defineProperty(c, "damping", {
+        get: () => damping,
+        set: (v) => {
+            damping = v;
+        },
+        enumerable: true,
+    });
+    c.velocity = (id, out = []) => {
+        velocities = ensureCapacity(velocities, c.solver.positions.length);
+        const off = c.solver.offsets[id];
+        const dim = c.solver.dims[id];
+        for (let k = 0; k < dim; k++)
+            out[k] = velocities[off + k];
+        out.length = dim;
+        return out;
+    };
+    c.setVelocity = (id, value) => {
+        velocities = ensureCapacity(velocities, c.solver.positions.length);
+        prevVelocities = ensureCapacity(prevVelocities, c.solver.positions.length);
+        const off = c.solver.offsets[id];
+        const dim = c.solver.dims[id];
+        for (let k = 0; k < dim; k++)
+            velocities[off + k] = value[k] ?? 0;
+    };
+    return c;
+}