bireactive 0.3.0 → 0.3.1

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/index.d.ts

@@ -1,7 +1,12 @@
-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 { Audio, type AudioClip, audio, stamp as audioStamp } from "./values/audio.js";

package/dist/core/index.js

@@ -1,7 +1,12 @@
+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 { Audio, audio, stamp as audioStamp } from "./values/audio.js";

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

@@ -383,9 +383,14 @@ export function pca(points) {
                     // the current axis length and is absorbed (cluster left put).
                     if (Math.abs(target) === c.lenThis)
                         return { updates: vals.map(() => SKIP), complement: c };
-                    // Non-degenerate fast path: scale current cluster along axis.
+                    // Non-degenerate fast path: scale current cluster along axis. The scale
+                    // sets the axis length to |target|, so the complement is consistent
+                    // without a post-write `step` (the engine no longer re-steps own writes).
                     const k = target / c.lenThis;
-                    return { updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k), complement: c };
+                    return {
+                        updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k),
+                        complement: { ...c, lenThis: Math.abs(target) },
+                    };
                 }
                 // Degenerate: reconstruct from complement. Centroid still
                 // derivable from current source (mean translates always work).
@@ -403,7 +408,7 @@ export function pca(points) {
                     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 };
+                return { updates: out, complement: { ...c, lenThis: Math.abs(target) } };
             },
         });
     };

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

@@ -4,4 +4,5 @@ export { bbox, meanDiff, procrustes } from "./decompositions.js";
 export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
 export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.js";
 export { type ContinuousOpts, continuous, type RememberOpts, remember, } from "./memory.js";
+export { type ClosestOpts, hullWeights, nearestIndex } from "./snap.js";
 export { bundle, type FactorOpts, type FactorResult, factor, factorTuple, type OutputSpec, type PackedInput, } from "./typed-factor.js";

package/dist/core/lenses/index.js

@@ -4,4 +4,5 @@ export { bbox, meanDiff, procrustes } from "./decompositions.js";
 export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
 export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.js";
 export { continuous, remember, } from "./memory.js";
+export { hullWeights, nearestIndex } from "./snap.js";
 export { bundle, factor, factorTuple, } from "./typed-factor.js";

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

@@ -0,0 +1,18 @@
+import { type Cell, type Read } from "../cell.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** Convex-hull barycentric weights of `q` over `pts` (Σ = 1, all ≥ 0,
+ *  clamped to the hull). Closed form for K ≤ 3; Frank–Wolfe for K > 3. */
+export declare function hullWeights(q: V, pts: readonly V[]): number[];
+export interface ClosestOpts {
+    /** Hysteresis margin (px): the current pick is kept until a rival is
+     *  nearer by more than this. Dragology's stickiness. Default 0. */
+    sticky?: number;
+}
+/** Index of the candidate nearest `pointer`, with hysteresis. Read-only
+ *  selection: the stickiness state lives in the lens complement (the
+ *  sanctioned place for path-dependence), so reads stay pure. */
+export declare function nearestIndex(pointer: Read<V>, candidates: readonly Read<V>[], opts?: ClosestOpts): Cell<number>;
+export {};

package/dist/core/lenses/snap.js

