bireactive 0.2.4 → 0.3.0

package/dist/animation/anim.js

@@ -11,6 +11,7 @@
 //
 //   T (generic), if the suspend is `(wake, spawn) => T`
 //   Example: `const result = yield (wake, spawn) => { ... }`
+import { settle } from "../core/cell.js";
 /** Cut sentinel — return `cut(v)` from a concurrent kid to settle the
  *  enclosing group with `v` and cancel siblings. Outside a group, the
  *  sentinel is transparently unwrapped to `v`. */
@@ -77,6 +78,9 @@ export class Anim {
                 }
             }
         }
+        // A frame advances reactive state; flush the effects it woke so observers
+        // (and the next frame) see this frame's results synchronously.
+        settle();
     }
     stepInner(dt) {
         if (dt > 0 && Number.isFinite(dt))

package/dist/coll.d.ts

@@ -1,7 +1,7 @@
 import { type Cell, type Read, type Writable } from "./core/index.js";
 /** Accessor for an element's writable field cell. Forward reads `.value`;
  *  the backward pass writes it. */
-export type Field<E, V> = (e: E) => Writable<Cell<V>>;
+export type Accessor<E, V> = (e: E) => Writable<Cell<V>>;
 /** A forward test over an element's fields, optionally assertable —
  *  `assert(e)` makes the test pass by writing fields. */
 export interface FieldPred<E> {
@@ -16,10 +16,10 @@ export interface GroupOpts<E, K> {
     /** Fixed key order; seeds empty buckets and pins column order. */
     order?: readonly K[];
     /** Order field within each group; enables `move(e, key, index)`. */
-    sort?: Field<E, number>;
+    sort?: Accessor<E, number>;
 }
 /** `field === value`, assertable by writing the field. */
-export declare function is<E, V>(field: Field<E, V>, value: V): FieldPred<E>;
+export declare function is<E, V>(field: Accessor<E, V>, value: V): FieldPred<E>;
 /** Conjunction; asserts every clause. */
 export declare function allPass<E>(...preds: readonly FieldPred<E>[]): FieldPred<E>;
 /** Read-only projection with chainable structural lenses. */
@@ -36,8 +36,8 @@ export declare class View<E> {
     assertContains(e: E): void;
     protected assertSelf(_e: E): void;
     filter(pred: FieldPred<E>): View<E>;
-    sortBy(field: Field<E, number>): SortView<E>;
-    groupBy<K>(field: Field<E, K>, opts?: GroupOpts<E, K>): GroupView<K, E>;
+    sortBy(field: Accessor<E, number>): SortView<E>;
+    groupBy<K>(field: Accessor<E, K>, opts?: GroupOpts<E, K>): GroupView<K, E>;
     map<F>(f: (e: E) => F): Read<readonly F[]>;
     /** Remove `e` from the source. */
     remove(e: E): void;
@@ -53,7 +53,7 @@ export declare class Coll<E> extends View<E> {
 /** Sorted view. `move` writes the order field between the drop neighbours. */
 export declare class SortView<E> extends View<E> {
     #private;
-    constructor(parent: View<E>, field: Field<E, number>);
+    constructor(parent: View<E>, field: Accessor<E, number>);
     move(e: E, to: number): void;
 }
 /** Grouped view. `move`/`insert` write the group field (and, with a `sort`
@@ -61,7 +61,7 @@ export declare class SortView<E> extends View<E> {
 export declare class GroupView<K, E> {
     #private;
     readonly groups: Read<readonly Group<K, E>[]>;
-    constructor(parent: View<E>, field: Field<E, K>, opts?: GroupOpts<E, K>);
+    constructor(parent: View<E>, field: Accessor<E, K>, opts?: GroupOpts<E, K>);
     get value(): readonly Group<K, E>[];
     map<F>(f: (g: Group<K, E>) => F): Read<readonly F[]>;
     /** Place `e` in group `toKey` at `index`. Inserts it into the source if

package/dist/core/cell.d.ts

@@ -1,3 +1,19 @@
+/** Multi-out / stateful back-write sentinel: "leave this parent untouched."
+ *  A `bwd` returning per-parent updates yields `SKIP` for a parent it declines
+ *  to write; every other slot value is written verbatim — INCLUDING `undefined`,
+ *  which is a first-class cell value, not a hole. A SHORT array skips the trailing
+ *  parents (so writing only the leading few needs no `SKIP` padding); `[]` skips
+ *  all. (Single-out 1→1 `put` has no skip notion: it always writes its one parent,
+ *  so it stays `undefined`-safe by construction.) */
+export declare const SKIP: unique symbol;
+export type Skip = typeof SKIP;
+/** Per-parent back-write result over parents `T`: any PREFIX of the full update
+ *  tuple. A shorter array skips the trailing parents; each present slot is a
+ *  value or `SKIP`. For a fixed tuple this is the prefix union, so `[a]` /
+ *  `[a, SKIP]` / `[]` all type against `[A, B]` while a bare `undefined` in a
+ *  non-undefined slot stays an error (the footgun the `SKIP`/short-array split
+ *  removes); for a variable-length array of parents it's just that array. */
+export type BackUpdates<T extends readonly unknown[]> = number extends T["length"] ? T : T extends readonly [infer H, ...infer R] ? readonly [] | readonly [H, ...BackUpdates<R>] : readonly [];
 interface ReactiveNode {
     flags: number;
     deps: Link | undefined;
@@ -19,39 +35,28 @@ interface Link {
 }
 /** Install a hook fired on every source value-change; returns a restore fn. */
 export declare function setCellWriteHook(fn: ((cell: Cell<unknown>) => void) | undefined): () => void;
-export interface MergePolicy<T> {
-    readonly identity: T;
-    combine(acc: T, x: T): T;
-    /** Optional inverse for incremental fold. */
-    remove?(acc: T, x: T): T;
-}
-export declare const DIRECT_SLOT: unique symbol;
+export type MergeFold<T> = (values: readonly T[]) => T;
 declare class MergeNode<T> {
-    readonly parent: Cell<T>;
-    readonly policy: MergePolicy<T>;
-    readonly slots: Map<unknown, T>;
-    readonly hasIncrementalAcc: boolean;
-    acc: T;
-    constructor(parent: Cell<T>, policy: MergePolicy<T>);
-    receive(slot: unknown, next: T): void;
-    fold(): T;
-    reset(): void;
+    readonly foldFn: MergeFold<T> | undefined;
+    /** Contributions gathered as this merge's cone resolves; folded and cleared
+     *  in `foldMerge` (the merge-owned buffer, mutated in place). The parent it
+     *  writes to is just `b.parent` (a merge's `b.parent` IS its fold target), so
+     *  this node carries only the policy + buffer — no duplicate edge. */
+    contributions: T[];
+    constructor(fold: MergeFold<T> | undefined);
 }
 declare class BwdSpec {
     /** Backward target(s): one `Cell` (1→1 / merge) or `Cell[]` (multi-out). */
     parent: Cell<unknown> | Cell<unknown>[] | undefined;
-    /** Lens `put` — backward derivation (dual of `getter`). Always called by
-     *  the engine in 1-arg form `put(target)`; a source-reading lens bakes
-     *  `settled(parent)` into this closure at build time. Multi-output:
-     *  returns a per-parent update array. Stateful: the spec's `bwd`. */
+    /** Lens `put` — backward derivation (dual of `getter`). A 1→1 / multi-out
+     *  lens is called as `put(target)` (a source-reading lens reads the current
+     *  parent(s) at walk time, untracked); multi-out returns a per-parent update
+     *  array. Stateful is the spec's `bwd`, called `put(target, sources, c)`. */
     put: ((target: any, current?: any) => any) | undefined;
     /** Backward aggregation node; presence IS the merge-mode discriminant. */
     merge: MergeNode<unknown> | undefined;
     /** Complement machinery; presence IS the stateful-mode discriminant. */
     stateful: StatefulCore | undefined;
-    /** Index in `bwdQueue` of this cell's latest push; the drain skips stale
-     *  entries so each cell propagates backward once per flush, last-write. */
-    queueIdx: number;
 }
 /** Runtime state of a stateful (complement-carrying) lens — the rare
  *  backward mode, kept off `BwdSpec` so plain lenses don't carry its slots.
@@ -60,14 +65,17 @@ declare class BwdSpec {
 declare class StatefulCore {
     /** Engine-owned memory the view discards. */
     complement: unknown;
-    /** Forward projection `fwd(sources, complement) → view`. */
-    fwd: (sources: any, complement: any) => any;
-    /** Advance the complement: `step(sources, complement, external)`. */
+    /** Advance the complement: `step(sources, complement, external)`. (The
+     *  forward projection `fwd` is captured directly in the getter closure — it
+     *  is only ever read there — so it costs no slot here.) */
     step: (sources: any, complement: any, external: boolean) => any;
-    /** Source values last written back (own-vs-external test); `undefined`
-     *  until the first back-write. */
-    lastBwd: unknown[] | undefined;
-    constructor(complement: unknown, fwd: (sources: any, complement: any) => any, step: (sources: any, complement: any, external: boolean) => any);
+    /** Sources this lens last committed back (the own-vs-external test compares
+     *  live sources against these); `undefined` until the first back-write. A
+     *  back-write reads the live sources into a fresh array, builds the committed
+     *  candidate in place, and keeps it as `last` for the next own-vs-external
+     *  comparison. */
+    last: unknown[] | undefined;
+    constructor(complement: unknown, step: (sources: any, complement: any, external: boolean) => any);
 }
 /** Plain T or any read-shape; snapshot via `readNow`, close via `reader`. */
 export type Val<T> = T | Read<T>;
@@ -110,52 +118,58 @@ export interface CellOptions<T = unknown> {
     equals?: (a: T, b: T) => boolean;
 }
 export declare class Cell<T = unknown> implements ReactiveNode {
+    /** @internal */
     flags: number;
+    /** @internal */
     subs: Link | undefined;
+    /** @internal */
     subsTail: Link | undefined;
+    /** @internal */
     deps: Link | undefined;
+    /** @internal */
     depsTail: Link | undefined;
-    /** Forward derivation (computed/lens/merge). `undefined` ⇒ source. */
+    /** @internal Forward derivation (computed/lens/merge). `undefined` ⇒ source. */
     getter: (() => T) | undefined;
-    /** Per-instance equality, always defined (defaults to `Object.is` at
-     *  construction) so hot paths call it without an `undefined` branch. */
+    /** @internal Per-instance equality; always defined (defaults to `Object.is`). */
     _equals: (a: T, b: T) => boolean;
-    /** First-subscriber / last-subscriber lifecycle hooks. */
+    /** @internal First-subscriber / last-subscriber lifecycle hooks. */
     _watched: (() => void) | undefined;
+    /** @internal */
     _unwatchedHook: (() => void) | undefined;
-    /** Source: `currentValue` = committed, `pendingValue` = staged write.
-     *  Getter cell: `currentValue` = last derived cache, `pendingValue`
-     *  reused as the deferred backward target (see `set value`). The two
-     *  roles never coexist, so two fields suffice for four. */
+    /** @internal Source: committed value + staged write. */
     currentValue: T;
+    /** @internal */
     pendingValue: T;
-    /** Backward sidecar: target(s) + lens closures + queue slot, or
-     *  `undefined` for a read-only cell (source or computed). Allocated only
-     *  for writable derived cells, keeping the common node lean. Writability
-     *  is exactly `_bwd !== undefined`. See `BwdSpec`. */
+    /** @internal Backward sidecar; `undefined` iff read-only. Writability is `_bwd !== undefined`. */
     _bwd: BwdSpec | undefined;
+    /** @internal Backward dual of `subs`: direct lens-children for back-write cone traversal. */
+    _lensSubs: Cell<unknown>[] | undefined;
+    /** @internal Backward flag word (`BF`), dual of forward `flags`. */
+    bflags: number;
+    /** @internal Guards against `linkBack` re-registering a duplicate in `_lensSubs`. */
+    _linkedBack: boolean;
     constructor(initial: T, opts?: CellOptions<T>);
     readonly value: T;
-    _enqueueBwd(): void;
-    /** Source write (alien's signal setter). Self-excludes the active
-     *  network so a body writing its own dep doesn't re-trigger itself. */
+    /** @internal Single write-commit point; self-excludes the active network. */
     _writeSource(next: T): void;
+    /** @internal */
     _update(): boolean;
+    /** @internal */
     _notify(): void;
+    /** @internal */
     _unwatched(): void;
     peek(): T;
-    /** Guard: silent coercion to string/number is almost always a bug. */
-    [Symbol.toPrimitive](hint: string): never;
     /** Endomorphic lens. A 2-arg `bwd(view, current)` consults the current
      *  source; a 1-arg `bwd(view)` reconstructs it from the view alone. */
     lens(this: Cell<T>, fwd: (v: T) => T, bwd: (target: T, current: T) => T): this;
     /** Read-only same-type view: the RO dual of the endo `.lens`. For a cross-type view use the typed static
      *  `Target.derive(src, fn)`. */
     derive(this: Cell<T>, fn: (v: T) => T): this;
-    /** Backward-aggregating node — bwd dual of computed. Forward, the
-     *  identity view of its parent; backward, folds contributions from
-     *  upstream lenses (slot-keyed) and direct writes (DIRECT_SLOT). */
-    merge(this: Cell<T>, policy: MergePolicy<T>): Cell<T>;
+    /** Backward fan-in node. Forward, the identity view of its parent;
+     *  backward, the convergence point where N contributors (upstream lenses
+     *  and direct writes) fold into one value for the parent. `fold` is handed
+     *  every live push at once; omitted, it is last-writer-wins. */
+    merge(this: Cell<T>, fold?: MergeFold<T>): Cell<T>;
     /** Read-only typed view. `Cls.derive(parent, fn)` (1-input),
      *  `Cls.derive(parents, fn)` (N-input), or `Cls.derive(fn)` (closure).
      *  Polymorphic-`this`: `Vec.derive(...)` → `Vec`. */
@@ -173,9 +187,9 @@ export declare class Cell<T = unknown> implements ReactiveNode {
         [K in keyof P]: P[K] extends Read<infer V> ? V : never;
     }) => Inner<InstanceType<C>>, bwd: (target: Inner<InstanceType<C>>, vals: {
         [K in keyof P]: P[K] extends Read<infer V> ? V : never;
-    }) => {
-        [K in keyof P]?: P[K] extends Read<infer V> ? V : never;
-    }): Writable<InstanceType<C>>;
+    }) => BackUpdates<{
+        [K in keyof P]: (P[K] extends Read<infer V> ? V : never) | Skip;
+    }>): Writable<InstanceType<C>>;
     static lens<C extends new (...args: never[]) => Cell<any>, P, Cm>(this: C, parent: Read<P>, spec: StatefulLensSpec<readonly [P], Inner<InstanceType<C>>, Cm>): Writable<InstanceType<C>>;
     static lens<C extends new (...args: never[]) => Cell<any>, P extends readonly Read<unknown>[], Cm>(this: C, parents: P, spec: StatefulLensSpec<{
         [K in keyof P]: P[K] extends Read<infer V> ? V : never;
@@ -183,21 +197,22 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     /** Type predicate against this class: `Vec.is(x)` narrows `x` to `Vec`.
      *  Inherited static; works for any subclass via polymorphic `this`. */
     static is<C extends new (...args: never[]) => Cell<any>>(this: C, v: unknown): v is InstanceType<C>;
-    /** Lift `Val<Inner<Cls>>` → `Cls`: instance → identity, RO cell →
+    /** Coerce `Val<Inner<Cls>>` → `Cls`: instance → identity, RO cell →
      *  tracked `derive`, literal → fresh seed. */
-    static from<C extends new (...args: never[]) => Cell<any>>(this: C, v: Val<Inner<InstanceType<C>>>): InstanceType<C>;
+    static coerce<C extends new (...args: never[]) => Cell<any>>(this: C, v: Val<Inner<InstanceType<C>>>): InstanceType<C>;
     /** Writable-shaped constant: always reads `v`, absorbs writes
      *  (parentless sink lens), for APIs demanding bidirectionality. */
     static pin<C extends new (...args: never[]) => Cell<any>>(this: C, v: Inner<InstanceType<C>>): Writable<InstanceType<C>>;
-    /** Typed field lens onto `parent.value[key]`. A read-only computed
-     *  parent yields a RO derive view; any writable parent yields a
-     *  bidirectional field lens with spread-replace `put`. */
-    static fieldOf<C extends new (...args: never[]) => Cell<any>>(parent: Cell<any>, key: string | number | symbol, Cls: C): InstanceType<C>;
 }
+/** Typed field lens onto `parent.value[key]`. RO parent → RO derive;
+ *  writable parent → bidirectional lens with spread-replace `put`. */
+export declare function fieldOf<C extends new (...args: never[]) => Cell<any>>(parent: Cell<any>, key: string | number | symbol, Cls: C): InstanceType<C>;
 export interface StatefulBwd<S extends readonly unknown[], C> {
-    updates: {
-        readonly [K in keyof S]: S[K] | undefined;
-    };
+    /** Per-parent updates: a value (written verbatim, `undefined` included) or
+     *  `SKIP` to leave that parent. A short array skips the trailing parents. */
+    updates: BackUpdates<{
+        [K in keyof S]: S[K] | Skip;
+    }>;
     complement: C;
 }
 export interface StatefulLensSpec<S extends readonly unknown[], V, C> {
@@ -224,13 +239,21 @@ export declare function lens<P extends readonly Read<unknown>[], R>(parents: P,
 }) => R, bwd: (target: R, vals: {
     [K in keyof P]: P[K] extends Read<infer V> ? V : never;
 }) => {
-    [K in keyof P]?: P[K] extends Read<infer V> ? V : never;
+    [K in keyof P]: (P[K] extends Read<infer V> ? V : never) | Skip;
 }): Writable<Cell<R>>;
 export declare function lens<P, R, C>(parent: Read<P>, spec: StatefulLensSpec<readonly [P], R, C>): Writable<Cell<R>>;
 export declare function lens<P extends readonly Read<unknown>[], R, C>(parents: P, spec: StatefulLensSpec<{
     [K in keyof P]: P[K] extends Read<infer V> ? V : never;
 }, R, C>): Writable<Cell<R>>;
 export declare function effect(fn: () => (() => void) | void): () => void;
