bireactive 0.2.0

package/dist/constraints/world.js

@@ -0,0 +1,245 @@
+// world.ts — `world(opts)` factory for 2D rigid-body scenes.
+//
+// Builds a `Constraints` with a physics + contacts pipeline:
+//
+//   [angularClamp, broadphase, snapshot, prepare, integrate,
+//    solveWithVelocity, writeback]
+//
+// Tracks bodies (via `onAdd`/`onRemove`), runs the box-box contact
+// manifold lifecycle, and skips joint-linked pairs in the broadphase.
+// The reactive driver is disposed on construction — rigid scenes
+// drive their step explicitly (`world.step(dt)`, `animate(world)`,
+// `fixedStep(world, 1/60)`). Splice `c.pipeline` to extend.
+import { Constraints } from "./cluster.js";
+import { ensureCapacity, prepare, snapshot, writeback } from "./phases.js";
+import { Body, BoxContact, Joint } from "./rigid.js";
+/** Build a `Constraints` configured for 2D rigid-body physics:
+ *  velocity + gravity + broadphase + contact manifolds.
+ *
+ *    const w = world({ gravity: [0, 1500], iterations: 24 });
+ *    const a = w.add(body({ size: { w: 40, h: 40 } }, { x: 0, y: 0 }));
+ *    const b = w.add(body({ size: { w: 40, h: 40 } }, { x: 100, y: 0 }));
+ *    w.add(joint(a, b, { x: 0, y: 0 }, { x: 0, y: 0 }));
+ *    this.anim.start(fixedStep(w, 1/60));
+ */
+export function world(opts = {}) {
+    // Defaults tuned for AVBD physics — postStabilize + gentle damping.
+    const c = new Constraints({
+        iterations: opts.iterations ?? 10,
+        alpha: opts.alpha ?? 0.99,
+        beta: opts.beta ?? 1e5,
+        gamma: opts.gamma ?? 0.99,
+        postStabilize: opts.postStabilize ?? true,
+    });
+    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;
+    const maxAngularSpeed = opts.maxAngularSpeed ?? 50;
+    const bodies = [];
+    const manifolds = new Map();
+    const jointed = new Map();
+    c.onAdd(rel => {
+        if (rel instanceof Body) {
+            bodies.push(rel);
+        }
+        else if (rel instanceof Joint) {
+            // Joint must be added AFTER its bodies (so cellIds are set).
+            const lo = Math.min(rel.bodyA.cellId, rel.bodyB.cellId);
+            const hi = Math.max(rel.bodyA.cellId, rel.bodyB.cellId);
+            const key = `${lo}_${hi}`;
+            jointed.set(key, (jointed.get(key) ?? 0) + 1);
+        }
+    });
+    c.onRemove(rel => {
+        if (rel instanceof Body) {
+            const idx = bodies.indexOf(rel);
+            if (idx >= 0)
+                bodies.splice(idx, 1);
+        }
+        else if (rel instanceof Joint) {
+            const lo = Math.min(rel.bodyA.cellId, rel.bodyB.cellId);
+            const hi = Math.max(rel.bodyA.cellId, rel.bodyB.cellId);
+            const key = `${lo}_${hi}`;
+            const n = (jointed.get(key) ?? 0) - 1;
+            if (n <= 0)
+                jointed.delete(key);
+            else
+                jointed.set(key, n);
+        }
+    });
+    // Clamp ω to ±maxAngularSpeed first each sub-step.
+    const angularClamp = (c, dt) => {
+        if (dt <= 0)
+            return;
+        velocities = ensureCapacity(velocities, c.solver.positions.length);
+        const offsets = c.solver.offsets;
+        const dims = c.solver.dims;
+        for (const body of bodies) {
+            if (body.cellId < 0)
+                continue;
+            const off = offsets[body.cellId];
+            if (dims[body.cellId] >= 3) {
+                const w = velocities[off + 2];
+                if (w > maxAngularSpeed)
+                    velocities[off + 2] = maxAngularSpeed;
+                else if (w < -maxAngularSpeed)
+                    velocities[off + 2] = -maxAngularSpeed;
+            }
+        }
+    };
+    // Broadphase: O(n²) bounding-radius sweep. Creates a `BoxContact`
+    // per newly-overlapping pair, disposes manifolds that no longer
+    // overlap. Joint-linked pairs are skipped.
+    const broadphase = c => {
+        const N = bodies.length;
+        const positions = c.solver.positions;
+        const offsets = c.solver.offsets;
+        const seen = new Set();
+        for (let i = 0; i < N; i++) {
+            const A = bodies[i];
+            if (A.cellId < 0)
+                continue;
+            const aOff = offsets[A.cellId];
+            const ax = positions[aOff];
+            const ay = positions[aOff + 1];
+            for (let j = i + 1; j < N; j++) {
+                const B = bodies[j];
+                if (B.cellId < 0)
+                    continue;
+                if (A.mass === 0 && B.mass === 0)
+                    continue;
+                const lo = Math.min(A.cellId, B.cellId);
+                const hi = Math.max(A.cellId, B.cellId);
+                if (jointed.has(`${lo}_${hi}`))
+                    continue;
+                const bOff = offsets[B.cellId];
+                const dx = ax - positions[bOff];
+                const dy = ay - positions[bOff + 1];
+                const r = A.radius + B.radius;
+                if (dx * dx + dy * dy > r * r)
+                    continue;
+                const key = `${lo}_${hi}`;
+                seen.add(key);
+                if (!manifolds.has(key)) {
+                    const m = new BoxContact(c.solver, A, B);
+                    c.solver.addTerm(m);
+                    manifolds.set(key, m);
+                }
+            }
+        }
+        for (const [key, m] of manifolds) {
+            if (!seen.has(key)) {
+                m.dispose();
+                manifolds.delete(key);
+            }
+        }
+    };
+    // Integrate (inertial extrapolation). Same shape as `physics()`'s
+    // integrate; kept local (closing over `velocities` / `aExt` /
+    // `damping`) to stay self-contained.
+    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];
+                anchors[off + k] = linTerm + dt2 * a;
+                positions[off + k] = linTerm + dt2 * a * accelWeight;
+            }
+        }
+    };
+    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 = [
+        angularClamp,
+        broadphase,
+        snapshot,
+        prepare,
+        integrate,
+        solveWithVelocity,
+        writeback,
+    ];
+    // Take over the time loop.
+    c.dispose();
+    Object.defineProperty(c, "aExt", { value: aExt, writable: false, enumerable: true });
+    Object.defineProperty(c, "bodies", { value: bodies, 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;
+}

package/dist/core/aggregates.d.ts

@@ -0,0 +1,64 @@
+import type { Cell, Writable } from "./signal.js";
+import { Num } from "./values/num.js";
+import { Vec } from "./values/vec.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** Equal-weight mean of N Linear values; writes distribute the delta evenly. */
+export declare function meanLens<T, C extends new (...args: never[]) => Cell<any>>(Cls: C, parents: readonly Cell<T>[]): Writable<InstanceType<C>>;
+/** Midpoint of two writable Vecs. Drag-translates both endpoints. */
+export declare function midpointLens(a: Cell<V>, b: Cell<V>): Writable<Vec>;
+/** Centroid of N writable Vecs. Drag-translates all members. */
+export declare function centroidLens(parents: readonly Cell<V>[]): Writable<Vec>;
+export interface ArgminOpts {
+    /** Finite-difference epsilon for the Jacobian. Default 1e-4. */
+    eps?: number;
+    /** Levenberg-Marquardt damping. Default `1e-6` for `argminNum`
+     *  (Jacobian is always well-conditioned for linear constraints) and
+     *  `1e-3` for `argminVec` (IK chains hit rank-deficient regimes at
+     *  full extension). Larger → smaller, more stable updates; smaller
+     *  → closer to pure pseudoinverse. */
+    damping?: number;
+}
+/** Target-shaping for `argminVec`: project a write into the reachable
+ *  workspace before the Jacobian step, sidestepping the rank-deficient
+ *  swings at the boundary. For an N-link chain rooted at `R` with reach
+ *  `L`, pass `clampToDisc(R, L)`. */
+export interface ArgminVecOpts extends ArgminOpts {
+    /** Pre-write hook: transform the requested target into one that's
+     *  guaranteed solvable. Most useful as a workspace clamp. */
+    clampTarget?: (target: {
+        x: number;
+        y: number;
+    }, currentInputs: readonly number[]) => {
+        x: number;
+        y: number;
+    };
+}
+/** Project `p` into the closed disc of radius `r` centred on `c` (points
+ *  inside pass through). Use as `argminVec`'s `clampTarget` to fix IK
+ *  explosion at maximum reach. */
+export declare function clampToDisc(c: {
+    x: number;
+    y: number;
+}, r: number): (p: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+/** Scalar-output argmin lens: write does one Newton step against the FD
+ *  Jacobian, distributing the residual by `weights`. For typed/multi-
+ *  output cases use `factor()`; this M=1 path is kept for its hand-rolled
+ *  inner loop. */
+export declare function argminNum(inputs: readonly Num[], forward: (xs: readonly number[]) => number, weights: readonly number[], opts?: ArgminOpts): Writable<Num>;
+/** 2D-output argmin lens (scalar Num inputs, `{x, y}` forward). For IK
+ *  arms, draggable points, handle projection. Kept for its hand-rolled
+ *  2×2 inverse + `clampTarget` hook; see `factor()` for other M. */
+export declare function argminVec(inputs: readonly Num[], forward: (xs: readonly number[]) => {
+    x: number;
+    y: number;
+}, weights: readonly number[], opts?: ArgminVecOpts): Writable<Vec>;
+export {};

package/dist/core/aggregates.js

@@ -0,0 +1,198 @@
+// aggregates.ts — N→1 aggregate lens primitives over `Cls.lens` /
+// `Cls.derive`.
+//
+// All route through the engine's N-input lens path. Stateless-bwd
+// (`(target) => updates`) skips the peek loop on the hot path;
+// stateful-bwd (`(target, vals) => updates`) reads the scratch.
+import { Num } from "./values/num.js";
+import { Vec } from "./values/vec.js";
+/** Equal-weight mean of N Linear values; writes distribute the delta evenly. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape, mirrors Cls.lens
+export function meanLens(Cls, parents) {
+    const lin = (Cls.traits?.linear ??
+        (() => {
+            throw new Error("meanLens: value class has no 'linear' trait");
+        })());
+    const n = parents.length;
+    const inv = 1 / n;
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.lens
+    return Cls.lens(parents, 
+    // biome-ignore lint/suspicious/noExplicitAny: tuple-vs-array variance
+    (vals) => {
+        let acc = vals[0];
+        for (let i = 1; i < n; i++)
+            acc = lin.add(acc, vals[i]);
+        return lin.scale(acc, inv);
+    }, 
+    // biome-ignore lint/suspicious/noExplicitAny: tuple-vs-array variance
+    (target, vals) => {
+        let cur = vals[0];
+        for (let i = 1; i < n; i++)
+            cur = lin.add(cur, vals[i]);
+        cur = lin.scale(cur, inv);
+        const delta = lin.sub(target, cur);
+        const out = new Array(n);
+        for (let i = 0; i < n; i++)
+            out[i] = lin.add(vals[i], delta);
+        return out;
+    });
+}
+/** Midpoint of two writable Vecs. Drag-translates both endpoints. */
+export function midpointLens(a, b) {
+    return Vec.lens([a, b], vals => {
+        const [av, bv] = vals;
+        return { x: (av.x + bv.x) / 2, y: (av.y + bv.y) / 2 };
+    }, (target, vals) => {
+        const [av, bv] = vals;
+        const dx = target.x - (av.x + bv.x) / 2;
+        const dy = target.y - (av.y + bv.y) / 2;
+        return [
+            { x: av.x + dx, y: av.y + dy },
+            { x: bv.x + dx, y: bv.y + dy },
+        ];
+    });
+}
+/** Centroid of N writable Vecs. Drag-translates all members. */
+export function centroidLens(parents) {
+    const n = parents.length;
+    const inv = 1 / n;
+    return Vec.lens(parents, vals => {
+        const arr = vals;
+        let sx = 0, sy = 0;
+        for (let i = 0; i < n; i++) {
+            sx += arr[i].x;
+            sy += arr[i].y;
+        }
+        return { x: sx * inv, y: sy * inv };
+    }, (target, vals) => {
+        const arr = vals;
+        let sx = 0, sy = 0;
+        for (let i = 0; i < n; i++) {
+            sx += arr[i].x;
+            sy += arr[i].y;
+        }
+        const dx = target.x - sx * inv;
+        const dy = target.y - sy * inv;
+        const out = new Array(n);
+        for (let i = 0; i < n; i++) {
+            out[i] = { x: arr[i].x + dx, y: arr[i].y + dy };
+        }
+        return out;
+    });
+}
+/** Project `p` into the closed disc of radius `r` centred on `c` (points
+ *  inside pass through). Use as `argminVec`'s `clampTarget` to fix IK
+ *  explosion at maximum reach. */
+export function clampToDisc(c, r) {
+    return p => {
+        const dx = p.x - c.x;
+        const dy = p.y - c.y;
+        const d = Math.hypot(dx, dy);
+        if (d <= r)
+            return p;
+        const k = r / d;
+        return { x: c.x + dx * k, y: c.y + dy * k };
+    };
+}
+/** Scalar-output argmin lens: write does one Newton step against the FD
+ *  Jacobian, distributing the residual by `weights`. For typed/multi-
+ *  output cases use `factor()`; this M=1 path is kept for its hand-rolled
+ *  inner loop. */
+export function argminNum(inputs, forward, weights, opts = {}) {
+    if (weights.length !== inputs.length) {
+        throw new Error("argminNum: weights/inputs length mismatch");
+    }
+    const eps = opts.eps ?? 1e-4;
+    const damping = opts.damping ?? 1e-6;
+    const n = inputs.length;
+    // Pre-allocated to avoid per-write allocations.
+    const J = new Array(n);
+    const out = new Array(n);
+    return Num.lens(inputs, vals => forward(vals), (target, vals) => {
+        const xs = vals;
+        const y0 = forward(xs);
+        const dy = target - y0;
+        for (let i = 0; i < n; i++) {
+            const saved = xs[i];
+            xs[i] = saved + eps;
+            J[i] = (forward(xs) - y0) / eps;
+            xs[i] = saved;
+        }
+        let denom = damping;
+        for (let i = 0; i < n; i++)
+            denom += weights[i] * J[i] * J[i];
+        const k = dy / denom;
+        for (let i = 0; i < n; i++) {
+            if (weights[i] === 0) {
+                out[i] = undefined;
+            }
+            else {
+                out[i] = xs[i] + weights[i] * J[i] * k;
+            }
+        }
+        return out;
+    });
+}
+/** 2D-output argmin lens (scalar Num inputs, `{x, y}` forward). For IK
+ *  arms, draggable points, handle projection. Kept for its hand-rolled
+ *  2×2 inverse + `clampTarget` hook; see `factor()` for other M. */
+export function argminVec(inputs, forward, weights, opts = {}) {
+    if (weights.length !== inputs.length) {
+        throw new Error("argminVec: weights/inputs length mismatch");
+    }
+    const eps = opts.eps ?? 1e-4;
+    const damping = opts.damping ?? 1e-3;
+    const clamp = opts.clampTarget;
+    const n = inputs.length;
+    // Pre-allocated to avoid per-write allocations.
+    const Jx = new Array(n);
+    const Jy = new Array(n);
+    const out = new Array(n);
+    return Vec.lens(inputs, vals => forward(vals), (rawTarget, vals) => {
+        const xs = vals;
+        const target = clamp ? clamp(rawTarget, xs) : rawTarget;
+        const y0 = forward(xs);
+        const dx = target.x - y0.x;
+        const dy = target.y - y0.y;
+        for (let i = 0; i < n; i++) {
+            const saved = xs[i];
+            xs[i] = saved + eps;
+            const ye = forward(xs);
+            xs[i] = saved;
+            Jx[i] = (ye.x - y0.x) / eps;
+            Jy[i] = (ye.y - y0.y) / eps;
+        }
+        // J·W·Jᵀ is the 2×2 [a b; b c]. Add damping to the diagonal, invert.
+        let a = damping;
+        let b = 0;
+        let c = damping;
+        for (let i = 0; i < n; i++) {
+            const w = weights[i];
+            a += w * Jx[i] * Jx[i];
+            b += w * Jx[i] * Jy[i];
+            c += w * Jy[i] * Jy[i];
+        }
+        const det = a * c - b * b;
+        if (Math.abs(det) < 1e-14) {
+            // Singular; leave inputs unchanged.
+            for (let i = 0; i < n; i++)
+                out[i] = undefined;
+            return out;
+        }
+        const invA = c / det;
+        const invB = -b / det;
+        const invC = a / det;
+        const kx = invA * dx + invB * dy;
+        const ky = invB * dx + invC * dy;
+        for (let i = 0; i < n; i++) {
+            const w = weights[i];
+            if (w === 0) {
+                out[i] = undefined;
+            }
+            else {
+                out[i] = xs[i] + w * (Jx[i] * kx + Jy[i] * ky);
+            }
+        }
+        return out;
+    });
+}

package/dist/core/anim.d.ts

@@ -0,0 +1,84 @@
+import { type Animator, type Easing, type Tick, type Yieldable } from "../animation/index.js";
+import { Cell, type Read, type Val, type Writable } from "./signal.js";
+import { type TraitKey, type Traits } from "./traits.js";
+/** Animator-style constraint: a writable reactive carrying `T` whose
+ *  class declares the listed traits. Reads as a sentence:
+ *
+ *      function spring<T>(s: Animatable<T, "linear" | "metric">, …) */
+export type Animatable<T, K extends TraitKey = never> = Writable<Cell<T>> & Traits<T, K>;
+type Seg<T> = {
+    readonly kind: "pose";
+    readonly target: T;
+} | {
+    readonly kind: "to";
+    readonly target: T;
+    readonly dur: Val<number>;
+    readonly ease?: Easing;
+};
+/** Chainable Animator over a writable cell: `.to(...).to(...).from(start)`
+ *  reads naturally. `.to`/`.from` are pure data — segments accumulate at
+ *  construction; the executor generator runs them in order on iteration. */
+export declare class Tween<T> implements Animator<void> {
+    #private;
+    /** @internal — use `tween(...)` or `sig.to(...)` to construct. */
+    constructor(sig: Animatable<T, "lerp">, segs?: readonly Seg<T>[]);
+    /** Append a tween segment from current value to `target` over `dur`. */
+    to(target: T, dur: Val<number>, ease?: Easing): Tween<T>;
+    /** Pose `start` as the first step, then run the rest of the chain. */
+    from(start: T): Tween<T>;
+    next(v?: Tick): IteratorResult<Yieldable, void>;
+    return(v?: void): IteratorResult<Yieldable, void>;
+    throw(e: unknown): IteratorResult<Yieldable, void>;
+    [Symbol.iterator](): this;
+}
+/** Free-fn form of one-shot tween — returns a chainable `Tween<T>`. */
+export declare function tween<T>(sig: Animatable<T, "lerp">, target: T, dur: Val<number>, ease?: Easing): Tween<T>;
+export interface SpringOpts<T = unknown> {
+    /** Natural angular frequency (rad/s). Default 13 (~0.48 s period). */
+    omega?: number;
+    /** Damping ratio. <1 underdamped, =1 critical, >1 overdamped. Default 1. */
+    zeta?: number;
+    /** Settle threshold; snap+complete when both ‖e‖ < eps and ‖v‖ < eps·ω. */
+    precision?: number;
+    /** Per-frame rate multiplier on `tick.dt`. 0 freezes evolution; 2× doubles
+     *  speed. Reactive — re-read each frame. Default 1. */
+    rate?: () => number;
+    /** Project each frame's next value into an admissible set (clamp to a
+     *  range, snap to a manifold, etc.). If projection moves the value,
+     *  velocity is reset to zero — soft absorbing wall, no integrator
+     *  fighting the boundary. Pair with `precision: 0` when the target
+     *  may lie outside the admissible set (settle never fires there). */
+    project?: (v: T) => T;
+}
+/** Second-order damped-spring pull. */
+export declare function spring<T>(sig: Animatable<T, "linear" | "metric">, target: Val<T>, opts?: SpringOpts<T>): Animator<void>;
+/** Constant-speed approach (units-of-T per second). Needs linear+metric. */
+export declare function toward<T>(sig: Animatable<T, "linear" | "metric">, target: Val<T>, speed: Val<number>): Animator<void>;
+/** Exponential pull toward `target` at rate `k`/s (no overshoot). Needs linear. */
+export declare function attract<T>(sig: Animatable<T, "linear">, target: Val<T>, k?: Val<number>): Animator<void>;
+/** Drive `sig` per frame with a pure function `f(t, initial)`. */
+export declare function wave<T>(sig: Writable<Cell<T>>, fn: (t: number, initial: T) => T): Animator<void>;
+/** Escape hatch: drive sig per frame with `step(dt, t, current)`.
+ *  Return `false` to terminate. Use `wave` instead for pure `f(t)`. */
+export declare function driven<T>(sig: Writable<Cell<T>>, step: (dt: number, t: number, v: T) => T | false): Animator<void>;
+type PlayTrigger = Yieldable | Read<unknown>;
+export interface Play<R = void> extends Animator<R> {
+    /** End when `p` fires (truthy cell / animator completion / sleep). */
+    until(p: PlayTrigger): Play<R>;
+    /** Sequence: this, then `next`. */
+    then(next: PlayTrigger): Play<unknown>;
+}
+/** Lift any yieldable / cell-trigger / animator-factory into a Play. */
+export declare function play<R>(g: Animator<R> | (() => Animator<R>)): Play<R>;
+export declare function play(p: PlayTrigger | (() => Animator)): Play<unknown>;
+/** Wait until `sig.value` is truthy. Wakes immediately if already true. */
+export declare function when(sig: Read<unknown>): Animator<void>;
+/** Reactive boolean negation as a `Cell<boolean>` (RO). */
+export declare function not(sig: Read<unknown>): Cell<boolean>;
+/** Wait until `sig` changes; resumes with the new value. */
+export declare function untilChange<T>(sig: Cell<T>): Animator<T>;
+/** Repeat `factory()` forever; bound via `.until(sig)`. */
+export declare function loop(factory: () => Yieldable): Play;
+/** Run `fn` every `sec` seconds (drift-corrected, `sec` may be reactive). */
+export declare function every(sec: Val<number>, fn: () => void): Play;
+export {};