bireactive 0.2.4 → 0.3.1

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/lenses/typed-factor.js

@@ -14,6 +14,7 @@
 //   centroid.value = { x: 100, y: 50 };  // typed
 //
 // `bundle()` is the 1→M case: `factor()` over a single typed source.
+import { SKIP } from "../index.js";
 import { solveSPD } from "../linalg.js";
 function getPack(cell) {
     const ctor = cell.constructor;
@@ -163,7 +164,7 @@ export function factor(inputs, outputs, opts = {}) {
         }
         // 6. Solve A · k = δy in place (LDLᵀ; `dy` is overwritten with k).
         if (!solveSPD(A, dy, M)) {
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         }
         // 7. δx = W J^T k, applied to flatIn → produces new flat input vector.
         //    Then unpack per-input to typed updates.
@@ -187,7 +188,7 @@ export function factor(inputs, outputs, opts = {}) {
             }
             updates[k] = anyChange
                 ? inputPacks[k].write(flatIn, baseOff)
-                : undefined;
+                : SKIP;
         }
         return updates;
     };
@@ -211,7 +212,7 @@ export function factor(inputs, outputs, opts = {}) {
             for (let it = 0; it < maxIters; it++) {
                 const updates = computeBwd(idx, target, cur);
                 for (let i = 0; i < cur.length; i++) {
-                    if (updates[i] !== undefined)
+                    if (updates[i] !== SKIP)
                         cur[i] = updates[i];
                 }
                 outPack.read(spec.fwd(cur), currentBuf, 0);

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

@@ -49,6 +49,7 @@ export type TraitKey = keyof TraitDict<unknown>;
  *      function spring<T>(sig: Traits<T, "linear" | "metric">, target: Val<T>)
  *      function tween<T>(sig: Traits<T, "lerp">, target: T, dur: Val<number>) */
 export type Traits<T, K extends TraitKey = never> = {
+    /** @internal Phantom slot; never accessed at runtime. */
     readonly _t: {
         [P in K]-?: NonNullable<TraitDict<T>[P]>;
     } & TraitDict<T>;

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 };
             },
         });
     }

package/dist/core/values/box.js

@@ -3,7 +3,7 @@
 // Invertibles (`add`, `sub`, `scale`, `expand`) return `: this` and ride
 // on `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
 import { tween } from "../../animation/index.js";
-import { Cell, cachedDerive, field, isReadonly, lazy, reader, readNow, } from "../cell.js";
+import { Cell, cachedDerive, fieldLens, isReadonly, lazy, reader, readNow, SKIP, } from "../cell.js";
 import { Bool } from "./bool.js";
 import { Num, num } from "./num.js";
 import { Vec } from "./vec.js";
