bireactive 0.2.4 → 0.3.0

package/dist/core/index.d.ts

@@ -1,33 +1,23 @@
-export { batch, Cell, type CellOptions, cachedDerive, cell, derive, effect, field, type Init, type Inner, isCell, isLens, isReadonly, lazy, lens, type Network, network, type Read, reader, readNow, type StatefulBwd, type StatefulLensSpec, setCellWriteHook, 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 Read, reader, readNow, SKIP, type Skip, type StatefulBwd, type StatefulLensSpec, setCellWriteHook, settle, transitiveDeps, untracked, type Val, type Writable, type WritableBrand, } from "./cell.js";
 export { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each, type Lifecycle } from "./lifecycle.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";
-export * as BoolMath from "./values/bool.js";
 export { Bool, bool } from "./values/bool.js";
-export * as BoxMath from "./values/box.js";
-export { Box, box } from "./values/box.js";
+export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
 export { Canvas, canvas, type Raster, stamp as canvasStamp } from "./values/canvas.js";
-export * as ColorMath from "./values/color.js";
 export { Color, rgb, rgba } from "./values/color.js";
+export { type ColorStop, Colour, Field, type FieldVal, field, type Kind as FieldKind, Scalar, Vector, } from "./values/field.js";
 export { Flags, flags } from "./values/flags.js";
 export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, type Tex, } from "./values/gpu.js";
-export * as MatrixMath from "./values/matrix.js";
-export { Matrix, matrix, transformBox, transformPoint } from "./values/matrix.js";
-export * as NumMath from "./values/num.js";
+export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
 export { Num, num } from "./values/num.js";
-export * as PoseMath from "./values/pose.js";
 export { Pose, pose } from "./values/pose.js";
-export * as RangeMath from "./values/range.js";
 export { Range, range, span } from "./values/range.js";
-export * as StrMath from "./values/str.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 * as TransformMath from "./values/transform.js";
 export { Transform, type TransformInit, transform } from "./values/transform.js";
-export * as TriMath from "./values/tri.js";
 export { Tri, tri } from "./values/tri.js";
-export * as VecMath from "./values/vec.js";
 export { type PolarPolicy, polar, tangentPoint, Vec, vec } from "./values/vec.js";

package/dist/core/index.js

@@ -1,33 +1,23 @@
-export { batch, Cell, cachedDerive, cell, derive, effect, field, isCell, isLens, isReadonly, lazy, lens, network, reader, readNow, setCellWriteHook, transitiveDeps, untracked, } from "./cell.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 { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each } from "./lifecycle.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";
-export * as BoolMath from "./values/bool.js";
 export { Bool, bool } from "./values/bool.js";
-export * as BoxMath from "./values/box.js";
-export { Box, box } from "./values/box.js";
+export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
 export { Canvas, canvas, stamp as canvasStamp } from "./values/canvas.js";
-export * as ColorMath from "./values/color.js";
 export { Color, rgb, rgba } from "./values/color.js";
+export { Colour, Field, field, Scalar, Vector, } from "./values/field.js";
 export { Flags, flags } from "./values/flags.js";
 export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, } from "./values/gpu.js";
-export * as MatrixMath from "./values/matrix.js";
-export { Matrix, matrix, transformBox, transformPoint } from "./values/matrix.js";
-export * as NumMath from "./values/num.js";
+export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
 export { Num, num } from "./values/num.js";
-export * as PoseMath from "./values/pose.js";
 export { Pose, pose } from "./values/pose.js";
-export * as RangeMath from "./values/range.js";
 export { Range, range, span } from "./values/range.js";
-export * as StrMath from "./values/str.js";
 export { Str, str } from "./values/str.js";
 export { enumCodec, numCodec, route, slot, strCodec, template, tpl, } from "./values/template.js";
-export * as TransformMath from "./values/transform.js";
 export { Transform, transform } from "./values/transform.js";
-export * as TriMath from "./values/tri.js";
 export { Tri, tri } from "./values/tri.js";
-export * as VecMath from "./values/vec.js";
 export { polar, tangentPoint, Vec, vec } from "./values/vec.js";

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

