bireactive 0.2.0

package/dist/core/lenses/domain-aggregates.js

@@ -0,0 +1,259 @@
+// domain-aggregates.ts — closed-form lenses beyond point clouds.
+//
+// The group-action patterns from `closed-form-policies.ts`, applied to:
+//   (1) Generic Linear/Metric-trait aggregates — `meanOf`, `spreadOf`,
+//       `paletteLens` work for colors, poses, ranges, boxes for free.
+//   (2) Color aggregates — `meanColor`.
+//   (3) Bezier gestalt handles ({start, end, startTangent, endTangent}).
+//   (4) Time-series ({mean, slope}) over (i, value) samples.
+// All exact, idempotent, cross-channel invariant by construction.
+import { Num, reader, Vec, } from "../index.js";
+import { remember } from "./memory.js";
+// Generic Linear-trait aggregates.
+//
+// Ergonomic entry points over `meanLens` / `scaleAbout` that infer the
+// value class from the first input (`meanOf(colors)` vs
+// `meanLens(Color, colors)`). Same engine, no new infrastructure.
+/** Class-inferring mean (writable of `inputs[0]`'s class). Needs `linear`. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape
+export function meanOf(inputs) {
+    if (inputs.length === 0)
+        throw new Error("meanOf: need ≥ 1 input");
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
+    const Cls = inputs[0].constructor;
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
+    const lin = Cls.traits?.linear;
+    if (!lin)
+        throw new Error(`meanOf: ${Cls.name ?? "?"} has no traits.linear`);
+    const n = inputs.length;
+    const inv = 1 / n;
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.lens
+    return Cls.lens(inputs, 
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape
+    (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: variance escape
+    (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;
+    });
+}
+/** Rigid-translate aggregate over any Linear type. Alias of `meanOf`,
+ *  named for the geometric intent. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape
+export function rigidTranslateOf(inputs) {
+    return meanOf(inputs);
+}
+// Weighted blend (the mix simplex).
+//
+// `mix` is `meanOf` with the uniform-weight assumption lifted: the read
+// is the normalized weighted sum `Σ wᵢ·aᵢ`, the write is the minimum-norm
+// delta `daᵢ = wᵢ·δ / Σwⱼ²` (the pseudoinverse of `wᵀ·da = δ`), so a
+// zero-weight branch is left untouched. Weights are read-only controls —
+// the bwd never writes them, keeping the blend fixed while the delta flows
+// into the branches.
+//
+// The control lives on the K-simplex: a one-hot vertex is `select`
+// (the live branch absorbs everything), a `(1−t, t)` edge is `crossfade`,
+// uniform weights recover `meanOf`. Reactive weights are dynamically
+// tracked (read via `.value` inside fwd), so flipping a Bool or sliding a
+// Num re-reads with no extra wiring.
+/** Weighted blend of K branches over any `Linear` type. See module note. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape
+export function mix(weights, branches) {
+    const K = branches.length;
+    if (K < 1)
+        throw new Error("mix: need ≥ 1 branch");
+    if (weights.length !== K)
+        throw new Error("mix: weights/branches length mismatch");
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
+    const Cls = branches[0].constructor;
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
+    const lin = Cls.traits?.linear;
+    if (!lin)
+        throw new Error(`mix: ${Cls.name ?? "?"} has no traits.linear`);
+    const wf = weights.map(w => reader(w));
+    // Normalized weights + Σw². Degenerate (all-zero) weights fall back to
+    // uniform so the read stays defined.
+    const readW = () => {
+        const raw = wf.map(f => f());
+        let sum = 0;
+        for (const x of raw)
+            sum += x;
+        const w = Math.abs(sum) > 1e-12 ? raw.map(x => x / sum) : raw.map(() => 1 / K);
+        let sumSq = 0;
+        for (const x of w)
+            sumSq += x * x;
+        return { w, sumSq };
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.lens
+    const combine = (vals, w) => {
+        let acc = lin.scale(vals[0], w[0]);
+        for (let i = 1; i < K; i++)
+            acc = lin.add(acc, lin.scale(vals[i], w[i]));
+        return acc;
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.lens
+    return Cls.lens(branches, 
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape
+    (vals) => combine(vals, readW().w), 
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape
+    (target, vals) => {
+        const { w, sumSq } = readW();
+        const delta = lin.sub(target, combine(vals, w));
+        if (sumSq < 1e-12)
+            return vals.map(() => undefined);
+        const inv = 1 / sumSq;
+        return vals.map((v, i) => w[i] === 0 ? undefined : lin.add(v, lin.scale(delta, w[i] * inv)));
+    });
+}
+/** 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. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape
+export function select(cond, whenFalse, whenTrue) {
+    return mix([Num.derive(() => (cond.value ? 0 : 1)), Num.derive(() => (cond.value ? 1 : 0))], [whenFalse, whenTrue]);
+}
+/** Two-branch crossfade (mix simplex *edge*): `lerp(a, b, t)`. Writing
+ *  keeps `t` fixed and splits the delta by influence. */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape
+export function crossfade(t, a, b) {
+    return mix([Num.derive(() => 1 - t.value), Num.derive(() => t.value)], [a, b]);
+}
+/** Mean color of a palette; write shifts every color by the delta
+ *  (rigid translate in RGBA). Via `meanOf`. */
+export function meanColor(colors) {
+    return meanOf(colors);
+}
+/** 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 function spreadOf(inputs) {
+    const K = inputs.length;
+    if (K < 1)
+        throw new Error("spreadOf: need ≥ 1 input");
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
+    const Cls = inputs[0].constructor;
+    const lin = Cls.traits?.linear;
+    const met = Cls.traits?.metric;
+    if (!lin || !met) {
+        throw new Error(`spreadOf: ${Cls.name ?? "?"} needs Linear + Metric`);
+    }
+    const inv = 1 / K;
+    const centroid = (vals) => {
+        let acc = vals[0];
+        for (let i = 1; i < K; i++)
+            acc = lin.add(acc, vals[i]);
+        return lin.scale(acc, inv);
+    };
+    const meanSpread = (vals, ctr) => {
+        let total = 0;
+        for (let i = 0; i < K; i++)
+            total += met(vals[i], ctr);
+        return total * inv;
+    };
+    // Mean metric-distance from the centroid is a magnitude `remember`:
+    // writing it scales the cluster's deviations about the centroid, and a
+    // collapse (spread → 0) reinflates the remembered shape.
+    return remember(inputs, {
+        anchor: (vals) => centroid(vals),
+        feature: (vals, ctr) => meanSpread(vals, ctr),
+    });
+}
+/** Palette decomposition: K values → {mean, spread}, i.e. centroid +
+ *  uniform scale about it. `meanOf` ∘ `spreadOf`; works for any
+ *  Linear + Metric class. */
+export function paletteLens(colors) {
+    return {
+        mean: meanOf(colors),
+        spread: spreadOf(colors),
+    };
+}
+export function bezierGestaltLens(p0, p1, p2, p3) {
+    const start = Vec.lens([p0, p1], (vals) => vals[0], (target, vals) => {
+        const dx = target.x - vals[0].x;
+        const dy = target.y - vals[0].y;
+        return [target, { x: vals[1].x + dx, y: vals[1].y + dy }];
+    });
+    const end = Vec.lens([p2, p3], (vals) => vals[1], (target, vals) => {
+        const dx = target.x - vals[1].x;
+        const dy = target.y - vals[1].y;
+        return [{ x: vals[0].x + dx, y: vals[0].y + dy }, target];
+    });
+    const startTangent = Vec.lens([p0, p1], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [undefined, { x: vals[0].x + target.x, y: vals[0].y + target.y }]);
+    const endTangent = Vec.lens([p2, p3], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [{ x: vals[1].x - target.x, y: vals[1].y - target.y }, undefined]);
+    return { start, end, startTangent, endTangent };
+}
+// Time-series aggregates.
+//
+// Scalar values indexed by position → {mean, slope}:
+//   mean  := average; writes shift all values by the delta.
+//   slope := least-squares slope of (i, value_i); writes tilt about mean.
+// mean and slope are invariant under each other (a y-shift preserves
+// slope; tilting about the mean preserves the mean).
+/** Time-series scalar aggregate over Num values as (i, value_i) samples. */
+export function timeSeriesLens(values) {
+    const N = values.length;
+    if (N < 2)
+        throw new Error("timeSeries: need ≥ 2 values");
+    const mean = Num.lens(values, (vals) => {
+        let s = 0;
+        for (let i = 0; i < N; i++)
+            s += vals[i];
+        return s / N;
+    }, (target, vals) => {
+        let s = 0;
+        for (let i = 0; i < N; i++)
+            s += vals[i];
+        const cur = s / N;
+        const delta = target - cur;
+        return vals.map(v => v + delta);
+    });
+    // Least-squares slope = Σ (i − idxMean)(v − mean) / Σ (i − idxMean)²,
+    // idxMean = (N−1)/2 constant. Write tilts about the mean:
+    // value_i = mean + (i − idxMean)·s.
+    const idxMean = (N - 1) / 2;
+    let denomSlope = 0;
+    for (let i = 0; i < N; i++) {
+        const di = i - idxMean;
+        denomSlope += di * di;
+    }
+    const slope = Num.lens(values, (vals) => {
+        let valMean = 0;
+        for (let i = 0; i < N; i++)
+            valMean += vals[i];
+        valMean /= N;
+        let num = 0;
+        for (let i = 0; i < N; i++)
+            num += (i - idxMean) * (vals[i] - valMean);
+        return num / denomSlope;
+    }, (target, vals) => {
+        let valMean = 0;
+        for (let i = 0; i < N; i++)
+            valMean += vals[i];
+        valMean /= N;
+        return vals.map((_, i) => valMean + (i - idxMean) * target);
+    });
+    return { mean, slope };
+}
+// `meanOf` / `rigidTranslateOf` / `spreadOf` are fully trait-driven
+// (Linear, Metric); `bezierGestalt` and `timeSeries` stay value-specific
+// (Vec / Num) since their operations don't benefit from the trait layer.

