bireactive 0.2.0

package/dist/constraints/cluster.d.ts

@@ -0,0 +1,83 @@
+import { type Cell, type Lifecycle, type Read } from "../core/index.js";
+import { type Phase } from "./phases.js";
+import { Solver, type SolverOpts } from "./solver.js";
+/** A constraint relation. `bind(c)` sets up (cell binding, term
+ *  registration, …) and returns a disposer. */
+export interface Relation {
+    bind(c: Constraints): () => void;
+}
+export declare class Constraints {
+    /** The numerical solver underneath. Phases read/write its buffers. */
+    readonly solver: Solver;
+    /** Phases run on each `step(dt)`. Mutable — factories specialise by
+     *  reassigning. Defaults to the reactive pipeline. */
+    pipeline: Phase[];
+    private readonly _sigToCell;
+    private readonly _bindings;
+    /** Active-relation disposers, keyed by relation reference. */
+    private readonly _disposers;
+    /** Add / remove hooks for factories tracking relation kinds (e.g.
+     *  `world` tracks `Body` instances for the broadphase). */
+    private readonly _addHooks;
+    private readonly _removeHooks;
+    /** Bumped on structural change so the reactive driver re-fires. */
+    private readonly _gen;
+    /** Reactive driver: a network calling `step()` on signal change.
+     *  Lazy-installed on first `_bind`; permanently silenced once
+     *  `dispose()`d (e.g. when physics/world take the time loop). */
+    private _network?;
+    private _networkDisposed;
+    constructor(opts?: SolverOpts);
+    get iterations(): number;
+    set iterations(v: number);
+    get alpha(): number;
+    set alpha(v: number);
+    get beta(): number;
+    set beta(v: number);
+    get gamma(): number;
+    set gamma(v: number);
+    get postStabilize(): boolean;
+    set postStabilize(v: boolean);
+    /** Run the pipeline once. `dt` defaults to `1` (static-edit case);
+     *  physics callers pass the real frame `dt`. */
+    step(dt?: number): void;
+    /** Add one or more relations. Single-arg returns the relation;
+     *  multi-arg returns an array (destructure as needed). */
+    add<R extends Relation>(rel: R): R;
+    add<R extends Relation>(rel1: R, rel2: R, ...rest: R[]): R[];
+    private _addOne;
+    /** Add `rels` while `cond` is truthy; remove them when falsy. */
+    addWhile(cond: Read<unknown>, ...rels: Relation[]): Lifecycle;
+    /** Remove a relation. No-op if not previously added. */
+    remove(rel: Relation): void;
+    /** Subscribe to relation-add events. Returns an unsubscribe thunk.
+     *  Called synchronously from `add` after the relation's `bind` runs. */
+    onAdd(fn: (rel: Relation) => void): () => void;
+    /** Subscribe to relation-remove events. Returns an unsubscribe thunk. */
+    onRemove(fn: (rel: Relation) => void): () => void;
+    /** Tear down the reactive driver, permanently — later `add`/`_bind`
+     *  won't re-install it. Bound signals keep their values but stop
+     *  being constraint-driven; `step(dt)` is the only way to advance.
+     *  Physics-flavored factories call this to take the time loop. */
+    dispose(): void;
+    /** Number of bound signal cells (= solver cell count). */
+    get cellCount(): number;
+    /** @internal — bind a signal as a cell. Idempotent (same signal →
+     *  same id); cells are append-only for the cluster's lifetime. */
+    _bind(sig: Cell<any>): number;
+    /** @internal — subscribe a reactive Term parameter. Without this,
+     *  mutating the param wouldn't fire the network (body reads don't
+     *  auto-track). Called from relations with reactive params. */
+    _trackParam(sig: Cell<any>): void;
+    /** Params bound before the network existed; folded in at install. */
+    private _pendingParamDeps;
+    private _installReactiveDriver;
+}
+/** Build a reactive `Constraints` (sketchpad / IK / layout, no time
+ *  integration). For physics use `physics(opts)` or `world(opts)`.
+ *
+ *    const c = constraints({ iterations: 24 });
+ *    c.add(distance(a, b, 100));
+ *    c.iterations = 30;
+ */
+export declare function constraints(opts?: SolverOpts): Constraints;

