bireactive 0.3.4 → 0.3.5

package/dist/core/index.d.ts

@@ -1,10 +1,10 @@
 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 { 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, 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 { atKey, 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";

package/dist/core/index.js

@@ -4,7 +4,7 @@ export { dumpGraph, explain, kind as cellKind, label as cellLabel, traceWrites,
 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 { atKey, 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";

package/dist/core/lenses/memory.js

@@ -31,28 +31,29 @@ export function remember(sources, opts) {
     };
     // biome-ignore lint/suspicious/noExplicitAny: spec is checked structurally
     return Num.lens(sources, {
-        init: (vals) => {
+        complement: (vals) => {
             const a = anchor(vals);
             return { shape: shapeOf(vals, a, feature(vals, a), null) };
         },
-        step: (vals, c) => {
+        // `get` is the sole refresh: recompute the view and (idempotently) the shape.
+        get: (vals, c) => {
             const a = anchor(vals);
-            return { shape: shapeOf(vals, a, feature(vals, a), c.shape) };
+            const f = feature(vals, a);
+            c.shape = shapeOf(vals, a, f, c.shape);
+            return f;
         },
-        fwd: (vals) => feature(vals, anchor(vals)),
-        bwd: (target, vals, c) => {
+        put: (target, vals, c) => {
             const a = anchor(vals);
             const f = feature(vals, a);
             // Magnitude is lossy (|−f| = f): a same-magnitude target re-projects
             // to the current feature, so the cluster is left put.
-            if (magnitude && Math.abs(target) === f) {
-                return { updates: vals.map(() => SKIP), complement: c };
-            }
+            if (magnitude && Math.abs(target) === f)
+                return vals.map(() => SKIP);
             if (f > eps) {
                 const k = target / f;
-                return { updates: vals.map(v => lin.add(a, lin.scale(lin.sub(v, a), k))), complement: c };
+                return vals.map(v => lin.add(a, lin.scale(lin.sub(v, a), k)));
             }
-            return { updates: c.shape.map(s => lin.add(a, lin.scale(s, target))), complement: c };
+            return c.shape.map(s => lin.add(a, lin.scale(s, target)));
         },
     });
 }
@@ -66,24 +67,27 @@ export function continuous(sources, opts) {
     const unwrap = (rawv, prev) => prev + wrap(rawv - prev);
     // biome-ignore lint/suspicious/noExplicitAny: spec is checked structurally
     return Num.lens(sources, {
-        init: (vals) => {
+        complement: (vals) => {
             const r = raw(vals);
             return { prev: r.defined ? r.value : 0 };
         },
-        step: (vals, c) => {
+        // `get` is the sole refresh: unwrap relative to `prev` and accumulate the
+        // winding. Idempotent — once the source settles, `unwrap` is a fixpoint.
+        get: (vals, c) => {
             const r = raw(vals);
-            return r.defined ? { prev: unwrap(r.value, c.prev) } : c;
+            if (r.defined)
+                c.prev = unwrap(r.value, c.prev);
+            return c.prev;
         },
-        fwd: (vals, c) => {
+        put: (target, vals, c) => {
             const r = raw(vals);
-            return r.defined ? unwrap(r.value, c.prev) : c.prev;
-        },
-        bwd: (target, vals, c) => {
-            const r = raw(vals);
-            if (!r.defined)
-                return { updates: vals.map(() => SKIP), complement: { prev: target } };
+            if (!r.defined) {
+                c.prev = target;
+                return vals.map(() => SKIP);
+            }
             const current = unwrap(r.value, c.prev);
-            return { updates: apply(target, vals, current), complement: { prev: target } };
+            c.prev = target;
+            return apply(target, vals, current);
         },
     });
 }

package/dist/core/lenses/point-cloud.js

@@ -61,33 +61,37 @@ export function scaleAbout(points, pivot) {
     });
     // biome-ignore lint/suspicious/noExplicitAny: variance escape — spec is checked structurally
     return Num.lens(points, {
-        init: (vals) => {
+        complement: (vals) => {
             const p = pivot.peek();
             return { devs: vals.map(v => ({ x: v.x - p.x, y: v.y - p.y })) };
         },
-        step: (vals, c) => ({ devs: refresh(c.devs, vals, pivot.peek()) }),
-        fwd: (vals) => {
+        // `get` is the sole refresh: re-derive the offsets (idempotent on a settled
+        // source), then emit the radius.
+        get: (vals, c) => {
             const p = pivot.peek();
+            c.devs = refresh(c.devs, vals, p);
             return Math.hypot(vals[0].x - p.x, vals[0].y - p.y);
         },
-        bwd: (target, vals, c) => {
+        put: (target, vals, c) => {
             const p = pivot.peek();
             // Lossy magnitude view: |−r| = r, so a same-magnitude target
             // re-projects to the current radius and is absorbed (sources put).
             const rNow = Math.hypot(vals[0].x - p.x, vals[0].y - p.y);
             if (Math.abs(target) === rNow)
-                return { updates: vals.map(() => SKIP), complement: c };
-            const d0 = c.devs[0];
+                return vals.map(() => SKIP);
+            // Re-derive offsets from the live source (so a sibling move is reflected);
+            // the guard keeps the stored direction through a collapse.
+            const devs = (c.devs = refresh(c.devs, vals, p));
+            const d0 = devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => SKIP), complement: c };
+                return vals.map(() => SKIP);
             const k = target / r0;
-            const out = vals.map((v, i) => ({
+            return vals.map((v, i) => ({
                 ...v,
-                x: p.x + k * c.devs[i].x,
-                y: p.y + k * c.devs[i].y,
+                x: p.x + k * devs[i].x,
+                y: p.y + k * devs[i].y,
             }));
-            return { updates: out, complement: c };
         },
     });
 }
@@ -109,7 +113,7 @@ export function scaleAboutXY(points, pivot) {
         }));
     };
     return Vec.lens(points, {
-        init: (vals) => {
+        complement: (vals) => {
             const p = pivot.peek();
             const ox = vals[0].x - p.x;
             const oy = vals[0].y - p.y;
@@ -120,15 +124,19 @@ export function scaleAboutXY(points, pivot) {
                 })),
             };
         },
-        step: (vals, c) => ({ fracs: refresh(c.fracs, vals, pivot.peek()) }),
-        fwd: (vals) => {
+        // `get` is the sole refresh: re-derive the per-axis fractions, then emit
+        // point 0's offset from the pivot.
+        get: (vals, c) => {
             const p = pivot.peek();
+            c.fracs = refresh(c.fracs, vals, p);
             return { x: vals[0].x - p.x, y: vals[0].y - p.y };
         },
-        bwd: (target, _vals, c) => {
+        put: (target, vals, c) => {
             const p = pivot.peek();
-            const out = c.fracs.map(f => ({ x: p.x + f.x * target.x, y: p.y + f.y * target.y }));
-            return { updates: out, complement: c };
+            // Re-derive fractions from the live source (reflect a sibling move); the
+            // guard keeps the stored fraction through a per-axis collapse.
+            const fracs = (c.fracs = refresh(c.fracs, vals, p));
+            return fracs.map(f => ({ x: p.x + f.x * target.x, y: p.y + f.y * target.y }));
         },
     });
 }
@@ -318,7 +326,7 @@ export function pca(points) {
             return { uX: ux, uY: uy, vX: vx, vY: vy, lenThis, lenOther, projThis, projOther };
         };
         return Num.lens(points, {
-            init: (vals) => {
+            complement: (vals) => {
                 const seed = {
                     uX: 1,
                     uY: 0,
@@ -332,26 +340,30 @@ export function pca(points) {
                 const d = decompose(vals);
                 return d ? axisFrom(d, seed, vals) : seed;
             },
-            step: (vals, c) => {
+            // `get` is the sole refresh: recompute the axis frame (idempotent — the
+            // sign is pinned to the previous frame), then emit this axis's length.
+            get: (vals, c) => {
                 const d = decompose(vals);
-                return d ? axisFrom(d, c, vals) : c;
+                if (d)
+                    Object.assign(c, axisFrom(d, c, vals));
+                return d ? c.lenThis : 0;
             },
-            fwd: (vals, c) => (decompose(vals) ? c.lenThis : 0),
-            bwd: (target, vals, c) => {
+            put: (target, vals, c) => {
                 const d = decompose(vals);
+                // Re-derive the frame from the live source (reflect a sibling move); when
+                // collapsed (`!d`) the stored frame/projections are kept as the fallback.
+                if (d)
+                    Object.assign(c, axisFrom(d, c, vals));
                 if (d && c.lenThis > 1e-12) {
                     // Lossy magnitude view: a same-magnitude target re-projects to
                     // 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. 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).
+                        return vals.map(() => SKIP);
+                    // Non-degenerate fast path: scale current cluster along the axis.
                     const k = target / c.lenThis;
-                    return {
-                        updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k),
-                        complement: { ...c, lenThis: Math.abs(target) },
-                    };
+                    const out = scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k);
+                    c.lenThis = Math.abs(target);
+                    return out;
                 }
                 // Degenerate: reconstruct from complement. Centroid still
                 // derivable from current source (mean translates always work).
@@ -369,7 +381,8 @@ 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, lenThis: Math.abs(target) } };
+                c.lenThis = Math.abs(target);
+                return out;
             },
         });
     };
@@ -481,24 +494,27 @@ export function procrustes(points) {
         });
     };
     const scale = Num.lens(points, {
-        init: (vals) => {
+        complement: (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);
+        // `get` is the sole refresh: re-derive the centroid offsets, then emit the radius.
+        get: (vals, c) => {
+            const cen = centroidOf(vals);
+            c.devs = refreshDevs(c.devs, vals);
+            return Math.hypot(vals[0].x - cen.x, vals[0].y - cen.y);
         },
-        bwd: (target, vals, c) => {
+        put: (target, vals, c) => {
             const cen = centroidOf(vals);
-            const d0 = c.devs[0];
+            // Re-derive offsets from the live source (reflect a sibling move); the
+            // guard keeps the stored direction through a collapse to the centroid.
+            const devs = (c.devs = refreshDevs(c.devs, vals));
+            const d0 = devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => SKIP), complement: c };
+                return vals.map(() => SKIP);
             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 devs.map(d => ({ x: cen.x + k * d.x, y: cen.y + k * d.y }));
         },
     });
     return { centroid, rotation, scale };
@@ -556,7 +572,7 @@ export function bbox(points) {
         }));
     };
     const size = Vec.lens(points, {
-        init: (vals) => {
+        complement: (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;
@@ -567,17 +583,20 @@ export function bbox(points) {
                 })),
             };
         },
-        step: (vals, c) => ({ fracs: refreshFracs(c.fracs, vals) }),
-        fwd: (vals) => {
+        // `get` is the sole refresh: re-derive the half-size fractions, then emit the size.
+        get: (vals, c) => {
             const b = computeBox(vals);
+            c.fracs = refreshFracs(c.fracs, vals);
             return { x: b.sx, y: b.sy };
         },
-        bwd: (target, vals, c) => {
+        put: (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 };
+            // Re-derive fractions from the live source (reflect a sibling move); the
+            // guard keeps the stored fraction through a per-axis collapse.
+            const fracs = (c.fracs = refreshFracs(c.fracs, vals));
+            return fracs.map(f => ({ x: b.cx + f.x * halfTx, y: b.cy + f.y * halfTy }));
         },
     });
     return { center, size };

package/dist/core/lenses/snap.js

@@ -127,12 +127,13 @@ 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,
-        }),
+        complement: (sources) => ({ index: pick(sources, -1, 0) }),
+        // `get` is the sole refresh: re-pick with hysteresis from the current pick.
+        // Idempotent — re-running on a settled source keeps the same index.
+        get: (sources, c) => {
+            c.index = pick(sources, c.index, sticky);
+            return c.index;
+        },
+        put: (_t, sources, _c) => sources.map(() => SKIP),
     });
 }

