bireactive 0.3.0 → 0.3.2

package/dist/core/debug.d.ts

@@ -0,0 +1,25 @@
+import { Cell } from "./cell.js";
+type SomeCell = Cell<any>;
+/** Short, stable display name: the cell's `name`, else `Ctor#n`. */
+export declare function label(c: SomeCell): string;
+/** `source` (no getter), `lens` (writable derived), or `computed` (read-only derived). */
+export declare function kind(c: SomeCell): "source" | "lens" | "computed";
+/** Upstream cells: eager lens parents unioned with dynamic forward deps. */
+export declare function upstream(c: SomeCell): Cell<unknown>[];
+/** One-line summary: `name = value  [kind]` plus upstream labels, if any. */
+export declare function explain(c: SomeCell): string;
+export interface DumpOpts {
+    /** Max upstream depth to descend. Default `Infinity`. */
+    depth?: number;
+    /** Include `= value` in each line. Default `true`. */
+    values?: boolean;
+}
+/** Render the upstream graph of `root` as an indented tree (cycle-safe). */
+export declare function dumpGraph(root: SomeCell, opts?: DumpOpts): string;
+/** Run `fn` and collect the source cells written during it (back-writes included,
+ *  since a view write commits through its sources' `_writeSource`). */
+export declare function traceWrites<T>(fn: () => T): {
+    result: T;
+    writes: Cell<unknown>[];
+};
+export {};

package/dist/core/debug.js

@@ -0,0 +1,121 @@
+// debug.ts — read-only inspection of the cell graph (dev-time, no hot-path cost).
+//
+// Three small tools: `explain` (one line about a cell), `dumpGraph` (the upstream
+// dependency tree), and `traceWrites` (which sources a block of work actually
+// wrote). All walk the same edges the engine maintains — lens parents
+// (`parentEdges`, eager) unioned with dynamic forward deps (`deps`, post-read) —
+// and label cells by their optional `name` (falling back to `Ctor#n`). Nothing
+// here mutates graph state; reads go through `peek` so they don't track.
+import { Cell, isLens, isReadonly, setCellWriteHook } from "./cell.js";
+const edges = (c) => c;
+const erase = (c) => c;
+const ids = new WeakMap();
+let nextId = 1;
+function idOf(c) {
+    let i = ids.get(c);
+    if (i === undefined) {
+        i = nextId++;
+        ids.set(c, i);
+    }
+    return i;
+}
+/** Short, stable display name: the cell's `name`, else `Ctor#n`. */
+export function label(c) {
+    return c.name ?? `${c.constructor.name}#${idOf(erase(c))}`;
+}
+/** `source` (no getter), `lens` (writable derived), or `computed` (read-only derived). */
+export function kind(c) {
+    return isLens(c) ? "lens" : isReadonly(c) ? "computed" : "source";
+}
+function short(v) {
+    try {
+        if (typeof v === "string")
+            return JSON.stringify(v);
+        if (v === null || v === undefined || typeof v !== "object")
+            return String(v);
+        const s = JSON.stringify(v);
+        if (s === undefined)
+            return Object.prototype.toString.call(v);
+        return s.length > 48 ? `${s.slice(0, 47)}…` : s;
+    }
+    catch {
+        return "?";
+    }
+}
+/** Upstream cells: eager lens parents unioned with dynamic forward deps. */
+export function upstream(c) {
+    const out = [];
+    const seen = new Set();
+    const push = (n) => {
+        if (n instanceof Cell && !seen.has(n)) {
+            seen.add(n);
+            out.push(n);
+        }
+    };
+    for (let e = edges(erase(c)).parentEdges; e !== undefined; e = e.nextParent)
+        push(e.parent);
+    for (let l = edges(erase(c)).deps; l !== undefined; l = l.nextDep)
+        push(l.dep);
+    return out;
+}
+/** One-line summary: `name = value  [kind]` plus upstream labels, if any. */
+export function explain(c) {
+    let v;
+    try {
+        v = c.peek();
+    }
+    catch {
+        v = "?";
+    }
+    const ups = upstream(c);
+    const tail = ups.length > 0 ? `  ← ${ups.map(label).join(", ")}` : "";
+    return `${label(c)} = ${short(v)}  [${kind(c)}]${tail}`;
+}
+/** Render the upstream graph of `root` as an indented tree (cycle-safe). */
+export function dumpGraph(root, opts = {}) {
+    const maxDepth = opts.depth ?? Number.POSITIVE_INFINITY;
+    const withValues = opts.values ?? true;
+    const lines = [];
+    const path = new Set();
+    const line = (c, indent) => {
+        if (!withValues)
+            return `${indent}${label(c)}  [${kind(c)}]`;
+        let v;
+        try {
+            v = c.peek();
+        }
+        catch {
+            v = "?";
+        }
+        return `${indent}${label(c)} = ${short(v)}  [${kind(c)}]`;
+    };
+    const walk = (c, indent, depth) => {
+        if (path.has(c)) {
+            lines.push(`${indent}${label(c)} ↺`); // back-edge into the current path
+            return;
+        }
+        lines.push(line(c, indent));
+        if (depth >= maxDepth)
+            return;
+        path.add(c);
+        for (const u of upstream(c))
+            walk(u, `${indent}  `, depth + 1);
+        path.delete(c);
+    };
+    walk(root, "", 0);
+    return lines.join("\n");
+}
+/** Run `fn` and collect the source cells written during it (back-writes included,
+ *  since a view write commits through its sources' `_writeSource`). */
+export function traceWrites(fn) {
+    const writes = [];
+    const restore = setCellWriteHook(c => {
+        writes.push(c);
+    });
+    try {
+        return { result: fn(), writes };
+    }
+    finally {
+        restore();
+    }
+}

