bireactive 0.2.0

package/dist/core/anim.js

@@ -0,0 +1,301 @@
+// anim.ts — animator primitives over `Animatable<T, K>` (writable +
+// nominal trait constraint), plus the signals↔generators bridge.
+//
+// Signatures read as a sentence ("spring takes a writable carrying T
+// with linear+metric"), so misuse is a compile error: `spring(box, …)`
+// (no metric), `spring(roVec, …)` (not writable).
+import { drive, easeOut, isGenerator, race, suspend, } from "../animation/index.js";
+import { Cell, derive, effect, reader } from "./signal.js";
+import { requireLerp, requireLinear, requireMetric } from "./traits.js";
+const defaultEase = easeOut;
+/** 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 class Tween {
+    #sig;
+    #segs;
+    #gen;
+    /** @internal — use `tween(...)` or `sig.to(...)` to construct. */
+    constructor(sig, segs = []) {
+        this.#sig = sig;
+        this.#segs = segs;
+        this.#gen = (function* () {
+            for (const seg of segs) {
+                if (seg.kind === "pose") {
+                    sig.value = seg.target;
+                    continue;
+                }
+                yield* tweenStep(sig, seg.target, seg.dur, seg.ease);
+            }
+        })();
+    }
+    /** Append a tween segment from current value to `target` over `dur`. */
+    to(target, dur, ease) {
+        return new Tween(this.#sig, [...this.#segs, { kind: "to", target, dur, ease }]);
+    }
+    /** Pose `start` as the first step, then run the rest of the chain. */
+    from(start) {
+        return new Tween(this.#sig, [{ kind: "pose", target: start }, ...this.#segs]);
+    }
+    next(v) {
+        return this.#gen.next(v);
+    }
+    return(v) {
+        return this.#gen.return(v);
+    }
+    throw(e) {
+        return this.#gen.throw(e);
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+}
+/** Append-only tween segment over a writable reactive target. */
+function* tweenStep(sig, target, dur, ease = defaultEase) {
+    const lerp = requireLerp(sig);
+    const start = sig.peek();
+    const D = reader(dur);
+    yield* drive((tick, t) => {
+        const total = D();
+        if (total <= 0 || t + tick.dt * 1e-3 >= total) {
+            sig.value = target;
+            return false;
+        }
+        sig.value = lerp(start, target, ease(t / total));
+    });
+}
+/** Free-fn form of one-shot tween — returns a chainable `Tween<T>`. */
+export function tween(sig, target, dur, ease) {
+    return new Tween(sig, [{ kind: "to", target, dur, ease }]);
+}
+/** Second-order damped-spring pull. */
+export function* spring(sig, target, opts = {}) {
+    const lin = requireLinear(sig);
+    const met = requireMetric(sig);
+    const omega = opts.omega ?? 13;
+    const zeta = opts.zeta ?? 1;
+    const eps = opts.precision ?? 1e-4;
+    const rate = opts.rate;
+    const project = opts.project;
+    const T = reader(target);
+    const zero = lin.scale(sig.peek(), 0);
+    let vel = zero;
+    yield* drive(tick => {
+        const dt = rate ? tick.dt * rate() : tick.dt;
+        const t = T();
+        const cur = sig.peek();
+        const e0 = lin.sub(cur, t);
+        const v0 = vel;
+        let e1, v1;
+        if (zeta < 1 - 1e-6) {
+            const zw = zeta * omega;
+            const wd = omega * Math.sqrt(1 - zeta * zeta);
+            const E = Math.exp(-zw * dt);
+            const c = Math.cos(wd * dt);
+            const s = Math.sin(wd * dt);
+            const B = lin.scale(lin.add(v0, lin.scale(e0, zw)), 1 / wd);
+            const inner = lin.add(lin.scale(e0, c), lin.scale(B, s));
+            e1 = lin.scale(inner, E);
+            const swing = lin.sub(lin.scale(B, c), lin.scale(e0, s));
+            v1 = lin.add(lin.scale(e1, -zw), lin.scale(swing, E * wd));
+        }
+        else if (zeta > 1 + 1e-6) {
+            const r = omega * Math.sqrt(zeta * zeta - 1);
+            const r1 = -zeta * omega + r;
+            const r2 = -zeta * omega - r;
+            const denom = r2 - r1;
+            const B = lin.scale(lin.sub(v0, lin.scale(e0, r1)), 1 / denom);
+            const A = lin.sub(e0, B);
+            const E1 = Math.exp(r1 * dt);
+            const E2 = Math.exp(r2 * dt);
+            e1 = lin.add(lin.scale(A, E1), lin.scale(B, E2));
+            v1 = lin.add(lin.scale(A, r1 * E1), lin.scale(B, r2 * E2));
+        }
+        else {
+            const E = Math.exp(-omega * dt);
+            const B = lin.add(v0, lin.scale(e0, omega));
+            const Bt = lin.scale(B, dt);
+            e1 = lin.scale(lin.add(e0, Bt), E);
+            v1 = lin.sub(lin.scale(B, E), lin.scale(e1, omega));
+        }
+        const raw = lin.add(t, e1);
+        const next = project ? project(raw) : raw;
+        if (project && met(next, raw) > 0) {
+            e1 = lin.sub(next, t);
+            v1 = zero;
+        }
+        vel = v1;
+        sig.value = next;
+        if (eps > 0 && met(e1, zero) < eps && met(v1, zero) < eps * omega) {
+            sig.value = t;
+            return false;
+        }
+    });
+}
+/** Constant-speed approach (units-of-T per second). Needs linear+metric. */
+export function* toward(sig, target, speed) {
+    const lin = requireLinear(sig);
+    const met = requireMetric(sig);
+    const T = reader(target);
+    const S = reader(speed);
+    yield* drive(tick => {
+        const t = T();
+        const cur = sig.peek();
+        const dist = met(cur, t);
+        const step = S() * tick.dt;
+        if (dist <= step) {
+            sig.value = t;
+            return false;
+        }
+        const dir = lin.scale(lin.sub(t, cur), 1 / dist);
+        sig.value = lin.add(cur, lin.scale(dir, step));
+    });
+}
+/** Exponential pull toward `target` at rate `k`/s (no overshoot). Needs linear. */
+export function* attract(sig, target, k = 1) {
+    const lin = requireLinear(sig);
+    const T = reader(target);
+    const K = reader(k);
+    yield* drive(tick => {
+        const cur = sig.peek();
+        const delta = lin.scale(lin.sub(T(), cur), K() * tick.dt);
+        sig.value = lin.add(cur, delta);
+    });
+}
+/** Drive `sig` per frame with a pure function `f(t, initial)`. */
+export function* wave(sig, fn) {
+    const initial = sig.peek();
+    yield* drive((_tick, t) => {
+        sig.value = fn(t, initial);
+    });
+}
+/** Escape hatch: drive sig per frame with `step(dt, t, current)`.
+ *  Return `false` to terminate. Use `wave` instead for pure `f(t)`. */
+export function* driven(sig, step) {
+    yield* drive((tick, t) => {
+        const next = step(tick.dt, t, sig.peek());
+        if (next === false)
+            return false;
+        sig.value = next;
+    });
+}
+class PlayImpl {
+    g;
+    constructor(g) {
+        this.g = g;
+    }
+    next(v) {
+        return this.g.next(v);
+    }
+    return(v) {
+        return this.g.return(v);
+    }
+    throw(e) {
+        return this.g.throw(e);
+    }
+    [Symbol.iterator]() {
+        return this;
+    }
+    until(p) {
+        const trigger = playableGen(p);
+        const g = this.g;
+        return new PlayImpl((function* () {
+            const result = yield* race(g, trigger);
+            return result;
+        })());
+    }
+    then(next) {
+        const g = this.g;
+        return new PlayImpl((function* () {
+            yield* g;
+            yield* playableGen(next);
+        })());
+    }
+}
+export function play(p) {
+    if (p instanceof PlayImpl)
+        return p;
+    if (typeof p === "function" && p.length === 0) {
+        p = p();
+    }
+    return new PlayImpl(playableGen(p));
+}
+function* playableGen(p) {
+    if (p instanceof Cell) {
+        yield* when(p);
+        return undefined;
+    }
+    if (p === undefined || p === null)
+        return undefined;
+    if (typeof p === "object" && p.next) {
+        return yield* p;
+    }
+    yield p;
+    return undefined;
+}
+/** Wait until `sig.value` is truthy. Wakes immediately if already true. */
+export function when(sig) {
+    return suspend(wake => {
+        let resolved = false;
+        return effect(() => {
+            if (resolved)
+                return;
+            if (sig.value) {
+                resolved = true;
+                wake();
+            }
+        });
+    });
+}
+/** Reactive boolean negation as a `Cell<boolean>` (RO). */
+export function not(sig) {
+    return derive(() => !sig.value);
+}
+/** Wait until `sig` changes; resumes with the new value. */
+export function untilChange(sig) {
+    return suspend(wake => {
+        const initial = sig.peek();
+        let resolved = false;
+        return effect(() => {
+            const v = sig.value;
+            if (resolved)
+                return;
+            if (v !== initial) {
+                resolved = true;
+                wake(v);
+            }
+        });
+    });
+}
+/** Repeat `factory()` forever; bound via `.until(sig)`. */
+export function loop(factory) {
+    return play((function* () {
+        while (true) {
+            const y = factory();
+            if (isGenerator(y))
+                yield* y;
+            else
+                yield y;
+        }
+    })());
+}
+/** Run `fn` every `sec` seconds (drift-corrected, `sec` may be reactive). */
+export function every(sec, fn) {
+    const getSec = reader(sec);
+    return play((function* () {
+        let tick = yield;
+        let nextAt = tick.elapsed + Math.max(0, getSec());
+        while (true) {
+            tick = yield;
+            const period = getSec();
+            if (period <= 0) {
+                nextAt = tick.elapsed;
+                continue;
+            }
+            while (tick.elapsed >= nextAt) {
+                fn();
+                nextAt += period;
+            }
+        }
+    })());
+}

package/dist/core/index.d.ts

@@ -0,0 +1,38 @@
+export { argminNum, argminVec, centroidLens, clampToDisc, meanLens, midpointLens, } from "./aggregates.js";
+export { type Animatable, attract, driven, every, loop, not, type Play, play, type SpringOpts, spring, Tween, toward, tween, untilChange, wave, when, } from "./anim.js";
+export { transitiveDeps } from "./introspect.js";
+export * from "./lenses/index.js";
+export { each, type Lifecycle } from "./network-utils.js";
+export { reflectionLens } from "./new-primitives.js";
+export { batch, Cell, type CellOptions, cell, derive, effect, type Init, type Inner, isCell, isComputed, isLens, lazy, lens, type Network, network, type Read, reader, readNow, type StatefulBwd, type StatefulLensSpec, setCellWriteHook, untracked, type Val, type Writable, type WritableBrand, } from "./signal.js";
+export { type Equals, type Lerp, type Linear, type Metric, type Pack, type Pivotal, requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, type TraitDict, type Traits, } from "./traits.js";
+export { allNodes, atPath, isLeaf, leavesOf, node as treeNode, nodeCount, type TreeNode, walkTree, } from "./tree.js";
+export { Anchor, Dir } from "./values/anchor.js";
+export { Audio, type AudioClip, audio, stamp as audioStamp } from "./values/audio.js";
+export * as BoolMath from "./values/bool.js";
+export { Bool, bool } from "./values/bool.js";
+export * as BoxMath from "./values/box.js";
+export { Box, box, edgeFrom, union as boxUnion } from "./values/box.js";
+export { Canvas, canvas, type Raster, stamp as canvasStamp } from "./values/canvas.js";
+export * as ColorMath from "./values/color.js";
+export { Color, rgb, rgba } from "./values/color.js";
+export { Flags, flags } from "./values/flags.js";
+export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, type Tex, } from "./values/gpu.js";
+export * as MatrixMath from "./values/matrix.js";
+export { compose, determinant, fromRotate, fromScale, fromTranslate, identity, invert, isIdentity, Matrix, matrix, multiply, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
+export * as NumMath from "./values/num.js";
+export { Num, num } from "./values/num.js";
+export * as PoseMath from "./values/pose.js";
+export { Pose, pose } from "./values/pose.js";
+export * as RangeMath from "./values/range.js";
+export { Range, range, span } from "./values/range.js";
+export * as StrMath from "./values/str.js";
+export { Str, str } from "./values/str.js";
+export { type Codec, enumCodec, numCodec, route, type Slot, slot, strCodec, template, tpl, } from "./values/template.js";
+export * as TransformMath from "./values/transform.js";
+export { Transform, type TransformInit, transform } from "./values/transform.js";
+export * as TriMath from "./values/tri.js";
+export { Tri, tri } from "./values/tri.js";
+export * as VecMath from "./values/vec.js";
+export { type PolarPolicy, polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { derived, field } from "./writable.js";

package/dist/core/index.js

@@ -0,0 +1,38 @@
+export { argminNum, argminVec, centroidLens, clampToDisc, meanLens, midpointLens, } from "./aggregates.js";
+export { attract, driven, every, loop, not, play, spring, Tween, toward, tween, untilChange, wave, when, } from "./anim.js";
+export { transitiveDeps } from "./introspect.js";
+export * from "./lenses/index.js";
+export { each } from "./network-utils.js";
+export { reflectionLens } from "./new-primitives.js";
+export { batch, Cell, cell, derive, effect, isCell, isComputed, isLens, lazy, lens, network, reader, readNow, setCellWriteHook, untracked, } from "./signal.js";
+export { requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, } from "./traits.js";
+export { allNodes, atPath, isLeaf, leavesOf, node as treeNode, nodeCount, walkTree, } from "./tree.js";
+export { Anchor, Dir } from "./values/anchor.js";
+export { Audio, audio, stamp as audioStamp } from "./values/audio.js";
+export * as BoolMath from "./values/bool.js";
+export { Bool, bool } from "./values/bool.js";
+export * as BoxMath from "./values/box.js";
+export { Box, box, edgeFrom, union as boxUnion } from "./values/box.js";
+export { Canvas, canvas, stamp as canvasStamp } from "./values/canvas.js";
+export * as ColorMath from "./values/color.js";
+export { Color, rgb, rgba } from "./values/color.js";
+export { Flags, flags } from "./values/flags.js";
+export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, } from "./values/gpu.js";
+export * as MatrixMath from "./values/matrix.js";
+export { compose, determinant, fromRotate, fromScale, fromTranslate, identity, invert, isIdentity, Matrix, matrix, multiply, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
+export * as NumMath from "./values/num.js";
+export { Num, num } from "./values/num.js";
+export * as PoseMath from "./values/pose.js";
+export { Pose, pose } from "./values/pose.js";
+export * as RangeMath from "./values/range.js";
+export { Range, range, span } from "./values/range.js";
+export * as StrMath from "./values/str.js";
+export { Str, str } from "./values/str.js";
+export { enumCodec, numCodec, route, slot, strCodec, template, tpl, } from "./values/template.js";
+export * as TransformMath from "./values/transform.js";
+export { Transform, transform } from "./values/transform.js";
+export * as TriMath from "./values/tri.js";
+export { Tri, tri } from "./values/tri.js";
+export * as VecMath from "./values/vec.js";
+export { polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { derived, field } from "./writable.js";

package/dist/core/introspect.d.ts

@@ -0,0 +1,5 @@
+import type { Cell } from "./signal.js";
+/** Every cell `s` transitively depends on, including itself. Raw cells
+ *  return `{s}`; lens chains return the chain plus all parents. BFS,
+ *  peeking each Computed to populate deps; the `seen` set breaks cycles. */
+export declare function transitiveDeps(s: Cell<unknown>): Set<Cell<unknown>>;

package/dist/core/introspect.js

@@ -0,0 +1,31 @@
+// introspect.ts — read-only inspection of a cell's dependency graph.
+//
+// Used by `Propagators` to expand declared reads into their transitive
+// parent set, so a propagator reading a lens chain reacts to writes that
+// touch the chain's parents but not the chain's identity. Inspection is
+// safe: it only reads engine state and peeks `.value` to populate deps
+// for lazy Computeds (idempotent).
+/** Every cell `s` transitively depends on, including itself. Raw cells
+ *  return `{s}`; lens chains return the chain plus all parents. BFS,
+ *  peeking each Computed to populate deps; the `seen` set breaks cycles. */
+export function transitiveDeps(s) {
+    const seen = new Set();
+    const queue = [s];
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        // Cast to reach engine fields the typed Cell<T> shape doesn't surface.
+        const c = cur;
+        if (c.getter !== undefined) {
+            void cur.value;
+            let l = c.deps;
+            while (l !== undefined) {
+                queue.push(l.dep);
+                l = l.nextDep;
+            }
+        }
+    }
+    return seen;
+}

package/dist/core/lenses/closed-form-policies.d.ts

@@ -0,0 +1,64 @@
+import { type Cell, Num, type Read, type Traits, Vec, type Writable } from "../index.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** Writable centroid; on write, translates every point by the delta.
+ *  Alias of `centroidLens` under the "policy" naming. */
+export declare function rigidTranslate(points: readonly Writable<Vec>[]): Writable<Vec>;
+/** Writable angle from `pivot` to `points[0]`; write rotates every input
+ *  about `pivot` by (target − current) via its `Pivotal` trait.
+ *
+ *  Trait-generic: Vec rotates position; Pose rotates position AND
+ *  orientation. Rotation-about-pivot fixes the pivot and preserves radial
+ *  distances, so scale-about-pivot reads unchanged. `pivot` is reactive
+ *  (re-read per write); pass `centroidLens(points)` for rotation about
+ *  the cluster's own centroid. */
+export declare function rotateAbout<T extends {
+    x: number;
+    y: number;
+}>(points: readonly Writable<Traits<T, "pivotal"> & Cell<T>>[], pivot: Read<V>): Writable<Num>;
+/** Writable radial distance from pivot to `points[0]`; write scales every
+ *  input radially about `pivot` (negative target reflects). Exact
+ *  cross-channel invariance with `rotateAbout`.
+ *
+ *  Complement carries per-point offsets from the pivot at the last
+ *  non-degenerate state, so a collapse onto the pivot (radius ≈ 0)
+ *  reinflates from the stored shape. Pose `theta` survives the round-trip
+ *  (only spatial offset is stored). */
+export declare function scaleAbout<T extends {
+    x: number;
+    y: number;
+}>(points: readonly Writable<Traits<T, "pivotal"> & Cell<T>>[], pivot: Read<V>): Writable<Num>;
+/** Per-axis scale about a pivot. Vec-specific (Pivotal has no per-axis
+ *  method yet). Complement carries per-point per-axis fractions of
+ *  point 0's offset, so a per-axis collapse is recoverable (cf.
+ *  `bboxLens.size`). */
+export declare function scaleAboutXY(points: readonly Writable<Vec>[], pivot: Read<V>): Writable<Vec>;
+/** Same semantics as `factor-lens.ts`'s `procrustesLens`, decomposed
+ *  into three building-block lenses sharing a centroid. */
+export declare function procrustesViaBuildingBlocks(points: readonly Writable<Vec>[]): {
+    centroid: Writable<Vec>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};
+export declare function bestFitLineLens(points: readonly Writable<Vec>[]): {
+    point: Writable<Vec>;
+    direction: Writable<Num>;
+};
+export declare function bestFitCircleLens(points: readonly Writable<Vec>[]): {
+    center: Writable<Vec>;
+    radius: Writable<Num>;
+};
+export declare function pcaLens(points: readonly Writable<Vec>[]): {
+    mean: Writable<Vec>;
+    rotation: Writable<Num>;
+    majorLength: Writable<Num>;
+    minorLength: Writable<Num>;
+};
+/** Writable total over K parts; write scales all parts proportionally,
+ *  preserving their ratios. A `remember` anchored at zero with a signed
+ *  sum feature: a collapse to zero reinflates the stored ratios, seeded
+ *  uniform so an all-zero start splits evenly. */
+export declare function totalLens(parts: readonly Writable<Num>[]): Writable<Num>;
+export {};