package/dist/constraints/cluster.js

@@ -0,0 +1,213 @@
+// cluster.ts — the `Constraints` holder.
+//
+// Holds a `Solver`, a registry of relations, and a `pipeline` of
+// phases run on every `step(dt)`. The default reactive pipeline plus
+// a driver that fires on bound-signal changes make a freshly
+// constructed `Constraints` a sketchpad-style reactive solver with
+// no further setup.
+//
+// Specialised factories (`physics`, `world`, …) overwrite the
+// pipeline, allocate their own per-cell state, and dispose the
+// reactive driver to take over the time loop.
+//
+// Relation contract: `bind(c)` registers what the relation needs and
+// returns a disposer. `c.add(rel)` calls `bind`; `c.remove(rel)`
+// calls the disposer.
+import { cell, network, requirePack, } from "../core/index.js";
+import { when } from "../core/network-utils.js";
+import { reactivePipeline } from "./phases.js";
+import { Solver } from "./solver.js";
+export class Constraints {
+    /** The numerical solver underneath. Phases read/write its buffers. */
+    solver;
+    /** Phases run on each `step(dt)`. Mutable — factories specialise by
+     *  reassigning. Defaults to the reactive pipeline. */
+    pipeline;
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous binding registry
+    _sigToCell = new Map();
+    _bindings = [];
+    /** Active-relation disposers, keyed by relation reference. */
+    _disposers = new Map();
+    /** Add / remove hooks for factories tracking relation kinds (e.g.
+     *  `world` tracks `Body` instances for the broadphase). */
+    _addHooks = new Set();
+    _removeHooks = new Set();
+    /** Bumped on structural change so the reactive driver re-fires. */
+    _gen;
+    /** Reactive driver: a network calling `step()` on signal change.
+     *  Lazy-installed on first `_bind`; permanently silenced once
+     *  `dispose()`d (e.g. when physics/world take the time loop). */
+    _network;
+    _networkDisposed = false;
+    constructor(opts = {}) {
+        this.solver = new Solver(opts);
+        this._gen = cell(0);
+        this.pipeline = reactivePipeline.slice();
+    }
+    get iterations() {
+        return this.solver.iterations;
+    }
+    set iterations(v) {
+        this.solver.iterations = v;
+    }
+    get alpha() {
+        return this.solver.alpha;
+    }
+    set alpha(v) {
+        this.solver.alpha = v;
+    }
+    get beta() {
+        return this.solver.beta;
+    }
+    set beta(v) {
+        this.solver.beta = v;
+    }
+    get gamma() {
+        return this.solver.gamma;
+    }
+    set gamma(v) {
+        this.solver.gamma = v;
+    }
+    get postStabilize() {
+        return this.solver.postStabilize;
+    }
+    set postStabilize(v) {
+        this.solver.postStabilize = v;
+    }
+    /** Run the pipeline once. `dt` defaults to `1` (static-edit case);
+     *  physics callers pass the real frame `dt`. */
+    step(dt = 1) {
+        const p = this.pipeline;
+        for (let i = 0; i < p.length; i++)
+            p[i](this, dt);
+    }
+    add(...rels) {
+        for (const rel of rels)
+            this._addOne(rel);
+        return rels.length === 1 ? rels[0] : rels;
+    }
+    _addOne(rel) {
+        if (this._disposers.has(rel))
+            return;
+        const dispose = rel.bind(this);
+        this._disposers.set(rel, dispose);
+        for (const fn of this._addHooks)
+            fn(rel);
+    }
+    /** Add `rels` while `cond` is truthy; remove them when falsy. */
+    addWhile(cond, ...rels) {
+        return when(cond, () => {
+            for (const r of rels)
+                this._addOne(r);
+            return () => {
+                for (const r of rels) {
+                    const dispose = this._disposers.get(r);
+                    if (dispose === undefined)
+                        continue;
+                    dispose();
+                    this._disposers.delete(r);
+                    for (const fn of this._removeHooks)
+                        fn(r);
+                }
+                this._gen.value += 1;
+            };
+        });
+    }
+    /** Remove a relation. No-op if not previously added. */
+    remove(rel) {
+        const dispose = this._disposers.get(rel);
+        if (dispose === undefined)
+            return;
+        dispose();
+        this._disposers.delete(rel);
+        for (const fn of this._removeHooks)
+            fn(rel);
+        this._gen.value += 1;
+    }
+    /** Subscribe to relation-add events. Returns an unsubscribe thunk.
+     *  Called synchronously from `add` after the relation's `bind` runs. */
+    onAdd(fn) {
+        this._addHooks.add(fn);
+        return () => this._addHooks.delete(fn);
+    }
+    /** Subscribe to relation-remove events. Returns an unsubscribe thunk. */
+    onRemove(fn) {
+        this._removeHooks.add(fn);
+        return () => this._removeHooks.delete(fn);
+    }
+    /** Tear down the reactive driver, permanently — later `add`/`_bind`
+     *  won't re-install it. Bound signals keep their values but stop
+     *  being constraint-driven; `step(dt)` is the only way to advance.
+     *  Physics-flavored factories call this to take the time loop. */
+    dispose() {
+        if (this._network !== undefined) {
+            this._network.dispose();
+            this._network = undefined;
+        }
+        this._networkDisposed = true;
+    }
+    /** Number of bound signal cells (= solver cell count). */
+    get cellCount() {
+        return this._sigToCell.size;
+    }
+    /** @internal — bind a signal as a cell. Idempotent (same signal →
+     *  same id); cells are append-only for the cluster's lifetime. */
+    // biome-ignore lint/suspicious/noExplicitAny: see header
+    _bind(sig) {
+        const existing = this._sigToCell.get(sig);
+        if (existing !== undefined)
+            return existing;
+        const pack = requirePack(sig);
+        const id = this.solver.addCell(pack.dim);
+        pack.read(sig.peek(), this.solver.positions, this.solver.offsets[id]);
+        this._sigToCell.set(sig, id);
+        this._bindings[id] = { sig, pack };
+        if (this._network === undefined && !this._networkDisposed) {
+            this._installReactiveDriver();
+        }
+        else if (this._network !== undefined) {
+            // Network already running — subscribe the new cell so its later
+            // `.value` mutations fire the body and trigger a solve.
+            this._network.subscribe(sig);
+        }
+        this._gen.value += 1;
+        return id;
+    }
+    /** @internal — subscribe a reactive Term parameter. Without this,
+     *  mutating the param wouldn't fire the network (body reads don't
+     *  auto-track). Called from relations with reactive params. */
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous params
+    _trackParam(sig) {
+        if (this._network !== undefined)
+            this._network.subscribe(sig);
+        else
+            this._pendingParamDeps.push(sig);
+    }
+    /** Params bound before the network existed; folded in at install. */
+    // biome-ignore lint/suspicious/noExplicitAny: same
+    _pendingParamDeps = [];
+    _installReactiveDriver() {
+        const gen = this._gen;
+        const initialDeps = [gen];
+        for (const [sig] of this._sigToCell)
+            initialDeps.push(sig);
+        for (const sig of this._pendingParamDeps)
+            initialDeps.push(sig);
+        this._pendingParamDeps.length = 0;
+        this._network = network(initialDeps, () => {
+            // Explicit-deps mode: body reads don't subscribe; deps come from
+            // the initial array + later `subscribe(...)` in `_bind`/`_trackParam`.
+            this.step();
+        });
+    }
+}
+/** Build a reactive `Constraints` (sketchpad / IK / layout, no time
+ *  integration). For physics use `physics(opts)` or `world(opts)`.
+ *
+ *    const c = constraints({ iterations: 24 });
+ *    c.add(distance(a, b, 100));
+ *    c.iterations = 30;
+ */
+export function constraints(opts = {}) {
+    return new Constraints(opts);
+}