@@ -0,0 +1,145 @@
+// snap.ts — the pointer math the `d` drag algebra (shapes/drag-spec.ts) and the
+// demos build on. Candidate positions are live layout cells, so there's no
+// speculative re-render to recover them:
+//
+//   • hullWeights — barycentric weights of a point in the convex hull of K
+//     targets (closed form for K ≤ 3, Frank–Wolfe for K > 3). Powers
+//     `d.between`'s blend and any pointer-in-hull interpolation.
+//   • nearestIndex — the candidate nearest the pointer, with hysteresis. The
+//     "stickiness" lives in the lens complement (the sanctioned home for
+//     path-dependence), so reads stay pure.
+import { lens, SKIP } from "../cell.js";
+const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+const dot = (a, b) => a.x * b.x + a.y * b.y;
+const dist2 = (a, b) => {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy;
+};
+// ── convex-hull barycentric weights ─────────────────────────────────
+/** Project `q` onto segment p0→p1; weights `[1−t, t]`, t clamped to [0,1]. */
+function segmentWeights(q, p0, p1) {
+    const d = sub(p1, p0);
+    const len2 = dot(d, d);
+    if (len2 < 1e-18)
+        return [0.5, 0.5];
+    const t = Math.max(0, Math.min(1, dot(sub(q, p0), d) / len2));
+    return [1 - t, t];
+}
+/** Barycentric weights of `q` in triangle (p0,p1,p2), CLAMPED to the
+ *  triangle: inside → the true coords; outside → the nearest point on the
+ *  hull (an edge projection or a vertex), so the blend never extrapolates. */
+function triangleWeights(q, p0, p1, p2) {
+    const v0 = sub(p1, p0);
+    const v1 = sub(p2, p0);
+    const v2 = sub(q, p0);
+    const d00 = dot(v0, v0);
+    const d01 = dot(v0, v1);
+    const d11 = dot(v1, v1);
+    const d20 = dot(v2, v0);
+    const d21 = dot(v2, v1);
+    const denom = d00 * d11 - d01 * d01;
+    if (Math.abs(denom) > 1e-18) {
+        const b1 = (d11 * d20 - d01 * d21) / denom;
+        const b2 = (d00 * d21 - d01 * d20) / denom;
+        const b0 = 1 - b1 - b2;
+        if (b0 >= -1e-9 && b1 >= -1e-9 && b2 >= -1e-9) {
+            const s = b0 + b1 + b2;
+            return [b0 / s, b1 / s, b2 / s];
+        }
+    }
+    // Outside (or degenerate): nearest point on the three edges.
+    const e01 = segmentWeights(q, p0, p1);
+    const e12 = segmentWeights(q, p1, p2);
+    const e20 = segmentWeights(q, p2, p0);
+    const at01 = { x: p0.x * e01[0] + p1.x * e01[1], y: p0.y * e01[0] + p1.y * e01[1] };
+    const at12 = { x: p1.x * e12[0] + p2.x * e12[1], y: p1.y * e12[0] + p2.y * e12[1] };
+    const at20 = { x: p2.x * e20[0] + p0.x * e20[1], y: p2.y * e20[0] + p0.y * e20[1] };
+    const c = [
+        [dist2(q, at01), [e01[0], e01[1], 0]],
+        [dist2(q, at12), [0, e12[0], e12[1]]],
+        [dist2(q, at20), [e20[1], 0, e20[0]]],
+    ];
+    c.sort((a, b) => a[0] - b[0]);
+    return c[0][1];
+}
+/** Frank–Wolfe projection of `q` onto the convex hull of `pts` in
+ *  barycentric coordinates (used for K > 3). Minimises |Σ wᵢ·pᵢ − q|² over
+ *  the simplex; O(K·iters), plenty fast for the handful of targets a drag
+ *  ever offers. */
+function hullProjectWeights(q, pts, iters = 60) {
+    const K = pts.length;
+    const w = new Array(K).fill(1 / K);
+    for (let t = 0; t < iters; t++) {
+        let cx = 0;
+        let cy = 0;
+        for (let i = 0; i < K; i++) {
+            cx += w[i] * pts[i].x;
+            cy += w[i] * pts[i].y;
+        }
+        const rx = cx - q.x;
+        const ry = cy - q.y;
+        let best = 0;
+        let bestG = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < K; i++) {
+            const g = rx * pts[i].x + ry * pts[i].y;
+            if (g < bestG) {
+                bestG = g;
+                best = i;
+            }
+        }
+        const gamma = 2 / (t + 2);
+        for (let i = 0; i < K; i++)
+            w[i] = w[i] * (1 - gamma);
+        w[best] = w[best] + gamma;
+    }
+    return w;
+}
+/** Convex-hull barycentric weights of `q` over `pts` (Σ = 1, all ≥ 0,
+ *  clamped to the hull). Closed form for K ≤ 3; Frank–Wolfe for K > 3. */
+export function hullWeights(q, pts) {
+    const K = pts.length;
+    if (K === 0)
+        return [];
+    if (K === 1)
+        return [1];
+    if (K === 2)
+        return segmentWeights(q, pts[0], pts[1]);
+    if (K === 3)
+        return triangleWeights(q, pts[0], pts[1], pts[2]);
+    return hullProjectWeights(q, pts);
+}
+function pick(sources, prev, sticky) {
+    const p = sources[0];
+    let best = -1;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (let i = 1; i < sources.length; i++) {
+        const d = dist2(sources[i], p);
+        if (d < bestD) {
+            bestD = d;
+            best = i - 1;
+        }
+    }
+    if (sticky > 0 && prev >= 0 && prev + 1 < sources.length) {
+        const prevD = Math.sqrt(dist2(sources[prev + 1], p));
+        if (prevD - Math.sqrt(bestD) < sticky)
+            return prev;
+    }
+    return best;
+}
+/** Index of the candidate nearest `pointer`, with hysteresis. Read-only
+ *  selection: the stickiness state lives in the lens complement (the
+ *  sanctioned place for path-dependence), so reads stay pure. */
+export function nearestIndex(pointer, candidates, opts = {}) {
+    const sticky = opts.sticky ?? 0;
+    const parents = [pointer, ...candidates];
+    return lens(parents, {
+        init: (sources) => ({ index: pick(sources, -1, 0) }),
+        step: (sources, c) => ({ index: pick(sources, c.index, sticky) }),
+        fwd: (_sources, c) => c.index,
+        bwd: (_t, sources, c) => ({
+            updates: sources.map(() => SKIP),
+            complement: c,
+        }),
+    });
+}