+/** Run all pending effects NOW, synchronously. The escape hatch for code (tests,
+ *  imperative call sites) that must observe effect side-effects before yielding
+ *  to the microtask queue. Reads never need it — they pull current values. */
+export declare function settle(): void;
+/** Group writes and flush effects SYNCHRONOUSLY at the end of `fn` — a sync
+ *  barrier. Effects coalesce on the microtask turn anyway (see `schedule`), so
+ *  `batch` is no longer needed for that; reach for it only when you must run the
+ *  woken effects before the call returns (and don't want a `settle()`). */
 export declare function batch<R>(fn: () => R): R;
 export declare function untracked<R>(fn: () => R): R;
 /** Handle to a `network` invocation. */
@@ -257,8 +280,8 @@ export declare function network(deps: readonly Cell<any>[], body: (dirty: Readon
  *  replaces the composite. Cached per (instance, key). Return type is
  *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO.
  *
- *      get x() { return field(this, "x", Num); } */
-export declare function field<S extends Cell<any>, K extends keyof Inner<S>, C extends new (...args: never[]) => Cell<Inner<S>[K]>>(parent: S, key: K, Cls: C): S extends WritableBrand ? Writable<InstanceType<C>> : InstanceType<C>;
+ *      get x() { return fieldLens(this, "x", Num); } */
+export declare function fieldLens<S extends Cell<any>, K extends keyof Inner<S>, C extends new (...args: never[]) => Cell<Inner<S>[K]>>(parent: S, key: K, Cls: C): S extends WritableBrand ? Writable<InstanceType<C>> : InstanceType<C>;
 /** Read-only derived view via `Cls.derive(parent, fn)`, memoized per
  *  (instance, key); always bare `Cls` (RO). The cache is the point — the
  *  getter form, not a new kind of cell.