package/dist/constraints/drivers.d.ts

@@ -0,0 +1,15 @@
+import type { Tick } from "../animation/anim.js";
+import type { Constraints } from "./cluster.js";
+/** Real-time driver: advance by the actual frame `dt`. Mainly for
+ *  cloth / particle physics (reactive scenes self-fire). */
+export declare function animate(c: Constraints): Generator<undefined, never, Tick>;
+/** Fixed-`dt` sub-stepping: accumulate frame time and fire as many
+ *  fixed steps as fit (capped at `maxSubSteps` against the
+ *  spiral-of-death). Fixed `dt` avoids the jitter variable `dt`
+ *  causes in warm-start / extrapolation / velocity. Defaults
+ *  (1/60s, 4) match the AVBD demo. */
+export declare function fixedStep(c: Constraints, fixedDt: number, maxSubSteps?: number): Generator<undefined, never, Tick>;
+/** Time-dilated driver: scale the wall-clock dt by `factor()` each
+ *  frame. `factor` is a thunk so callers can flip it live (slow-mo
+ *  toggles, pause via `factor: () => 0`, scrubbing, etc.). */
+export declare function dilated(c: Constraints, factor: () => number): Generator<undefined, never, Tick>;

package/dist/constraints/drivers.js

@@ -0,0 +1,40 @@
+// drivers.ts — animation drivers for `Constraints.step(dt)`.
+//
+// Generators that wrap `c.step(dt)` with different rhythms. Driven by
+// any `Tick`-yielding animation loop (`anim.start(...)`). Custom
+// drivers (scrubbing, pause/resume) just yield then call `c.step`.
+/** Real-time driver: advance by the actual frame `dt`. Mainly for
+ *  cloth / particle physics (reactive scenes self-fire). */
+export function* animate(c) {
+    for (;;) {
+        const tick = yield;
+        c.step(tick.dt);
+    }
+}
+/** Fixed-`dt` sub-stepping: accumulate frame time and fire as many
+ *  fixed steps as fit (capped at `maxSubSteps` against the
+ *  spiral-of-death). Fixed `dt` avoids the jitter variable `dt`
+ *  causes in warm-start / extrapolation / velocity. Defaults
+ *  (1/60s, 4) match the AVBD demo. */
+export function* fixedStep(c, fixedDt, maxSubSteps = 4) {
+    let acc = 0;
+    for (;;) {
+        const tick = yield;
+        acc += Math.min(tick.dt, fixedDt * maxSubSteps);
+        let n = 0;
+        while (acc >= fixedDt && n < maxSubSteps) {
+            c.step(fixedDt);
+            acc -= fixedDt;
+            n++;
+        }
+    }
+}
+/** Time-dilated driver: scale the wall-clock dt by `factor()` each
+ *  frame. `factor` is a thunk so callers can flip it live (slow-mo
+ *  toggles, pause via `factor: () => 0`, scrubbing, etc.). */
+export function* dilated(c, factor) {
+    for (;;) {
+        const tick = yield;
+        c.step(tick.dt * factor());
+    }
+}