package/dist/core/optic.d.ts

@@ -0,0 +1,13 @@
+import type { Optic } from "./cell.js";
+/** Build an optic from a forward and a backward. A 2-arg `put(b, a)` reads the
+ *  source; a 1-arg `put(b)` reconstructs it (and is treated as an `iso`). */
+export declare function optic<A, B>(get: (a: A) => B, put: (b: B, a: A) => A): Optic<A, B>;
+/** A lossless, source-independent optic (an isomorphism): `to`/`from` invert. */
+export declare function iso<A, B>(to: (a: A) => B, from: (b: B) => A): Optic<A, B>;
+/** Field optic: project key `K`, putting back with a spread-replace. */
+export declare function atKey<T, K extends keyof T>(key: K): Optic<T, T[K]>;
+/** Compose optics left-to-right into one: `compose(a, b, c)` is `a` then `b` then
+ *  `c`. Typed for up to three; falls back to `Optic<unknown, unknown>` beyond. */
+export declare function compose<A, B>(a: Optic<A, B>): Optic<A, B>;
+export declare function compose<A, B, C>(a: Optic<A, B>, b: Optic<B, C>): Optic<A, C>;
+export declare function compose<A, B, C, D>(a: Optic<A, B>, b: Optic<B, C>, c: Optic<C, D>): Optic<A, D>;

package/dist/core/optic.js

