bireactive 0.3.1 → 0.3.2

package/dist/coll.js

@@ -1,210 +0,0 @@
-// coll.ts — a keyed, ordered, *bidirectional* collection.
-//
-// The structural sibling of `tree.ts`. A `Coll<E>` holds stable element
-// handles (records of cells), and each projection — `filter` / `sortBy` /
-// `groupBy` — is a WRITABLE structural lens. You edit the *view* and the
-// backward pass writes the elements' own fields:
-//
-//   sortBy(rank)  → move(e, i)        writes `rank`   (position is a field)
-//   groupBy(key)  → move(e, k, i)     writes `key`    (membership is a field)
-//   filter(pred)  → insert/assert     writes whatever pred demands
-//
-// Because position / group / visibility are the elements' own writable
-// cells, these lenses are COMPLEMENT-FREE — the "complement" lives in the
-// field cells, not the lens (contrast `Seq<T>`, where order is imposed and
-// must be remembered). One `move`/`insert` composes the backward passes up
-// the chain in a single `batch`: drop into a filtered + grouped + sorted
-// view and the filter's predicate, the group key, and the rank all get set
-// at once.
-//
-// Two change classes, mirroring the engine's two levels:
-//   • value change   — a field cell changes; forward derivations re-flow.
-//   • structural edit — insert/remove/move; a discrete batched transition.
-// No lens edges are built at runtime, so acyclicity holds as ever.
-import { batch, cell, derive } from "./core/index.js";
-/** `field === value`, assertable by writing the field. */
-export function is(field, value) {
-    const p = ((e) => field(e).value === value);
-    p.assert = (e) => {
-        field(e).value = value;
-    };
-    return p;
-}
-/** Conjunction; asserts every clause. */
-export function allPass(...preds) {
-    const p = ((e) => preds.every(q => q(e)));
-    p.assert = (e) => {
-        for (const q of preds)
-            q.assert?.(e);
-    };
-    return p;
-}
-/** Read-only projection with chainable structural lenses. */
-export class View {
-    list;
-    key;
-    parent;
-    constructor(list, key, parent) {
-        this.list = list;
-        this.key = key;
-        this.parent = parent;
-    }
-    /** Current members; tracked when read in an effect/derive. */
-    get items() {
-        return this.list.value;
-    }
-    /** The source collection at the head of the chain. */
-    get root() {
-        let v = this;
-        while (v.parent)
-            v = v.parent;
-        return v;
-    }
-    /** Make `e` appear in this view: satisfy own constraint, recursively up. */
-    assertContains(e) {
-        this.parent?.assertContains(e);
-        this.assertSelf(e);
-    }
-    assertSelf(_e) { }
-    filter(pred) {
-        return new FilterView(this, pred);
-    }
-    sortBy(field) {
-        return new SortView(this, field);
-    }
-    groupBy(field, opts) {
-        return new GroupView(this, field, opts);
-    }
-    map(f) {
-        return derive(() => this.list.value.map(f));
-    }
-    /** Remove `e` from the source. */
-    remove(e) {
-        this.root.removeFromSource(e);
-    }
-}
-/** A writable source collection. */
-export class Coll extends View {
-    #src;
-    constructor(items, key) {
-        const src = cell(items);
-        super(src, key, null);
-        this.#src = src;
-    }
-    assertContains(e) {
-        if (!this.#src.value.includes(e))
-            this.insert(e);
-    }
-    insert(e, at) {
-        const arr = [...this.#src.value];
-        if (at == null)
-            arr.push(e);
-        else
-            arr.splice(at, 0, e);
-        this.#src.value = arr;
-    }
-    removeFromSource(e) {
-        this.#src.value = this.#src.value.filter(x => x !== e);
-    }
-}
-class FilterView extends View {
-    #pred;
-    constructor(parent, pred) {
-        super(derive(() => parent.items.filter(pred)), parent.key, parent);
-        this.#pred = pred;
-    }
-    assertSelf(e) {
-        this.#pred.assert?.(e);
-    }
-}
-/** Sorted view. `move` writes the order field between the drop neighbours. */
-export class SortView extends View {
-    #field;
-    constructor(parent, field) {
-        super(derive(() => [...parent.items].sort((a, b) => field(a).value - field(b).value)), parent.key, parent);
-        this.#field = field;
-    }
-    move(e, to) {
-        const others = this.items.filter(x => x !== e);
-        batch(() => {
-            this.assertContains(e);
-            this.#field(e).value = between(rankAt(others, this.#field, to - 1), rankAt(others, this.#field, to));
-        });
-    }
-}
-/** Grouped view. `move`/`insert` write the group field (and, with a `sort`
- *  field, the order field). Backward composition runs the parent chain. */
-export class GroupView {
-    groups;
-    #parent;
-    #field;
-    #order;
-    #sort;
-    constructor(parent, field, opts = {}) {
-        this.#parent = parent;
-        this.#field = field;
-        this.#order = opts.order ?? [];
-        this.#sort = opts.sort;
-        this.groups = derive(() => {
-            const sort = this.#sort;
-            const items = sort
-                ? [...parent.items].sort((a, b) => sort(a).value - sort(b).value)
-                : parent.items;
-            return groupItems(items, e => field(e).value, this.#order);
-        });
-    }
-    get value() {
-        return this.groups.value;
-    }
-    map(f) {
-        return derive(() => this.value.map(f));
-    }
-    /** Place `e` in group `toKey` at `index`. Inserts it into the source if
-     *  it isn't there yet, asserts every upstream filter, then writes the
-     *  group key and order field — all in one batch. */
-    move(e, toKey, index) {
-        const target = (this.value.find(g => Object.is(g.key, toKey))?.items ?? []).filter(x => x !== e);
-        const sort = this.#sort;
-        batch(() => {
-            this.#parent.assertContains(e);
-            this.#field(e).value = toKey;
-            if (sort && index != null)
-                sort(e).value = between(rankAt(target, sort, index - 1), rankAt(target, sort, index));
-        });
-    }
-    insert(e, toKey, index) {
-        this.move(e, toKey, index);
-    }
-    remove(e) {
-        this.#parent.remove(e);
-    }
-}
-function groupItems(items, keyOf, order) {
-    const buckets = new Map();
-    for (const k of order)
-        buckets.set(k, []);
-    for (const e of items) {
-        const k = keyOf(e);
-        const arr = buckets.get(k);
-        if (arr)
-            arr.push(e);
-        else
-            buckets.set(k, [e]);
-    }
-    return [...buckets].map(([key, items]) => ({ key, items }));
-}
-function rankAt(arr, field, i) {
-    return i >= 0 && i < arr.length ? field(arr[i]).value : undefined;
-}
-function between(a, b) {
-    if (a != null && b != null)
-        return (a + b) / 2;
-    if (a != null)
-        return a + 1;
-    if (b != null)
-        return b - 1;
-    return 0;
-}
-export function coll(items, key) {
-    return new Coll(items, key);
-}

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

@@ -1,57 +0,0 @@
-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.
- *  The Vec-specific group-action reading of `mean`. */
-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 `rigidTranslate(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>;
-export declare function bestFitLine(points: readonly Writable<Vec>[]): {
-    point: Writable<Vec>;
-    direction: Writable<Num>;
-};
-export declare function bestFitCircle(points: readonly Writable<Vec>[]): {
-    center: Writable<Vec>;
-    radius: Writable<Num>;
-};
-export declare function pca(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 total(parts: readonly Writable<Num>[]): Writable<Num>;
-export {};

package/dist/core/lenses/decompositions.d.ts

@@ -1,14 +0,0 @@
-import { Num, Vec, type Writable } from "../index.js";
-export declare function meanDiff(a: Num, b: Num): {
-    mean: Writable<Num>;
-    diff: Writable<Num>;
-};
-export declare function procrustes(points: readonly Writable<Vec>[]): {
-    centroid: Writable<Vec>;
-    rotation: Writable<Num>;
-    scale: Writable<Num>;
-};
-export declare function bbox(points: readonly Writable<Vec>[]): {
-    center: Writable<Vec>;
-    size: Writable<Vec>;
-};

package/dist/core/lenses/decompositions.js

@@ -1,224 +0,0 @@
-// decompositions.ts — closed-form N→M lens decompositions (Vec/Num).
-//
-// N inputs → M coupled writable outputs, where writing one output
-// preserves the readings of the other M−1 (cross-channel invariance).
-// Each bwd is a hand-rolled group action (translate / rotate / scale
-// about the centroid), so cross-channel invariance is EXACT and one
-// write lands in O(K). For the generic numerical N→M escape hatch (when
-// no closed form fits) see `factor` in `typed-factor.ts`.
-import { Num, SKIP, Vec } from "../index.js";
-// meanDiff — 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.
-export function meanDiff(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 };
-}
-// procrustes — 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. 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 procrustes(points) {
-    const K = points.length;
-    if (K < 2)
-        throw new Error("procrustes: 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(() => SKIP);
-        }
-        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(() => SKIP), 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 };
-}
-// bbox — 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 bbox(points) {
-    const K = points.length;
-    if (K < 1)
-        throw new Error("bbox: 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 };
-}

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

@@ -1,42 +0,0 @@
-import { type Cell, Num, type Read, type Traits, type Val, Vec, type Writable } from "../index.js";
-/** Equal-weight mean (writable of `inputs[0]`'s class); writes distribute
- *  the delta evenly. Class inferred from the first input; needs `linear`. */
-export declare function mean<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>;
-/** 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 spread<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(inputs: readonly Writable<S>[]): Writable<Num>;
-/** 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 declare function meanSpread<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 bezierGestalt(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 timeSeries(values: readonly Writable<Num>[]): {
-    mean: Writable<Num>;
-    slope: Writable<Num>;
-};