bireactive 0.3.1 → 0.3.2

package/dist/core/linalg.js

@@ -1,14 +1,8 @@
-// linalg.ts — small dense linear algebra for the numerical backward
-// directions. Two callers, one kernel:
-//   - lenses: the factor/argmin pseudoinverse solves `A k = δy` where
-//     `A = J W Jᵀ + λI` is SPD by construction.
-//   - constraints: AVBD's per-cell local Newton solve, `n = cell DOF`.
-//
-// Systems are tiny (n ≤ ~12), so unrolled direct solves (n = 2, 3) and
-// in-place LDLᵀ beat anything general-purpose AND allocate nothing — the
-// matrix is destroyed, the solution is written into `b`. This replaces the
-// old full-inverse-then-multiply path (1.9–5.3× slower; allocated an
-// `n×2n` augmented buffer per write).
+// Small dense linear algebra for the numerical backward directions (the
+// factor/argmin pseudoinverse `A k = δy` with `A = J W Jᵀ + λI` SPD, and the
+// per-cell Newton solves in constraints). Systems are tiny (n ≤ ~12), so
+// unrolled solves (n = 2, 3) and in-place LDLᵀ beat anything general-purpose and
+// allocate nothing: the matrix is destroyed, the solution written into `b`.
 //
 // Convention: matrices are row-major, length `n*n`.
 const TINY = 1e-14;

package/dist/core/optic.js

@@ -1,19 +1,14 @@
-// optic.ts — lenses as first-class values, independent of any `Cell`.
+// Lenses as first-class values, independent of any `Cell`. An `Optic<A, B>` is a
+// lens transform *unbound* — a `get`/`put` pair you compose, store, and apply to
+// a source with `cell.through(optic)` (≡ `lens(cell, o.get, o.put)`). Composition
+// is ordinary lens composition: `(f ∘ g).put(c, a) = f.put(g.put(c, f.get(a)),
+// a)`, reconstructing the inner source from `a` each back-write. An `iso` is the
+// lossless case whose `put` ignores the source (`readsSource = false`), so
+// `through` can bind a cheaper 1-arg backward. No complement here — use
+// `lens(parent, spec)` when you need one.
 //
