bireactive 0.3.0 → 0.3.2

package/dist/core/lenses/text.js

@@ -0,0 +1,202 @@
+import { Str } from "../values/str.js";
+// ── word parsing ─────────────────────────────────────────────────────
+/** A "word" character: letters, digits, underscore, apostrophe, hyphen
+ *  (handles "don't", "co-op"). Everything else is a separator. */
+const WORD_CHAR = /[\p{L}\p{N}_'-]/u;
+/** Split `s` into words and separators. Returns:
+ *
+ *    words[i] — the i-th run of word characters
+ *    seps[0]  — leading non-word characters (possibly empty)
+ *    seps[i]  — for 1 ≤ i ≤ words.length-1, the separator BETWEEN
+ *               `words[i-1]` and `words[i]`
+ *    seps[words.length] — trailing non-word characters
+ *
+ *  Always satisfies `seps.length === words.length + 1`. */
+export function parseWords(s) {
+    const words = [];
+    const seps = [];
+    let cur = "";
+    let inWord = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (WORD_CHAR.test(c)) {
+            if (!inWord) {
+                seps.push(cur);
+                cur = "";
+                inWord = true;
+            }
+            cur += c;
+        }
+        else {
+            if (inWord) {
+                words.push(cur);
+                cur = "";
+                inWord = false;
+            }
+            cur += c;
+        }
+    }
+    if (inWord) {
+        words.push(cur);
+        seps.push("");
+    }
+    else {
+        seps.push(cur);
+    }
+    return { words, seps };
+}
+/** Inverse of `parseWords`. Interleaves words with `seps`; added words
+ *  get `" "` gaps, removed words keep the original trailing separator.
+ *  A zero-word original (`seps.length === 1`) treats its one entry as
+ *  lead only, so words append after it without double-counting as trail. */
+export function rebuildWords(words, seps) {
+    const n = words.length;
+    if (n === 0)
+        return seps[0] ?? "";
+    const lead = seps[0] ?? "";
+    const trail = seps.length > 1 ? (seps[seps.length - 1] ?? "") : "";
+    let out = lead;
+    for (let i = 0; i < n; i++) {
+        out += words[i];
+        if (i < n - 1) {
+            const idx = i + 1;
+            // Interior separators only; the final `seps` entry is the trail.
+            const sep = idx < seps.length - 1 ? seps[idx] : undefined;
+            out += sep !== undefined ? sep : " ";
+        }
+        else {
+            out += trail;
+        }
+    }
+    return out;
+}
+// ── case masks ───────────────────────────────────────────────────────
+/** Per-character case mask: `U` upper letter, `L` lower letter,
+ *  `" "` non-letter. Length matches the source. */
+export function caseMaskOf(s) {
+    let mask = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c >= "A" && c <= "Z")
+            mask += "U";
+        else if (c >= "a" && c <= "z")
+            mask += "L";
+        else
+            mask += " ";
+    }
+    return mask;
+}
+/** Apply a case mask to `target`, position by position. Mask positions
+ *  beyond `target.length` are ignored; target positions beyond the
+ *  mask keep their native case (e.g. user appended a longer word). */
+export function applyCaseMask(target, mask) {
+    let out = "";
+    for (let i = 0; i < target.length; i++) {
+        const c = target[i];
+        const m = i < mask.length ? mask[i] : " ";
+        if (m === "U")
+            out += c.toUpperCase();
+        else if (m === "L")
+            out += c.toLowerCase();
+        else
+            out += c;
+    }
+    return out;
+}
+const ASCII_LETTER = (c) => (c >= "a" && c <= "z") || (c >= "A" && c <= "Z");
+/** Apply the case pattern of a source word to a target word. Detects
+ *  all-upper / all-lower / title case, else falls back to position-wise
+ *  `applyCaseMask`. Non-letter target chars always pass through unchanged
+ *  (title-casing "-gng" → "-Gng"). */
+export function applyCasePattern(target, mask) {
+    if (target.length === 0 || mask.length === 0)
+        return target;
+    const letters = [...mask].filter(c => c === "U" || c === "L");
+    if (letters.length === 0)
+        return target;
+    if (letters.every(c => c === "U"))
+        return target.toUpperCase();
+    if (letters.every(c => c === "L"))
+        return target.toLowerCase();
+    if (letters[0] === "U" && letters.slice(1).every(c => c === "L")) {
+        // Title case: uppercase the first letter (skipping leading
+        // non-letters), lowercase the rest, pass non-letters through.
+        let out = "";
+        let firstLetterDone = false;
+        for (let i = 0; i < target.length; i++) {
+            const c = target[i];
+            if (ASCII_LETTER(c)) {
+                out += firstLetterDone ? c.toLowerCase() : c.toUpperCase();
+                firstLetterDone = true;
+            }
+            else {
+                out += c;
+            }
+        }
+        return out;
+    }
+    return applyCaseMask(target, mask);
+}
+/** (Re)build the case complement: positional `wordMasks` and content-keyed
+ *  `byContent` in one pass. `byContent` lists stay in source order for FIFO
+ *  consumption on write-back. */
+function refreshCaseComplement(s, c) {
+    const { words } = parseWords(s);
+    const wordMasks = words.map(caseMaskOf);
+    const byContent = new Map();
+    for (let i = 0; i < words.length; i++) {
+        const key = words[i].toLowerCase();
+        let list = byContent.get(key);
+        if (list === undefined) {
+            list = [];
+            byContent.set(key, list);
+        }
+        list.push(wordMasks[i]);
+    }
+    c.wordMasks = wordMasks;
+    c.byContent = byContent;
+}
+/** Apply the case complement to a target string and rebuild. Each
+ *  target word goes through three lookup tiers — content match
+ *  (FIFO-consumed from a per-call clone), positional fallback, then
+ *  native pass-through. */
+function applyCaseComplement(target, c) {
+    const { words, seps } = parseWords(target);
+    // Per-call clone: consume FIFO without mutating the stored map, so
+    // repeated writes start from the same state.
+    const remaining = new Map();
+    for (const [k, list] of c.byContent)
+        remaining.set(k, list.slice());
+    const cased = words.map((w, i) => {
+        const key = w.toLowerCase();
+        const matches = remaining.get(key);
+        if (matches !== undefined && matches.length > 0) {
+            return applyCasePattern(w, matches.shift());
+        }
+        const mask = i < c.wordMasks.length ? c.wordMasks[i] : "";
+        return mask.length === 0 ? w : applyCasePattern(w, mask);
+    });
+    return rebuildWords(cased, seps);
+}
+function buildCaseComplement(s) {
+    const c = { wordMasks: [], byContent: new Map() };
+    refreshCaseComplement(s, c);
+    return c;
+}
+// ── caseFold ─────────────────────────────────────────────────────────
+/** Case-folded view of a string cell with word-aware case recovery on
+ *  write. Read folds to lower (default) or upper; write recovers the
+ *  source's per-word case — lookup priority: (1) content match (FIFO
+ *  across duplicates); (2) per-position fallback for new content; (3)
+ *  native for content beyond the source structure. */
+export function caseFold(parent, to = "lower") {
+    const fold = to === "upper" ? (s) => s.toUpperCase() : (s) => s.toLowerCase();
+    return Str.lens(parent, {
+        init: (s) => buildCaseComplement(s),
+        fwd: (s) => fold(s),
+        bwd: (target, _s, c) => ({
+            update: applyCaseComplement(target, c),
+            complement: c,
+        }),
+    });
+}

