bireactive 0.2.0 → 0.2.1

package/dist/core/lenses/factor-lens.js

@@ -1,419 +0,0 @@
-// factor-lens.ts — N→M lens prototypes (Vec-specific monoliths).
-//
-// N inputs → M coupled writable outputs, where writing one output
-// preserves the readings of the other M−1 (cross-channel invariance).
-// Two regimes:
-//
-//   1. Numerical (Jacobian-LSQ): `factorLens` builds an M×N Jacobian by
-//      finite differences and solves `(J W Jᵀ + λI) k = δy` for `k`,
-//      then writes `δx = W Jᵀ k`. δy is sparse (only the written
-//      channel), so the solve leaves other channels near-stationary.
-//      Invariance is approximate, set by the local condition number.
-//
-//   2. Closed-form (geometric): `procrustesLens`, `bboxLens`,
-//      `meanDiffLens` — hand-rolled bwd via the right group action, so
-//      cross-channel invariance is EXACT. Cost: crafted per topology.
-//
-// `bundleLens` sketches the 1→M dual (single source → M coupled views).
-import { Num, Vec } from "../index.js";
-export function factorLens(inputs, forwards, opts = {}) {
-    const N = inputs.length;
-    const M = forwards.length;
-    if (M === 0)
-        return [];
-    const w = opts.inputWeights ?? new Array(N).fill(1);
-    const eps = opts.eps ?? 1e-5;
-    const lambda = opts.damping ?? 1e-6;
-    // Per-call (NOT per-cell) scratch; safe because writes execute
-    // synchronously inside `_setWithExclusion`.
-    const J = new Array(M * N);
-    const A = new Array(M * M);
-    const Ainv = new Array(M * M);
-    const ys = new Array(M);
-    const dy = new Array(M);
-    const kvec = new Array(M);
-    const outputs = [];
-    for (let outIdx = 0; outIdx < M; outIdx++) {
-        const idx = outIdx;
-        const out = new Array(N);
-        const cell = Num.lens(inputs, (vals) => forwards[idx](vals), (target, valsReadonly) => {
-            // Snapshot inputs into a mutable scratch so FD perturbations
-            // don't leak into upstream cell state.
-            const xs = valsReadonly;
-            const xsm = xs.slice();
-            for (let j = 0; j < M; j++)
-                ys[j] = forwards[j](xsm);
-            for (let j = 0; j < M; j++)
-                dy[j] = 0;
-            dy[idx] = target - ys[idx];
-            // Build Jacobian column-by-column.
-            for (let i = 0; i < N; i++) {
-                const saved = xsm[i];
-                xsm[i] = saved + eps;
-                for (let j = 0; j < M; j++) {
-                    J[j * N + i] = (forwards[j](xsm) - ys[j]) / eps;
-                }
-                xsm[i] = saved;
-            }
-            // A = J W Jᵀ + λI
-            for (let r = 0; r < M; r++) {
-                for (let c = 0; c < M; c++) {
-                    let s = 0;
-                    for (let i = 0; i < N; i++)
-                        s += J[r * N + i] * w[i] * J[c * N + i];
-                    A[r * M + c] = s + (r === c ? lambda : 0);
-                }
-            }
-            if (!invertMatrix(A, M, Ainv)) {
-                // Singular — leave inputs unchanged.
-                for (let i = 0; i < N; i++)
-                    out[i] = undefined;
-                return out;
-            }
-            for (let r = 0; r < M; r++) {
-                let s = 0;
-                for (let c = 0; c < M; c++)
-                    s += Ainv[r * M + c] * dy[c];
-                kvec[r] = s;
-            }
-            for (let i = 0; i < N; i++) {
-                let dxi = 0;
-                for (let r = 0; r < M; r++)
-                    dxi += J[r * N + i] * kvec[r];
-                out[i] = xsm[i] + w[i] * dxi;
-            }
-            return out;
-        });
-        outputs.push(cell);
-    }
-    return outputs;
-}
-/** Gauss-Jordan inverse of a row-major M×M matrix. Returns false if
- *  singular (pivot below 1e-14). Allocates one 2M-wide row buffer.
- *  For M ≤ ~10 this is competitive with LAPACK and avoids the dep. */
-function invertMatrix(A, M, out) {
-    const W = 2 * M;
-    const aug = new Array(M * W);
-    for (let r = 0; r < M; r++) {
-        for (let c = 0; c < M; c++)
-            aug[r * W + c] = A[r * M + c];
-        for (let c = 0; c < M; c++)
-            aug[r * W + M + c] = r === c ? 1 : 0;
-    }
-    for (let i = 0; i < M; i++) {
-        let p = i;
-        let pv = Math.abs(aug[i * W + i]);
-        for (let r = i + 1; r < M; r++) {
-            const v = Math.abs(aug[r * W + i]);
-            if (v > pv) {
-                pv = v;
-                p = r;
-            }
-        }
-        if (pv < 1e-14)
-            return false;
-        if (p !== i) {
-            for (let c = 0; c < W; c++) {
-                const t = aug[i * W + c];
-                aug[i * W + c] = aug[p * W + c];
-                aug[p * W + c] = t;
-            }
-        }
-        const inv = 1 / aug[i * W + i];
-        for (let c = 0; c < W; c++)
-            aug[i * W + c] = aug[i * W + c] * inv;
-        for (let r = 0; r < M; r++) {
-            if (r === i)
-                continue;
-            const f = aug[r * W + i];
-            if (f === 0)
-                continue;
-            for (let c = 0; c < W; c++)
-                aug[r * W + c] = aug[r * W + c] - f * aug[i * W + c];
-        }
-    }
-    for (let r = 0; r < M; r++) {
-        for (let c = 0; c < M; c++)
-            out[r * M + c] = aug[r * W + M + c];
-    }
-    return true;
-}
-// meanDiffLens — M=2 isomorphism baseline.
-//
-// (a, b) → ((a+b)/2, a−b). Square full-rank linear lens; bwd is the
-// inverse change of basis — exact, cross-channel invariant. Sanity
-// baseline for the property tests.
-export function meanDiffLens(a, b) {
-    const mean = Num.lens([a, b], vals => (vals[0] + vals[1]) / 2, (target, vals) => {
-        const d = vals[0] - vals[1];
-        return [target + d / 2, target - d / 2];
-    });
-    const diff = Num.lens([a, b], vals => vals[0] - vals[1], (target, vals) => {
-        const m = (vals[0] + vals[1]) / 2;
-        return [m + target / 2, m - target / 2];
-    });
-    return { mean, diff };
-}
-// procrustesLens — closed-form similarity (the showcase).
-//
-// K writable Vecs → {centroid, rotation (angle of point[0] about
-// centroid), scale (its distance from centroid)}. Each bwd is a
-// closed-form transform about the centroid:
-//   write centroid → translate every point by (c − old c)
-//   write rotation → rotate every point about centroid by (θ − old θ)
-//   write scale    → scale every point about centroid by (s / old s)
-// These commute on the cluster's similarity orbit, so the three outputs
-// have EXACT cross-channel invariance (cf. `procrustesJacobianLens`'s
-// approximate version). Degenerate: K < 2 leaves rotation/scale
-// undefined; a collapsed cluster (scale → 0) makes rotation singular and
-// scale writes no-ops; target scale = 0 collapses to the centroid.
-export function procrustesLens(points) {
-    const K = points.length;
-    if (K < 2)
-        throw new Error("procrustesLens: need ≥ 2 points");
-    const centroid = Vec.lens(points, (vals) => {
-        let sx = 0;
-        let sy = 0;
-        for (let i = 0; i < K; i++) {
-            sx += vals[i].x;
-            sy += vals[i].y;
-        }
-        return { x: sx / K, y: sy / K };
-    }, (target, vals) => {
-        let sx = 0;
-        let sy = 0;
-        for (let i = 0; i < K; i++) {
-            sx += vals[i].x;
-            sy += vals[i].y;
-        }
-        const dx = target.x - sx / K;
-        const dy = target.y - sy / K;
-        const out = new Array(K);
-        for (let i = 0; i < K; i++)
-            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
-        return out;
-    });
-    const rotation = Num.lens(points, (vals) => {
-        let sx = 0;
-        let sy = 0;
-        for (let i = 0; i < K; i++) {
-            sx += vals[i].x;
-            sy += vals[i].y;
-        }
-        const cx = sx / K;
-        const cy = sy / K;
-        return Math.atan2(vals[0].y - cy, vals[0].x - cx);
-    }, (target, vals) => {
-        let sx = 0;
-        let sy = 0;
-        for (let i = 0; i < K; i++) {
-            sx += vals[i].x;
-            sy += vals[i].y;
-        }
-        const cx = sx / K;
-        const cy = sy / K;
-        const rx0 = vals[0].x - cx;
-        const ry0 = vals[0].y - cy;
-        if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
-            // Collapsed cluster; no angle to rotate from.
-            return vals.map(() => undefined);
-        }
-        const oldθ = Math.atan2(ry0, rx0);
-        const dθ = target - oldθ;
-        const cos = Math.cos(dθ);
-        const sin = Math.sin(dθ);
-        const out = new Array(K);
-        for (let i = 0; i < K; i++) {
-            const rx = vals[i].x - cx;
-            const ry = vals[i].y - cy;
-            out[i] = { x: cx + cos * rx - sin * ry, y: cy + sin * rx + cos * ry };
-        }
-        return out;
-    });
-    const centroidOf = (vals) => {
-        let sx = 0;
-        let sy = 0;
-        for (let i = 0; i < K; i++) {
-            sx += vals[i].x;
-            sy += vals[i].y;
-        }
-        return { x: sx / K, y: sy / K };
-    };
-    const refreshDevs = (devs, vals) => {
-        const c = centroidOf(vals);
-        return devs.map((d, i) => {
-            const dx = vals[i].x - c.x;
-            const dy = vals[i].y - c.y;
-            return dx * dx + dy * dy > 1e-18 ? { x: dx, y: dy } : d;
-        });
-    };
-    const scale = Num.lens(points, {
-        init: (vals) => {
-            const c = centroidOf(vals);
-            return { devs: vals.map(v => ({ x: v.x - c.x, y: v.y - c.y })) };
-        },
-        step: (vals, c) => ({ devs: refreshDevs(c.devs, vals) }),
-        fwd: (vals) => {
-            const c = centroidOf(vals);
-            return Math.hypot(vals[0].x - c.x, vals[0].y - c.y);
-        },
-        bwd: (target, vals, c) => {
-            const cen = centroidOf(vals);
-            const d0 = c.devs[0];
-            const r0 = Math.hypot(d0.x, d0.y);
-            if (r0 < 1e-12)
-                return { updates: vals.map(() => undefined), complement: c };
-            const k = target / r0;
-            const out = c.devs.map(d => ({ x: cen.x + k * d.x, y: cen.y + k * d.y }));
-            return { updates: out, complement: c };
-        },
-    });
-    return { centroid, rotation, scale };
-}
-// bboxLens — closed-form axis-aligned bounding box.
-//
-// K Vecs → {center, size}. Forward is min/max (piecewise-constant
-// Jacobian — fatal for FD), but the closed-form bwd is exact:
-//   write center → translate all points by (c − old c)
-//   write size   → scale all about center by component-wise ratio
-// Center↔size invariance is exact. Degenerate axes (size = 0) write
-// as no-ops; negative size reflects (kept permissive).
-export function bboxLens(points) {
-    const K = points.length;
-    if (K < 1)
-        throw new Error("bboxLens: need ≥ 1 point");
-    const computeBox = (vals) => {
-        let minX = Number.POSITIVE_INFINITY;
-        let minY = Number.POSITIVE_INFINITY;
-        let maxX = Number.NEGATIVE_INFINITY;
-        let maxY = Number.NEGATIVE_INFINITY;
-        for (let i = 0; i < K; i++) {
-            const x = vals[i].x;
-            const y = vals[i].y;
-            if (x < minX)
-                minX = x;
-            if (x > maxX)
-                maxX = x;
-            if (y < minY)
-                minY = y;
-            if (y > maxY)
-                maxY = y;
-        }
-        return {
-            cx: (minX + maxX) / 2,
-            cy: (minY + maxY) / 2,
-            sx: maxX - minX,
-            sy: maxY - minY,
-        };
-    };
-    const center = Vec.lens(points, (vals) => {
-        const b = computeBox(vals);
-        return { x: b.cx, y: b.cy };
-    }, (target, vals) => {
-        const b = computeBox(vals);
-        const dx = target.x - b.cx;
-        const dy = target.y - b.cy;
-        const out = new Array(K);
-        for (let i = 0; i < K; i++)
-            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
-        return out;
-    });
-    const refreshFracs = (fracs, vals) => {
-        const b = computeBox(vals);
-        const hx = b.sx > 1e-12 ? b.sx / 2 : 0;
-        const hy = b.sy > 1e-12 ? b.sy / 2 : 0;
-        return fracs.map((f, i) => ({
-            x: hx > 0 ? (vals[i].x - b.cx) / hx : f.x,
-            y: hy > 0 ? (vals[i].y - b.cy) / hy : f.y,
-        }));
-    };
-    const size = Vec.lens(points, {
-        init: (vals) => {
-            const b = computeBox(vals);
-            const halfX0 = b.sx > 1e-12 ? b.sx / 2 : 1;
-            const halfY0 = b.sy > 1e-12 ? b.sy / 2 : 1;
-            return {
-                fracs: vals.map(v => ({
-                    x: b.sx > 1e-12 ? (v.x - b.cx) / halfX0 : 0,
-                    y: b.sy > 1e-12 ? (v.y - b.cy) / halfY0 : 0,
-                })),
-            };
-        },
-        step: (vals, c) => ({ fracs: refreshFracs(c.fracs, vals) }),
-        fwd: (vals) => {
-            const b = computeBox(vals);
-            return { x: b.sx, y: b.sy };
-        },
-        bwd: (target, vals, c) => {
-            const b = computeBox(vals);
-            const halfTx = target.x / 2;
-            const halfTy = target.y / 2;
-            const out = c.fracs.map(f => ({ x: b.cx + f.x * halfTx, y: b.cy + f.y * halfTy }));
-            return { updates: out, complement: c };
-        },
-    });
-    return { center, size };
-}
-// procrustesJacobianLens — comparison point.
-//
-// Same forward map as `procrustesLens` but with the generic Jacobian-LSQ
-// bwd, to quantify the numerical path vs. the closed-form one.
-export function procrustesJacobianLens(points) {
-    const K = points.length;
-    if (K < 2)
-        throw new Error("procrustesJacobianLens: need ≥ 2 points");
-    // Flatten K Vecs into 2K scalar field lenses.
-    const xs = [];
-    const ys = [];
-    for (const p of points) {
-        xs.push(Num.lens([p], v => v[0].x, (t, v) => [{ x: t, y: v[0].y }]));
-        ys.push(Num.lens([p], v => v[0].y, (t, v) => [{ x: v[0].x, y: t }]));
-    }
-    // factorLens wants a flat input array.
-    const flat = [];
-    for (let i = 0; i < K; i++) {
-        flat.push(xs[i], ys[i]);
-    }
-    // Indexing helpers
-    const xAt = (a, i) => a[2 * i];
-    const yAt = (a, i) => a[2 * i + 1];
-    const fwdCx = (a) => {
-        let s = 0;
-        for (let i = 0; i < K; i++)
-            s += xAt(a, i);
-        return s / K;
-    };
-    const fwdCy = (a) => {
-        let s = 0;
-        for (let i = 0; i < K; i++)
-            s += yAt(a, i);
-        return s / K;
-    };
-    const fwdRot = (a) => {
-        return Math.atan2(yAt(a, 0) - fwdCy(a), xAt(a, 0) - fwdCx(a));
-    };
-    const fwdScale = (a) => {
-        return Math.hypot(xAt(a, 0) - fwdCx(a), yAt(a, 0) - fwdCy(a));
-    };
-    const [centroidX, centroidY, rotation, scale] = factorLens(flat, [fwdCx, fwdCy, fwdRot, fwdScale], { damping: 1e-4 });
-    return { centroidX, centroidY, rotation, scale };
-}
-export function bundleLens(pose, rotateAbout) {
-    const position = Vec.lens([pose], (v) => ({ x: v[0].x, y: v[0].y }), (target, v) => [{ ...v[0], x: target.x, y: target.y }]);
-    const rotation = Num.lens([pose], (v) => v[0].theta, (target, v) => {
-        const cur = v[0];
-        const dθ = target - cur.theta;
-        const cos = Math.cos(dθ);
-        const sin = Math.sin(dθ);
-        const rx = cur.x - rotateAbout.x;
-        const ry = cur.y - rotateAbout.y;
-        return [
-            {
-                x: rotateAbout.x + cos * rx - sin * ry,
-                y: rotateAbout.y + sin * rx + cos * ry,
-                theta: target,
-            },
-        ];
-    });
-    return { position, rotation };
-}