package/dist/core/lenses/text.js

@@ -192,11 +192,13 @@ function buildCaseComplement(s) {
 export function caseFold(parent, to = "lower") {
     const fold = to === "upper" ? (s) => s.toUpperCase() : (s) => s.toLowerCase();
     return Str.lens(parent, {
-        init: (s) => buildCaseComplement(s),
-        fwd: (s) => fold(s),
-        bwd: (target, _s, c) => ({
-            update: applyCaseComplement(target, c),
-            complement: c,
-        }),
+        complement: (s) => buildCaseComplement(s),
+        // `get` is the sole refresh: re-derive the case complement from the source
+        // (pure ⇒ idempotent), then fold.
+        get: (s, c) => {
+            refreshCaseComplement(s, c);
+            return fold(s);
+        },
+        put: (target, _s, c) => applyCaseComplement(target, c),
     });
 }

package/dist/core/optic.d.ts

@@ -6,8 +6,3 @@ export declare function optic<A, B>(get: (a: A) => B, put: (b: B, a: A) => A): O
 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

@@ -1,39 +1,27 @@
-// Lenses as first-class values, independent of any `Cell`. An `Optic<A, B>` is a
-// lens transform *unbound* — a `get`/`put` pair you compose, store, and 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)`, reconstructing the inner source from `a` each back-write. An `iso` is the
-// lossless case whose `put` ignores the source (`readsSource = false`), so
-// `through` can bind a cheaper 1-arg backward. No complement here — use
-// `lens(parent, spec)` when you need one.
+// Lenses as first-class values, independent of any `Cell`. An `Optic<S, V>` is a
+// lens transform *unbound* — a `get`/`put` pair you store and apply to a source
+// with `cell.lens(optic)` / `lens(source, optic)`. Chain several by passing them to
+// one `lens(source, a, b, …)` call; the binder folds the chain by re-binding (its
+// `put` reconstructs the inner source on each back-write). An `iso` is the lossless
+// case whose `put` ignores the source (a 1-arg `put`). These constructors build the
+// *pure* (complement-free) optics; complement-carrying optics are plain objects with
+// a `complement` seed (see the Optic type and the stateful-lens header in cell.ts).
 //
-// The `Optic` type lives in cell.ts so that file 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);
-        },
-    };
-}
+// `optic.ts` imports only *types* from `cell.ts`, so `cell.ts` can apply optics by
+// re-binding without importing this module (no cycle).
 /** 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);
+    return { get, put: put };
 }
 /** A lossless, source-independent optic (an isomorphism): `to`/`from` invert. */
 export function iso(to, from) {
-    return make(to, b => from(b), false);
+    return { get: to, put: ((b) => from(b)) };
 }
 /** 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));
+    return {
+        get: (t) => t[key],
+        put: ((v, t) => ({ ...t, [key]: v })),
+    };
 }

package/dist/core/values/audio.js

@@ -61,14 +61,15 @@ export class Audio extends Cell {
         const tf = reader(target);
         const self = this;
         return Audio.lens(self, {
-            init: s => peak(s),
-            fwd: s => {
-                const p = peak(s);
+            complement: (s) => ({ peak: peak(s) }),
+            // `get` is the sole refresh: re-measure the source peak (pure ⇒ idempotent).
+            get: (s, c) => {
+                const p = (c.peak = peak(s));
                 return p === 0 ? s : scaled(s, tf() / p);
             },
-            bwd: (view, _src, c) => {
+            put: (view, _src, c) => {
                 const t = tf();
-                return { update: t === 0 ? view : scaled(view, c / t), complement: c };
+                return t === 0 ? view : scaled(view, c.peak / t);
             },
         });
     }

package/dist/core/values/canvas.js

@@ -189,19 +189,22 @@ export class Canvas extends Cell {
         };
         const self = this;
         return Canvas.lens(self, {
-            init: s => chromaOf(s),
-            fwd: s => {
+            complement: (s) => chromaOf(s),
+            // `get` is the sole refresh: re-run the chroma pass into the complement
+            // tex (pure GPU pass ⇒ idempotent), then emit the luma view.
+            get: (s, c) => {
+                Object.assign(c, chromaOf(s));
                 const out = sf(s.w, s.h);
                 pass(LUMA, out, x => x.tex("u_s", 0, s.tex));
                 return stamp(out.tex, s.w, s.h);
             },
-            bwd: (target, s, c) => {
+            put: (target, s, c) => {
                 const out = sb(s.w, s.h);
                 pass(RECOLOR, out, x => {
                     x.tex("u_t", 0, target.tex);
                     x.tex("u_c", 1, c.tex);
                 });
-                return { update: stamp(out.tex, s.w, s.h), complement: c };
+                return stamp(out.tex, s.w, s.h);
             },
         });
     }
@@ -218,19 +221,21 @@ export class Canvas extends Cell {
         };
         const self = this;
         return Canvas.lens(self, {
-            init: s => lumaOf(s),
-            fwd: s => {
+            complement: (s) => lumaOf(s),
+            // `get` is the sole refresh: re-run the luma pass into the complement tex.
+            get: (s, c) => {
+                Object.assign(c, lumaOf(s));
                 const out = sf(s.w, s.h);
                 pass(CHROMA_VIEW, out, x => x.tex("u_s", 0, s.tex));
                 return stamp(out.tex, s.w, s.h);
             },
-            bwd: (target, s, c) => {
+            put: (target, s, c) => {
                 const out = sb(s.w, s.h);
                 pass(DELUMA, out, x => {
                     x.tex("u_t", 0, target.tex);
                     x.tex("u_c", 1, c.tex);
                 });
-                return { update: stamp(out.tex, s.w, s.h), complement: c };
+                return stamp(out.tex, s.w, s.h);
             },
         });
     }
@@ -305,12 +310,15 @@ export class Canvas extends Cell {
         };
         const self = this;
         return Canvas.lens(self, {
-            init: s => residualOf(s),
-            fwd: s => {
+            complement: (s) => residualOf(s),
+            // `get` is the sole refresh: recompute the Laplacian residual (pure ⇒
+            // idempotent), then emit the box-downsampled thumbnail.
+            get: (s, c) => {
+                Object.assign(c, residualOf(s));
                 const small = down(sdF, s.tex, s.w, s.h);
                 return stamp(small.tex, small.w, small.h);
             },
-            bwd: (target, s, c) => {
+            put: (target, s, c) => {
                 const up = suB(s.w, s.h);
                 pass(UP, up, x => {
                     x.tex("u_small", 0, target.tex);
@@ -322,7 +330,7 @@ export class Canvas extends Cell {
                     x.tex("u_a", 0, up.tex);
                     x.tex("u_b", 1, c.tex);
                 });
-                return { update: stamp(out.tex, s.w, s.h), complement: c };
+                return stamp(out.tex, s.w, s.h);
             },
         });
     }

package/dist/core/values/field.d.ts

@@ -48,6 +48,8 @@ export declare class Field<T> extends Cell<FieldVal> {
     evolve(frag: string, uniforms?: Record<string, number | readonly number[]>, steps?: number): void;
     /** Stamp a Gaussian disc of `value` at data pixel `(x, y)`, radius `r`. */
     splat(x: number, y: number, r: number, value: T, strength?: number): void;