package/dist/core/derived-geometry.js

@@ -1,10 +1,7 @@
-// derived-geometry.ts — read-only geometric readouts over `Cls.derive`.
-//
-// One-way derives whose inverse is genuinely under-determined (a point
-// sampled at parameter `t` constrains the curve at one point, but the
-// control points have many DOF). They live here, off the lens surface,
-// to keep `lenses/` exclusively bidirectional. For the writable bezier
-// shape decomposition see `bezierGestalt` in `lenses/domain-aggregates`.
+// Read-only geometric readouts over `Cls.derive`: one-way derives whose inverse
+// is under-determined (a point at parameter `t` pins the curve at one point, but
+// the control points keep many DOF). For the writable bezier decomposition see
+// `bezierGestalt` in `lenses/geometry`.
 import { Vec } from "./values/vec.js";
 /** Quadratic Bézier point at parameter `t`. RO. */
 export function bezier2(p0, p1, p2, t) {

package/dist/core/index.d.ts

@@ -1,9 +1,15 @@
-export { batch, Cell, type CellOptions, cachedDerive, cell, derive, effect, fieldLens, fieldOf, type Init, type Inner, isCell, isLens, isReadonly, lazy, lens, type Network, network, type Read, reader, readNow, SKIP, type Skip, type StatefulBwd, type StatefulLensSpec, setCellWriteHook, settle, transitiveDeps, untracked, type Val, type Writable, type WritableBrand, } from "./cell.js";
+export { type Counts, counts, resetCounts, snapshotCounts, withCounts } from "./_counts.js";
+export { batch, Cell, type CellOptions, cachedDerive, cell, derive, effect, fieldLens, fieldOf, type Init, type Inner, isCell, isLens, isReadonly, lazy, lens, type Network, network, type Optic, type Read, reader, readNow, SKIP, type Skip, type StatefulBwd, type StatefulBwd1, type StatefulLensSpec, type StatefulLensSpec1, setCellWriteHook, settle, transitiveDeps, untracked, type Val, type Writable, type WritableBrand, } from "./cell.js";
+export { type DumpOpts, dumpGraph, explain, kind as cellKind, label as cellLabel, traceWrites, upstream, } from "./debug.js";
 export { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each, type Lifecycle } from "./lifecycle.js";
+export { atKey, compose, iso, optic } from "./optic.js";
+export { at, fields } from "./optics.js";
+export { type Store, store } from "./store.js";
 export { type Equals, type Lerp, type Linear, type Metric, type Pack, type Pivotal, requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, type TraitDict, type Traits, } from "./traits.js";
 export { Anchor, Dir } from "./values/anchor.js";
+export { Arr, allPass, arr, type CellPred, type Group, GroupArr, is, } from "./values/arr.js";
 export { Audio, type AudioClip, audio, stamp as audioStamp } from "./values/audio.js";
 export { Bool, bool } from "./values/bool.js";
 export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
@@ -16,8 +22,9 @@ export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox,
 export { Num, num } from "./values/num.js";
 export { Pose, pose } from "./values/pose.js";
 export { Range, range, span } from "./values/range.js";
+export { type AltVal, type BindOpts, type Handle, type HandleKind, type HandleOf, Reg, type RegVal, type Silent, type StarVal, } from "./values/reg.js";
 export { Str, str } from "./values/str.js";
 export { type Codec, enumCodec, numCodec, route, type Slot, slot, strCodec, template, tpl, } from "./values/template.js";
 export { Transform, type TransformInit, transform } from "./values/transform.js";
 export { Tri, tri } from "./values/tri.js";
-export { type PolarPolicy, polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { tangentPoint, Vec, vec } from "./values/vec.js";

package/dist/core/index.js

@@ -1,9 +1,15 @@
+export { counts, resetCounts, snapshotCounts, withCounts } from "./_counts.js";
 export { batch, Cell, cachedDerive, cell, derive, effect, fieldLens, fieldOf, isCell, isLens, isReadonly, lazy, lens, network, reader, readNow, SKIP, setCellWriteHook, settle, transitiveDeps, untracked, } from "./cell.js";
+export { dumpGraph, explain, kind as cellKind, label as cellLabel, traceWrites, upstream, } from "./debug.js";
 export { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each } from "./lifecycle.js";
+export { atKey, compose, iso, optic } from "./optic.js";
+export { at, fields } from "./optics.js";
+export { store } from "./store.js";
 export { requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, } from "./traits.js";
 export { Anchor, Dir } from "./values/anchor.js";
+export { Arr, allPass, arr, GroupArr, is, } from "./values/arr.js";
 export { Audio, audio, stamp as audioStamp } from "./values/audio.js";
 export { Bool, bool } from "./values/bool.js";
 export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
@@ -16,8 +22,9 @@ export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox,
 export { Num, num } from "./values/num.js";
 export { Pose, pose } from "./values/pose.js";
 export { Range, range, span } from "./values/range.js";
+export { Reg, } from "./values/reg.js";
 export { Str, str } from "./values/str.js";
 export { enumCodec, numCodec, route, slot, strCodec, template, tpl, } from "./values/template.js";
 export { Transform, transform } from "./values/transform.js";
 export { Tri, tri } from "./values/tri.js";
-export { polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { tangentPoint, Vec, vec } from "./values/vec.js";

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

@@ -1,53 +1,43 @@
-import { type Writable } from "../cell.js";
-import { Num } from "../values/num.js";
-import { Vec } from "../values/vec.js";
-export interface ArgminOpts {
-    /** Finite-difference epsilon for the Jacobian. Default 1e-4. */
-    eps?: number;
-    /** Levenberg-Marquardt damping. Default `1e-6` for `argminNum`
-     *  (Jacobian is always well-conditioned for linear constraints) and
-     *  `1e-3` for `argminVec` (IK chains hit rank-deficient regimes at
-     *  full extension). Larger → smaller, more stable updates; smaller
-     *  → closer to pure pseudoinverse. */
-    damping?: number;
-}
-/** Target-shaping for `argminVec`: project a write into the reachable
- *  workspace before the Jacobian step, sidestepping the rank-deficient
- *  swings at the boundary. For an N-link chain rooted at `R` with reach
- *  `L`, pass `clampToDisc(R, L)`. */
-export interface ArgminVecOpts extends ArgminOpts {
-    /** Pre-write hook: transform the requested target into one that's
-     *  guaranteed solvable. Most useful as a workspace clamp. */
-    clampTarget?: (target: {
-        x: number;
-        y: number;
-    }, currentInputs: readonly number[]) => {
-        x: number;
-        y: number;
-    };
-}
-/** Project `p` into the closed disc of radius `r` centred on `c` (points
- *  inside pass through). Use as `argminVec`'s `clampTarget` to fix IK
- *  explosion at maximum reach. */
-export declare function clampToDisc(c: {
-    x: number;
-    y: number;
-}, r: number): (p: {
-    x: number;
-    y: number;
-}) => {
-    x: number;
-    y: number;
+import { type Cell, Num, type Read, type Traits, type Val, 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: reads the normalized
+ *  weighted sum `Σ wᵢ·aᵢ`, writes the minimum-norm delta back into the
+ *  branches (zero-weight branches untouched). Weights are read-only reactive
+ *  controls — a one-hot is `select`, a `(1−t, t)` edge is `crossfade`. */
+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 distance from the centroid (needs `Linear` + `Metric`); write scales
+ *  the cluster's deviations so the new mean matches. The complement carries
+ *  normalized deviations, so a collapse (spread → 0) reinflates the shape. */
+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>;
+};
+/** (a, b) → {mean: (a+b)/2, diff: a−b}. Square linear iso; each write is the
+ *  inverse change of basis, so mean and diff are cross-channel invariant. */
+export declare function meanDiff(a: Num, b: Num): {
+    mean: Writable<Num>;
+    diff: Writable<Num>;
+};
+/** Mean of N nums, clamped to `[lo, hi]` on read and write (writes are
+ *  clamped before the delta is distributed). */
+export declare function clampedMean(parents: readonly Num[], lo: number, hi: number): Writable<Num>;
+/** Num values as (i, valueᵢ) samples → {mean, slope}. Writing `mean` shifts
+ *  all values; writing `slope` (least-squares) tilts them about the mean.
+ *  Each preserves the other's reading. */
+export declare function timeSeries(values: readonly Writable<Num>[]): {
+    mean: Writable<Num>;
+    slope: Writable<Num>;
 };
-/** Scalar-output argmin lens: write does one Newton step against the FD
- *  Jacobian, distributing the residual by `weights`. For typed/multi-
- *  output cases use `factor()`; this M=1 path is kept for its hand-rolled
- *  inner loop. */
-export declare function argminNum(inputs: readonly Num[], forward: (xs: readonly number[]) => number, weights: readonly number[], opts?: ArgminOpts): Writable<Num>;
-/** 2D-output argmin lens (scalar Num inputs, `{x, y}` forward). For IK
- *  arms, draggable points, handle projection. Kept for its hand-rolled
- *  2×2 inverse + `clampTarget` hook; see `factor()` for other M. */
-export declare function argminVec(inputs: readonly Num[], forward: (xs: readonly number[]) => {
-    x: number;
-    y: number;
-}, weights: readonly number[], opts?: ArgminVecOpts): Writable<Vec>;