package/dist/core/writable.d.ts

@@ -1,15 +0,0 @@
-import { Cell, type Inner, type Writable, type WritableBrand } from "./signal.js";
-/** Bidirectional field lens onto `parent.value[key]`; write spread-
- *  replaces the composite. Cached per (instance, key). Return type is
- *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO
- *  (runtime dispatch in `Cell.fieldOf` mirrors this).
- *
- *      get x() { return field(this, "x", Num); } */
-export declare function field<S extends Cell<any>, K extends keyof Inner<S>, C extends new (...args: never[]) => Cell<Inner<S>[K]>>(parent: S, key: K, Cls: C): S extends WritableBrand ? Writable<InstanceType<C>> : InstanceType<C>;
-/** Read-only derived view via `Cls.derive(parent, fn)`. Cached per
- *  (instance, key); always bare `Cls` (RO).
- *
- *      get magnitude() {
- *        return derived(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
- *      } */
-export declare function derived<S extends Cell<any>, C extends new (...args: never[]) => Cell<any>>(parent: S, key: string | symbol, Cls: C, fn: (v: Inner<S>) => Inner<InstanceType<C>>): InstanceType<C>;

package/dist/core/writable.js

@@ -1,29 +0,0 @@
-// writable.ts — value-class authoring helpers.
-//
-// `field(this, "x", Num)` — bidirectional field lens; conditional
-// return (writable on writable parent, bare on RO). `derived(this,
-// "k", Cls, fn)` — read-only derived view via `Cls.derive`. The choice
-// between them IS the local declaration of writability at each getter,
-// mirroring `: this` invertible method returns. For arbitrary cached
-// views, use `lazy()` from "../signal" directly.
-import { Cell, lazy } from "./signal.js";
-/** Bidirectional field lens onto `parent.value[key]`; write spread-
- *  replaces the composite. Cached per (instance, key). Return type is
- *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO
- *  (runtime dispatch in `Cell.fieldOf` mirrors this).
- *
- *      get x() { return field(this, "x", Num); } */
-export function field(parent, key, Cls) {
-    return lazy(parent, key, () => Cell.fieldOf(parent, key, Cls));
-}
-/** Read-only derived view via `Cls.derive(parent, fn)`. Cached per
- *  (instance, key); always bare `Cls` (RO).
- *
- *      get magnitude() {
- *        return derived(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
- *      } */
-// biome-ignore lint/suspicious/noExplicitAny: variance escape, mirrors Cls.derive
-export function derived(parent, key, Cls, fn) {
-    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.derive
-    return lazy(parent, key, () => Cls.derive(parent, fn));
-}