@@ -0,0 +1,44 @@
+// optic.ts — lenses as first-class values, independent of any `Cell`.
+//
+// A `Cell` lens binds a transform to a specific source. An `Optic<A, B>` is that
+// transform *unbound* — a pair of pure functions you can compose, store, and
+// hand around, then apply to a source with `cell.through(optic)` (≡ `lens(cell,
+// o.get, o.put)`). Composition is ordinary lens composition: `(f ∘ g).put(c, a) =
+// f.put(g.put(c, f.get(a)), a)`, so the inner source is reconstructed from `a` on
+// every back-write. An `iso` is the lossless special case whose `put` ignores the
+// source (`readsSource = false`), letting `through` bind a cheaper 1-arg backward.
+//
+// This is deliberately the pure/stateless slice of the lens algebra: no
+// complement, no effects. Stateful and effectful optics-as-values are future work
+// (see _notes); for now reach for `lens(parent, spec)` when you need a complement.
+//
+// The `Optic` type lives in cell.ts (so cell.ts stays import-free and its
+// `Cell.through` can name it); this module is the constructor/algebra surface.
+function make(get, put, readsSource) {
+    return {
+        get,
+        put,
+        readsSource,
+        through(next) {
+            // Composed backward reconstructs the inner B from the outer A, so it always
+            // reads the source regardless of either side's own `readsSource`.
+            return make(a => next.get(get(a)), (c, a) => put(next.put(c, get(a)), a), true);
+        },
+    };
+}
+/** Build an optic from a forward and a backward. A 2-arg `put(b, a)` reads the
+ *  source; a 1-arg `put(b)` reconstructs it (and is treated as an `iso`). */
+export function optic(get, put) {
+    return make(get, put, put.length >= 2);
+}
+/** A lossless, source-independent optic (an isomorphism): `to`/`from` invert. */
+export function iso(to, from) {
+    return make(to, b => from(b), false);
+}
+/** Field optic: project key `K`, putting back with a spread-replace. */
+export function atKey(key) {
+    return make(t => t[key], (v, t) => ({ ...t, [key]: v }), true);
+}
+export function compose(...optics) {
+    return optics.reduce((a, b) => a.through(b));
+}

package/dist/core/optics.d.ts

@@ -0,0 +1,10 @@
+import { Cell, type Read, type Writable } from "./cell.js";
+/** Writable field view of `c.value[key]` (spread-replace put). A read-only
+ *  parent yields a read-only view. */
+export declare function at<T, K extends keyof T>(c: Writable<Cell<T>>, key: K): Writable<Cell<T[K]>>;
+export declare function at<T, K extends keyof T>(c: Read<T>, key: K): Cell<T[K]>;
+/** Lens view of every field, lazily and memoized — `const { r, g, b } =
+ *  fields(rgb)` yields one writable `at` per key. */
+export declare function fields<T extends object>(c: Writable<Cell<T>>): {
+    [K in keyof T]-?: Writable<Cell<T[K]>>;
+};

package/dist/core/optics.js

@@ -0,0 +1,30 @@
+// optics.ts — plain-record field optics over a `Cell<T>`.
+//
+// `fieldOf` / `fieldLens` (cell.ts) project a value-class field and need the
+// field's Cell constructor, so `Vec.x` comes back as a typed `Num` carrying its
+// domain methods. For a plain record you just want `Cell<T[K]>` with the same
+// spread-replace put — `at` / `fields` supply that with full key inference and
+// no constructor argument. Both are thin sugar over `fieldOf` with the base
+// `Cell` as the result type.
+import { Cell, fieldOf } from "./cell.js";
+export function at(c, key) {
+    const ctor = Cell;
+    return fieldOf(c, key, ctor);
+}
+/** Lens view of every field, lazily and memoized — `const { r, g, b } =
+ *  fields(rgb)` yields one writable `at` per key. */
+export function fields(c) {
+    const cache = new Map();
+    return new Proxy(Object.create(null), {
+        get(_t, key) {
+            if (typeof key === "symbol")
+                return undefined;
+            let v = cache.get(key);
+            if (v === undefined) {
+                v = at(c, key);
+                cache.set(key, v);
+            }
+            return v;
+        },
+    });
+}

package/dist/core/store.d.ts

@@ -0,0 +1,10 @@
+import type { Cell, Writable } from "./cell.js";
+/** Deep store view: the cell itself, plus a `Store` per object field. Primitives
+ *  and functions bottom out at the plain `Writable<Cell<T>>`. */
+export type Store<T> = Writable<Cell<T>> & (T extends readonly any[] ? unknown : T extends (...args: any[]) => any ? unknown : T extends object ? {
+    [K in keyof T]-?: Store<T[K]>;
+} : unknown);
+/** Deep, lens-backed store view of `cell`. Field access returns a nested `Store`;
+ *  write through `.value` at any depth. Works over any writable cell, including a
+ *  lens, so the store stays one source of truth with the rest of the graph. */
+export declare function store<T>(cell: Writable<Cell<T>>): Store<T>;