@@ -138,24 +138,24 @@ export class Box extends Cell {
                 return mk([this, p], vals => contains(vals[0], vals[1]), (target, vals) => {
                     const [b, v] = vals;
                     if (contains(b, v) === target)
-                        return [undefined, undefined];
-                    return [undefined, target ? clampToBox(v, b) : ejectFromBox(v, b)];
+                        return [SKIP, SKIP];
+                    return [SKIP, target ? clampToBox(v, b) : ejectFromBox(v, b)];
                 });
             }
         }
         return Bool.derive(() => contains(this.value, readNow(p)));
     }
     get x() {
-        return field(this, "x", Num);
+        return fieldLens(this, "x", Num);
     }
     get y() {
-        return field(this, "y", Num);
+        return fieldLens(this, "y", Num);
     }
     get w() {
-        return field(this, "w", Num);
+        return fieldLens(this, "w", Num);
     }
     get h() {
-        return field(this, "h", Num);
+        return fieldLens(this, "h", Num);
     }
     get area() {
         return cachedDerive(this, "area", Num, b => b.w * b.h);

package/dist/core/values/canvas.js

@@ -213,21 +213,20 @@ export class Canvas extends Cell {
             return c;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => chromaOf(s),
-            step: ([s], c, external) => (external ? chromaOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => chromaOf(s),
+            fwd: 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) => {
+            bwd: (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 { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }
@@ -244,21 +243,20 @@ export class Canvas extends Cell {
             return c;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => lumaOf(s),
-            step: ([s], c, external) => (external ? lumaOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => lumaOf(s),
+            fwd: 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) => {
+            bwd: (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 { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }
@@ -332,14 +330,13 @@ export class Canvas extends Cell {
             return res;
         };
         const self = this;
-        return Canvas.lens([self], {
-            init: ([s]) => residualOf(s),
-            step: ([s], c, external) => (external ? residualOf(s) : c),
-            fwd: ([s]) => {
+        return Canvas.lens(self, {
+            init: s => residualOf(s),
+            fwd: s => {
                 const small = down(sdF, s.tex, s.w, s.h);
                 return stamp(small.tex, small.w, small.h);
             },
-            bwd: (target, [s], c) => {
+            bwd: (target, s, c) => {
                 const up = suB(s.w, s.h);
                 pass(UP, up, x => {
                     x.tex("u_small", 0, target.tex);
@@ -351,7 +348,7 @@ export class Canvas extends Cell {
                     x.tex("u_a", 0, up.tex);
                     x.tex("u_b", 1, c.tex);
                 });
-                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+                return { update: stamp(out.tex, s.w, s.h), complement: c };
             },
         });
     }

package/dist/core/values/color.js

@@ -3,7 +3,7 @@
 // Invertibles (`add`, `sub`, `scale`) return `: this` and ride on
 // `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
 import { tween } from "../../animation/index.js";
-import { Cell, cachedDerive, derive, field, lazy, reader, readNow, } from "../cell.js";
+import { Cell, cachedDerive, derive, fieldLens, lazy, reader, readNow, } from "../cell.js";
 import { Num, num } from "./num.js";
 export const add = (a, b) => ({ r: a.r + b.r, g: a.g + b.g, b: a.b + b.b, a: a.a + b.a });
 export const sub = (a, b) => ({ r: a.r - b.r, g: a.g - b.g, b: a.b - b.b, a: a.a - b.a });
@@ -55,16 +55,16 @@ export class Color extends Cell {
         return Color.derive(() => lerp(this.value, readNow(b), readNow(t)));
     }
     get r() {
-        return field(this, "r", Num);
+        return fieldLens(this, "r", Num);
     }
     get g() {
-        return field(this, "g", Num);
+        return fieldLens(this, "g", Num);
     }
     get b() {
-        return field(this, "b", Num);
+        return fieldLens(this, "b", Num);
     }
     get a() {
-        return field(this, "a", Num);
+        return fieldLens(this, "a", Num);
     }
     get luminance() {
         return cachedDerive(this, "luminance", Num, c => 0.299 * c.r + 0.587 * c.g + 0.114 * c.b);

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

@@ -0,0 +1,70 @@
+import { Cell, type Read, type Val } from "../cell.js";
+import type { Pack } from "../traits.js";
+import { Canvas } from "./canvas.js";
+/** Field cell value: a GPU handle. The graph compares `epoch`. */
+export interface FieldVal {
+    readonly tex: WebGLTexture;
+    readonly w: number;
+    readonly h: number;
+    readonly epoch: number;
+}
+type Ctor<T> = new (...args: never[]) => Cell<T>;
+/** Texel encoding: channel count, the flat-buffer codec, and the boundary
+ *  cell class that reductions return. */
+export interface Kind<T> {
+    readonly dim: 1 | 2 | 4;
+    readonly pack: Pack<T>;
+    readonly cls: Ctor<T>;
+}
+/** Scalar field (1 channel) — heatmaps, SDFs, density, height. */
+export declare const Scalar: Kind<number>;
+/** Vector field (2 channels) — flow, gradient, displacement, RD chemicals. */
+export declare const Vector: Kind<{
+    x: number;
+    y: number;
+}>;
+/** Colour field (4 channels) — i.e. a Canvas. */
+export declare const Colour: Kind<{
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}>;
+/** A colormap stop: a field value mapped to an RGB triple (0–1). */
+export type ColorStop = readonly [number, readonly [number, number, number]];
+export declare class Field<T> extends Cell<FieldVal> {
+    readonly kind: Kind<T>;
+    static traits: {
+        equals: (a: FieldVal, b: FieldVal) => boolean;
+    };
+    readonly _t: typeof Field.traits;
+    /** Feedback-safe ping-pong pair for `evolve`/`splat`, lazily allocated. */
+    private io;
+    constructor(kind: Kind<T>, v?: FieldVal);
+    private pingTex;
+    /** Step the field by `steps` GPU passes of `frag` (which samples the current
+     *  field as `u_src`; `u_texel` = 1/size is provided). One value is committed
+     *  after the substeps, so the reactive graph sees a single new epoch/frame. */
+    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`. The
+     *  raster interaction primitive — seed a sim, inject, paint density. */
+    splat(x: number, y: number, r: number, value: T, strength?: number): void;
+    /** Whole-field mean as a read-only `T` cell. Reactive: recomputes on every
+     *  new epoch, propagates only when the value moves. One 1×1 GPU readback. */
+    mean(): Read<T>;
+    /** Mean over a sub-rectangle (data pixels, reactive `box`) as a read-only
+     *  `T` cell — the field's "density of this region" observation. */
+    regionMean(box: Val<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>): Read<T>;
+    /** Render `channel` through a colormap to a read-only `Canvas`. Reactive:
+     *  re-renders on every new epoch, so rendering is itself a reactive edge. */
+    colormap(channel: number, stops: readonly ColorStop[]): Canvas;
+}
+/** Writable `Field<T>` of size `w×h`. `painter` fills each texel (returns a
+ *  `T`); omit for an all-zero field. Linear-filtered for continuous sampling. */
+export declare function field<T>(kind: Kind<T>, w: number, h: number, painter?: (x: number, y: number) => T): Field<T>;
+export {};