bireactive 0.3.1 → 0.3.3

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) {

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

@@ -11,13 +11,10 @@ export interface Tex {
  *  downgraded to NEAREST where `OES_texture_float_linear` is unavailable. */
 export declare function newTex(w: number, h: number, data?: Float32Array | null, linear?: boolean): WebGLTexture;
 export declare function disposeTex(t: WebGLTexture): void;
-/** A reusable owned texture, reallocated on size change — the GPU analog of
- *  the CPU scratch buffer. */
+/** A reusable owned texture, reallocated on size change. */
 export declare function scratch(): (w: number, h: number) => Tex;
 /** A feedback-safe scratch pair: returns an owned texture guaranteed not to
- *  equal `avoid` (the input being read), so a pass never reads and writes the
- *  same texture. Needed for backward passes that produce a root cell's next
- *  value (whose current value may be this same scratch). */
+ *  equal `avoid`, so a pass never reads and writes the same texture. */
 export declare function scratch2(): (w: number, h: number, avoid: WebGLTexture | null) => Tex;
 /** Copy `srcTex` into `dst` (distinct textures). */
 export declare function copy(srcTex: WebGLTexture, dst: Tex): void;
@@ -35,7 +32,7 @@ export declare function pass(frag: string, target: Tex, setup: (s: Setup) => voi
 /** Mean of all texels (RGBA, 0–1) via GPU pyramid reduction; one 1×1
  *  readback. */
 export declare function reduceMean(src: Tex): [number, number, number, number];
-/** Mean of squared texels — the spring settle metric. */
+/** Mean of squared texels (spring settle metric). */
 export declare function reduceMeanSquare(src: Tex): number;
 /** Render `src` to a 2D canvas (GPU draw + drawImage; no CPU readback). */
 export declare function blit(src: Tex, ctx: CanvasRenderingContext2D): void;
@@ -61,10 +58,9 @@ export declare class Spring {
     private springFbo;
     constructor(w: number, h: number, opts?: SpringOpts);
     private clearTex;
-    /** Snap position + target to `srcTex`, zero the velocity. `srcTex` may
-     *  alias one of our own position textures (the host feeds `current()` back
-     *  as the root value), so skip any copy that would read and write the same
-     *  texture — illegal GL feedback, and a no-op anyway. */
+    /** Snap position + target to `srcTex`, zero the velocity. `srcTex` may alias
+     *  one of our own position textures, so skip a copy that would read and write
+     *  the same texture (illegal GL feedback). */
     seed(srcTex: WebGLTexture): void;
     /** Retarget (keeps current position + velocity). */
     setTarget(srcTex: WebGLTexture): void;

package/dist/core/values/gpu.js

@@ -1,15 +1,5 @@
-// gpu.ts — shared WebGL2 core for GPU-resident Canvas values.
-//
-// There is ONE compute context (a hidden canvas). That is a hard WebGL
-// constraint, not a shared buffer: a lens pass samples its parent's texture
-// and renders into its child's, and textures can't cross contexts (browsers
-// also cap contexts at ~16). Every Canvas value still owns its own float
-// texture(s); display blits each value into its own DOM canvas. The only
-// CPU readbacks are 1×1 reductions (mean colour, settle energy).
-//
-// Coordinate convention: data row 0 lives at texture v=0, so every compute
-// pass works in a single consistent data space (no flips); only `blit`
-// flips Y so the image reads upright on screen.
+// Coordinate convention: data row 0 lives at texture v=0, so every compute pass
+// works in one consistent data space; only `blit` flips Y for the screen.
 let _gl = null;
 /** Lazily create the shared WebGL2 context (browser-only). */
 export function gl() {
@@ -103,8 +93,7 @@ export function newTex(w, h, data = null, linear = false) {
 export function disposeTex(t) {
     gl().deleteTexture(t);
 }
-/** A reusable owned texture, reallocated on size change — the GPU analog of
- *  the CPU scratch buffer. */
+/** A reusable owned texture, reallocated on size change. */
 export function scratch() {
     let t = null;
     let cw = 0;
@@ -121,9 +110,7 @@ export function scratch() {
     };
 }
 /** A feedback-safe scratch pair: returns an owned texture guaranteed not to
- *  equal `avoid` (the input being read), so a pass never reads and writes the
- *  same texture. Needed for backward passes that produce a root cell's next
- *  value (whose current value may be this same scratch). */
+ *  equal `avoid`, so a pass never reads and writes the same texture. */
 export function scratch2() {
     let a = null;
     let b = null;
@@ -246,7 +233,7 @@ export function reduceMean(src) {
     return [buf[0] / n, buf[1] / n, buf[2] / n, buf[3] / n];
 }
 let _sq = null;
-/** Mean of squared texels — the spring settle metric. */
+/** Mean of squared texels (spring settle metric). */
 export function reduceMeanSquare(src) {
     if (!_sq || _sq.w !== src.w || _sq.h !== src.h) {
         if (_sq)
@@ -373,10 +360,9 @@ export class Spring {
         g.clearColor(0, 0, 0, 0);
         g.clear(g.COLOR_BUFFER_BIT);
     }
-    /** Snap position + target to `srcTex`, zero the velocity. `srcTex` may
-     *  alias one of our own position textures (the host feeds `current()` back
-     *  as the root value), so skip any copy that would read and write the same
-     *  texture — illegal GL feedback, and a no-op anyway. */
+    /** Snap position + target to `srcTex`, zero the velocity. `srcTex` may alias
+     *  one of our own position textures, so skip a copy that would read and write
+     *  the same texture (illegal GL feedback). */
     seed(srcTex) {
         for (const tex of [this.pos[0], this.pos[1], this.targetTex])
             if (srcTex !== tex)

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

@@ -45,9 +45,7 @@ export declare class Matrix extends Cell<V> {
     get determinant(): Num;
 }
 /** Writable `Matrix` with entries `(a, b, c, d, e, f)` (SVG/Canvas order).
- *  Each entry 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 `Matrix.derive(...)` for reactive RO tracking, or
- *  `cell.value` to snapshot. Lock an entry with `Num.pin(c)`. */
+ *  Each entry is a literal (new cell) or existing writable (passed through);
+ *  for read-only sources use `Matrix.derive`. Lock an entry with `Num.pin`. */
 export declare function matrix(a?: Init<Num>, b?: Init<Num>, c?: Init<Num>, d?: Init<Num>, e?: Init<Num>, f?: Init<Num>): Writable<Matrix>;
 export {};

package/dist/core/values/matrix.js

@@ -1,10 +1,3 @@
-// matrix.ts — reactive 2D affine matrix (SVG/Canvas convention).
-//
-// Sparse-trait: only `equals`. Element-wise linear combine / lerp don't
-// decompose for matrices, so `spring`/`tween`/`mean` reject Matrix at
-// compile time. Two invertibles, both `: this` via `Cell#lens`:
-//   - `multiply(b)` — inverse multiplies by `invert(b)`
-//   - `invert()`    — its own inverse
 import { Cell, cachedDerive, fieldLens, reader, } from "../cell.js";
 import { Num, num } from "./num.js";
 export const identity = () => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
@@ -115,10 +108,8 @@ export class Matrix extends Cell {
     }
 }
 /** Writable `Matrix` with entries `(a, b, c, d, e, f)` (SVG/Canvas order).
- *  Each entry 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 `Matrix.derive(...)` for reactive RO tracking, or
- *  `cell.value` to snapshot. Lock an entry with `Num.pin(c)`. */
+ *  Each entry is a literal (new cell) or existing writable (passed through);
+ *  for read-only sources use `Matrix.derive`. Lock an entry with `Num.pin`. */
 export function matrix(a = 1, b = 0, c = 0, d = 1, e = 0, f = 0) {
     if (typeof a === "number" &&
         typeof b === "number" &&
@@ -134,6 +125,5 @@ export function matrix(a = 1, b = 0, c = 0, d = 1, e = 0, f = 0) {
     const dN = num(d);
     const eN = num(e);
     const fN = num(f);
-    // The view fully reconstructs all 6 cells (1-arg bwd ⇒ no source read).
     return Matrix.lens([aN, bN, cN, dN, eN, fN], ([a, b, c, d, e, f]) => ({ a, b, c, d, e, f }), v => [v.a, v.b, v.c, v.d, v.e, v.f]);
 }

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

@@ -22,46 +22,37 @@ export declare class Num extends Cell<V> {
     add(b: Val<V>): this;
     sub(b: Val<V>): this;
     scale(k: Val<number>): this;
-    /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
-     *  for `.scale(k).add(off)`. */
+    /** Affine map `v ↦ k·v + off`. Invertible when k ≠ 0. */
     affine(k: Val<number>, off: Val<number>): this;
-    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
-     *  multi-valued, so a write clamps to that domain and returns the
-     *  pre-image nearest the current source — the drag stays on its branch. */
+    /** Sine of `this` (radians). The inverse is multi-valued; a write picks the
+     *  angle nearest the current value, so a drag stays on its branch. */
     sin(): this;
-    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    /** Natural exponential; inverts via log. */
     exp(): this;
-    /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
-     *  the range reads back clamped, not as written). */
+    /** Clamp to `[lo, hi]`. Lossy: a write outside the range reads back clamped. */
     clamp(lo: Val<V>, hi: Val<V>): this;
-    /** Lossy lens snapping reads/writes to the nearest multiple of `step`. */
+    /** Snap reads and writes to the nearest multiple of `step` (lossy). */
     quantize(step: Val<number>): this;
-    /** Cyclic-coordinate lens. Reads pass through; writes pick the
-     *  representative closest to current modulo `period`, so dragging an
-     *  angle never jumps a full revolution. The 2-arg bwd is arity-detected
-     *  as stateful, threading the accumulated value through `s`. */
+    /** Reads pass through; a write picks the value closest to the current one
+     *  modulo `period`, so dragging an angle never jumps a full turn. */
     cyclic(period: Val<number>): this;
-    /** `this > t` as a Bool. Flipping the view bumps the source across
-     *  the threshold by `eps`. */
+    /** `this > t` as a Bool. Flipping it bumps the source across the
+     *  threshold by `eps`. */
     greaterThan<T extends Num>(this: T, t: Val<V>, eps?: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
-    /** `this < t`. Dual of `greaterThan`. */
+    /** `this < t` as a Bool. */
     lessThan<T extends Num>(this: T, t: Val<V>, eps?: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
-    /** `round(this) ≡ 0 (mod d)` as a Bool; pair with `quantize(1)` for
-     *  integer sliders. Bwd: to make divisible, snap to the nearer
-     *  multiple of `d`; to make non-divisible, bump by `+1`; no-op when
-     *  the class already matches. */
+    /** True when `round(this)` is divisible by `d`. A write snaps to the nearest
+     *  multiple of `d` to make it divisible, or bumps by 1 to make it not. */
     divisibleBy<T extends Num>(this: T, d: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
-    /** `divisibleBy(2)` — lazy getter for the common case. */
+    /** True when even. */
     get isEven(): this extends WritableBrand ? Writable<Bool> : Bool;
-    /** `not(divisibleBy(2))` — lazy getter. */
+    /** True when odd. */
     get isOdd(): this extends WritableBrand ? Writable<Bool> : Bool;
-    /** Tween-builder; `this: Writable<Num>` gates the call to writable
-     *  receivers. */
+    /** Tween-builder. */
     to(this: Writable<Num>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** Writable `Num`. Literal seeds a fresh cell; existing `Writable<Num>`
- *  passes through by identity. RO sources are rejected at the type level —
- *  use `Num.derive(...)` for reactive RO tracking, or `Num.coerce(...)` for
- *  the permissive lift over any `Val<number>`. */
+/** Writable `Num` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Num.derive`, or `Num.coerce` to lift
+ *  any `Val<number>`. */
 export declare function num(v?: Init<Num>): Writable<Num>;
 export {};

package/dist/core/values/num.js

@@ -1,7 +1,3 @@
-// num.ts — reactive scalar.
-//
-// Invertibles return `: this` and ride on `Cell#lens(fwd, bwd)`;
-// chained calls compose into a lens chain.
 import { tween } from "../../animation/index.js";
 import { Cell, lazy, reader, } from "../cell.js";
 import { Bool } from "./bool.js";
@@ -47,16 +43,14 @@ export class Num extends Cell {
         const kf = reader(k);
         return this.lens(v => v * kf(), n => n / kf());
     }
-    /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
-     *  for `.scale(k).add(off)`. */
+    /** Affine map `v ↦ k·v + off`. Invertible when k ≠ 0. */
     affine(k, off) {
         const kf = reader(k);
         const of = reader(off);
         return this.lens(v => v * kf() + of(), n => (n - of()) / kf());
     }
-    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
-     *  multi-valued, so a write clamps to that domain and returns the
-     *  pre-image nearest the current source — the drag stays on its branch. */
+    /** Sine of `this` (radians). The inverse is multi-valued; a write picks the
+     *  angle nearest the current value, so a drag stays on its branch. */
     sin() {
         return this.lens(v => Math.sin(v), (target, s) => {
             const p = Math.asin(unit(target));
@@ -65,12 +59,11 @@ export class Num extends Cell {
             return Math.abs(a - s) <= Math.abs(b - s) ? a : b;
         });
     }
-    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    /** Natural exponential; inverts via log. */
     exp() {
         return this.lens(v => Math.exp(v), n => Math.log(n));
     }
-    /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
-     *  the range reads back clamped, not as written). */
+    /** Clamp to `[lo, hi]`. Lossy: a write outside the range reads back clamped. */
     clamp(lo, hi) {
         const lf = reader(lo);
         const hf = reader(hi);
@@ -78,31 +71,29 @@ export class Num extends Cell {
             const l = lf(), h = hf();
             return v < l ? l : v > h ? h : v;
         };
-        // A write whose clamped projection matches the current view leaves
-        // the source untouched (off-range source preserved).
+        // If the clamped write matches the current view, keep the source
+        // (preserves an off-range source value).
         return this.lens(c, (v, s) => {
             const cv = c(v);
             return cv === c(s) ? s : cv;
         });
     }
-    /** Lossy lens snapping reads/writes to the nearest multiple of `step`. */
+    /** Snap reads and writes to the nearest multiple of `step` (lossy). */
     quantize(step) {
         const sf = reader(step);
         const q = (v) => {
             const s = sf();
             return Math.round(v / s) * s;
         };
-        // A write that snaps to the current bucket leaves the source
-        // untouched (off-grid remainder preserved).
+        // If the write snaps to the current bucket, keep the source
+        // (preserves an off-grid remainder).
         return this.lens(q, (v, src) => {
             const qv = q(v);
             return qv === q(src) ? src : qv;
         });
     }
-    /** Cyclic-coordinate lens. Reads pass through; writes pick the
-     *  representative closest to current modulo `period`, so dragging an
-     *  angle never jumps a full revolution. The 2-arg bwd is arity-detected
-     *  as stateful, threading the accumulated value through `s`. */
+    /** Reads pass through; a write picks the value closest to the current one
+     *  modulo `period`, so dragging an angle never jumps a full turn. */
     cyclic(period) {
         const pf = reader(period);
         return this.lens(v => v, (v, s) => {
@@ -111,13 +102,8 @@ export class Num extends Cell {
             return s + delta - p * Math.round(delta / p);
         });
     }
-    // Predicate bridges to Bool.
-    //
-    // Cross-type quotient lenses projecting Num through a boolean
-    // predicate. Conditional return type: writable receiver yields
-    // `Writable<Bool>`, RO receiver yields RO `Bool`.
-    /** `this > t` as a Bool. Flipping the view bumps the source across
-     *  the threshold by `eps`. */
+    /** `this > t` as a Bool. Flipping it bumps the source across the
+     *  threshold by `eps`. */
     greaterThan(t, eps = 1e-6) {
         const tf = reader(t);
         const ef = reader(eps);
@@ -128,7 +114,7 @@ export class Num extends Cell {
             return target ? th + ef() : th - ef();
         });
     }
-    /** `this < t`. Dual of `greaterThan`. */
+    /** `this < t` as a Bool. */
     lessThan(t, eps = 1e-6) {
         const tf = reader(t);
         const ef = reader(eps);
@@ -139,10 +125,8 @@ export class Num extends Cell {
             return target ? th - ef() : th + ef();
         });
     }
-    /** `round(this) ≡ 0 (mod d)` as a Bool; pair with `quantize(1)` for
-     *  integer sliders. Bwd: to make divisible, snap to the nearer
-     *  multiple of `d`; to make non-divisible, bump by `+1`; no-op when
-     *  the class already matches. */
+    /** True when `round(this)` is divisible by `d`. A write snaps to the nearest
+     *  multiple of `d` to make it divisible, or bumps by 1 to make it not. */
     divisibleBy(d) {
         const df = reader(d);
         return Bool.lens(this, v => Math.round(v) % df() === 0, (target, current) => {
@@ -161,24 +145,22 @@ export class Num extends Cell {
             return r + 1;
         });
     }
-    /** `divisibleBy(2)` — lazy getter for the common case. */
+    /** True when even. */
     get isEven() {
         return lazy(this, "isEven", () => this.divisibleBy(2));
     }
-    /** `not(divisibleBy(2))` — lazy getter. */
+    /** True when odd. */
     get isOdd() {
         return lazy(this, "isOdd", () => this.divisibleBy(2).not());
     }
-    /** Tween-builder; `this: Writable<Num>` gates the call to writable
-     *  receivers. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** Writable `Num`. Literal seeds a fresh cell; existing `Writable<Num>`
- *  passes through by identity. RO sources are rejected at the type level —
- *  use `Num.derive(...)` for reactive RO tracking, or `Num.coerce(...)` for
- *  the permissive lift over any `Val<number>`. */
+/** Writable `Num` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Num.derive`, or `Num.coerce` to lift
+ *  any `Val<number>`. */
 export function num(v = 0) {
     if (v instanceof Num)
         return v;

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

@@ -27,9 +27,7 @@ export declare class Pose extends Cell<V> {
     get y(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
     get theta(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
 }
-/** Writable `Pose`. Literal seeds a fresh cell; existing `Pose` passes
- *  through by identity. RO sources are rejected at the type level — use
- *  `Pose.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. */
+/** Writable `Pose` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Pose.derive`. */
 export declare function pose(v?: Init<Pose>): Writable<Pose>;
 export {};

package/dist/core/values/pose.js

@@ -1,9 +1,3 @@
-// pose.ts — reactive 2D rigid-body pose: { x, y, theta }.
-//
-// Single source of truth for a rigid body. The solver binds the cell as
-// a 3-DOF block and writes back through it, so renderers, drag handlers,
-// IK, and physics all observe the same value. Vec / Num lenses compose
-// for consumers that care only about translation or rotation.
 import { Cell, fieldLens } from "../cell.js";
 import { Num } from "./num.js";
 export const add = (a, b) => ({
@@ -38,8 +32,7 @@ const packImpl = {
     },
     write: (a, o) => ({ x: a[o], y: a[o + 1], theta: a[o + 2] }),
 };
-/** Rotate-about-pivot moves the position and adds dθ to orientation;
- *  scale-about-pivot scales position, orientation untouched. */
+// rotateAbout moves position and adds dθ; scaleAbout scales position, leaves θ.
 const pivotalImpl = {
     rotateAbout: (v, p, dθ) => {
         const cos = Math.cos(dθ);
@@ -80,10 +73,8 @@ export class Pose extends Cell {
         return fieldLens(this, "theta", Num);
     }
 }
-/** Writable `Pose`. Literal seeds a fresh cell; existing `Pose` passes
- *  through by identity. RO sources are rejected at the type level — use
- *  `Pose.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. */
+/** Writable `Pose` from a literal (new cell) or existing writable (passed
+ *  through). For read-only sources use `Pose.derive`. */
 export function pose(v = { x: 0, y: 0, theta: 0 }) {
     if (v instanceof Pose)
         return v;