package/dist/core/store.js

@@ -0,0 +1,85 @@
+// store.ts — a lens-backed deep store proxy over a `Cell`.
+//
+// Signal libraries grow a separate `store` primitive for nested objects:
+// `store.user.name` reads a path, `setStore(...)` writes one. Here that's just
+// field lenses (`at`) under a recursive proxy — no second reactive primitive, no
+// fine-grained store engine. `store(cell).a.b` is a `Cell` (a chain of `at`
+// lenses), so it composes with everything else: read `.value`, write `.value`,
+// pass it to a component, bind it in JSX. Writes are spread-replace puts straight
+// back to the root cell, so the whole tree stays one source of truth.
+//
+// Navigation yields Stores; the leaf is written through `.value`
+// (`store.user.name.value = "x"`). A property whose name collides with the cell
+// surface below (`value`, `peek`, `lens`, `derive`, `merge`, `through`) resolves
+// to the cell member, not a field — drop to `at(cell, key)` for such a field.
+import { at } from "./optics.js";
+// Cell members forwarded to the underlying cell rather than treated as a field,
+// plus the object protocol methods JS itself may touch.
+const FORWARD = new Set([
+    "value",
+    "peek",
+    "lens",
+    "derive",
+    "merge",
+    "through",
+    "toString",
+    "valueOf",
+    "toJSON",
+    "constructor",
+]);
+// One proxy per cell, so `store(c).a === store(c).a` and child stores are stable.
+const wrapped = new WeakMap();
+function wrap(cell) {
+    const hit = wrapped.get(cell);
+    if (hit !== undefined)
+        return hit;
+    // Per-key field lenses and their child stores, both memoized.
+    const lensFor = new Map();
+    const fieldLens = (key) => {
+        let l = lensFor.get(key);
+        if (l === undefined) {
+            l = at(cell, key);
+            lensFor.set(key, l);
+        }
+        return l;
+    };
+    const childStores = new Map();
+    const proxy = new Proxy(cell, {
+        get(target, key) {
+            if (typeof key === "symbol" || FORWARD.has(key)) {
+                const v = target[key];
+                return typeof v === "function" ? v.bind(target) : v;
+            }
+            if (key === "then")
+                return undefined; // never a thenable
+            let s = childStores.get(key);
+            if (s === undefined) {
+                s = wrap(fieldLens(key));
+                childStores.set(key, s);
+            }
+            return s;
+        },
+        set(target, key, value) {
+            if (typeof key === "symbol" || FORWARD.has(key)) {
+                target[key] = value;
+                return true;
+            }
+            fieldLens(key).value = value;
+            return true;
+        },
+        has(target, key) {
+            if (typeof key === "symbol" || FORWARD.has(key))
+                return true;
+            const v = target.peek();
+            return typeof v === "object" && v !== null && key in v;
+        },
+    });
+    wrapped.set(cell, proxy);
+    return proxy;
+}
+/** Deep, lens-backed store view of `cell`. Field access returns a nested `Store`;
+ *  write through `.value` at any depth. Works over any writable cell, including a
+ *  lens, so the store stays one source of truth with the rest of the graph. */
+export function store(cell) {
+    return wrap(cell);
+}

package/dist/core/values/audio.js

@@ -76,16 +76,15 @@ export class Audio extends Cell {
     normalize(target = 1) {
         const tf = reader(target);
         const self = this;
-        return Audio.lens([self], {
-            init: ([s]) => peak(s),
-            step: ([s], c, external) => (external ? peak(s) : c),
-            fwd: ([s]) => {
+        return Audio.lens(self, {
+            init: s => peak(s),
+            fwd: s => {
                 const p = peak(s);
                 return p === 0 ? s : scaled(s, tf() / p);
             },
             bwd: (view, _src, c) => {
                 const t = tf();
-                return { updates: [t === 0 ? view : scaled(view, c / t)], complement: c };
+                return { update: t === 0 ? view : scaled(view, c / t), complement: c };
             },
         });
     }