-// A `Cell` lens binds a transform to a specific source. An `Optic<A, B>` is that
-// transform *unbound* — a pair of pure functions you can compose, store, and
-// hand around, then apply to a source with `cell.through(optic)` (≡ `lens(cell,
-// o.get, o.put)`). Composition is ordinary lens composition: `(f ∘ g).put(c, a) =
-// f.put(g.put(c, f.get(a)), a)`, so the inner source is reconstructed from `a` on
-// every back-write. An `iso` is the lossless special case whose `put` ignores the
-// source (`readsSource = false`), letting `through` bind a cheaper 1-arg backward.
-//
-// This is deliberately the pure/stateless slice of the lens algebra: no
-// complement, no effects. Stateful and effectful optics-as-values are future work
-// (see _notes); for now reach for `lens(parent, spec)` when you need a complement.
-//
-// The `Optic` type lives in cell.ts (so cell.ts stays import-free and its
-// `Cell.through` can name it); this module is the constructor/algebra surface.
+// The `Optic` type lives in cell.ts so that file stays import-free and its
+// `Cell.through` can name it; this module is the constructor/algebra surface.
 function make(get, put, readsSource) {
     return {
         get,

package/dist/core/optics.js

@@ -1,11 +1,7 @@
-// optics.ts — plain-record field optics over a `Cell<T>`.
-//
-// `fieldOf` / `fieldLens` (cell.ts) project a value-class field and need the
-// field's Cell constructor, so `Vec.x` comes back as a typed `Num` carrying its
-// domain methods. For a plain record you just want `Cell<T[K]>` with the same
-// spread-replace put — `at` / `fields` supply that with full key inference and
-// no constructor argument. Both are thin sugar over `fieldOf` with the base
-// `Cell` as the result type.
+// Plain-record field optics over a `Cell<T>`. Unlike `fieldOf`/`fieldLens`
+// (cell.ts), which need the field's Cell constructor to return a typed value
+// class, `at`/`fields` return a base `Cell<T[K]>` with full key inference and no
+// constructor argument — thin sugar over `fieldOf` for plain records.
 import { Cell, fieldOf } from "./cell.js";
 export function at(c, key) {
     const ctor = Cell;

package/dist/core/store.d.ts

@@ -5,6 +5,5 @@ export type Store<T> = Writable<Cell<T>> & (T extends readonly any[] ? unknown :
     [K in keyof T]-?: Store<T[K]>;
 } : unknown);
 /** Deep, lens-backed store view of `cell`. Field access returns a nested `Store`;
- *  write through `.value` at any depth. Works over any writable cell, including a
- *  lens, so the store stays one source of truth with the rest of the graph. */
+ *  write through `.value` at any depth. */
 export declare function store<T>(cell: Writable<Cell<T>>): Store<T>;

package/dist/core/store.js

@@ -1,17 +1,10 @@
-// store.ts — a lens-backed deep store proxy over a `Cell`.
+// Deep store proxy over a `Cell`: `store(cell).a.b` is a chain of `at` field
+// lenses, so it's an ordinary `Cell` (read/write `.value`, bind in JSX, compose
+// with the graph). Writes are spread-replace puts back to the root.
 //
-// Signal libraries grow a separate `store` primitive for nested objects:
-// `store.user.name` reads a path, `setStore(...)` writes one. Here that's just
-// field lenses (`at`) under a recursive proxy — no second reactive primitive, no
-// fine-grained store engine. `store(cell).a.b` is a `Cell` (a chain of `at`
-// lenses), so it composes with everything else: read `.value`, write `.value`,
-// pass it to a component, bind it in JSX. Writes are spread-replace puts straight
-// back to the root cell, so the whole tree stays one source of truth.
-//
-// Navigation yields Stores; the leaf is written through `.value`
-// (`store.user.name.value = "x"`). A property whose name collides with the cell
-// surface below (`value`, `peek`, `lens`, `derive`, `merge`, `through`) resolves
-// to the cell member, not a field — drop to `at(cell, key)` for such a field.
+// A field whose name collides with the cell surface (`value`, `peek`, `lens`,
+// `derive`, `merge`, `through`) resolves to the cell member — use `at(cell, key)`
+// to reach such a field.
 import { at } from "./optics.js";
 // Cell members forwarded to the underlying cell rather than treated as a field,
 // plus the object protocol methods JS itself may touch.
@@ -78,8 +71,7 @@ function wrap(cell) {
     return proxy;
 }
 /** Deep, lens-backed store view of `cell`. Field access returns a nested `Store`;
- *  write through `.value` at any depth. Works over any writable cell, including a
- *  lens, so the store stays one source of truth with the rest of the graph. */
+ *  write through `.value` at any depth. */
 export function store(cell) {
     return wrap(cell);
 }

package/dist/core/traits.d.ts

@@ -41,13 +41,10 @@ export interface TraitDict<T> {
 }
 /** Valid keys of `TraitDict`. The set of declarable traits. */
 export type TraitKey = keyof TraitDict<unknown>;
-/** "A reactive whose class declares the listed traits." `_t` is a
- *  phantom slot typed against `typeof Cls.traits`; listed keys must
- *  resolve to non-null. Pure constraint — doesn't imply `Cell<T>`;
- *  intersect with `Writable<Cell<T>>` / `Read<T>` for capability.
- *
- *      function spring<T>(sig: Traits<T, "linear" | "metric">, target: Val<T>)
- *      function tween<T>(sig: Traits<T, "lerp">, target: T, dur: Val<number>) */
+/** "A reactive whose class declares the listed traits." `_t` is a phantom slot
+ *  typed against `typeof Cls.traits`; listed keys must resolve to non-null. Pure
+ *  constraint — doesn't imply `Cell<T>`; intersect with `Writable<Cell<T>>` /
+ *  `Read<T>` for capability. */
 export type Traits<T, K extends TraitKey = never> = {
     /** @internal Phantom slot; never accessed at runtime. */
     readonly _t: {

package/dist/core/traits.js

@@ -1,19 +1,15 @@
-// Traits — polymorphic interfaces declared on the class via a single
-// `static traits = { … }` dictionary. One nominal constraint type
-// `Traits<T, K>` covers any combination of required traits via a union
-// of keys (no per-trait alias proliferation):
+// Traits — polymorphic interfaces declared on a class via a single
+// `static traits = { … }` dictionary. One constraint type `Traits<T, K>` covers
+// any combination of required traits via a union of keys (no per-trait alias
+// proliferation):
 //
 //   function spring<T>(sig: Traits<T, "linear" | "metric">, target: Val<T>) …
 //   function tween<T>(sig: Traits<T, "lerp">, target: T, dur: Val<number>) …
 //
-// The dictionary shape is `TraitDict<T>`; `Traits<T, K>` is the
-// constraint consumers see. Two separate axes:
-//   - Type level: `Traits<T, K>` requires a phantom `_t` slot typed
-//     against the class's static traits (`declare readonly _t: …`).
-//   - Runtime: `requireLinear` & siblings walk `s.constructor.traits.*`.
-//
-// The engine (signal.ts) is trait-ignorant; subclasses thread equality
-// through `super(v, { equals })` themselves.
+// Two axes: at the type level `Traits<T, K>` requires a phantom `_t` slot typed
+// against the class's static traits; at runtime `requireLinear` & siblings walk
+// `s.constructor.traits.*`. The engine itself is trait-ignorant — subclasses
+// thread equality through `super(v, { equals })`.
 /** Class-level traits dictionary for any Cell subclass. */
 const dictOf = (s) => s.constructor?.traits ?? {};
 const className = (s) => s.constructor?.name ?? "?";

package/dist/core/values/anchor.js

@@ -1,7 +1,3 @@
-// anchor.ts — points on the unit box `[0,1]²` (registration on a shape).
-// dir.ts — unit direction vectors in `[-1,1]²` (displacement from rest).
-//
-// Plain constants — no reactive wrapping. Use as defaults / arguments.
 /** Anchor points on the unit box (`Center = {0.5, 0.5}`). */
 export const Anchor = {
     TopLeft: { x: 0, y: 0 },

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

@@ -0,0 +1,110 @@
+import { Cell, type Read, type Writable } from "../cell.js";
+import { Num } from "./num.js";
+/** The value of an `Arr<T>`: its element cells, in order. */
+type Elems<T> = readonly Cell<T>[];
+/** A predicate over an element cell; optional `assert(c)` makes the test pass
+ *  by writing the cell. */
+export interface CellPred<T> {
+    (c: Cell<T>): boolean;
+    assert?: (c: Cell<T>) => void;
+}
+export declare class Arr<T> extends Cell<Elems<T>> {
+    #private;
+    static traits: {
+        equals: <E>(a: readonly E[], b: readonly E[]) => boolean;
+    };
+    readonly _t: typeof Arr.traits;
+    constructor(items?: Elems<T>);
+    /** An `Arr` whose elements are derived from an external `source` and whose
+     *  structural edits rewrite that source via `ops`. */
+    static fromSource<S, R>(source: Read<S>, getter: (s: S) => Elems<R>, ops: {
+        insert?: (v: R | Cell<R>, at?: number) => Cell<R>;
+        remove?: (e: Cell<R>) => void;
+        moveBefore?: (e: Cell<R>, anchor: Cell<R> | null) => void;
+    }): Arr<R>;
+    /** The element cells in order; tracked when read in an effect/derive. */
+    get cells(): Elems<T>;
+    /** Snapshot of element values, `readonly T[]`; re-derives on any value or
+     *  structural change. Memoized per instance. */
+    get values(): Read<readonly T[]>;
+    /** Element count as a reactive `Num` (structural changes only). */
+    get length(): Num;
+    /** 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: Cell<T>): Writable<Num>;
+    /** Append `v` (a value is wrapped in a fresh cell; a cell passes through).
+     *  Returns the element cell. */
+    push(v: T | Cell<T>): Cell<T>;
+    /** 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: T | Cell<T>, at?: number): Cell<T>;
+    /** Remove element `e` (by reference). On a view, delegates through the
+     *  view's `remove`. */
+    remove(e: Cell<T>): void;
+    /** Remove the element at index `i` in this (view's) order. */
+    removeAt(i: number): void;
+    /** Move `e` to index `to` (rounded, clamped) in this (view's) order. */
+    move(e: Cell<T>, to: number): void;
+    /** 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: Cell<T>, anchor: Cell<T> | null): void;
+    /** Make `e` appear in this view: insert into the base if absent, then assert
+     *  each view's constraint up the chain. */
+    assertContains(e: Cell<T>): void;
+    /** Empty the collection (a view removes only its visible elements). */
+    clear(): void;
+    /** 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: CellPred<T>): Arr<T>;
+    /** 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: (c: Cell<T>) => number): Arr<T>;
+    /** 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<U>(f: (v: T) => U, g?: (u: U, v: T) => T): Arr<U>;
+    /** 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<K>(field: (e: Cell<T>) => Writable<Cell<K>>, opts?: {
+        order?: readonly K[];
+    }): GroupArr<K, T>;
+}
+/** One bucket of a `groupBy`: its key and the derived sub-`Arr` of members. */
+export interface Group<K, T> {
+    key: K;
+    items: Arr<T>;
+}
+/** The result of `Arr.groupBy`: derived buckets plus a grouped `move`/`insert`
+ *  whose backward pass writes the group field and reorders the base. */
+export declare class GroupArr<K, T> {
+    #private;
+    /** The buckets in order; tracked when read in an effect/derive. */
+    readonly groups: Read<readonly Group<K, T>[]>;
+    constructor(parent: Arr<T>, field: (e: Cell<T>) => Writable<Cell<K>>, order: readonly K[]);
+    get value(): readonly Group<K, T>[];
+    map<F>(f: (g: Group<K, T>) => F): Read<readonly 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: Cell<T>, key: K, index?: number): void;
+    /** Alias of `move`. */
+    insert(e: Cell<T>, key: K, index?: number): void;
+    /** Remove `e` from the source through the chain. */
+    remove(e: Cell<T>): void;
+}
+/** `field === value`, assertable by writing the field; for `filter` predicates. */
+export declare function is<T, V>(field: (e: Cell<T>) => Writable<Cell<V>>, value: V): CellPred<T>;
+/** Conjunction of cell predicates; asserts every clause. */
+export declare function allPass<T>(...preds: readonly CellPred<T>[]): CellPred<T>;
+/** Writable `Arr<T>` from values and/or cells (values are wrapped in fresh
+ *  cells; cells pass through by identity). */
+export declare function arr<T>(items?: Iterable<T | Cell<T>>): Writable<Arr<T>>;
+export {};

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 {};