@@ -1,4 +1,4 @@
-import type { Writable } from "../cell.js";
+import { type Writable } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 export interface ArgminOpts {

package/dist/core/lenses/aggregates.js

@@ -5,6 +5,7 @@
 // All route through the engine's N-input lens path. Stateless-bwd
 // (`(target) => updates`) skips the peek loop on the hot path;
 // stateful-bwd (`(target, vals) => updates`) reads the scratch.
+import { SKIP } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 /** Project `p` into the closed disc of radius `r` centred on `c` (points
@@ -51,7 +52,7 @@ export function argminNum(inputs, forward, weights, opts = {}) {
         const k = dy / denom;
         for (let i = 0; i < n; i++) {
             if (weights[i] === 0) {
-                out[i] = undefined;
+                out[i] = SKIP;
             }
             else {
                 out[i] = xs[i] + weights[i] * J[i] * k;
@@ -103,7 +104,7 @@ export function argminVec(inputs, forward, weights, opts = {}) {
         if (Math.abs(det) < 1e-14) {
             // Singular; leave inputs unchanged.
             for (let i = 0; i < n; i++)
-                out[i] = undefined;
+                out[i] = SKIP;
             return out;
         }
         const invA = c / det;
@@ -114,7 +115,7 @@ export function argminVec(inputs, forward, weights, opts = {}) {
         for (let i = 0; i < n; i++) {
             const w = weights[i];
             if (w === 0) {
-                out[i] = undefined;
+                out[i] = SKIP;
             }
             else {
                 out[i] = xs[i] + w * (Jx[i] * kx + Jy[i] * ky);

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

@@ -10,7 +10,7 @@
 // (bestFitLine, bestFitCircle, pca, total). All exact, idempotent,
 // cross-channel invariant by construction, on the same `Cls.lens`
 // machinery — no engine changes.
-import { mean, Num, Vec, } from "../index.js";
+import { mean, Num, SKIP, Vec, } from "../index.js";
 import { continuous, remember } from "./memory.js";
 // Pivotal trait lookup via the value class's `static traits.pivotal` slot.
 // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
@@ -50,7 +50,7 @@ export function rotateAbout(points, pivot) {
         const rx0 = vals[0].x - p.x;
         const ry0 = vals[0].y - p.y;
         if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         }
         const oldθ = Math.atan2(ry0, rx0);
         const dθ = target - oldθ;
@@ -96,11 +96,11 @@ export function scaleAbout(points, pivot) {
             // 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(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const d0 = c.devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const k = target / r0;
             const out = vals.map((v, i) => ({
                 ...v,
@@ -299,7 +299,7 @@ export function pca(points) {
     const rotation = Num.lens(points, (vals) => decompose(vals)?.θ ?? 0, (target, vals) => {
         const d = decompose(vals);
         if (!d)
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         const dθ = target - d.θ;
         const cos = Math.cos(dθ);
         const sin = Math.sin(dθ);
@@ -382,7 +382,7 @@ export function pca(points) {
                     // 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(() => undefined), complement: c };
+                        return { updates: vals.map(() => SKIP), complement: c };
                     // Non-degenerate fast path: scale current cluster along axis.
                     const k = target / c.lenThis;
                     return { updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k), complement: c };

package/dist/core/lenses/decompositions.js

@@ -6,7 +6,7 @@
 // about the centroid), so cross-channel invariance is EXACT and one
 // write lands in O(K). For the generic numerical N→M escape hatch (when
 // no closed form fits) see `factor` in `typed-factor.ts`.
-import { Num, Vec } from "../index.js";
+import { Num, SKIP, Vec } from "../index.js";
 // meanDiff — M=2 isomorphism baseline.
 //
 // (a, b) → ((a+b)/2, a−b). Square full-rank linear lens; bwd is the
@@ -84,7 +84,7 @@ export function procrustes(points) {
         const ry0 = vals[0].y - cy;
         if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
             // Collapsed cluster; no angle to rotate from.
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         }
         const oldθ = Math.atan2(ry0, rx0);
         const dθ = target - oldθ;
@@ -130,7 +130,7 @@ export function procrustes(points) {
             const d0 = c.devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const k = target / r0;
             const out = c.devs.map(d => ({ x: cen.x + k * d.x, y: cen.y + k * d.y }));
             return { updates: out, complement: c };

package/dist/core/lenses/domain-aggregates.js

@@ -6,7 +6,7 @@
 //   (2) Bezier gestalt handles ({start, end, startTangent, endTangent}).
 //   (3) Time-series ({mean, slope}) over (i, value) samples.
 // All exact, idempotent, cross-channel invariant by construction.
-import { Num, reader, Vec, } from "../index.js";
+import { Num, reader, SKIP, Vec, } from "../index.js";
 import { remember } from "./memory.js";
 // Generic Linear-trait aggregates.
 //
@@ -107,9 +107,9 @@ export function mix(weights, branches) {
         const { w, sumSq } = readW();
         const delta = lin.sub(target, combine(vals, w));
         if (sumSq < 1e-12)
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         const inv = 1 / sumSq;
-        return vals.map((v, i) => w[i] === 0 ? undefined : lin.add(v, lin.scale(delta, w[i] * inv)));
+        return vals.map((v, i) => w[i] === 0 ? SKIP : lin.add(v, lin.scale(delta, w[i] * inv)));
     });
 }
 /** Two-branch router (mix simplex *vertex*): reads the live branch, writes
@@ -187,8 +187,8 @@ export function bezierGestalt(p0, p1, p2, p3) {
         const dy = target.y - vals[1].y;
         return [{ x: vals[0].x + dx, y: vals[0].y + dy }, target];
     });
-    const startTangent = Vec.lens([p0, p1], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [undefined, { x: vals[0].x + target.x, y: vals[0].y + target.y }]);
-    const endTangent = Vec.lens([p2, p3], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [{ x: vals[1].x - target.x, y: vals[1].y - target.y }, undefined]);
+    const startTangent = Vec.lens([p0, p1], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [SKIP, { x: vals[0].x + target.x, y: vals[0].y + target.y }]);
+    const endTangent = Vec.lens([p2, p3], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [{ x: vals[1].x - target.x, y: vals[1].y - target.y }, SKIP]);
     return { start, end, startTangent, endTangent };
 }
 // Time-series aggregates.

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

@@ -1,4 +1,4 @@
-import type { Cell, Read, Writable } from "../cell.js";
+import { type Cell, type Read, type Writable } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 type V = {

package/dist/core/lenses/geometry.js

@@ -1,5 +1,6 @@
 // geometry.ts — geometric lens building blocks over the N-input
 // `Cls.lens` / `Cls.derive` forms. All are a few lines on top of the engine.
+import { SKIP } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 import { rotateAbout } from "./closed-form-policies.js";
@@ -36,7 +37,7 @@ export function reflection(point, axisStart, axisEnd) {
         const projY = a.y + t * dy;
         return { x: 2 * projX - p.x, y: 2 * projY - p.y };
     };
-    return Vec.lens([point, axisStart, axisEnd], vals => reflect(vals[0], vals[1], vals[2]), (target, vals) => [reflect(target, vals[1], vals[2]), undefined, undefined]);
+    return Vec.lens([point, axisStart, axisEnd], vals => reflect(vals[0], vals[1], vals[2]), (target, vals) => [reflect(target, vals[1], vals[2]), SKIP, SKIP]);
 }
 /** Lerp between two Vecs at parameter `t`. Writing the interpolated point
  *  shifts both endpoints rigidly (preserving t). */
@@ -48,7 +49,7 @@ export function vecLerp(a, b, t) {
         const [av, bv, tv] = vals;
         const dx = target.x - (av.x + (bv.x - av.x) * tv);
         const dy = target.y - (av.y + (bv.y - av.y) * tv);
-        return [{ x: av.x + dx, y: av.y + dy }, { x: bv.x + dx, y: bv.y + dy }, undefined];
+        return [{ x: av.x + dx, y: av.y + dy }, { x: bv.x + dx, y: bv.y + dy }, SKIP];
     });
 }
 /** Sum of two nums; writing the sum splits the delta equally between
@@ -77,23 +78,21 @@ export function clampedMean(parents, lo, hi) {
     const n = parents.length;
     const inv = 1 / n;
     return Num.lens(parents, vals => {
-        const arr = vals;
         let s = 0;
         for (let i = 0; i < n; i++)
-            s += arr[i];
+            s += vals[i];
         const m = s * inv;
         return m < lo ? lo : m > hi ? hi : m;
     }, (target, vals) => {
-        const arr = vals;
         const clamped = target < lo ? lo : target > hi ? hi : target;
         let s = 0;
         for (let i = 0; i < n; i++)
-            s += arr[i];
+            s += vals[i];
         const cur = s * inv;
         const delta = clamped - cur;
         const out = new Array(n);
         for (let i = 0; i < n; i++)
-            out[i] = arr[i] + delta;
+            out[i] = vals[i] + delta;
         return out;
     });
 }

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

@@ -1,4 +1,4 @@
-import { type Cell, Num, type Traits, type Writable } from "../index.js";
+import { type Cell, Num, type Skip, type Traits, type Writable } from "../index.js";
 /** Options for {@link remember}. `anchor` is the fixed point sources scale
  *  about (a pivot, or the live centroid); `feature` is the writable scalar
  *  (a radius, mean distance, or sum). */
