bireactive 0.3.1 → 0.3.3

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

@@ -1,245 +0,0 @@
-// 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 — `mean`, `spread`,
-//       `palette` work for colors, poses, ranges, boxes for free.
-//   (2) Bezier gestalt handles ({start, end, startTangent, endTangent}).
-//   (3) Time-series ({mean, slope}) over (i, value) samples.
-// All exact, idempotent, cross-channel invariant by construction.
-import { Num, reader, SKIP, Vec, } from "../index.js";
-import { remember } from "./memory.js";
-// Generic Linear-trait aggregates.
-//
-// Ergonomic entry points that infer the value class from the first input
-// (`mean(colors)` works for any `linear` class). Same engine, no new
-// infrastructure.
-/** Equal-weight mean (writable of `inputs[0]`'s class); writes distribute
- *  the delta evenly. Class inferred from the first input; needs `linear`. */
-// biome-ignore lint/suspicious/noExplicitAny: variance escape
-export function mean(inputs) {
-    if (inputs.length === 0)
-        throw new Error("mean: 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(`mean: ${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;
-    });
-}
-// Weighted blend (the mix simplex).
-//
-// `mix` is `mean` 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 `mean`. 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(() => SKIP);
-        const inv = 1 / sumSq;
-        return vals.map((v, i) => w[i] === 0 ? SKIP : 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 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 spread(inputs) {
-    const K = inputs.length;
-    if (K < 1)
-        throw new Error("spread: 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(`spread: ${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),
-    });
-}
-/** Mean/spread decomposition: K values → {mean, spread}, i.e. centroid +
- *  uniform scale about it. `mean` ∘ `spread`; works for any
- *  Linear + Metric class (palettes, point clouds, poses, …). */
-export function meanSpread(colors) {
-    return {
-        mean: mean(colors),
-        spread: spread(colors),
-    };
-}
-export function bezierGestalt(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) => [SKIP, { 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 }, SKIP]);
-    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 timeSeries(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 };
-}

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

@@ -1,40 +0,0 @@
-import type { Cell, Inner, Read, Traits, Writable } from "../index.js";
-/** Input cell: writable cell whose value class declares the `pack`
- *  trait. Vec, Num, Pose, Box, Color, Range all satisfy this. */
-export type PackedInput<T = any> = Writable<Read<T> & Traits<T, "pack">>;
-/** Output specification: a target class + a fwd from typed inputs to
- *  the value the class wraps. Optional analytical Jacobian skips FD. */
-export interface OutputSpec<C extends new (...args: never[]) => Cell<any>> {
-    Cls: C;
-    fwd: (inputs: ReadonlyArray<any>) => Inner<InstanceType<C>>;
-    /** Optional analytical Jacobian. Returns dim(Cls) rows, each of
-     *  length `sum(input pack dims)`. If supplied for ALL outputs, FD
-     *  is skipped entirely → faster AND exact (no eps drift). */
-    jacobian?: (inputs: ReadonlyArray<any>) => readonly (readonly number[])[];
-}
-/** Result type: writable cell per output key, typed by the spec's Cls. */
-export type FactorResult<O extends Record<string, OutputSpec<any>>> = {
-    [K in keyof O]: Writable<InstanceType<O[K]["Cls"]>>;
-};
-export interface FactorOpts {
-    /** Per-input mobility weights. 0 = pinned. Defaults to 1 for all. */
-    inputWeights?: readonly number[];
-    /** Levenberg-Marquardt damping. Default 1e-6. */
-    damping?: number;
-    /** Finite-difference epsilon. Default 1e-5. */
-    eps?: number;
-    /** Auto-iterate the bwd until the written channel's reading is
-     *  within `tol` of target (or `maxIters` exhausted). Cheap when
-     *  forwards are linear (1 iter); needed for non-linear forwards
-     *  to land exactly without user-side loops. Default `false`. */
-    converge?: boolean;
-    /** Max iters when `converge: true`. Default 10. */
-    maxIters?: number;
-    /** Convergence tolerance (per-channel L2). Default 1e-4. */
-    tol?: number;
-}
-export declare function factor<O extends Record<string, OutputSpec<any>>>(inputs: readonly PackedInput[], outputs: O, opts?: FactorOpts): FactorResult<O>;
-export declare function factorTuple<T extends readonly OutputSpec<any>[]>(inputs: readonly PackedInput[], outputs: readonly [...T], opts?: FactorOpts): {
-    [K in keyof T]: Writable<InstanceType<T[K]["Cls"]>>;
-};
-export declare function bundle<T, O extends Record<string, OutputSpec<any>>>(source: Writable<Read<T> & Traits<T, "pack">>, views: O, opts?: FactorOpts): FactorResult<O>;