bireactive 0.3.0 → 0.3.2

package/dist/core/values/box.js

@@ -1,7 +1,3 @@
-// box.ts — reactive axis-aligned rectangle.
-//
-// 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, fieldLens, isReadonly, lazy, reader, readNow, SKIP, } from "../cell.js";
 import { Bool } from "./bool.js";
@@ -17,7 +13,7 @@ export const lerp = (a, b, t) => ({
     h: a.h + (b.h - a.h) * t,
 });
 export const equals = (a, b) => a === b || (a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h);
-/** L2 distance over the flat (x, y, w, h) representation. */
+/** Euclidean distance over (x, y, w, h). */
 export const metric = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.w - b.w, a.h - b.h);
 export const expand = (b, n) => ({
     x: b.x - n,
@@ -26,15 +22,14 @@ export const expand = (b, n) => ({
     h: b.h + 2 * n,
 });
 export const contains = (b, p) => p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h;
-/** Closest point inside `b` to `p`. Already-inside is identity; outside
- *  snaps to the nearest boundary point. `Box#contains`'s true-side bwd. */
+/** Closest point inside `b` to `p`; already-inside is identity, outside snaps
+ *  to the nearest boundary point. */
 export const clampToBox = (p, b) => ({
     x: Math.max(b.x, Math.min(b.x + b.w, p.x)),
     y: Math.max(b.y, Math.min(b.y + b.h, p.y)),
 });
-/** Closest point strictly outside `b` to `p`, displaced past the nearest
- *  edge by `eps`. Already-outside is identity. `Box#contains`'s
- *  false-side bwd. */
+/** Closest point strictly outside `b` to `p`, displaced past the nearest edge
+ *  by `eps`; already-outside is identity. */
 export const ejectFromBox = (p, b, eps = 1e-6) => {
     if (!contains(b, p))
         return p;
@@ -70,7 +65,7 @@ export function union(...bs) {
     }
     return { x: xMin, y: yMin, w: xMax - xMin, h: yMax - yMin };
 }
-/** Perimeter point on a Box facing `toward`. Default `Shape.boundary`. */
+/** Perimeter point on a box facing `toward`. */
 export function edgeFrom(b, toward) {
     const cx = b.x + b.w / 2;
     const cy = b.y + b.h / 2;
@@ -122,18 +117,16 @@ export class Box extends Cell {
     lerp(b, t) {
         return Box.derive(() => lerp(this.value, readNow(b), readNow(t)));
     }
-    /** Membership predicate. Conditional return type: a writable `Vec`
-     *  yields `Writable<Bool>` and flipping the view moves the source —
-     *  `true` clamps to the nearest in-box point, `false` ejects past the
-     *  nearest edge by `eps`. Literal / RO inputs yield a bare RO `Bool`. */
+    /** True when `p` is inside the box. A writable `Vec` yields a `Writable<Bool>`:
+     *  flipping it clamps `p` to the nearest in-box point (`true`) or ejects it
+     *  past the nearest edge (`false`). Literal/RO inputs yield a read-only `Bool`. */
     contains(p) {
         if (p instanceof Vec) {
-            // A read-only Vec has no backward path → RO branch; sources and
-            // writable lenses accept write-back.
+            // RO Vec has no backward path; only writable Vecs accept write-back.
             if (!isReadonly(p)) {
-                // `.bind(Bool)` + cast steps past the generic overloads, whose
-                // mapped-tuple inference over the full class types otherwise blows
-                // the instantiation depth.
+                // `.bind(Bool)` + cast sidesteps the generic overloads, whose
+                // mapped-tuple inference over the full class types blows the
+                // instantiation depth.
                 const mk = Bool.lens.bind(Bool);
                 return mk([this, p], vals => contains(vals[0], vals[1]), (target, vals) => {
                     const [b, v] = vals;
@@ -160,15 +153,12 @@ export class Box extends Cell {
     get area() {
         return cachedDerive(this, "area", Num, b => b.w * b.h);
     }
-    /** Vec at parametric (u, v) within `[0,1]²`. Not memoised (arbitrary
-     *  pairs would leak a cache entry each) — use the named edge getters
-     *  (`.center`, `.top`, …) for stable identity. */
+    /** Vec at parametric `(u, v)` in `[0,1]²`. Not memoised; use the named edge
+     *  getters (`.center`, `.top`, …) for stable identity. */
     at(u, v) {
         return Vec.derive(this, b => ({ x: b.x + u * b.w, y: b.y + v * b.h }));
     }
-    // Named edges — RO views over `at(u, v)`, memoised under stable keys
-    // so subscribers always see the same Vec. `lazy()` directly since
-    // `at()` already returns a Vec.
+    // Named edges: memoised views over `at(u, v)` with stable identity.
     get center() {
         return lazy(this, "center", () => this.at(0.5, 0.5));
     }
@@ -184,16 +174,14 @@ export class Box extends Cell {
     get right() {
         return lazy(this, "right", () => this.at(1, 0.5));
     }
-    /** Tween-builder, implied by the lerp trait. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** Writable `Box` at `(x, y, w, h)`. Each component is a literal `number`
- *  (lifted to a fresh seed) or an existing `Writable<Num>` (identity
- *  passthrough). RO sources are rejected at the type level — use
- *  `Box.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. Lock a component with `Num.pin(c)`. */
+/** Writable `Box` at `(x, y, w, h)`. Each component is a literal (new cell) or
+ *  existing writable (passed through); for read-only sources use `Box.derive`.
+ *  Lock a component with `Num.pin`. */
 export function box(x = 0, y = 0, w = 0, h = 0) {
     if (typeof x === "number" &&
         typeof y === "number" &&
@@ -205,6 +193,5 @@ export function box(x = 0, y = 0, w = 0, h = 0) {
     const yN = num(y);
     const wN = num(w);
     const hN = num(h);
-    // The view fully reconstructs all 4 axes (1-arg bwd ⇒ no source read).
     return Box.lens([xN, yN, wN, hN], ([bx, by, bw, bh]) => ({ x: bx, y: by, w: bw, h: bh }), v => [v.x, v.y, v.w, v.h]);
 }

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

@@ -3,8 +3,8 @@ import { Bool } from "./bool.js";
 import { Color } from "./color.js";
 import { Spring, type SpringOpts } from "./gpu.js";
 import { Vec } from "./vec.js";
-/** Raster header. The graph compares `epoch`; `tex` is an RGBA32F texture in
- *  the shared GL context (channels 0–1, may overshoot mid-deconvolution). */
+/** Raster header; the graph compares `epoch`. `tex` is an RGBA32F texture in
+ *  the shared GL context. */
 export interface Raster {
     readonly tex: WebGLTexture;
     readonly w: number;
@@ -21,20 +21,18 @@ export declare class Canvas extends Cell<V> {
     };
     readonly _t: typeof Canvas.traits;
     constructor(v?: V);
-    /** Per-channel invert (alpha preserved). Involution. */
+    /** Per-channel invert (alpha preserved). */
     invert(): this;
-    /** Horizontal flip. Involution. */
+    /** Horizontal flip. */
     flipH(): this;
     /** Multiply RGB by reactive `k` (alpha preserved). Invertible while
      *  k ≠ 0. */
     brightness(k: Val<number>): this;
-    /** Grayscale (Rec.601 luma) view; complement is the per-pixel chroma
-     *  residual `(r−Y, g−Y, b−Y)`, so editing the gray view recolours the
-     *  source. The raster analog of `str.lowercase()`. */
+    /** Grayscale (Rec.601 luma) view; the complement is the per-pixel chroma
+     *  residual `(r−Y, g−Y, b−Y)`, so editing the gray view recolours the source. */
     grayscale(): Writable<Canvas>;
-    /** Chroma view (the dual of `grayscale`): `(r−Y, g−Y, b−Y)` on a mid-grey
-     *  base, complement is the luma `Y`. Editing the colour re-lights nothing —
-     *  it rewrites hue while keeping the original brightness. */
+    /** Chroma view: `(r−Y, g−Y, b−Y)` on a mid-grey base, complement is the luma
+     *  `Y`. Editing it rewrites hue while keeping the original brightness. */
     chroma(): Writable<Canvas>;
     /** Sub-rectangle view (reactive `x,y,w,h`). Editing the crop composites
      *  back into the source; the surround reads straight from the parent. */
@@ -43,26 +41,21 @@ export declare class Canvas extends Cell<V> {
      *  Laplacian residual `source − up(down(source))`; editing the thumbnail
      *  reconstructs full-res detail on top of the edit. */
     downsample(factor: number): Writable<Canvas>;
-    /** Gaussian blur (reactive `radius`). Writable: the backward direction
-     *  runs an iterated Richardson–Lucy deconvolution seeded from the source.
-     *  Each step is `x ← x · H(target / H(x))`, non-negative and multiplicative,
-     *  so untouched regions stay fixed (their ratio is 1) while a stroke
-     *  back-solves to a sharp pre-image with far less ringing than an additive
-     *  solve. PutGet, not exact GetPut — the residual is the honest signature
-     *  of an ill-posed inverse. */
+    /** Gaussian blur (reactive `radius`). The backward pass runs an iterated
+     *  Richardson–Lucy deconvolution seeded from the source
+     *  (`x ← x · H(target / H(x))`), so untouched regions stay fixed. PutGet,
+     *  not exact GetPut. */
     blur(radius: Val<number>): this;
-    /** Mean colour (0–1) as a writable `Color`; the GPU reduces, the write
-     *  shifts every pixel by the delta (a rigid translate in RGB). */
+    /** Mean colour (0–1) as a writable `Color`; the GPU reduces, a write shifts
+     *  every pixel by the delta. */
     meanColor(): Writable<Color>;
-    /** Mean luma ≥ reactive `threshold` (0–1) as a writable `Bool`; flipping
-     *  the bit auto-exposes — iterate the gain (clipping caps a single step)
-     *  until the mean crosses the line. */
+    /** Mean luma ≥ `threshold` (0–1) as a writable `Bool`; flipping the bit
+     *  auto-exposes by iterating the gain until the mean crosses the threshold. */
     brighterThan(threshold: Val<number>): Writable<Bool>;
     /** Dimensions `(w, h)` as a read-only `Vec`. */
     get dimensions(): Vec;
-    /** A GPU per-pixel spring driver seeded from this value's texture. The
-     *  host steps it and writes `current()` back into a root cell each frame;
-     *  settle is the GPU energy reduction. */
+    /** GPU per-pixel spring driver seeded from this value's texture. The host
+     *  steps it and writes `current()` back each frame. */
     spring(opts?: SpringOpts): Spring;
 }
 /** Writable `Canvas` of size `w×h`. `painter` fills it pixel-by-pixel

package/dist/core/values/canvas.js

@@ -1,25 +1,3 @@
-// canvas.ts — GPU-resident reactive raster (handle-as-value).
-//
-// Every Canvas value is a float texture in the shared WebGL2 context (see
-// gpu.ts); the reactive graph transports only a tiny HEADER {tex, w, h,
-// epoch}, comparing the monotonic epoch, so propagation never reads a pixel
-// and nothing is copied across the bus. Forward lenses render into a per-lens
-// scratch texture (reused across recomputes); the single ownership rule that
-// keeps no-copy safe is the same as on the CPU — a node writes only its own
-// texture, never one another live node still reads, which holds under the
-// engine's glitch-free flush.
-//
-// Tiers mirror the rest of values/:
-//   - pure isomorphisms (`invert`, `flipH`) — one pointwise shader each way.
-//   - reactive-param invertibles (`brightness(k)`) — read `Val<number>`.
-//   - complement projections (`grayscale`, `downsample`) — the lossy view
-//     plus a complement texture (chroma / Laplacian residual) recovered on
-//     write-back, the raster analog of str.ts's case-preserving lenses.
-//   - cross-type lenses (`meanColor` → Color, `brighterThan` → Bool).
-//
-// A backward pass that produces a ROOT cell's next value reads that root and
-// writes a result that becomes its value, so it uses `scratch2` (a feedback-
-// safe pair) to avoid reading and writing the same texture.
 import { Cell, cachedDerive, reader } from "../cell.js";
 import { Bool } from "./bool.js";
 import { Color } from "./color.js";
@@ -98,9 +76,7 @@ void main() {
   o = vec4(acc / wsum, a);
 }`;
 // Richardson–Lucy step. RL_RATIO forms target / blur(estimate) (guarded);
-// RL_MUL multiplies the estimate by blur(ratio) and clamps to [0,1]. Both
-// the non-negativity clamp and the multiplicative form keep ringing far
-// below an additive Van-Cittert iteration.
+// RL_MUL multiplies the estimate by blur(ratio) and clamps to [0,1].
 const RL_RATIO = `${HEAD}
 uniform sampler2D u_t; uniform sampler2D u_est;
 void main() {
@@ -162,7 +138,7 @@ export class Canvas extends Cell {
     constructor(v = { tex: null, w: 0, h: 0, epoch: 0 }) {
         super(v, { equals });
     }
-    /** Per-channel invert (alpha preserved). Involution. */
+    /** Per-channel invert (alpha preserved). */
     invert() {
         const sf = scratch();
         const sb = scratch();
@@ -173,7 +149,7 @@ export class Canvas extends Cell {
         };
         return this.lens(run(sf), run(sb));
     }
-    /** Horizontal flip. Involution. */
+    /** Horizontal flip. */
     flipH() {
         const sf = scratch();
         const sb = scratch();
@@ -200,9 +176,8 @@ export class Canvas extends Cell {
         };
         return this.lens(run(sf, () => kf()), run(sb, () => 1 / kf()));
     }
-    /** Grayscale (Rec.601 luma) view; complement is the per-pixel chroma
-     *  residual `(r−Y, g−Y, b−Y)`, so editing the gray view recolours the
-     *  source. The raster analog of `str.lowercase()`. */
+    /** Grayscale (Rec.601 luma) view; the complement is the per-pixel chroma
+     *  residual `(r−Y, g−Y, b−Y)`, so editing the gray view recolours the source. */
     grayscale() {
         const sc = scratch();
         const sf = scratch();
@@ -213,27 +188,25 @@ 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 };
             },
         });
     }
-    /** Chroma view (the dual of `grayscale`): `(r−Y, g−Y, b−Y)` on a mid-grey
-     *  base, complement is the luma `Y`. Editing the colour re-lights nothing —
-     *  it rewrites hue while keeping the original brightness. */
+    /** Chroma view: `(r−Y, g−Y, b−Y)` on a mid-grey base, complement is the luma
+     *  `Y`. Editing it rewrites hue while keeping the original brightness. */
     chroma() {
         const sc = scratch();
         const sf = scratch();
@@ -244,21 +217,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 +304,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,17 +322,14 @@ 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 };
             },
         });
     }
-    /** Gaussian blur (reactive `radius`). Writable: the backward direction
-     *  runs an iterated Richardson–Lucy deconvolution seeded from the source.
-     *  Each step is `x ← x · H(target / H(x))`, non-negative and multiplicative,
-     *  so untouched regions stay fixed (their ratio is 1) while a stroke
-     *  back-solves to a sharp pre-image with far less ringing than an additive
-     *  solve. PutGet, not exact GetPut — the residual is the honest signature
-     *  of an ill-posed inverse. */
+    /** Gaussian blur (reactive `radius`). The backward pass runs an iterated
+     *  Richardson–Lucy deconvolution seeded from the source
+     *  (`x ← x · H(target / H(x))`), so untouched regions stay fixed. PutGet,
+     *  not exact GetPut. */
     blur(radius) {
         const rf = reader(radius);
         const fTmp = scratch();
@@ -405,8 +373,8 @@ export class Canvas extends Cell {
             return stamp(cur.tex, v.w, v.h);
         });
     }
-    /** Mean colour (0–1) as a writable `Color`; the GPU reduces, the write
-     *  shifts every pixel by the delta (a rigid translate in RGB). */
+    /** Mean colour (0–1) as a writable `Color`; the GPU reduces, a write shifts
+     *  every pixel by the delta. */
     meanColor() {
         const self = this;
         const sb = scratch2();
@@ -423,9 +391,8 @@ export class Canvas extends Cell {
             return stamp(out.tex, v.w, v.h);
         });
     }
-    /** Mean luma ≥ reactive `threshold` (0–1) as a writable `Bool`; flipping
-     *  the bit auto-exposes — iterate the gain (clipping caps a single step)
-     *  until the mean crosses the line. */
+    /** Mean luma ≥ `threshold` (0–1) as a writable `Bool`; flipping the bit
+     *  auto-exposes by iterating the gain until the mean crosses the threshold. */
     brighterThan(threshold) {
         const tf = reader(threshold);
         const self = this;
@@ -465,9 +432,8 @@ export class Canvas extends Cell {
     get dimensions() {
         return cachedDerive(this, "dimensions", Vec, v => ({ x: v.w, y: v.h }));
     }
-    /** A GPU per-pixel spring driver seeded from this value's texture. The
-     *  host steps it and writes `current()` back into a root cell each frame;
-     *  settle is the GPU energy reduction. */
+    /** GPU per-pixel spring driver seeded from this value's texture. The host
+     *  steps it and writes `current()` back each frame. */
     spring(opts) {
         const s = new Spring(this.value.w, this.value.h, opts);
         s.seed(this.value.tex);

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

@@ -13,7 +13,7 @@ export declare const sub: (a: V, b: V) => V;
 export declare const scale: (a: V, k: number) => V;
 export declare const lerp: (a: V, b: V, t: number) => V;
 export declare const equals: (a: V, b: V) => boolean;
-/** L2 distance in RGBA-space. */
+/** Euclidean distance in RGBA-space. */
 export declare const metric: (a: V, b: V) => number;
 export declare class Color extends Cell<V> {
     static traits: {
@@ -35,14 +35,12 @@ export declare class Color extends Cell<V> {
     get a(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
     get luminance(): Num;
     get css(): Cell<string>;
-    /** Tween-builder, implied by the lerp trait. */
+    /** Tween-builder. */
     to(this: Writable<Color>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** Writable `Color` from RGB channels (alpha = 1). Each channel is a
- *  literal `number` (lifted to a fresh seed) or an existing `Writable<Num>`
- *  (identity passthrough). All-literal inputs take a fast path; mixed
- *  inputs build a lens so channel-writes round-trip to source. */
+/** Writable `Color` from RGB channels (alpha = 1). Each channel is a literal
+ *  or a `Writable<Num>`. */
 export declare function rgb(r: Init<Num>, g: Init<Num>, b: Init<Num>): Writable<Color>;
-/** Writable `Color` from RGBA channels. Same lift rule as `rgb`. */
+/** Writable `Color` from RGBA channels. */
 export declare function rgba(r: Init<Num>, g: Init<Num>, b: Init<Num>, a: Init<Num>): Writable<Color>;
 export {};

package/dist/core/values/color.js

@@ -1,7 +1,3 @@
-// color.ts — reactive RGBA color.
-//
-// 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, fieldLens, lazy, reader, readNow, } from "../cell.js";
 import { Num, num } from "./num.js";
@@ -15,7 +11,7 @@ export const lerp = (a, b, t) => ({
     a: a.a + (b.a - a.a) * t,
 });
 export const equals = (a, b) => a === b || (a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a);
-/** L2 distance in RGBA-space. */
+/** Euclidean distance in RGBA-space. */
 export const metric = (a, b) => Math.hypot(a.r - b.r, a.g - b.g, a.b - b.b, a.a - b.a);
 const linearImpl = { add, sub, scale };
 const packImpl = {
@@ -78,22 +74,20 @@ export class Color extends Cell {
             return `rgba(${r}, ${g}, ${b}, ${c.a})`;
         }));
     }
-    /** Tween-builder, implied by the lerp trait. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** Writable `Color` from RGB channels (alpha = 1). Each channel is a
- *  literal `number` (lifted to a fresh seed) or an existing `Writable<Num>`
- *  (identity passthrough). All-literal inputs take a fast path; mixed
- *  inputs build a lens so channel-writes round-trip to source. */
+/** Writable `Color` from RGB channels (alpha = 1). Each channel is a literal
+ *  or a `Writable<Num>`. */
 export function rgb(r, g, b) {
     if (typeof r === "number" && typeof g === "number" && typeof b === "number") {
         return new Color({ r, g, b, a: 1 });
     }
     return Color.lens([num(r), num(g), num(b)], ([r, g, b]) => ({ r, g, b, a: 1 }), target => [target.r, target.g, target.b]);
 }
-/** Writable `Color` from RGBA channels. Same lift rule as `rgb`. */
+/** Writable `Color` from RGBA channels. */
 export function rgba(r, g, b, a) {
     if (typeof r === "number" &&
         typeof g === "number" &&

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

@@ -46,22 +46,21 @@ export declare class Field<T> extends Cell<FieldVal> {
      *  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. */
+    /** 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;
-    /** 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. */
+    /** Whole-field mean as a read-only `T` cell. Recomputes per epoch; 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. */
+     *  `T` cell. */
     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. */
+    /** Render `channel` through a colormap to a read-only `Canvas`; re-renders
+     *  per epoch. */
     colormap(channel: number, stops: readonly ColorStop[]): Canvas;
 }
 /** Writable `Field<T>` of size `w×h`. `painter` fills each texel (returns a

package/dist/core/values/field.js

@@ -1,26 +1,3 @@
-// field.ts — dense, GPU-resident reactive field: a grid of `T` as ONE cell.
-//
-// A Field is a single reactive node, not one-per-texel: the value is a header
-// {tex, w, h, epoch} (the Canvas handle trick, see gpu.ts), the graph compares
-// `epoch`, and no pixel crosses the bus. So a 1000×1000 field costs the engine
-// exactly what a 4×4 does — graph size is the lens-chain length, independent of
-// resolution. Per-frame work is allocation-free: `evolve`/`splat` ping-pong
-// through reused scratch textures and mint only the small header.
-//
-// Generic over the texel encoding via `Kind<T>` (channel `dim` + the `Pack`
-// codec + the boundary cell class). The dense interior stays a flat RGBA32F
-// texture forever; `T` (Num/Vec/Color) is instantiated ONLY at the boundary —
-// `mean`, `regionMean` — never per-texel. `dim` (1/2/4) selects the channel
-// mask: scalar (heatmap / SDF / density), vector (flow / gradient), colour
-// (i.e. a Canvas).
-//
-// The point of interest is the GPU↔reactivity bridge. `evolve` runs a sim on
-// its own clock (a raf/Anim loop), committing one new value per frame; the
-// reductions (`mean`, `regionMean`) are ordinary read-only derived cells, so
-// they recompute when the field's epoch changes and only *propagate* when their
-// scalar actually moves. Reactive logic downstream (`density > 0.5` → effect)
-// is thereby loosely coupled to time: it observes a continuously-running GPU
-// simulation without knowing a frame exists.
 import { Cell, reader } from "../cell.js";
 import { Canvas, stamp as canvasStamp } from "./canvas.js";
 import { Color } from "./color.js";
@@ -70,8 +47,7 @@ void main() {
 /** 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])}`;
-/** Build a piecewise-linear ramp shader over `channel` (baked per stop set,
- *  cached by source string in gpu.ts's program cache). */
+/** Build a piecewise-linear ramp shader over `channel`. */
 function rampFrag(channel, stops) {
     const ch = "rgba"[channel] ?? "r";
     let body = `  vec3 c = vec3(${glv3(stops[0][1])});\n`;
@@ -87,9 +63,9 @@ void main() {
 ${body}  o = vec4(c, 1.0);
 }`;
 }
-/** Read-only typed view via the kind's boundary class (`Num`/`Vec`/`Color`).
- *  Cast through the concrete `derive` signature — the static's polymorphic
- *  `this` rejects the abstract `Ctor<T>`, but at runtime `k.cls` is concrete. */
+/** Read-only typed view via the kind's boundary class. The cast bypasses the
+ *  polymorphic `this` rejecting the abstract `Ctor<T>`; `k.cls` is concrete at
+ *  runtime. */
 function deriveT(k, parent, fn) {
     const d = k.cls;
     return d.derive(parent, fn);
@@ -152,8 +128,7 @@ export class Field extends Cell {
         if (last)
             this.value = stamp(last.tex, w, h);
     }
-    /** Stamp a Gaussian disc of `value` at data pixel `(x, y)`, radius `r`. The
-     *  raster interaction primitive — seed a sim, inject, paint density. */
+    /** Stamp a Gaussian disc of `value` at data pixel `(x, y)`, radius `r`. */
     splat(x, y, r, value, strength = 1) {
         const ping = this.pingTex();
         const v = this.peek();
@@ -169,14 +144,14 @@ export class Field extends Cell {
         });
         this.value = stamp(dst.tex, v.w, v.h);
     }
-    /** 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. */
+    /** Whole-field mean as a read-only `T` cell. Recomputes per epoch; one 1×1
+     *  GPU readback. */
     mean() {
         const k = this.kind;
         return deriveT(k, this, v => packT(k, reduceMean({ tex: v.tex, w: v.w, h: v.h })));
     }
     /** Mean over a sub-rectangle (data pixels, reactive `box`) as a read-only
-     *  `T` cell — the field's "density of this region" observation. */
+     *  `T` cell. */
     regionMean(box) {
         const k = this.kind;
         const bf = reader(box);
@@ -197,8 +172,8 @@ export class Field extends Cell {
             return packT(k, [m[0] / cov, m[1] / cov, m[2] / cov, 1]);
         });
     }
-    /** Render `channel` through a colormap to a read-only `Canvas`. Reactive:
-     *  re-renders on every new epoch, so rendering is itself a reactive edge. */
+    /** Render `channel` through a colormap to a read-only `Canvas`; re-renders
+     *  per epoch. */
     colormap(channel, stops) {
         const frag = rampFrag(channel, stops);
         const sc = scratch();

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

@@ -8,8 +8,7 @@ export declare class Flags<K extends string> extends Cell<number> {
     };
     readonly _t: typeof Flags.traits;
     constructor(names: readonly K[], v?: number);
-    /** Bit lens for `name`; set/clear round-trips through the packed mask.
-     *  Cached per name so repeated calls return the same lens. */
+    /** Cached writable bit lens for `name`. */
     flag<F extends K>(name: F): Writable<Bool>;
 }
 /** Writable `Flags` from variadic bit names (bit `i` = the i-th name), or

package/dist/core/values/flags.js

@@ -1,18 +1,3 @@
-// flags.ts — named bit-flags over a packed integer.
-//
-// A `number` bitmask whose bits are named at construction. `flag(name)` is a
-// `Writable<Bool>` mask lens onto one bit — set/clear round-trips through the
-// packed value, so the integer and its named booleans are one source seen
-// two ways. Sparse-trait (`equals` only): bits are discrete, so there's no
-// linear/pack/factor surface. Bit `i` carries value `2^i`, so a flag list
-// ordered low→high makes the packed int equal the conventional mask (e.g.
-// chmod octal). Two front-ends: variadic names, or an object of defaults.
-//
-// `flag()` is the collision-free accessor (a single generic method, names
-// checked as a union) rather than dynamic `.name` members — no risk of a
-// flag named "value"/"flag" shadowing the class. Since each flag is a
-// writable Bool, `Tri.allOf([f.flag(a), f.flag(b)])` gives all/none/mixed
-// group toggles for free.
 import { Cell } from "../cell.js";
 import { Bool } from "./bool.js";
 const equals = (a, b) => a === b;
@@ -24,8 +9,7 @@ export class Flags extends Cell {
         super(v, { equals });
         this.names = names;
     }
-    /** Bit lens for `name`; set/clear round-trips through the packed mask.
-     *  Cached per name so repeated calls return the same lens. */
+    /** Cached writable bit lens for `name`. */
     flag(name) {
         let lens = this.#bits.get(name);
         if (lens === undefined) {