bireactive 0.2.0

package/dist/core/lenses/closed-form-policies.js

@@ -0,0 +1,452 @@
+// closed-form-policies.ts — exact group-action lenses for point clouds.
+//
+// When an aggregate lens has a closed-form inverse, its bwd applies a
+// GROUP ELEMENT to the source set. Translation, rotation-about-pivot,
+// and scale-about-pivot are the building blocks; Procrustes, best-fit
+// line/circle, and PCA decompose into combinations of them.
+//
+// Layout: building-block actions (rigidTranslate, rotateAbout,
+// scaleAbout, scaleAboutXY), Procrustes re-expressed via them, then
+// closed-form decompositions (bestFitLine, bestFitCircle, pcaLens,
+// totalLens). All exact, idempotent, cross-channel invariant by
+// construction, on the same `Cls.lens` machinery — no engine changes.
+import { centroidLens, Num, Vec, } from "../index.js";
+import { continuous, remember } from "./memory.js";
+// Pivotal trait lookup via the value class's `static traits.pivotal` slot.
+// biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
+function pivotalOf(input) {
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
+    const Cls = input.constructor;
+    const p = Cls.traits?.pivotal;
+    if (!p) {
+        const name = Cls.name ?? "?";
+        throw new Error(`closed-form-policies: ${name} has no traits.pivotal`);
+    }
+    return p;
+}
+/** Writable centroid; on write, translates every point by the delta.
+ *  Alias of `centroidLens` under the "policy" naming. */
+export function rigidTranslate(points) {
+    return centroidLens(points);
+}
+/** 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 function rotateAbout(points, pivot) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("rotateAbout: need ≥ 1 point");
+    const pv = pivotalOf(points[0]);
+    return Num.lens(points, (vals) => {
+        const p = pivot.peek();
+        return Math.atan2(vals[0].y - p.y, vals[0].x - p.x);
+    }, (target, vals) => {
+        const p = pivot.peek();
+        const rx0 = vals[0].x - p.x;
+        const ry0 = vals[0].y - p.y;
+        if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
+            return vals.map(() => undefined);
+        }
+        const oldθ = Math.atan2(ry0, rx0);
+        const dθ = target - oldθ;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++)
+            out[i] = pv.rotateAbout(vals[i], p, dθ);
+        return out;
+    });
+}
+/** 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 function scaleAbout(points, pivot) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("scaleAbout: need ≥ 1 point");
+    // Eager lookup so an undeclared class fails at construction:
+    pivotalOf(points[0]);
+    const refresh = (devs, vals, p) => devs.map((d, i) => {
+        const dx = vals[i].x - p.x;
+        const dy = vals[i].y - p.y;
+        return dx * dx + dy * dy > 1e-18 ? { x: dx, y: dy } : d;
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape — spec is checked structurally
+    return Num.lens(points, {
+        init: (vals) => {
+            const p = pivot.peek();
+            return { devs: vals.map(v => ({ x: v.x - p.x, y: v.y - p.y })) };
+        },
+        step: (vals, c) => ({ devs: refresh(c.devs, vals, pivot.peek()) }),
+        fwd: (vals) => {
+            const p = pivot.peek();
+            return Math.hypot(vals[0].x - p.x, vals[0].y - p.y);
+        },
+        bwd: (target, vals, c) => {
+            const p = pivot.peek();
+            // Lossy magnitude view: |−r| = r, so a same-magnitude target
+            // re-projects to the current radius and is absorbed (sources put).
+            const rNow = Math.hypot(vals[0].x - p.x, vals[0].y - p.y);
+            if (Math.abs(target) === rNow)
+                return { updates: vals.map(() => undefined), complement: c };
+            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 = vals.map((v, i) => ({
+                ...v,
+                x: p.x + k * c.devs[i].x,
+                y: p.y + k * c.devs[i].y,
+            }));
+            return { updates: out, complement: c };
+        },
+    });
+}
+/** 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 function scaleAboutXY(points, pivot) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("scaleAboutXY: need ≥ 1 point");
+    const refresh = (fracs, vals, p) => {
+        const ox = vals[0].x - p.x;
+        const oy = vals[0].y - p.y;
+        const okx = Math.abs(ox) > 1e-12;
+        const oky = Math.abs(oy) > 1e-12;
+        return fracs.map((f, i) => ({
+            x: okx ? (vals[i].x - p.x) / ox : f.x,
+            y: oky ? (vals[i].y - p.y) / oy : f.y,
+        }));
+    };
+    return Vec.lens(points, {
+        init: (vals) => {
+            const p = pivot.peek();
+            const ox = vals[0].x - p.x;
+            const oy = vals[0].y - p.y;
+            return {
+                fracs: vals.map(v => ({
+                    x: Math.abs(ox) > 1e-12 ? (v.x - p.x) / ox : 0,
+                    y: Math.abs(oy) > 1e-12 ? (v.y - p.y) / oy : 0,
+                })),
+            };
+        },
+        step: (vals, c) => ({ fracs: refresh(c.fracs, vals, pivot.peek()) }),
+        fwd: (vals) => {
+            const p = pivot.peek();
+            return { x: vals[0].x - p.x, y: vals[0].y - p.y };
+        },
+        bwd: (target, _vals, c) => {
+            const p = pivot.peek();
+            const out = c.fracs.map(f => ({ x: p.x + f.x * target.x, y: p.y + f.y * target.y }));
+            return { updates: out, complement: c };
+        },
+    });
+}
+/** Same semantics as `factor-lens.ts`'s `procrustesLens`, decomposed
+ *  into three building-block lenses sharing a centroid. */
+export function procrustesViaBuildingBlocks(points) {
+    if (points.length < 2)
+        throw new Error("procrustes: need ≥ 2 points");
+    const centroid = rigidTranslate(points);
+    const rotation = rotateAbout(points, centroid);
+    const scale = scaleAbout(points, centroid);
+    return { centroid, rotation, scale };
+}
+// Best-fit line.
+//
+// K points → {point: centroid, direction: principal-axis angle}.
+//   write point     → rigidTranslate
+//   write direction → rotate all about centroid to set principal axis
+// Invariance: principal axis is translation-invariant; centroid is
+// invariant under rotation-about-itself.
+/** Angle of the dominant eigenvector of symmetric 2×2 [[cxx,cxy],[cxy,cyy]]. */
+function dominantAxisAngle(cxx, cxy, cyy) {
+    return 0.5 * Math.atan2(2 * cxy, cxx - cyy);
+}
+function covariance(points, cx, cy) {
+    const K = points.length;
+    let cxx = 0;
+    let cxy = 0;
+    let cyy = 0;
+    for (let i = 0; i < K; i++) {
+        const dx = points[i].x - cx;
+        const dy = points[i].y - cy;
+        cxx += dx * dx;
+        cxy += dx * dy;
+        cyy += dy * dy;
+    }
+    return { cxx: cxx / K, cxy: cxy / K, cyy: cyy / K };
+}
+export function bestFitLineLens(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("bestFitLine: need ≥ 2 points");
+    const point = rigidTranslate(points);
+    // The principal axis is an eigenvector — defined only up to sign, so the
+    // raw atan2 jumps by π as the cloud rotates. `continuous` lifts it to its
+    // universal cover (period π, since axis ≡ axis + π), tracking the last
+    // emitted angle so the direction stays continuous; a collapsed cloud has
+    // no axis (`defined: false`), so it freezes and stashes the target.
+    // Centroid + dominant-axis raw angle; `degenerate` when covariance vanishes.
+    const axisOf = (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 { cxx, cxy, cyy } = covariance(vals, cx, cy);
+        if (cxx + cyy < 1e-18)
+            return { cx, cy, rawθ: 0, degenerate: true };
+        return { cx, cy, rawθ: dominantAxisAngle(cxx, cxy, cyy), degenerate: false };
+    };
+    const direction = continuous(points, {
+        period: Math.PI,
+        raw: (vals) => {
+            const { rawθ, degenerate } = axisOf(vals);
+            return { value: rawθ, defined: !degenerate };
+        },
+        apply: (target, vals, current) => {
+            const { cx, cy } = axisOf(vals);
+            const dθ = target - current;
+            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;
+        },
+    });
+    return { point, direction };
+}
+// Best-fit circle.
+//
+// K points → {center: centroid, radius: mean distance from center}.
+//   write center → rigidTranslate
+//   write radius → scale all about center by target/current
+// Simplest closed-form fit (mean center). Invariance: translation
+// preserves radii; uniform scale-about-center preserves the center.
+export function bestFitCircleLens(points) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("bestFitCircle: need ≥ 1 point");
+    const center = rigidTranslate(points);
+    // Radius = mean distance from the centroid; writing it scales the cluster
+    // about the centroid, and a collapse (mean → 0) reinflates the remembered
+    // shape — exactly `remember`'s magnitude view, anchored at the centroid.
+    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 meanRadius = (vals, c) => {
+        let sum = 0;
+        for (let i = 0; i < K; i++)
+            sum += Math.hypot(vals[i].x - c.x, vals[i].y - c.y);
+        return sum / K;
+    };
+    const radius = remember(points, {
+        anchor: (vals) => centroidOf(vals),
+        feature: (vals, c) => meanRadius(vals, c),
+    });
+    return { center, radius };
+}
+// PCA / affine similarity decomposition.
+//
+// K points → {mean: centroid, rotation: dominant-eigenvector angle,
+//   majorLength: √λ_major, minorLength: √λ_minor (per-axis std-devs)}.
+//   write mean        → rigidTranslate
+//   write rotation    → rotate all about mean to set principal axis
+//   write major/minor → scale along that axis by target/current
+// Each write is a single group action; cross-channel invariance holds
+// for all pairs.
+export function pcaLens(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("pcaLens: need ≥ 2 points");
+    const mean = rigidTranslate(points);
+    // 2×2 symmetric eigendecomp → {θ, λ_major, λ_minor}; null when fully
+    // collapsed (λ_major ≈ 0).
+    const decompose = (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 { cxx, cxy, cyy } = covariance(vals, cx, cy);
+        const tr = cxx + cyy;
+        const disc = Math.sqrt((cxx - cyy) * (cxx - cyy) + 4 * cxy * cxy);
+        const lambdaMajor = (tr + disc) / 2;
+        const lambdaMinor = (tr - disc) / 2;
+        if (lambdaMajor < 1e-24)
+            return null;
+        const θ = 0.5 * Math.atan2(2 * cxy, cxx - cyy);
+        return { cx, cy, θ, lambdaMajor, lambdaMinor };
+    };
+    const rotation = Num.lens(points, (vals) => decompose(vals)?.θ ?? 0, (target, vals) => {
+        const d = decompose(vals);
+        if (!d)
+            return vals.map(() => undefined);
+        const dθ = target - d.θ;
+        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 - d.cx;
+            const ry = vals[i].y - d.cy;
+            out[i] = { x: d.cx + cos * rx - sin * ry, y: d.cy + sin * rx + cos * ry };
+        }
+        return out;
+    });
+    // Scale by k along axis (ux, uy): project each point onto (u, u_perp),
+    // scale the u component, project back. Relative to mean.
+    const scaleAlongAxis = (vals, cx, cy, ux, uy, k) => {
+        const vx = -uy;
+        const vy = ux;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++) {
+            const rx = vals[i].x - cx;
+            const ry = vals[i].y - cy;
+            const a = rx * ux + ry * uy;
+            const b = rx * vx + ry * vy;
+            const ap = a * k;
+            out[i] = { x: cx + ap * ux + b * vx, y: cy + ap * uy + b * vy };
+        }
+        return out;
+    };
+    // majorLength / minorLength: complement carries the axis basis and
+    // per-point projections (normalized by the std-devs) at the last
+    // non-degenerate state, so an axis collapse (λ → 0) reinflates from the
+    // stored geometry. Non-degenerate writes take the scaleAlongAxis fast path.
+    const buildAxisLens = (which) => {
+        // Decompose and rebuild the axis basis + normalized projections;
+        // returns the prior complement when fully collapsed.
+        const axisFrom = (d, c, vals) => {
+            const ux = which === "major" ? Math.cos(d.θ) : -Math.sin(d.θ);
+            const uy = which === "major" ? Math.sin(d.θ) : Math.cos(d.θ);
+            const vx = -uy;
+            const vy = ux;
+            const lenThis = Math.sqrt(Math.max(0, which === "major" ? d.lambdaMajor : d.lambdaMinor));
+            const lenOther = Math.sqrt(Math.max(0, which === "major" ? d.lambdaMinor : d.lambdaMajor));
+            // Only refresh projections on axes that aren't collapsed.
+            const invThis = lenThis > 1e-12 ? 1 / lenThis : null;
+            const invOther = lenOther > 1e-12 ? 1 / lenOther : null;
+            const projThis = c.projThis.slice();
+            const projOther = c.projOther.slice();
+            for (let i = 0; i < K; i++) {
+                const dx = vals[i].x - d.cx;
+                const dy = vals[i].y - d.cy;
+                if (invThis !== null)
+                    projThis[i] = (dx * ux + dy * uy) * invThis;
+                if (invOther !== null)
+                    projOther[i] = (dx * vx + dy * vy) * invOther;
+            }
+            return { uX: ux, uY: uy, vX: vx, vY: vy, lenThis, lenOther, projThis, projOther };
+        };
+        return Num.lens(points, {
+            init: (vals) => {
+                const seed = {
+                    uX: 1,
+                    uY: 0,
+                    vX: 0,
+                    vY: 1,
+                    lenThis: 0,
+                    lenOther: 0,
+                    projThis: vals.map(() => 0),
+                    projOther: vals.map(() => 0),
+                };
+                const d = decompose(vals);
+                return d ? axisFrom(d, seed, vals) : seed;
+            },
+            step: (vals, c) => {
+                const d = decompose(vals);
+                return d ? axisFrom(d, c, vals) : c;
+            },
+            fwd: (vals, c) => (decompose(vals) ? c.lenThis : 0),
+            bwd: (target, vals, c) => {
+                const d = decompose(vals);
+                if (d && c.lenThis > 1e-12) {
+                    // Lossy magnitude view: a same-magnitude target re-projects to
+                    // the current axis length and is absorbed (cluster left put).
+                    if (Math.abs(target) === c.lenThis)
+                        return { updates: vals.map(() => undefined), complement: c };
+                    // Non-degenerate fast path: scale current cluster along axis.
+                    const k = target / c.lenThis;
+                    return { updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k), complement: c };
+                }
+                // Degenerate: reconstruct from complement. Centroid still
+                // derivable from current source (mean translates always work).
+                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 out = new Array(K);
+                for (let i = 0; i < K; i++) {
+                    const a = c.projThis[i] * target;
+                    const b = c.projOther[i] * c.lenOther;
+                    out[i] = { x: cx + a * c.uX + b * c.vX, y: cy + a * c.uY + b * c.vY };
+                }
+                return { updates: out, complement: c };
+            },
+        });
+    };
+    const majorLength = buildAxisLens("major");
+    const minorLength = buildAxisLens("minor");
+    return { mean, rotation, majorLength, minorLength };
+}
+// Partition / simplex lens.
+//
+// K parts → {total}: writing total scales all parts proportionally.
+// (A {total, ratios} form is possible but ratios on a K-simplex have
+// K−1 DOF, so it's left out of this prototype.)
+/** 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 function totalLens(parts) {
+    const K = parts.length;
+    if (K < 1)
+        throw new Error("totalLens: need ≥ 1 part");
+    return remember(parts, {
+        anchor: () => 0,
+        feature: (vals) => {
+            let s = 0;
+            for (let i = 0; i < K; i++)
+                s += vals[i];
+            return s;
+        },
+        magnitude: false,
+        seed: () => parts.map(() => 1 / K),
+    });
+}
+// Every lens here is a group action about a pivot (translate, rotateAbout,
+// scaleAbout, scaleAboutXY, scaleAlongAxis) or a `remember`/`continuous`
+// shape-memory; the decompositions combine them, each measured against a
+// derived feature (centroid, principal axis, mean radius).

package/dist/core/lenses/domain-aggregates.d.ts

@@ -0,0 +1,54 @@
+import { type Cell, Num, type Read, type Traits, type Val, Vec, type Writable } from "../index.js";
+/** Class-inferring mean (writable of `inputs[0]`'s class). Needs `linear`. */
+export declare function meanOf<S extends Traits<any, "linear">>(inputs: readonly Writable<S>[]): Writable<S>;
+/** Rigid-translate aggregate over any Linear type. Alias of `meanOf`,
+ *  named for the geometric intent. */
+export declare function rigidTranslateOf<S extends Traits<any, "linear">>(inputs: readonly Writable<S>[]): Writable<S>;
+/** Weighted blend of K branches over any `Linear` type. See module note. */
+export declare function mix<S extends Traits<any, "linear">>(weights: readonly Val<number>[], branches: readonly Writable<S>[]): Writable<S>;
+/** Two-branch router (mix simplex *vertex*): reads the live branch, writes
+ *  flow entirely to it, the other is left put. Flipping `cond` snaps the
+ *  output to the other branch's stored value. */
+export declare function select<S extends Traits<any, "linear">>(cond: Read<boolean>, whenFalse: Writable<S>, whenTrue: Writable<S>): Writable<S>;
+/** Two-branch crossfade (mix simplex *edge*): `lerp(a, b, t)`. Writing
+ *  keeps `t` fixed and splits the delta by influence. */
+export declare function crossfade<S extends Traits<any, "linear">>(t: Read<number>, a: Writable<S>, b: Writable<S>): Writable<S>;
+type ColorV = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/** Mean color of a palette; write shifts every color by the delta
+ *  (rigid translate in RGBA). Via `meanOf`. */
+export declare function meanColor(colors: readonly Writable<Traits<ColorV, "linear">>[]): Writable<Traits<ColorV, "linear">>;
+/** Mean radial distance from the centroid; write scales the cluster's
+ *  deviations so the new mean matches the target. Trait-driven via
+ *  `Linear` + `Metric`, so it works for any class declaring both (Vec,
+ *  Color, Pose, Box, Range, custom).
+ *
+ *  Complement carries per-input deviations normalized by the current mean
+ *  radius, so `spread = T` places each input at `centroid + normDev_i * T`
+ *  and a collapse (spread → 0) reinflates the original SHAPE. Centroid is
+ *  recomputed every read/write, so an intervening mean translate is not
+ *  stale. */
+export declare function spreadOf<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(inputs: readonly Writable<S>[]): Writable<Num>;
+/** Palette decomposition: K values → {mean, spread}, i.e. centroid +
+ *  uniform scale about it. `meanOf` ∘ `spreadOf`; works for any
+ *  Linear + Metric class. */
+export declare function paletteLens<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(colors: readonly Writable<S>[]): {
+    mean: Writable<S>;
+    spread: Writable<Num>;
+};
+export declare function bezierGestaltLens(p0: Writable<Vec>, p1: Writable<Vec>, p2: Writable<Vec>, p3: Writable<Vec>): {
+    start: Writable<Vec>;
+    end: Writable<Vec>;
+    startTangent: Writable<Vec>;
+    endTangent: Writable<Vec>;
+};
+/** Time-series scalar aggregate over Num values as (i, value_i) samples. */
+export declare function timeSeriesLens(values: readonly Writable<Num>[]): {
+    mean: Writable<Num>;
+    slope: Writable<Num>;
+};
+export {};