package/dist/constraints/factories.d.ts

@@ -0,0 +1,73 @@
+import { type Cell, type Writable } from "../core/index.js";
+import type { Relation } from "./cluster.js";
+import { type ResidualFn, Strength } from "./terms.js";
+export { Strength };
+type S = Cell<any>;
+/** Pin a signal in place: while attached, its solver cell has mass 0
+ *  (kinematic). Removing the relation restores the prior mass.
+ *
+ *    c.add(pin(O1));                       // static pin
+ *    c.addWhile(h.dragging, pin(sig));     // conditional pin */
+export declare function pin(sig: S): Relation;
+/** Hard equality `a = b`. Cell dims must match. */
+export declare function eq(a: S, b: S): Relation;
+/** Distance constraint `‖b − a‖ = rest`. Hard by default; pass
+ *  `stiffness` for a Hooke spring. `rest` and `stiffness` are mutable
+ *  signals on the returned relation. */
+export interface DistanceRelation extends Relation {
+    readonly rest: Writable<Cell<number>>;
+    /** Present only for the spring (finite-stiffness) variant. */
+    readonly stiffness?: Writable<Cell<number>>;
+}
+export declare function distance(a: S, b: S, rest: number | Writable<Cell<number>>, opts?: {
+    stiffness?: number | Writable<Cell<number>>;
+}): DistanceRelation;
+/** Soft distance constraint — alias for `distance(a, b, rest, { stiffness })`. */
+export declare function spring(a: S, b: S, rest: number | Writable<Cell<number>>, stiffness: number | Writable<Cell<number>>): DistanceRelation;
+/** Scalar relation `b = fwd(a)` between two `Num` signals. */
+export declare function lensNum(a: S, b: S, fwd: (x: number) => number): Relation;
+/** Hard 1D range `lo ≤ x ≤ hi`. `r.lo` / `r.hi` are mutable signals. */
+export declare function clamp(x: S, lo: number | Writable<Cell<number>>, hi: number | Writable<Cell<number>>): Relation & {
+    lo: Writable<Cell<number>>;
+    hi: Writable<Cell<number>>;
+};
+/** Hard minimum distance: `‖b − a‖ ≥ minDist`. */
+export declare function gap(a: S, b: S, minDist: number): Relation;
+/** Soft long-range repulsion: pushes two points apart with force
+ *  `stiffness · (range − ‖b − a‖)` while they're closer than `range`,
+ *  dropping to zero outside. */
+export declare function repel(a: S, b: S, range: number, stiffness: number): Relation;
+/** Hard rectangular containment: keep a `Vec` inside the AABB
+ *  `[xLo, xHi] × [yLo, yHi]`. */
+export declare function inside(P: S, xLo: number, yLo: number, xHi: number, yHi: number): Relation;
+/** Hard inequality `a ≤ b`. */
+export declare function leq(a: S, b: S): Relation;
+/** Hard inequality `a ≥ b`. */
+export declare function geq(a: S, b: S): Relation;
+/** Pull `cell` toward `target` with finite stiffness. */
+export declare function softTarget(cell: S, target: ArrayLike<number>, stiffness: number): Relation;
+/** Custom constraint with `rows` residual outputs computed by `fn`. */
+export declare function generic(cells: readonly S[], rows: number, fn: ResidualFn, opts?: {
+    fdStep?: number;
+    hard?: boolean;
+    stiffness?: number;
+    lambdaMax?: readonly number[];
+}): Relation;
+/** Interior angle ABC = θ. */
+export declare function angle(A: S, B: S, C: S, theta: number): Relation;
+/** Lines AB ∥ CD: cross product of direction vectors = 0. */
+export declare function parallel(A: S, B: S, C: S, D: S): Relation;
+/** Lines AB ⟂ CD: dot product = 0. */
+export declare function perpendicular(A: S, B: S, C: S, D: S): Relation;
+/** Right angle at B between segments AB and BC. */
+export declare function rightAngle(A: S, B: S, C: S): Relation;
+/** Soft 3-point bending resistance at vertex B. */
+export declare function bend(A: S, B: S, C: S, stiffness?: number): Relation;
+/** Point P on line AB. */
+export declare function collinear(P: S, A: S, B: S): Relation;
+/** Point P on a circle of given center and radius. */
+export declare function onCircle(P: S, center: S, radius: number): Relation;
+/** Equal distance: ‖A − B‖ = ‖C − D‖. */
+export declare function equalDist(A: S, B: S, C: S, D: S): Relation;
+/** Midpoint: M = (A + B) / 2. */
+export declare function midpoint(M: S, A: S, B: S): Relation;

