bireactive 0.3.0 → 0.3.2

package/dist/core/values/arr.js

@@ -0,0 +1,336 @@
+import { batch, Cell, cell, derive, lazy, lens } from "../cell.js";
+import { Num } from "./num.js";
+/** Structural equality: same element cells (by reference) in the same order; a
+ *  value change inside an element doesn't affect it. */
+const sameCells = (a, b) => a === b || (a.length === b.length && a.every((c, i) => c === b[i]));
+const clampInt = (v, lo, hi) => {
+    const r = Math.round(v);
+    return r < lo ? lo : r > hi ? hi : r;
+};
+const views = new WeakMap();
+export class Arr extends Cell {
+    static traits = {
+        equals: sameCells,
+    };
+    constructor(items = []) {
+        super(items, { equals: sameCells });
+    }
+    /** Build a derived `Arr` over any `Read` source. Variance escape: `Cell<R>`
+     *  isn't assignable to `Cell<unknown>` (contravariant `_equals`), so typed
+     *  `Arr.derive` can't see element subtyping. */
+    static #view(parent, getter) {
+        // biome-ignore lint/suspicious/noExplicitAny: variance escape (see above)
+        return Arr.derive(parent, getter);
+    }
+    /** An `Arr` whose elements are derived from an external `source` and whose
+     *  structural edits rewrite that source via `ops`. */
+    static fromSource(source, getter, ops) {
+        const view = Arr.#view(source, getter);
+        views.set(view, {
+            insert: ops.insert,
+            remove: ops.remove,
+            moveBefore: ops.moveBefore,
+        });
+        return view;
+    }
+    // ── reads ────────────────────────────────────────────────────────────
+    /** The element cells in order; tracked when read in an effect/derive. */
+    get cells() {
+        return this.value;
+    }
+    /** Snapshot of element values, `readonly T[]`; re-derives on any value or
+     *  structural change. Memoized per instance. */
+    get values() {
+        return lazy(this, "values", () => derive(this, cs => cs.map(c => c.value)));
+    }
+    /** Element count as a reactive `Num` (structural changes only). */
+    get length() {
+        return lazy(this, "length", () => Num.derive(this, cs => cs.length));
+    }
+    /** This element's index as a writable `Num`: reading gives its position,
+     *  writing reorders (splices the reference to the rounded, clamped target).
+     *  Writable on a base `Arr`; read-only over a derived view. */
+    indexOf(e) {
+        return Num.lens(this, cs => cs.indexOf(e), (to, cs) => {
+            const from = cs.indexOf(e);
+            if (from < 0)
+                return cs;
+            const others = cs.filter(x => x !== e);
+            const t = clampInt(to, 0, others.length);
+            if (t === from)
+                return cs;
+            return [...others.slice(0, t), e, ...others.slice(t)];
+        });
+    }
+    // ── structural edits ────────────────────────────────────────────────
+    /** Append `v` (a value is wrapped in a fresh cell; a cell passes through).
+     *  Returns the element cell. */
+    push(v) {
+        return this.insert(v);
+    }
+    /** Insert at `at` (default: end). On a view, delegates through the view's
+     *  `insert` (a filter asserts its predicate; `map` has none, so it throws). */
+    insert(v, at) {
+        const info = views.get(this);
+        if (info) {
+            if (!info.insert)
+                throw new TypeError("Arr: this view does not support insert");
+            return info.insert(v, at);
+        }
+        const e = (v instanceof Cell ? v : cell(v));
+        const cur = this.peek();
+        const next = cur.slice();
+        if (at == null || at >= next.length)
+            next.push(e);
+        else
+            next.splice(Math.max(0, at), 0, e);
+        this._writeSource(next);
+        return e;
+    }
+    /** Remove element `e` (by reference). On a view, delegates through the
+     *  view's `remove`. */
+    remove(e) {
+        const info = views.get(this);
+        if (info) {
+            if (!info.remove)
+                throw new TypeError("Arr: this view does not support remove");
+            info.remove(e);
+            return;
+        }
+        const cur = this.peek();
+        const next = cur.filter(x => x !== e);
+        if (next.length !== cur.length)
+            this._writeSource(next);
+    }
+    /** Remove the element at index `i` in this (view's) order. */
+    removeAt(i) {
+        const e = this.peek()[i];
+        if (e)
+            this.remove(e);
+    }
+    /** Move `e` to index `to` (rounded, clamped) in this (view's) order. */
+    move(e, to) {
+        const cur = this.peek();
+        const others = cur.filter(x => x !== e);
+        const t = clampInt(to, 0, others.length);
+        this.moveBefore(e, t < others.length ? others[t] : null);
+    }
+    /** Splice `e` to just before `anchor` (or to the end when `anchor` is null).
+     *  On a base `Arr` this rewrites the reference order; on a view it delegates
+     *  through the view's `moveBefore`, where the shared `anchor` cell stays
+     *  meaningful in the base order. No-op if `e` isn't present. */
+    moveBefore(e, anchor) {
+        const info = views.get(this);
+        if (info) {
+            if (!info.moveBefore)
+                throw new TypeError("Arr: this view does not support move");
+            info.moveBefore(e, anchor);
+            return;
+        }
+        const cur = this.peek();
+        if (!cur.includes(e))
+            return;
+        const without = cur.filter(x => x !== e);
+        const ai = anchor == null ? -1 : without.indexOf(anchor);
+        const at = ai < 0 ? without.length : ai;
+        const next = [...without.slice(0, at), e, ...without.slice(at)];
+        if (!sameCells(next, cur))
+            this._writeSource(next);
+    }
+    /** Make `e` appear in this view: insert into the base if absent, then assert
+     *  each view's constraint up the chain. */
+    assertContains(e) {
+        const info = views.get(this);
+        if (info) {
+            info.assertContains?.(e);
+            return;
+        }
+        if (!this.peek().includes(e))
+            this.insert(e);
+    }
+    /** Empty the collection (a view removes only its visible elements). */
+    clear() {
+        if (views.get(this)) {
+            for (const e of [...this.peek()])
+                this.remove(e);
+            return;
+        }
+        if (this.peek().length > 0)
+            this._writeSource([]);
+    }
+    // ── views ────────────────────────────────────────────────────────────
+    /** Subset whose elements pass `pred` (which reads element values, so the
+     *  view re-derives reactively). Shares the element cells. `insert` adds to
+     *  the parent and asserts the predicate. */
+    filter(pred) {
+        const base = this;
+        const view = Arr.#view(base, cs => cs.filter(c => pred(c)));
+        views.set(view, {
+            insert: (v, at) => {
+                const e = base.insert(v, at);
+                pred.assert?.(e);
+                return e;
+            },
+            remove: e => base.remove(e),
+            moveBefore: (e, anchor) => base.moveBefore(e, anchor),
+            assertContains: e => {
+                base.assertContains(e);
+                pred.assert?.(e);
+            },
+        });
+        return view;
+    }
+    /** Projection ordered by `key` (read off each element, so it re-sorts
+     *  reactively). Shares the element cells; structural edits delegate to the
+     *  base (a `move`/`insert` repositions in the base order, not the view's). */
+    sortBy(key) {
+        const base = this;
+        const view = Arr.#view(base, cs => [...cs].sort((a, b) => key(a) - key(b)));
+        views.set(view, {
+            insert: (v, at) => base.insert(v, at),
+            remove: e => base.remove(e),
+            moveBefore: (e, anchor) => base.moveBefore(e, anchor),
+            assertContains: e => base.assertContains(e),
+        });
+        return view;
+    }
+    /** Per-element map. `f` projects each element value; with the inverse `g`
+     *  the mapped elements are writable lenses (editing one writes the source
+     *  cell), else they're read-only. Element identity is stable: one lens per
+     *  source cell, memoized. */
+    map(f, g) {
+        const fwd = new WeakMap();
+        const back = new WeakMap();
+        const lensOf = (c) => {
+            let m = fwd.get(c);
+            if (m === undefined) {
+                m = (g ? lens(c, f, (u, v) => g(u, v)) : derive(c, f));
+                fwd.set(c, m);
+                back.set(m, c);
+            }
+            return m;
+        };
+        const base = this;
+        const view = Arr.#view(base, cs => cs.map(lensOf));
+        views.set(view, {
+            remove: mc => {
+                const src = back.get(mc);
+                if (src)
+                    base.remove(src);
+            },
+            moveBefore: (mc, anchor) => {
+                const src = back.get(mc);
+                const a = anchor ? (back.get(anchor) ?? null) : null;
+                if (src)
+                    base.moveBefore(src, a);
+            },
+            assertContains: mc => {
+                const src = back.get(mc);
+                if (src)
+                    base.assertContains(src);
+            },
+        });
+        return view;
+    }
+    /** Partition by a per-element key field into derived sub-`Arr`s, one writable
+     *  filter view per bucket. `move(e, key, index)` writes the key field and
+     *  splices the base so `e` lands at `index` in its new group. `order` seeds
+     *  empty buckets and pins their order. */
+    groupBy(field, opts = {}) {
+        return new GroupArr(this, field, opts.order ?? []);
+    }
+}
+/** The result of `Arr.groupBy`: derived buckets plus a grouped `move`/`insert`
+ *  whose backward pass writes the group field and reorders the base. */
+export class GroupArr {
+    #parent;
+    #field;
+    #order;
+    #subs = new Map();
+    /** The buckets in order; tracked when read in an effect/derive. */
+    groups;
+    constructor(parent, field, order) {
+        this.#parent = parent;
+        this.#field = field;
+        this.#order = order;
+        this.groups = derive(parent, cells => this.#bucket(cells));
+    }
+    #bucket(cells) {
+        const keys = [...this.#order];
+        const seen = new Set(keys);
+        for (const c of cells) {
+            const k = this.#field(c).value;
+            if (!seen.has(k)) {
+                seen.add(k);
+                keys.push(k);
+            }
+        }
+        return keys.map(key => ({ key, items: this.#sub(key) }));
+    }
+    /** One memoized filter view per key — stable identity across re-buckets. */
+    #sub(key) {
+        let s = this.#subs.get(key);
+        if (s === undefined) {
+            const pred = c => Object.is(this.#field(c).value, key);
+            pred.assert = c => {
+                this.#field(c).value = key;
+            };
+            s = this.#parent.filter(pred);
+            this.#subs.set(key, s);
+        }
+        return s;
+    }
+    get value() {
+        return this.groups.value;
+    }
+    map(f) {
+        return derive(this.groups, gs => gs.map(f));
+    }
+    /** Place `e` in group `key` at `index` (within that group's order). Asserts
+     *  every upstream filter, writes the group field, and splices the base — one
+     *  batch, so every view re-flows once. Omit `index` to keep base order. */
+    move(e, key, index) {
+        batch(() => {
+            this.#parent.assertContains(e);
+            this.#field(e).value = key;
+            if (index != null) {
+                const members = this.#parent
+                    .peek()
+                    .filter(c => c !== e && Object.is(this.#field(c).peek(), key));
+                const t = index < 0 ? 0 : index > members.length ? members.length : index;
+                this.#parent.moveBefore(e, t < members.length ? members[t] : null);
+            }
+        });
+    }
+    /** Alias of `move`. */
+    insert(e, key, index) {
+        this.move(e, key, index);
+    }
+    /** Remove `e` from the source through the chain. */
+    remove(e) {
+        this.#parent.remove(e);
+    }
+}
+/** `field === value`, assertable by writing the field; for `filter` predicates. */
+export function is(field, value) {
+    const p = ((c) => Object.is(field(c).value, value));
+    p.assert = c => {
+        field(c).value = value;
+    };
+    return p;
+}
+/** Conjunction of cell predicates; asserts every clause. */
+export function allPass(...preds) {
+    const p = ((c) => preds.every(q => q(c)));
+    p.assert = c => {
+        for (const q of preds)
+            q.assert?.(c);
+    };
+    return p;
+}
+/** Writable `Arr<T>` from values and/or cells (values are wrapped in fresh
+ *  cells; cells pass through by identity). */
+export function arr(items = []) {
+    const cells = [...items].map(x => (x instanceof Cell ? x : cell(x)));
+    return new Arr(cells);
+}

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

@@ -1,13 +1,13 @@
 import { Cell, type Init, type Val, type Writable } from "../cell.js";
 import { Num } from "./num.js";
-/** Clip header. The graph compares `epoch`; `pcm` is one channel buffer each. */
+/** Clip header; the graph compares `epoch`. One `pcm` buffer per channel. */
 export interface AudioClip {
     readonly pcm: readonly Float32Array[];
     readonly sampleRate: number;
     readonly epoch: number;
 }
 type V = AudioClip;
-/** 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 declare const stamp: (pcm: readonly Float32Array[], sampleRate: number) => V;
 export declare const equals: (a: V, b: V) => boolean;
 export declare class Audio extends Cell<V> {
@@ -16,18 +16,17 @@ export declare class Audio extends Cell<V> {
     };
     readonly _t: typeof Audio.traits;
     constructor(v?: V);
-    /** Time-reverse every channel. Involution. */
+    /** Time-reverse every channel. */
     reverse(): this;
-    /** Scalar gain. Invertible while k ≠ 0 — the audio twin of Canvas.brightness. */
+    /** Scalar gain. Invertible while k ≠ 0. */
     gain(k: Val<number>): this;
-    /** 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?: Val<number>): Writable<Audio>;
     /** RMS loudness as a writable `Num`; writing rescales the clip to hit it. */
     rms(): Writable<Num>;
 }
-/** 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 declare function audio(v: Init<Audio>): Writable<Audio>;
 export {};

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,27 +50,25 @@ 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;
-        return Audio.lens([self], {
-            init: ([s]) => peak(s),
-            step: ([s], c, external) => (external ? peak(s) : c),
-            fwd: ([s]) => {
+        return Audio.lens(self, {
+            init: s => peak(s),
+            fwd: s => {
                 const p = peak(s);
                 return p === 0 ? s : scaled(s, tf() / p);
             },
             bwd: (view, _src, c) => {
                 const t = tf();
-                return { updates: [t === 0 ? view : scaled(view, c / t)], complement: c };
+                return { update: t === 0 ? view : scaled(view, c / t), complement: c };
             },
         });
     }
@@ -98,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 {};