bireactive 0.3.0 → 0.3.2

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;

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

@@ -12,15 +12,14 @@ 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 (lo, hi). Treats a range as a point in 2-space. */
+/** Euclidean distance over (lo, hi). */
 export declare const metric: (a: V, b: V) => number;
 export declare const width: (r: V) => number;
 export declare const center: (r: V) => number;
 export declare const contains: (r: V, v: number) => boolean;
 export declare const clamp: (r: V, v: number) => number;
-/** Closest value STRICTLY outside `[lo, hi]`, displaced past the
- *  nearest endpoint by `eps`. Used by `Range#contains` as the bwd's
- *  false-side policy. */
+/** Closest value strictly outside `[lo, hi]`, displaced past the nearest
+ *  endpoint by `eps`. */
 export declare const eject: (r: V, v: number, eps?: number) => number;
 /** Sample at parameter `t`: `lo + t·(hi - lo)`. `t ∈ [0, 1]` stays
  *  inside the range; values outside extrapolate linearly. */
@@ -43,43 +42,36 @@ export declare class Range extends Cell<V> {
     /** End endpoint. Writes preserve `lo` (end-knob semantics). */
     get hi(): this extends WritableBrand ? Writable<Num> : Num;
     get width(): Num;
-    /** Midpoint body-drag: read returns the center; write shifts the range
-     *  so the center matches (width preserved). `.start` is the lo-anchored
-     *  variant; `.lo` / `.hi` edit the endpoints. */
+    /** Midpoint body-drag: reads the center; a write shifts the range so the
+     *  center matches (width preserved). */
     get center(): Writable<Num>;
-    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    /** Translate by `by`. */
     shift(by: Val<number>): this;
-    /** Scale uniformly about the origin. Iso for `k ≠ 0`. */
+    /** Scale about the origin. Invertible when k ≠ 0. */
     scale(k: Val<number>): this;
-    /** Body-drag handle: read returns `lo`; write shifts the range so `lo`
-     *  matches (width preserved). For start-knob editing use `.lo`. */
+    /** Body-drag handle: reads `lo`; a write shifts the range so `lo` matches
+     *  (width preserved). */
     get start(): Writable<Num>;
     /** RO sample at `t`. `t ∈ [0, 1]` stays inside; outside extrapolates. */
     sample(t: Val<number>): Num;
     /** Bidirectional `t ↔ value` slider. Read `lo + t·(hi - lo)`; write
      *  solves for `t` and updates `t` only, leaving `lo` / `hi` put. */
     slider(t: Writable<Num>): Writable<Num>;
-    /** Membership predicate. Conditional return type: a writable `Num`
-     *  yields `Writable<Bool>` and flipping the view bumps the source
-     *  (`true` clamps into `[lo, hi]`, `false` ejects past the nearest
-     *  endpoint by `eps`). Literal / RO inputs yield a bare RO `Bool`. */
+    /** True when `v` is in `[lo, hi]`. A writable `Num` yields a `Writable<Bool>`:
+     *  flipping it clamps `v` inside (`true`) or ejects it past the nearest
+     *  endpoint (`false`). Literal/RO inputs yield a read-only `Bool`. */
     contains<P extends Val<number>>(v: P): P extends WritableBrand ? Writable<Bool> : Bool;
-    /** RO clamp: read `v` into `[lo, hi]`. For a writable clamping lens
-     *  on a single Num, see `Num#clamp(lo, hi)`. */
+    /** Read-only clamp of `v` into `[lo, hi]`. */
     clampedRead(v: Val<number>): Num;
     /** Inverse of `sample`: derive the `t` that would produce `v`. */
     paramOf(v: Val<number>): Num;
-    /** Tween-builder; animates `{lo, hi}` jointly. */
+    /** Tween-builder. */
     to(this: Writable<Range>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** Range over `[at, at + dur]`, parameterised by start + duration. The
- *  timeline-clip shape: `.lo` slides the start, `.hi` the end, `.start`
- *  body-drags (preserving width). Backed by the live `at` / `dur` Nums. */
+/** Range over `[at, at + dur]`, backed by the live `at` and `dur` Nums. */
 export declare function span(at: Writable<Num>, dur: Writable<Num>): Writable<Range>;
-/** Writable `Range` over `[lo, hi]`. Each endpoint 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
- *  `Range.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. Lock an endpoint with `Num.pin(c)`. */
+/** Writable `Range` over `[lo, hi]`. Each endpoint is a literal (new cell) or
+ *  existing writable (passed through); for read-only sources use `Range.derive`.
+ *  Lock an endpoint with `Num.pin`. */
 export declare function range(lo?: Init<Num>, hi?: Init<Num>): Writable<Range>;
 export {};

package/dist/core/values/range.js

@@ -1,10 +1,3 @@
-// range.ts — reactive numeric interval `[lo, hi]`.
-//
-// Home for sliders, scrollbars, and timeline clip spans. Field lenses
-// give start-knob (`.lo`) and end-knob (`.hi`) drag; `.start` / `.center`
-// are body-drags (shift both, preserving width — anchored at lo / midpoint
-// respectively); `.slider(t)` is the bidirectional `t ↔ lo + t·(hi - lo)`
-// iso. Traits: `linear`, `lerp`, `equals`, `pack` (scalar-only).
 import { tween } from "../../animation/index.js";
 import { Cell, cachedDerive, fieldLens, isReadonly, reader, readNow, SKIP, } from "../cell.js";
 import { Bool } from "./bool.js";
@@ -17,15 +10,14 @@ export const lerp = (a, b, t) => ({
     hi: a.hi + (b.hi - a.hi) * t,
 });
 export const equals = (a, b) => a === b || (a.lo === b.lo && a.hi === b.hi);
-/** L2 distance over (lo, hi). Treats a range as a point in 2-space. */
+/** Euclidean distance over (lo, hi). */
 export const metric = (a, b) => Math.hypot(a.lo - b.lo, a.hi - b.hi);
 export const width = (r) => r.hi - r.lo;
 export const center = (r) => (r.lo + r.hi) / 2;
 export const contains = (r, v) => v >= r.lo && v <= r.hi;
 export const clamp = (r, v) => (v < r.lo ? r.lo : v > r.hi ? r.hi : v);
-/** Closest value STRICTLY outside `[lo, hi]`, displaced past the
- *  nearest endpoint by `eps`. Used by `Range#contains` as the bwd's
- *  false-side policy. */
+/** Closest value strictly outside `[lo, hi]`, displaced past the nearest
+ *  endpoint by `eps`. */
 export const eject = (r, v, eps = 1e-6) => {
     if (!contains(r, v))
         return v;
@@ -71,21 +63,20 @@ export class Range extends Cell {
     get width() {
         return cachedDerive(this, "width", Num, width);
     }
-    /** Midpoint body-drag: read returns the center; write shifts the range
-     *  so the center matches (width preserved). `.start` is the lo-anchored
-     *  variant; `.lo` / `.hi` edit the endpoints. */
+    /** Midpoint body-drag: reads the center; a write shifts the range so the
+     *  center matches (width preserved). */
     get center() {
         return Num.lens(this, center, (c, src) => {
             const half = (src.hi - src.lo) / 2;
             return { lo: c - half, hi: c + half };
         });
     }
-    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    /** Translate by `by`. */
     shift(by) {
         const f = reader(by);
         return this.lens(v => ({ lo: v.lo + f(), hi: v.hi + f() }), n => ({ lo: n.lo - f(), hi: n.hi - f() }));
     }
-    /** Scale uniformly about the origin. Iso for `k ≠ 0`. */
+    /** Scale about the origin. Invertible when k ≠ 0. */
     scale(k) {
         const kf = reader(k);
         return this.lens(v => {
@@ -96,8 +87,8 @@ export class Range extends Cell {
             return { lo: n.lo / k, hi: n.hi / k };
         });
     }
-    /** Body-drag handle: read returns `lo`; write shifts the range so `lo`
-     *  matches (width preserved). For start-knob editing use `.lo`. */
+    /** Body-drag handle: reads `lo`; a write shifts the range so `lo` matches
+     *  (width preserved). */
     get start() {
         return Num.lens(this, v => v.lo, (newLo, src) => ({ lo: newLo, hi: newLo + (src.hi - src.lo) }));
     }
@@ -108,21 +99,19 @@ export class Range extends Cell {
     /** Bidirectional `t ↔ value` slider. Read `lo + t·(hi - lo)`; write
      *  solves for `t` and updates `t` only, leaving `lo` / `hi` put. */
     slider(t) {
-        // `this as Range` pins the tuple element type (polymorphic `this`
-        // defeats the mapped-tuple inference on `[this, t]`).
+        // `this as Range` pins the tuple element type; polymorphic `this` breaks
+        // the mapped-tuple inference.
         return Num.lens([this, t], ([r, tv]) => sample(r, tv), (v, [r]) => {
             const w = r.hi - r.lo;
             return [SKIP, w === 0 ? 0 : (v - r.lo) / w];
         });
     }
-    /** Membership predicate. Conditional return type: a writable `Num`
-     *  yields `Writable<Bool>` and flipping the view bumps the source
-     *  (`true` clamps into `[lo, hi]`, `false` ejects past the nearest
-     *  endpoint by `eps`). Literal / RO inputs yield a bare RO `Bool`. */
+    /** True when `v` is in `[lo, hi]`. A writable `Num` yields a `Writable<Bool>`:
+     *  flipping it clamps `v` inside (`true`) or ejects it past the nearest
+     *  endpoint (`false`). Literal/RO inputs yield a read-only `Bool`. */
     contains(v) {
         if (v instanceof Num) {
-            // RO Num has no backward path → RO branch. Sources and
-            // writable lenses both accept write-back.
+            // RO Num has no backward path; only writable Nums accept write-back.
             if (!isReadonly(v)) {
                 return Bool.lens([this, v], (vals) => contains(vals[0], vals[1]), (target, vals) => {
                     const [r, n] = vals;
@@ -134,8 +123,7 @@ export class Range extends Cell {
         }
         return Bool.derive(() => contains(this.value, readNow(v)));
     }
-    /** RO clamp: read `v` into `[lo, hi]`. For a writable clamping lens
-     *  on a single Num, see `Num#clamp(lo, hi)`. */
+    /** Read-only clamp of `v` into `[lo, hi]`. */
     clampedRead(v) {
         return Num.derive(() => clamp(this.value, readNow(v)));
     }
@@ -143,27 +131,22 @@ export class Range extends Cell {
     paramOf(v) {
         return Num.derive(() => paramOf(this.value, readNow(v)));
     }
-    /** Tween-builder; animates `{lo, hi}` jointly. */
+    /** Tween-builder. */
     to(target, dur, ease) {
         return tween(this, target, dur, ease);
     }
 }
-/** @internal — 2-input lens over two writable `Num`s; `range()` delegates
- *  here after lifting literals. */
+/** Lens combining two writable `Num`s into a `Range`. */
 function ends(lo, hi) {
     return Range.lens([lo, hi], (vals) => ({ lo: vals[0], hi: vals[1] }), (target) => [target.lo, target.hi]);
 }
-/** Range over `[at, at + dur]`, parameterised by start + duration. The
- *  timeline-clip shape: `.lo` slides the start, `.hi` the end, `.start`
- *  body-drags (preserving width). Backed by the live `at` / `dur` Nums. */
+/** Range over `[at, at + dur]`, backed by the live `at` and `dur` Nums. */
 export function span(at, dur) {
     return Range.lens([at, dur], (vals) => ({ lo: vals[0], hi: vals[0] + vals[1] }), (target) => [target.lo, target.hi - target.lo]);
 }
-/** Writable `Range` over `[lo, hi]`. Each endpoint 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
- *  `Range.derive(...)` for reactive RO tracking, or `cell.value` to
- *  snapshot. Lock an endpoint with `Num.pin(c)`. */
+/** Writable `Range` over `[lo, hi]`. Each endpoint is a literal (new cell) or
+ *  existing writable (passed through); for read-only sources use `Range.derive`.
+ *  Lock an endpoint with `Num.pin`. */
 export function range(lo = 0, hi = 1) {
     if (typeof lo === "number" && typeof hi === "number") {
         return new Range({ lo, hi });