package/dist/core/lenses/factor-lens.d.ts

@@ -0,0 +1,42 @@
+import { type Cell, Num, Vec, type Writable } from "../index.js";
+export interface FactorLensOpts {
+    /** Per-input mobility weights. 0 = pinned input. Defaults to all 1. */
+    inputWeights?: readonly number[];
+    /** Levenberg-Marquardt damping on the M×M normal matrix. Default 1e-6. */
+    damping?: number;
+    /** Finite-difference epsilon. Default 1e-5. */
+    eps?: number;
+}
+export declare function factorLens(inputs: readonly Num[], forwards: readonly ((xs: readonly number[]) => number)[], opts?: FactorLensOpts): Writable<Num>[];
+export declare function meanDiffLens(a: Num, b: Num): {
+    mean: Writable<Num>;
+    diff: Writable<Num>;
+};
+export declare function procrustesLens(points: readonly Writable<Vec>[]): {
+    centroid: Writable<Vec>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};
+export declare function bboxLens(points: readonly Writable<Vec>[]): {
+    center: Writable<Vec>;
+    size: Writable<Vec>;
+};
+export declare function procrustesJacobianLens(points: readonly Writable<Vec>[]): {
+    centroidX: Writable<Num>;
+    centroidY: Writable<Num>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};
+type PoseV = {
+    x: number;
+    y: number;
+    theta: number;
+};
+export declare function bundleLens(pose: Writable<Cell<PoseV>>, rotateAbout: {
+    x: number;
+    y: number;
+}): {
+    position: Writable<Vec>;
+    rotation: Writable<Num>;
+};
+export {};