bireactive 0.3.1 → 0.3.2

package/dist/core/values/audio.js

@@ -1,22 +1,7 @@
-// audio.ts — reactive audio clip (handle-as-value), the sound twin of canvas.ts.
-//
-// A Clip is context-free PCM: one Float32Array per channel plus a sample rate.
-// The graph transports only the tiny header {pcm, sampleRate, epoch} and compares
-// the monotonic epoch, so propagation never scans a sample and nothing is copied
-// across the bus (same handle-as-value rule as Canvas, minus the GL context — PCM
-// needs no ambient AudioContext, that only appears at the playback sink).
-//
-// Tiers mirror the rest of values/:
-//   - pure isomorphisms (`reverse`) — one pass each way.
-//   - reactive-param invertible (`gain(k)`) — reads `Val<number>`.
-//   - complement projection (`normalize`) — the lossy view (peak-scaled) plus a
-//     complement (the original peak) recovered on write-back, the audio analog of
-//     str.lowercase()/canvas.grayscale().
-//   - cross-type lens (`rms` → Num).
 import { Cell, reader } from "../cell.js";
 import { Num } from "./num.js";
 let EPOCH = 0;
-/** Stamp channel buffers with a fresh epoch — the only way to mint a value. */
+/** Stamp buffers with a fresh epoch — the only way to mint a `Clip` value. */
 export const stamp = (pcm, sampleRate) => ({
     pcm,
     sampleRate,
@@ -55,7 +40,7 @@ export class Audio extends Cell {
     constructor(v = { pcm: [], sampleRate: 44100, epoch: 0 }) {
         super(v, { equals });
     }
-    /** Time-reverse every channel. Involution. */
+    /** Time-reverse every channel. */
     reverse() {
         const run = (v) => stamp(v.pcm.map(ch => {
             const o = new Float32Array(ch.length);
@@ -65,14 +50,13 @@ export class Audio extends Cell {
         }), v.sampleRate);
         return this.lens(run, run);
     }
-    /** Scalar gain. Invertible while k ≠ 0 — the audio twin of Canvas.brightness. */
+    /** Scalar gain. Invertible while k ≠ 0. */
     gain(k) {
         const kf = reader(k);
         return this.lens(v => scaled(v, kf()), n => scaled(n, 1 / kf()));
     }
-    /** Peak-normalize to reactive `target` (default 1). The view alone can't
-     *  know the source's loudness, so the complement carries the original peak and
-     *  the backward pass restores it. The audio analog of str.lowercase(). */
+    /** Peak-normalize to `target` (default 1). The complement stores the original
+     *  peak so a write-back restores it. */
     normalize(target = 1) {
         const tf = reader(target);
         const self = this;
@@ -97,8 +81,8 @@ export class Audio extends Cell {
         });
     }
 }
-/** Writable `Audio`. A `Clip` seeds a fresh cell; an existing `Writable<Audio>`
- *  passes through by identity. */
+/** Writable `Audio` from a `Clip` (new cell) or existing writable (passed
+ *  through). */
 export function audio(v) {
     if (v instanceof Audio)
         return v;

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

@@ -13,25 +13,25 @@ export declare class Bool extends Cell<V> {
     };
     readonly _t: typeof Bool.traits;
     constructor(v?: V);
-    /** Logical negation. Involution; chains compose. */
+    /** Logical negation. */
     not(): this;
-    /** Symmetric difference / parity. Invertible:
-     *  `a ^ b = c  ↔  a = c ^ b`. The F₂ analog of `Num#add`. */
+    /** True when exactly one side is true (XOR); its own inverse. */
     xor(b: Val<V>): this;
-    /** `this && b`. RO: fan-in write-back isn't unique — use
-     *  `Bool.lens([a, b], ...)` with an explicit policy for a writable AND. */
+    /** True when both sides are true. Read-only — a write can't be split
+     *  between the two inputs. */
     and(b: Val<V>): Bool;
+    /** True when either side is true. */
     or(b: Val<V>): Bool;
-    /** `this → b ≡ ¬this ∨ b`. */
+    /** True unless `this` is true and `b` is false (`this → b`). */
     implies(b: Val<V>): Bool;
-    /** Boolean equality — XNOR. */
+    /** True when both sides match (XNOR). */
     eq(b: Val<V>): Bool;
+    /** True unless both sides are true (NAND). */
     nand(b: Val<V>): Bool;
+    /** True when both sides are false (NOR). */
     nor(b: Val<V>): Bool;
 }
-/** Writable `Bool`. Literal seeds a fresh cell; existing `Writable<Bool>`
- *  passes through by identity. RO sources are rejected at the type level —
- *  use `Bool.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. */
+/** Writable `Bool` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Bool.derive`. */
 export declare function bool(v?: Init<Bool>): Writable<Bool>;
 export {};

package/dist/core/values/bool.js

@@ -1,20 +1,10 @@
-// bool.ts — reactive boolean.
-//
-// Invertibles ride the plain endo `.lens(fwd, bwd)`: `not()` (involution,
-// `.not().not()` round-trips to identity) and `xor(b)` (its own inverse;
-// `a ^ b = c ↔ a = c ^ b`). xor carries Bool's `linear` trait.
-//
-// `and` / `or` / `implies` / `eq` / `nand` / `nor` return bare RO `Bool`
-// — lossy fan-ins whose write-back is ambiguous. Lift to writable via
-// `Bool.lens([a, b], fwd, bwd)` with an explicit policy.
 import { Cell, reader } from "../cell.js";
 export const not = (a) => !a;
 export const and = (a, b) => a && b;
 export const or = (a, b) => a || b;
 export const xor = (a, b) => a !== b;
 export const equals = (a, b) => a === b;
-// F₂-linear structure: xor is both add and sub (a ^ a = false);
-// scale-by-integer collapses by parity (even k → false, odd k → a).
+// F₂-linear: xor is both add and sub; scale collapses by parity.
 const linearImpl = {
     add: xor,
     sub: xor,
@@ -25,49 +15,49 @@ export class Bool extends Cell {
     constructor(v = false) {
         super(v, { equals });
     }
-    /** Logical negation. Involution; chains compose. */
+    /** Logical negation. */
     not() {
         return this.lens(not, not);
     }
-    /** Symmetric difference / parity. Invertible:
-     *  `a ^ b = c  ↔  a = c ^ b`. The F₂ analog of `Num#add`. */
+    /** True when exactly one side is true (XOR); its own inverse. */
     xor(b) {
         const bf = reader(b);
         return this.lens(v => v !== bf(), n => n !== bf());
     }
-    /** `this && b`. RO: fan-in write-back isn't unique — use
-     *  `Bool.lens([a, b], ...)` with an explicit policy for a writable AND. */
+    /** True when both sides are true. Read-only — a write can't be split
+     *  between the two inputs. */
     and(b) {
         const bf = reader(b);
         return Bool.derive(() => this.value && bf());
     }
+    /** True when either side is true. */
     or(b) {
         const bf = reader(b);
         return Bool.derive(() => this.value || bf());
     }
-    /** `this → b ≡ ¬this ∨ b`. */
+    /** True unless `this` is true and `b` is false (`this → b`). */
     implies(b) {
         const bf = reader(b);
         return Bool.derive(() => !this.value || bf());
     }
-    /** Boolean equality — XNOR. */
+    /** True when both sides match (XNOR). */
     eq(b) {
         const bf = reader(b);
         return Bool.derive(() => this.value === bf());
     }
+    /** True unless both sides are true (NAND). */
     nand(b) {
         const bf = reader(b);
         return Bool.derive(() => !(this.value && bf()));
     }
+    /** True when both sides are false (NOR). */
     nor(b) {
         const bf = reader(b);
         return Bool.derive(() => !(this.value || bf()));
     }
 }
-/** Writable `Bool`. Literal seeds a fresh cell; existing `Writable<Bool>`
- *  passes through by identity. RO sources are rejected at the type level —
- *  use `Bool.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. */
+/** Writable `Bool` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Bool.derive`. */
 export function bool(v = false) {
     if (v instanceof Bool)
         return v;

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

@@ -15,20 +15,19 @@ 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 over the flat (x, y, w, h) representation. */
+/** Euclidean distance over (x, y, w, h). */
 export declare const metric: (a: V, b: V) => number;
 export declare const expand: (b: V, n: number) => V;
 export declare const contains: (b: V, p: Inner<Vec>) => boolean;
-/** 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 declare const clampToBox: (p: Inner<Vec>, b: V) => Inner<Vec>;
-/** 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 declare const ejectFromBox: (p: Inner<Vec>, b: V, eps?: number) => Inner<Vec>;
 /** Bounding box around a set of boxes. */
 export declare function union(...bs: V[]): V;
-/** Perimeter point on a Box facing `toward`. Default `Shape.boundary`. */
+/** Perimeter point on a box facing `toward`. */
 export declare function edgeFrom(b: V, toward: Inner<Vec>): Inner<Vec>;
 export declare class Box extends Cell<V> {
     static traits: {
@@ -45,32 +44,28 @@ export declare class Box extends Cell<V> {
     scale(k: Val<number>): this;
     expand(n: Val<number>): this;
     lerp(b: Val<V>, t: Val<number>): Box;
-    /** 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 extends Val<Inner<Vec>>>(p: P): P extends WritableBrand ? Writable<Bool> : Bool;
     get x(): this extends WritableBrand ? Writable<Num> : Num;
     get y(): this extends WritableBrand ? Writable<Num> : Num;
     get w(): this extends WritableBrand ? Writable<Num> : Num;
     get h(): this extends WritableBrand ? Writable<Num> : Num;
     get area(): Num;
-    /** 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: number, v: number): Vec;
     get center(): Vec;
     get top(): Vec;
     get bottom(): Vec;
     get left(): Vec;
     get right(): Vec;
-    /** Tween-builder, implied by the lerp trait. */
+    /** Tween-builder. */
     to(this: Writable<Box>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** 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 declare function box(x?: Init<Num>, y?: Init<Num>, w?: Init<Num>, h?: Init<Num>): Writable<Box>;
 export {};

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();
@@ -230,9 +205,8 @@ export class Canvas extends Cell {
             },
         });
     }
-    /** 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();
@@ -352,13 +326,10 @@ export class Canvas extends Cell {
             },
         });
     }
-    /** 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();
@@ -402,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();
@@ -420,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;
@@ -462,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 {};