@@ -38,7 +38,7 @@ export interface ContinuousOpts<T> {
     };
     /** Realize `target` (already unwrapped, absolute) onto the sources,
      *  given the `current` unwrapped reading (for a delta). */
-    apply: (target: number, vals: readonly T[], current: number) => readonly (T | undefined)[];
+    apply: (target: number, vals: readonly T[], current: number) => readonly (T | Skip)[];
 }
 /** Continuous (winding-aware) lens over a cyclic reading. The complement
  *  tracks the last emitted value and unwraps each raw reading to the

package/dist/core/lenses/memory.js

@@ -15,7 +15,7 @@
 //                unwraps the raw reading to the nearest sheet, so the
 //                view never tears at a branch cut. Covers the eigenvector
 //                angle of bestFitLine; the primitive behind winding.
-import { Num } from "../index.js";
+import { Num, SKIP } from "../index.js";
 /** Scalar shape-memory lens. Reads `feature(sources)`; writing it scales
  *  the cluster about `anchor` so the new feature matches, reinflating the
  *  remembered shape when the cluster has collapsed onto the anchor. The
@@ -59,7 +59,7 @@ export function remember(sources, opts) {
             // 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(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             }
             if (f > eps) {
                 const k = target / f;
@@ -94,7 +94,7 @@ export function continuous(sources, opts) {
         bwd: (target, vals, c) => {
             const r = raw(vals);
             if (!r.defined)
-                return { updates: vals.map(() => undefined), complement: { prev: target } };
+                return { updates: vals.map(() => SKIP), complement: { prev: target } };
             const current = unwrap(r.value, c.prev);
             return { updates: apply(target, vals, current), complement: { prev: target } };
         },

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/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/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/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 {};