package/dist/constraints/factories.js

@@ -0,0 +1,248 @@
+// factories.ts — free constraint factories returning `Relation`s.
+//
+// Each returns a plain object with a `bind(c)` (→ disposer) plus
+// `Cell` fields for mutable params. Pass a number (wrapped in a
+// fresh signal) or your own signal (used directly, so UI bindings
+// flow through):
+//
+//   const len = signal(100);
+//   const r = c.add(distance(a, b, len));
+//   len.value = 50;     // re-solves
+//   r.rest.value = 75;  // same underlying signal
+//
+// Cell-signal args must declare the `pack` trait (checked in `_bind`).
+//
+// Caveats:
+//   - Multi-solution constraints can branch-flip under fast drags (no
+//     branch tracking).
+//   - Infeasible configs saturate, not explode (λ capped at LAMBDA_MAX).
+//   - Duplicate cells in `generic` (e.g. `[A, B, B, C]`) are treated as
+//     independent by the FD path — use `rightAngle(A, B, C)`, not
+//     `perpendicular(A, B, B, C)`.
+import { cell } from "../core/index.js";
+import { BoundsTerm, DistanceTerm, EqTerm, GenericTerm, LensNumTerm, SoftTargetTerm, Strength, } from "./terms.js";
+export { Strength };
+/** Pin a signal in place: while attached, its solver cell has mass 0
+ *  (kinematic). Removing the relation restores the prior mass.
+ *
+ *    c.add(pin(O1));                       // static pin
+ *    c.addWhile(h.dragging, pin(sig));     // conditional pin */
+export function pin(sig) {
+    return {
+        bind(c) {
+            const id = c._bind(sig);
+            const prev = c.solver.massOf(id);
+            c.solver.setMass(id, 0);
+            return () => c.solver.setMass(id, prev);
+        },
+    };
+}
+/** Hard equality `a = b`. Cell dims must match. */
+export function eq(a, b) {
+    return {
+        bind(c) {
+            const f = new EqTerm(c.solver, c._bind(a), c._bind(b));
+            c.solver.addTerm(f);
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+export function distance(a, b, rest, opts) {
+    const rest_ = cell(rest);
+    const hard = opts?.stiffness === undefined;
+    const stiff_ = hard ? undefined : cell(opts.stiffness);
+    return {
+        rest: rest_,
+        stiffness: stiff_,
+        bind(c) {
+            const f = new DistanceTerm(c.solver, c._bind(a), c._bind(b), rest_, hard, stiff_);
+            c.solver.addTerm(f);
+            // Track params so mutating rest / stiffness fires the network.
+            c._trackParam(rest_);
+            if (stiff_ !== undefined)
+                c._trackParam(stiff_);
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+/** Soft distance constraint — alias for `distance(a, b, rest, { stiffness })`. */
+export function spring(a, b, rest, stiffness) {
+    return distance(a, b, rest, { stiffness });
+}
+/** Scalar relation `b = fwd(a)` between two `Num` signals. */
+export function lensNum(a, b, fwd) {
+    return {
+        bind(c) {
+            const f = new LensNumTerm(c.solver, c._bind(a), c._bind(b), fwd);
+            c.solver.addTerm(f);
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+/** Hard 1D range `lo ≤ x ≤ hi`. `r.lo` / `r.hi` are mutable signals. */
+export function clamp(x, lo, hi) {
+    const lo_ = cell(lo);
+    const hi_ = cell(hi);
+    return {
+        lo: lo_,
+        hi: hi_,
+        bind(c) {
+            const f = new BoundsTerm(c.solver, c._bind(x), lo_, hi_);
+            c.solver.addTerm(f);
+            c._trackParam(lo_);
+            c._trackParam(hi_);
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+/** Hard minimum distance: `‖b − a‖ ≥ minDist`. */
+export function gap(a, b, minDist) {
+    return generic([a, b], 1, (pos, out) => {
+        const dx = pos[1][0] - pos[0][0];
+        const dy = pos[1][1] - pos[0][1];
+        out[0] = Math.hypot(dx, dy) - minDist;
+    }, { lambdaMax: [0] });
+}
+/** Soft long-range repulsion: pushes two points apart with force
+ *  `stiffness · (range − ‖b − a‖)` while they're closer than `range`,
+ *  dropping to zero outside. */
+export function repel(a, b, range, stiffness) {
+    return generic([a, b], 1, (pos, out) => {
+        const dx = pos[1][0] - pos[0][0];
+        const dy = pos[1][1] - pos[0][1];
+        out[0] = Math.hypot(dx, dy) - range;
+    }, { hard: false, stiffness, lambdaMax: [0] });
+}
+/** Hard rectangular containment: keep a `Vec` inside the AABB
+ *  `[xLo, xHi] × [yLo, yHi]`. */
+export function inside(P, xLo, yLo, xHi, yHi) {
+    return generic([P], 4, (pos, out) => {
+        const p = pos[0];
+        out[0] = p[0] - xLo;
+        out[1] = xHi - p[0];
+        out[2] = p[1] - yLo;
+        out[3] = yHi - p[1];
+    }, { lambdaMax: [0, 0, 0, 0] });
+}
+/** Hard inequality `a ≤ b`. */
+export function leq(a, b) {
+    return generic([a, b], 1, (pos, out) => {
+        out[0] = pos[1][0] - pos[0][0];
+    }, { lambdaMax: [0] });
+}
+/** Hard inequality `a ≥ b`. */
+export function geq(a, b) {
+    return leq(b, a);
+}
+/** Pull `cell` toward `target` with finite stiffness. */
+export function softTarget(cell, target, stiffness) {
+    return {
+        bind(c) {
+            const f = new SoftTargetTerm(c.solver, c._bind(cell), target, stiffness);
+            c.solver.addTerm(f);
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+/** Custom constraint with `rows` residual outputs computed by `fn`. */
+export function generic(cells, rows, fn, opts) {
+    return {
+        bind(c) {
+            const f = new GenericTerm(c.solver, cells.map(s => c._bind(s)), rows, fn, opts);
+            c.solver.addTerm(f);
+            if (opts?.lambdaMax) {
+                for (let i = 0; i < opts.lambdaMax.length && i < rows; i++) {
+                    f.lambdaMax[i] = opts.lambdaMax[i];
+                }
+            }
+            return () => c.solver.removeTerm(f);
+        },
+    };
+}
+/** Interior angle ABC = θ. */
+export function angle(A, B, C, theta) {
+    return generic([A, B, C], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2];
+        const ux = a[0] - b[0], uy = a[1] - b[1];
+        const vx = cc[0] - b[0], vy = cc[1] - b[1];
+        const lu = Math.hypot(ux, uy);
+        const lv = Math.hypot(vx, vy);
+        if (lu < 1e-12 || lv < 1e-12) {
+            out[0] = 0;
+            return;
+        }
+        const cosA = (ux * vx + uy * vy) / (lu * lv);
+        const cur = Math.acos(cosA < -1 ? -1 : cosA > 1 ? 1 : cosA);
+        out[0] = cur - theta;
+    });
+}
+/** Lines AB ∥ CD: cross product of direction vectors = 0. */
+export function parallel(A, B, C, D) {
+    return generic([A, B, C, D], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2], d = pos[3];
+        const ux = b[0] - a[0], uy = b[1] - a[1];
+        const vx = d[0] - cc[0], vy = d[1] - cc[1];
+        out[0] = ux * vy - uy * vx;
+    });
+}
+/** Lines AB ⟂ CD: dot product = 0. */
+export function perpendicular(A, B, C, D) {
+    return generic([A, B, C, D], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2], d = pos[3];
+        const ux = b[0] - a[0], uy = b[1] - a[1];
+        const vx = d[0] - cc[0], vy = d[1] - cc[1];
+        out[0] = ux * vx + uy * vy;
+    });
+}
+/** Right angle at B between segments AB and BC. */
+export function rightAngle(A, B, C) {
+    return generic([A, B, C], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2];
+        const ux = b[0] - a[0], uy = b[1] - a[1];
+        const vx = cc[0] - b[0], vy = cc[1] - b[1];
+        out[0] = ux * vx + uy * vy;
+    });
+}
+/** Soft 3-point bending resistance at vertex B. */
+export function bend(A, B, C, stiffness = Strength.MEDIUM) {
+    return generic([A, B, C], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2];
+        const ux = b[0] - a[0], uy = b[1] - a[1];
+        const vx = cc[0] - b[0], vy = cc[1] - b[1];
+        out[0] = ux * vy - uy * vx;
+    }, { hard: false, stiffness });
+}
+/** Point P on line AB. */
+export function collinear(P, A, B) {
+    return generic([P, A, B], 1, (pos, out) => {
+        const p = pos[0], a = pos[1], b = pos[2];
+        const ux = p[0] - a[0], uy = p[1] - a[1];
+        const vx = b[0] - a[0], vy = b[1] - a[1];
+        out[0] = ux * vy - uy * vx;
+    });
+}
+/** Point P on a circle of given center and radius. */
+export function onCircle(P, center, radius) {
+    return generic([P, center], 1, (pos, out) => {
+        const p = pos[0], cc = pos[1];
+        const dx = p[0] - cc[0], dy = p[1] - cc[1];
+        out[0] = Math.hypot(dx, dy) - radius;
+    });
+}
+/** Equal distance: ‖A − B‖ = ‖C − D‖. */
+export function equalDist(A, B, C, D) {
+    return generic([A, B, C, D], 1, (pos, out) => {
+        const a = pos[0], b = pos[1], cc = pos[2], d = pos[3];
+        const ab = Math.hypot(a[0] - b[0], a[1] - b[1]);
+        const cd = Math.hypot(cc[0] - d[0], cc[1] - d[1]);
+        out[0] = ab - cd;
+    });
+}
+/** Midpoint: M = (A + B) / 2. */
+export function midpoint(M, A, B) {
+    return generic([M, A, B], 2, (pos, out) => {
+        const m = pos[0], a = pos[1], b = pos[2];
+        out[0] = 2 * m[0] - a[0] - b[0];
+        out[1] = 2 * m[1] - a[1] - b[1];
+    });
+}

package/dist/constraints/index.d.ts

@@ -0,0 +1,11 @@
+export { Constraints, constraints, type Relation } 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 { type Phase, prepare, snapshot, solve, writeback } from "./phases.js";
+export { type Physics, type PhysicsOpts, physics } from "./physics.js";
+export { Body, BodyAnchor, BodyAnchorTerm, type BodyInit, type BodyOpts, BoxContact, body, bodyAnchor, Joint, type JointStiffness, JointTerm, joint, weld, } from "./rigid.js";
+export { Solver, type SolverOpts } from "./solver.js";
+export { LAMBDA_MAX, PENALTY_MAX, PENALTY_MIN, Term } from "./term.js";
+export { BoundsTerm, DistanceTerm, EqTerm, GenericTerm, LensNumTerm, type ResidualFn, SoftTargetTerm, Strength, } from "./terms.js";
+export { type World, type WorldOpts, world } from "./world.js";