+    /** Fill a hard-edged rectangle `(x, y, w, h)` in data pixels with `value`. */
+    fillRect(x: number, y: number, w: number, h: number, value: T, strength?: number): void;
     /** Whole-field mean as a read-only `T` cell. Recomputes per epoch; one 1×1
      *  GPU readback. */
     mean(): Read<T>;

package/dist/core/values/field.js

@@ -44,6 +44,15 @@ void main() {
   float f = clamp(exp(-(d * d) / (u_r * u_r)) * u_mix, 0.0, 1.0);
   o = vec4(mix(s.rgb, u_v, f), s.a);
 }`;
+const FILL_RECT = `${HEAD}
+uniform sampler2D u_src; uniform vec2 u_res; uniform vec2 u_o; uniform vec2 u_wh;
+uniform vec3 u_v; uniform float u_mix;
+void main() {
+  vec2 px = v_uv * u_res;
+  bool inside = px.x >= u_o.x && px.y >= u_o.y && px.x < u_o.x + u_wh.x && px.y < u_o.y + u_wh.y;
+  vec4 s = texture(u_src, v_uv);
+  o = inside ? vec4(mix(s.rgb, u_v, u_mix), s.a) : s;
+}`;
 /** GLSL float literal (always carries a decimal point). */
 const glf = (n) => (Number.isInteger(n) ? `${n}.0` : String(n));
 const glv3 = (c) => `${glf(c[0])}, ${glf(c[1])}, ${glf(c[2])}`;
@@ -144,6 +153,22 @@ export class Field extends Cell {
         });
         this.value = stamp(dst.tex, v.w, v.h);
     }
+    /** Fill a hard-edged rectangle `(x, y, w, h)` in data pixels with `value`. */
+    fillRect(x, y, w, h, value, strength = 1) {
+        const ping = this.pingTex();
+        const v = this.peek();
+        this.kind.pack.read(value, TMP, 0);
+        const dst = ping(v.w, v.h, v.tex);
+        pass(FILL_RECT, dst, s => {
+            s.tex("u_src", 0, v.tex);
+            s.v2("u_res", v.w, v.h);
+            s.v2("u_o", x, y);
+            s.v2("u_wh", w, h);
+            s.v3("u_v", TMP[0], TMP[1], TMP[2]);
+            s.f("u_mix", strength);
+        });
+        this.value = stamp(dst.tex, v.w, v.h);
+    }
     /** Whole-field mean as a read-only `T` cell. Recomputes per epoch; one 1×1
      *  GPU readback. */
     mean() {

package/dist/core/values/reg.d.ts

@@ -190,9 +190,8 @@ export declare class Reg<V = RegVal, N extends boolean = boolean, F extends Boun
     /** This grammar as a first-class, composable `Optic<string, V>`: `get`
      *  parses (falling back to the default value off-language), `put` reprints
      *  and round-trip-guards (an off-language source or a non-round-tripping
-     *  value leaves the source untouched). Drops straight into `compose(...)`
-     *  and `cell.through(...)`, so it chains with `atKey`/`iso` and string
-     *  lenses like `caseFold`. */
+     *  value leaves the source untouched). Drops straight into `cell.lens(...)`,
+     *  so it chains with `atKey`/`iso` and string lenses like `caseFold`. */
     optic(): Optic<string, V>;
     /** The whole abstract value as a writable lens over `source`. */
     view(source: Cell<string>): Writable<Cell<V>>;

package/dist/core/values/reg.js

@@ -465,9 +465,8 @@ export class Reg {
     /** This grammar as a first-class, composable `Optic<string, V>`: `get`
      *  parses (falling back to the default value off-language), `put` reprints
      *  and round-trip-guards (an off-language source or a non-round-tripping
-     *  value leaves the source untouched). Drops straight into `compose(...)`
-     *  and `cell.through(...)`, so it chains with `atKey`/`iso` and string
-     *  lenses like `caseFold`. */
+     *  value leaves the source untouched). Drops straight into `cell.lens(...)`,
+     *  so it chains with `atKey`/`iso` and string lenses like `caseFold`. */
     optic() {
         const def = defaultVal(this.root);
         return optic((s) => (this.match(s) ?? def), (v, s) => {
@@ -479,7 +478,7 @@ export class Reg {
     }
     /** The whole abstract value as a writable lens over `source`. */
     view(source) {
-        return source.through(this.optic());
+        return source.lens(this.optic());
     }
     bind(source, opts = {}) {
         const captures = new Map();