package/dist/core/lifecycle.js

@@ -1,9 +1,6 @@
-// lifecycle.ts — reactive-collection lifecycle helpers over the
-// `network` model. Implemented purely via `effect`:
-//
-//   `each(source, body)` — body runs per element (keyed by reference
-//                          identity); cleanup on removal.
-//   `when(source, body)` — body runs while truthy; cleanup on falsy.
+// Reactive-collection lifecycle helpers, implemented via `effect`: `each` runs a
+// body per element (keyed by reference identity) with cleanup on removal; `when`
+// runs a body while truthy with cleanup on falsy.
 import { effect } from "./cell.js";
 /** Run `body(item)` per element on first sight (storing its cleanup) and
  *  run that cleanup when the element leaves. Identity is element

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.d.ts

@@ -0,0 +1,13 @@
+import type { Optic } from "./cell.js";
+/** Build an optic from a forward and a backward. A 2-arg `put(b, a)` reads the
+ *  source; a 1-arg `put(b)` reconstructs it (and is treated as an `iso`). */
+export declare function optic<A, B>(get: (a: A) => B, put: (b: B, a: A) => A): Optic<A, B>;
+/** A lossless, source-independent optic (an isomorphism): `to`/`from` invert. */
+export declare function iso<A, B>(to: (a: A) => B, from: (b: B) => A): Optic<A, B>;
+/** Field optic: project key `K`, putting back with a spread-replace. */
+export declare function atKey<T, K extends keyof T>(key: K): Optic<T, T[K]>;
+/** Compose optics left-to-right into one: `compose(a, b, c)` is `a` then `b` then
+ *  `c`. Typed for up to three; falls back to `Optic<unknown, unknown>` beyond. */
+export declare function compose<A, B>(a: Optic<A, B>): Optic<A, B>;
+export declare function compose<A, B, C>(a: Optic<A, B>, b: Optic<B, C>): Optic<A, C>;
+export declare function compose<A, B, C, D>(a: Optic<A, B>, b: Optic<B, C>, c: Optic<C, D>): Optic<A, D>;

package/dist/core/optic.js

@@ -0,0 +1,39 @@
+// 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.
+//
+// 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,
+        put,
+        readsSource,
+        through(next) {
+            // Composed backward reconstructs the inner B from the outer A, so it always
+            // reads the source regardless of either side's own `readsSource`.
+            return make(a => next.get(get(a)), (c, a) => put(next.put(c, get(a)), a), true);
+        },
+    };
+}
+/** Build an optic from a forward and a backward. A 2-arg `put(b, a)` reads the
+ *  source; a 1-arg `put(b)` reconstructs it (and is treated as an `iso`). */
+export function optic(get, put) {
+    return make(get, put, put.length >= 2);
+}
+/** A lossless, source-independent optic (an isomorphism): `to`/`from` invert. */
+export function iso(to, from) {
+    return make(to, b => from(b), false);
+}
+/** Field optic: project key `K`, putting back with a spread-replace. */
+export function atKey(key) {
+    return make(t => t[key], (v, t) => ({ ...t, [key]: v }), true);
+}
+export function compose(...optics) {
+    return optics.reduce((a, b) => a.through(b));
+}

package/dist/core/optics.d.ts

@@ -0,0 +1,10 @@
+import { Cell, type Read, type Writable } from "./cell.js";
+/** Writable field view of `c.value[key]` (spread-replace put). A read-only
+ *  parent yields a read-only view. */
+export declare function at<T, K extends keyof T>(c: Writable<Cell<T>>, key: K): Writable<Cell<T[K]>>;
+export declare function at<T, K extends keyof T>(c: Read<T>, key: K): Cell<T[K]>;
+/** Lens view of every field, lazily and memoized — `const { r, g, b } =
+ *  fields(rgb)` yields one writable `at` per key. */
+export declare function fields<T extends object>(c: Writable<Cell<T>>): {
+    [K in keyof T]-?: Writable<Cell<T[K]>>;
+};

package/dist/core/optics.js

@@ -0,0 +1,26 @@
+// 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;
+    return fieldOf(c, key, ctor);
+}
+/** Lens view of every field, lazily and memoized — `const { r, g, b } =
+ *  fields(rgb)` yields one writable `at` per key. */
+export function fields(c) {
+    const cache = new Map();
+    return new Proxy(Object.create(null), {
+        get(_t, key) {
+            if (typeof key === "symbol")
+                return undefined;
+            let v = cache.get(key);
+            if (v === undefined) {
+                v = at(c, key);
+                cache.set(key, v);
+            }
+            return v;
+        },
+    });
+}

package/dist/core/store.d.ts

@@ -0,0 +1,9 @@
+import type { Cell, Writable } from "./cell.js";
+/** Deep store view: the cell itself, plus a `Store` per object field. Primitives
+ *  and functions bottom out at the plain `Writable<Cell<T>>`. */
+export type Store<T> = Writable<Cell<T>> & (T extends readonly any[] ? unknown : T extends (...args: any[]) => any ? unknown : T extends object ? {
+    [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. */
+export declare function store<T>(cell: Writable<Cell<T>>): Store<T>;

package/dist/core/store.js

@@ -0,0 +1,77 @@
+// 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.
+//
+// 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.
+const FORWARD = new Set([
+    "value",
+    "peek",
+    "lens",
+    "derive",
+    "merge",
+    "through",
+    "toString",
+    "valueOf",
+    "toJSON",
+    "constructor",
+]);
+// One proxy per cell, so `store(c).a === store(c).a` and child stores are stable.
+const wrapped = new WeakMap();
+function wrap(cell) {
+    const hit = wrapped.get(cell);
+    if (hit !== undefined)
+        return hit;
+    // Per-key field lenses and their child stores, both memoized.
+    const lensFor = new Map();
+    const fieldLens = (key) => {
+        let l = lensFor.get(key);
+        if (l === undefined) {
+            l = at(cell, key);
+            lensFor.set(key, l);
+        }
+        return l;
+    };
+    const childStores = new Map();
+    const proxy = new Proxy(cell, {
+        get(target, key) {
+            if (typeof key === "symbol" || FORWARD.has(key)) {
+                const v = target[key];
+                return typeof v === "function" ? v.bind(target) : v;
+            }
+            if (key === "then")
+                return undefined; // never a thenable
+            let s = childStores.get(key);
+            if (s === undefined) {
+                s = wrap(fieldLens(key));
+                childStores.set(key, s);
+            }
+            return s;
+        },
+        set(target, key, value) {
+            if (typeof key === "symbol" || FORWARD.has(key)) {
+                target[key] = value;
+                return true;
+            }
+            fieldLens(key).value = value;
+            return true;
+        },
+        has(target, key) {
+            if (typeof key === "symbol" || FORWARD.has(key))
+                return true;
+            const v = target.peek();
+            return typeof v === "object" && v !== null && key in v;
+        },
+    });
+    wrapped.set(cell, proxy);
+    return proxy;
+}
+/** Deep, lens-backed store view of `cell`. Field access returns a nested `Store`;
+ *  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 {};