bireactive 0.3.3 → 0.3.5

package/dist/automerge/apply-patches.d.ts

@@ -0,0 +1,4 @@
+import type { Patch } from "@automerge/automerge-repo";
+/** Rebuild `prev` to match the post-change doc `after`, cloning only the spine to
+ *  each patched value and sharing every untouched subtree by reference. */
+export declare function applyPatches<T extends object>(prev: T, patches: Patch[], after: T): T;

package/dist/automerge/apply-patches.js

@@ -0,0 +1,62 @@
+// apply-patches.ts — doc → cell incremental invalidation.
+//
+// The naive bridge re-snapshots the whole doc on every change
+// (`structuredClone(handle.doc())`), giving every sub-object a fresh identity, so
+// every field lens recomputes even where nothing changed. `applyPatches` instead
+// walks the Automerge `change` patches and rebuilds only the spine to each changed
+// value: ancestors are shallow-cloned (new identity), the changed value is taken
+// from the post-change doc, and every untouched sibling keeps its prior reference.
+// Unchanged slices stay `Object.is`-equal, so their lenses never fire.
+const shallow = (v) => (Array.isArray(v) ? v.slice() : { ...v });
+function getIn(root, path) {
+    let cur = root;
+    for (const k of path)
+        cur = cur[k];
+    return cur;
+}
+/** Rebuild `prev` to match the post-change doc `after`, cloning only the spine to
+ *  each patched value and sharing every untouched subtree by reference. */
+export function applyPatches(prev, patches, after) {
+    if (patches.length === 0)
+        return prev;
+    const root = shallow(prev);
+    const owned = new Set([root]);
+    // Descend `path`, shallow-cloning each container the first time we enter it so a
+    // shared (prev) object is never mutated; returns the owned container at `path`.
+    const spine = (path) => {
+        let cur = root;
+        for (const k of path) {
+            let child = cur[k];
+            if (!owned.has(child)) {
+                child = shallow(child);
+                owned.add(child);
+                cur[k] = child;
+            }
+            cur = child;
+        }
+        return cur;
+    };
+    for (const p of patches) {
+        const path = p.path;
+        if (path.length === 0)
+            return structuredClone(after);
+        const last = path[path.length - 1];
+        // Object-key deletion: rebuild the container minus the key, surviving siblings shared.
+        if (p.action === "del" && typeof last === "string") {
+            delete spine(path.slice(0, -1))[last];
+            continue;
+        }
+        // Sequence ops (list splice/insert/del, text splice, range marks) point *into*
+        // their container; drop the trailing index to replace the whole list/string.
+        const seqOp = p.action === "del" ||
+            p.action === "insert" ||
+            p.action === "splice" ||
+            p.action === "mark" ||
+            p.action === "unmark";
+        const vp = seqOp && typeof last === "number" ? path.slice(0, -1) : path;
+        if (vp.length === 0)
+            return structuredClone(after);
+        spine(vp.slice(0, -1))[vp[vp.length - 1]] = structuredClone(getIn(after, vp));
+    }
+    return root;
+}

package/dist/automerge/doc-cell.d.ts

@@ -1,11 +1,15 @@
 import type { DocHandle } from "@automerge/automerge-repo";
 import { type Cell, type Writable } from "../core/cell.js";
 import { type Store } from "../core/store.js";
-import { type By } from "./reconcile.js";
+import { type By, type Replace } from "./reconcile.js";
 /** Bridge options shared by every `connect*` entry. */
 export interface DocOptions {
     /** Identity key for list elements, enabling keyed reconciliation (see `reconcile`). */
     by?: By;
+    /** Keys whose values are written wholesale (a `put`) rather than deep-merged —
+     *  for opaque blobs a downstream bridge can only apply as whole-object puts
+     *  (see `reconcile`'s `Replace`). */
+    replace?: Replace;
 }
 /** Lifecycle shared by every bridge: retarget the doc, detach both directions. */
 export interface DocLifecycle<T> {

package/dist/automerge/doc-cell.js

@@ -17,6 +17,7 @@
 // CRDT is the shared core, every schema is just a projection.
 import { cell, effect } from "../core/cell.js";
 import { store } from "../core/store.js";
+import { applyPatches } from "./apply-patches.js";
 import { reconcile } from "./reconcile.js";
 function deepEqual(a, b) {
     if (Object.is(a, b))
@@ -39,14 +40,19 @@ function deepEqual(a, b) {
     return true;
 }
 /** Wire an existing cell to a handle in both directions; returns an unbind. */
-function bind(c, handle, by) {
-    const onChange = () => {
-        c.value = structuredClone(handle.doc());
+function bind(c, handle, by, replace) {
+    // Patch-driven invalidation: rebuild only the spine to each changed value so
+    // untouched slices keep their identity and their lenses don't recompute. Fall
+    // back to a full snapshot when the change replaced this handle's whole scope.
+    const onChange = (p) => {
+        c.value = p.scopeReplaced
+            ? structuredClone(handle.doc())
+            : applyPatches(c.peek(), p.patches, p.patchInfo.after);
     };
     handle.on("change", onChange);
     const stop = effect(() => {
         const next = c.value;
-        handle.change((d) => reconcile(d, next, by));
+        handle.change((d) => reconcile(d, next, by, replace));
     });
     return () => {
         stop();
@@ -56,8 +62,9 @@ function bind(c, handle, by) {
 /** Core: a doc-backed cell plus lifecycle. The cell projections layer on top. */
 function connect(handle, opts) {
     const by = opts?.by;
+    const replace = opts?.replace;
     const c = cell(structuredClone(handle.doc()), { equals: deepEqual, name: "doc" });
-    let unbind = bind(c, handle, by);
+    let unbind = bind(c, handle, by, replace);
     return {
         cell: c,
         retarget: next => {
@@ -65,7 +72,7 @@ function connect(handle, opts) {
             // Seed the cell from the new doc *before* re-binding, so the cell→doc
             // effect doesn't push the old value into the freshly targeted doc.
             c.value = structuredClone(next.doc());
-            unbind = bind(c, next, by);
+            unbind = bind(c, next, by, replace);
         },
         dispose: () => unbind(),
     };

package/dist/automerge/index.d.ts

@@ -1,4 +1,4 @@
 export type { CellBridge, DocBridge, DocLifecycle, DocOptions, StoreBridge } from "./doc-cell.js";
 export { connectCell, connectDoc, connectStore } from "./doc-cell.js";
-export type { By } from "./reconcile.js";
+export type { By, Replace } from "./reconcile.js";
 export { reconcile } from "./reconcile.js";

package/dist/automerge/reconcile.d.ts

@@ -2,7 +2,17 @@ type Any = any;
 /** Stable identity key for a list element; return a primitive. `undefined` (or a
  *  collision) on any element makes that list fall back to positional. */
 export type By = (element: unknown) => unknown;
+/** Selects fields whose value is *replaced* wholesale (a scalar assignment → an
+ *  Automerge `put`) instead of recursively merged. Use this for opaque JSON blobs
+ *  a downstream bridge can only consume as whole-object puts — e.g. tldraw's
+ *  `richText`, whose patch applier rejects nested text `splice`s and mis-reads
+ *  nested `del`s. A predicate receives the value's full path from the doc root
+ *  (e.g. `["store", "shape:1", "props", "richText"]`); an array or Set of names
+ *  matches any path whose last segment is one of them (key-name sugar). The value
+ *  is still only written when it differs, so unrelated commits don't churn it. */
+export type Replace = ((path: (string | number)[]) => boolean) | readonly string[] | ReadonlySet<string>;
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. Pass `by` for identity-keyed list reconciliation. */
-export declare function reconcile(target: Any, next: Any, by?: By): void;
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation, and
+ *  `replace` to assign chosen keys wholesale instead of merging into them. */
+export declare function reconcile(target: Any, next: Any, by?: By, replace?: Replace): void;
 export {};

package/dist/automerge/reconcile.js

@@ -16,28 +16,71 @@
 // common subsequence keeps shared elements in place and emits minimal keyed
 // splices/inserts for the rest, so reorders and mid-inserts merge cleanly.
 import { updateText } from "@automerge/automerge-repo";
+/** Normalize the `Replace` sugar (array/Set of key names) into a path predicate. */
+function toReplacePred(r) {
+    if (typeof r === "function")
+        return r;
+    const names = r instanceof Set ? r : new Set(r);
+    return path => names.has(String(path[path.length - 1]));
+}
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Structural equality, used to skip a wholesale `replace` write when the field
+ *  is already deep-equal (so reconciling an unrelated change doesn't rewrite it).
+ *  Note `a` may be a live Automerge proxy: its *lists* don't expose indices via
+ *  `Object.keys`, so arrays are walked by length/index, not key enumeration. */
+function deepEq(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object")
+        return false;
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++)
+            if (!deepEq(av[i], bv[i]))
+                return false;
+        return true;
+    }
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.hasOwn(b, k))
+            return false;
+        if (!deepEq(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. Pass `by` for identity-keyed list reconciliation. */
-export function reconcile(target, next, by) {
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation, and
+ *  `replace` to assign chosen keys wholesale instead of merging into them. */
+export function reconcile(target, next, by, replace) {
+    const ctx = { by, replace: replace && toReplacePred(replace), path: [] };
     if (Array.isArray(next) && Array.isArray(target))
-        reconcileList(target, next, by);
+        reconcileList(target, next, ctx);
     else
-        reconcileObject(target, next, by);
+        reconcileObject(target, next, ctx);
 }
-function reconcileObject(target, next, by) {
+function reconcileObject(target, next, ctx) {
     for (const k of Object.keys(target))
         if (!(k in next))
             delete target[k];
     for (const k of Object.keys(next))
-        setKey(target, k, target[k], next[k], false, by);
+        setKey(target, k, target[k], next[k], false, ctx);
 }
-function reconcileList(target, next, by) {
-    if (by !== undefined && reconcileKeyed(target, next, by))
+function reconcileList(target, next, ctx) {
+    if (ctx.by !== undefined && reconcileKeyed(target, next, ctx))
         return;
     const shared = Math.min(target.length, next.length);
     for (let i = 0; i < shared; i++)
-        setKey(target, i, target[i], next[i], true, by);
+        setKey(target, i, target[i], next[i], true, ctx);
     if (next.length < target.length)
         target.splice(next.length);
     else
@@ -46,7 +89,8 @@ function reconcileList(target, next, by) {
 }
 /** Keyed list reconcile via LCS. Returns false (→ positional fallback) when keys
  *  aren't total + unique on either side. */
-function reconcileKeyed(target, next, by) {
+function reconcileKeyed(target, next, ctx) {
+    const by = ctx.by;
     const tKeys = target.map(by);
     const nKeys = next.map(by);
     if (!totalUnique(tKeys) || !totalUnique(nKeys))
@@ -57,7 +101,7 @@ function reconcileKeyed(target, next, by) {
         if (keep.has(nKeys[n])) {
             while (i < target.length && !keep.has(by(target[i])))
                 target.splice(i, 1);
-            setKey(target, i, target[i], next[n], true, by); // same identity → merge edits
+            setKey(target, i, target[i], next[n], true, ctx); // same identity → merge edits
             i++;
         }
         else {
@@ -98,24 +142,39 @@ function lcs(a, b) {
     }
     return keep;
 }
-function setKey(parent, key, a, b, inList, by) {
-    if (typeof b === "string" && typeof a === "string") {
-        // Char-level merge for object text fields; list string elements just assign
-        // (path-relative updateText targets a keyed field, not an array slot).
-        if (a !== b) {
-            if (inList)
+function setKey(parent, key, a, b, inList, ctx) {
+    ctx.path.push(key);
+    try {
+        // Wholesale-replace paths bypass the merge entirely: assign the value so
+        // Automerge emits a single `put` of the (re)built subtree — no nested text
+        // `splice`s, no `del`s — which is all some bridges can apply. Guard on
+        // deep-equality so reconciling an unrelated change doesn't rewrite it.
+        if (ctx.replace?.(ctx.path)) {
+            if (!deepEq(a, b))
                 parent[key] = b;
-            else
-                updateText(parent, [key], b);
+            return;
+        }
+        if (typeof b === "string" && typeof a === "string") {
+            // Char-level merge for object text fields; list string elements just assign
+            // (path-relative updateText targets a keyed field, not an array slot).
+            if (a !== b) {
+                if (inList)
+                    parent[key] = b;
+                else
+                    updateText(parent, [key], b);
+            }
+        }
+        else if (Array.isArray(b) && Array.isArray(a)) {
+            reconcileList(a, b, ctx);
+        }
+        else if (isPlainObject(b) && isPlainObject(a)) {
+            reconcileObject(a, b, ctx);
+        }
+        else if (a !== b) {
+            parent[key] = b;
         }
     }
-    else if (Array.isArray(b) && Array.isArray(a)) {
-        reconcileList(a, b, by);
-    }
-    else if (isPlainObject(b) && isPlainObject(a)) {
-        reconcileObject(a, b, by);
-    }
-    else if (a !== b) {
-        parent[key] = b;
+    finally {
+        ctx.path.pop();
     }
 }

package/dist/core/_counts.d.ts

@@ -29,8 +29,6 @@ export interface Counts {
     put: number;
     /** A merge `fold` was invoked. */
     fold: number;
-    /** A stateful `step` was invoked (backward commit path). */
-    step: number;
 }
 /** Live counter record. Mutated in place so importers hold a stable reference. */
 export declare const counts: Counts;

package/dist/core/_counts.js

@@ -20,7 +20,6 @@ function fresh() {
         reassertScan: 0,
         put: 0,
         fold: 0,
-        step: 0,
     };
 }
 /** Live counter record. Mutated in place so importers hold a stable reference. */

package/dist/core/cell.d.ts

@@ -21,9 +21,8 @@ interface LensLink {
     index: number;
     parent: Cell<unknown>;
     child: Cell<unknown>;
-    /** Spliced into `parent.childEdges` yet? The down-list (`parentEdges`) is
-     *  eager at construction; the up-list is lazy on first back-mark so the
-     *  parent's child order is arm-order (co-writer resolution is last-write-wins). */
+    /** Spliced into `parent.childEdges` yet? The up-list is lazy on first back-mark,
+     *  so a parent's child order is arm-order (co-writer resolution is last-wins). */
     linked: boolean;
     nextParent: LensLink | undefined;
     prevChild: LensLink | undefined;
@@ -39,35 +38,19 @@ declare class MergeNode<T> {
     constructor(fold: MergeFold<T> | undefined);
 }
 declare class BwdSpec {
-    /** Lens `put` (dual of `getter`): `put(target)` for 1→1 / multi-out (a
-     *  source-reading lens reads its parents at walk time), `put(target, sources, c)`
-     *  for stateful. `undefined` for a merge (folds) or pin (absorbs). */
+    /** Lens `put` (dual of `getter`): `put(target)` for 1→1 / multi-out,
+     *  `put(target, sources, c)` for stateful. `undefined` for a merge or pin. */
     put: ((target: any, current?: any) => any) | undefined;
     /** Fold payload; present ⇒ a fan-in merge. */
     merge: MergeNode<unknown> | undefined;
-    /** Complement state; present ⇒ a complement-carrying (stateful) lens. */
-    stateful: StatefulCore | undefined;
+    /** The mutable complement object a stateful optic's `get`/`put` thread (and may
+     *  mutate in place); present ⇒ a complement-carrying (stateful) lens. Seeded once
+     *  per bind from `optic.complement`, never reassigned. */
+    stateful: object | undefined;
     /** `put` yields a per-parent tuple (split / stateful) vs a scalar (1→1). The
      *  only discriminant not derivable from topology (a 1-parent split is a tuple). */
     scatter: boolean;
 }
-/** Runtime state of a symmetric-lens complement, kept off `BwdSpec` so plain
- *  lenses don't carry its slots. See the stateful-lens header for the theory
- *  (symmetric/edit lenses) and the version-stamp provenance. */
-declare class StatefulCore {
-    /** Engine-owned memory the view discards. */
-    complement: unknown;
-    /** Advance the complement: `step(sources, complement)`. Run only when the
-     *  sources actually moved (the engine gates it; see the stateful header). */
-    step: (sources: any, complement: any) => any;
-    /** Sum of the parents' `version`s as of the last sync. Sources moved iff the
-     *  live sum differs — the lazy own-vs-external provenance that replaces a value
-     *  witness. A read syncs it after stepping; a back-write re-stamps it post-order
-     *  (own writes don't re-step, so `bwd` must leave the complement consistent).
-     *  Seeded to `-1` (sums are ≥ 0) so the first use always folds the sources in. */
-    stamp: number;
-    constructor(complement: unknown, step: (sources: any, complement: any) => any);
-}
 /** Multi-out / stateful back-write sentinel: "leave this parent untouched."
  *  Every non-`SKIP` slot is written verbatim, `undefined` included; a short array
  *  skips the trailing parents. (1→1 `put` always writes its one parent.) */
@@ -129,17 +112,24 @@ export interface CellOptions<T = unknown> {
     /** Debug label; surfaces in cyclic-read errors and graph dumps (see debug.ts). */
     name?: string;
 }
-/** A lens as a first-class value, unbound from any source: `get` projects A→B,
- *  `put` writes B back into an A. Apply with `cell.through(optic)`; build with
- *  `optic` / `iso` / `atKey` / `compose` (optic.ts). `readsSource` is `false`
- *  only for an `iso`, letting `through` bind a cheaper 1-arg backward. */
-export interface Optic<A, B> {
-    readonly get: (a: A) => B;
-    readonly put: (b: B, a: A) => A;
-    readonly readsSource: boolean;
-    /** Compose with a following optic (this first, then `next`). */
-    through<C>(next: Optic<B, C>): Optic<A, C>;
+/** Per-source back-write shape: a partial SKIP-able tuple for N parents (an
+ *  array source), the whole new source (or `SKIP`) for one. */
+export type Updates<S> = S extends readonly unknown[] ? BackUpdates<{
+    [K in keyof S]: S[K] | Skip;
+}> : S | Skip;
+/** A lens as a first-class value, unbound from any source. `get` projects the
+ *  source(s) `S` to a view `V`; `put` writes the view back as per-source
+ *  `Updates<S>`. A 1-arg `put` is an `iso` and ignores the source. `complement`
+ *  present ⇒ stateful (see the stateful-optic header). Apply with `cell.lens` /
+ *  `lens`; build with `optic` / `iso` / `atKey`. */
+export interface Optic<S, V, C extends object = never> {
+    get(s: S, c: C): V;
+    put(target: V, s: S, c: C): Updates<S>;
+    /** Present ⇒ stateful; seeds the per-bind complement. */
+    complement?: (s: S) => C;
 }
+/** An optic bound to a source, with its complement type hidden. */
+export type AppliedOptic<S, V> = Optic<S, V, any>;
 export declare class Cell<T = unknown> implements ReactiveNode {
     /** @internal */
     flags: number;
@@ -180,10 +170,6 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     /** @internal Visit epoch for `backResolve`'s collect phase (dedups diamonds
      *  without a Set; compared against the global `backCycle`). */
     bEpoch: number;
-    /** @internal Monotone committed-change counter. A stateful lens sums its
-     *  parents' versions to detect "did my sources move since I last synced?" —
-     *  the lazy provenance that replaces a value witness (see the stateful header). */
-    version: number;
     /** Optional debug label (`cell(0, { name })`); used by errors and graph dumps. */
     name: string | undefined;
     constructor(initial: T, opts?: CellOptions<T>);
@@ -197,18 +183,16 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     /** @internal */
     _unwatched(): void;
     peek(): T;
-    /** Endomorphic lens. A 2-arg `bwd(view, current)` consults the current
-     *  source; a 1-arg `bwd(view)` reconstructs it from the view alone. */
+    /** Endomorphic lens from a `fwd`/`bwd` pair (2-arg `bwd` reads the source, 1-arg
+     *  reconstructs it), or apply optic value(s), chaining left-to-right. The function
+     *  form is same-type (returns `this`); optics are cross-type. */
     lens(this: Cell<T>, fwd: (v: T) => T, bwd: (target: T, current: T) => T): this;
+    lens<V1>(this: Cell<T>, o: AppliedOptic<T, V1>): Writable<Cell<V1>>;
+    lens<V1, V2>(this: Cell<T>, o1: AppliedOptic<T, V1>, o2: AppliedOptic<V1, V2>): Writable<Cell<V2>>;
+    lens<V1, V2, V3>(this: Cell<T>, o1: AppliedOptic<T, V1>, o2: AppliedOptic<V1, V2>, o3: AppliedOptic<V2, V3>): Writable<Cell<V3>>;
     /** 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;
-    /** Apply optic value(s) as a writable lens: `c.through(o)` ≡ `lens(c, o.get,
-     *  o.put)`; multiple optics compose left-to-right (`c.through(a, b)` = `a`
-     *  then `b`). Cross-type, unlike the endomorphic instance `.lens`. */
-    through<B>(this: Cell<T>, o: Optic<T, B>): Writable<Cell<B>>;
-    through<B, C>(this: Cell<T>, o1: Optic<T, B>, o2: Optic<B, C>): Writable<Cell<C>>;
-    through<B, C, D>(this: Cell<T>, o1: Optic<T, B>, o2: Optic<B, C>, o3: Optic<C, D>): Writable<Cell<D>>;
     /** Backward fan-in: forwards its parent's value unchanged; on write, folds N
      *  contributors into one value. `fold` defaults to last-writer-wins. */
     merge(this: Cell<T>, fold?: MergeFold<T>): Cell<T>;
@@ -218,14 +202,14 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     static derive<C extends AnyCellCtor, P>(this: C, parent: Read<P>, fn: (v: P) => Inner<InstanceType<C>>): InstanceType<C>;
     static derive<C extends AnyCellCtor, P extends readonly Read<unknown>[]>(this: C, parents: P, fn: (vals: ReadValues<P>) => Inner<InstanceType<C>>): InstanceType<C>;
     static derive<C extends AnyCellCtor>(this: C, fn: () => Inner<InstanceType<C>>): InstanceType<C>;
-    /** Writable lens. `Cls.lens(parent, fwd, bwd)` for one input,
-     *  `Cls.lens(parents, fwd, bwd)` for N; a 2-arg `bwd` reads the source,
-     *  a 1-arg `bwd` reconstructs it. `Cls.lens(parent(s), spec)` builds a
-     *  complement-carrying lens from `{ init, step, fwd, bwd }`. */
+    /** Writable lens, typed to this class. `Cls.lens(parent, fwd, bwd)` for one
+     *  input, `Cls.lens(parents, fwd, bwd)` for N (a 2-arg `bwd` reads the source, a
+     *  1-arg `bwd` reconstructs it); `Cls.lens(parent(s), optic)` applies an optic
+     *  value (pure or complement-carrying), chaining if several are given. */
     static lens<C extends AnyCellCtor, P>(this: C, parent: Read<P>, fwd: (v: P) => Inner<InstanceType<C>>, bwd: (target: Inner<InstanceType<C>>, v: P) => P): Writable<InstanceType<C>>;
     static lens<C extends AnyCellCtor, P extends readonly Read<unknown>[]>(this: C, parents: P, fwd: (vals: ReadValues<P>) => Inner<InstanceType<C>>, bwd: (target: Inner<InstanceType<C>>, vals: ReadValues<P>) => BackUpdates<ReadValuesOrSkip<P>>): Writable<InstanceType<C>>;
-    static lens<C extends AnyCellCtor, P, Cm>(this: C, parent: Read<P>, spec: StatefulLensSpec1<P, Inner<InstanceType<C>>, Cm>): Writable<InstanceType<C>>;
-    static lens<C extends AnyCellCtor, P extends readonly Read<unknown>[], Cm>(this: C, parents: P, spec: StatefulLensSpec<ReadValues<P>, Inner<InstanceType<C>>, Cm>): Writable<InstanceType<C>>;
+    static lens<C extends AnyCellCtor, P>(this: C, parent: Read<P>, optic: AppliedOptic<P, Inner<InstanceType<C>>>): Writable<InstanceType<C>>;
+    static lens<C extends AnyCellCtor, P extends readonly Read<unknown>[]>(this: C, parents: P, optic: AppliedOptic<ReadValues<P>, Inner<InstanceType<C>>>): Writable<InstanceType<C>>;
     /** 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 AnyCellCtor>(this: C, v: unknown): v is InstanceType<C>;
@@ -239,35 +223,6 @@ export declare class Cell<T = unknown> implements ReactiveNode {
 /** 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 AnyCellCtor>(parent: Cell<any>, key: string | number | symbol, Cls: C): InstanceType<C>;
-export interface StatefulBwd<S extends readonly unknown[], C> {
-    /** 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> {
-    init: (sources: S) => C;
-    /** Advance the complement on an outside change. Optional — defaults to `init`
-     *  (the memoryless refresh); the engine runs it only when sources actually move. */
-    step?: (sources: S, complement: C) => C;
-    fwd: (sources: S, complement: C) => V;
-    bwd: (target: V, sources: S, complement: C) => StatefulBwd<S, C>;
-}
-/** Single-source `bwd` result: a scalar `update` (or `SKIP`) plus the complement. */
-export interface StatefulBwd1<S, C> {
-    update: S | Skip;
-    complement: C;
-}
-/** Single-source stateful spec — the scalar fast-path of `StatefulLensSpec`: one
- *  parent, so `init`/`step`/`fwd`/`bwd` take the source value directly, not a tuple. */
-export interface StatefulLensSpec1<S, V, C> {
-    init: (source: S) => C;
-    step?: (source: S, complement: C) => C;
-    fwd: (source: S, complement: C) => V;
-    bwd: (target: V, source: S, complement: C) => StatefulBwd1<S, C>;
-}
 /** Writable source; passes an existing `Writable` through (idempotent). */
 export declare function cell<T>(initial: T | Writable<Cell<T>>, opts?: CellOptions<T>): Writable<Cell<T>>;
 /** Untyped read-only view: `derive(parent, fn)`, `derive(parents, fn)`,
@@ -275,9 +230,9 @@ export declare function cell<T>(initial: T | Writable<Cell<T>>, opts?: CellOptio
 export declare function derive<P, R>(parent: Read<P>, fn: (v: P) => R): Cell<R>;
 export declare function derive<P extends readonly Read<unknown>[], R>(parents: P, fn: (vals: ReadValues<P>) => R): Cell<R>;
 export declare function derive<R>(fn: () => R): Cell<R>;
-/** Untyped lens, inferring `R` from the closures. A 2-arg `bwd` reads the
- *  source, a 1-arg `bwd` reconstructs it; `lens(parent(s), spec)` builds a
- *  complement-carrying lens. */
+/** Untyped lens, inferring `R` from the closures or optic. A 2-arg `bwd` reads
+ *  the source, a 1-arg `bwd` reconstructs it; `lens(parent(s), optic)` applies an
+ *  optic value (pure or complement-carrying), chaining if several are given. */
 export declare function lens<P, R>(parent: Read<P>, fwd: (v: P) => R, bwd: (target: R, v: P) => P): Writable<Cell<R>>;
 export declare function lens<P extends readonly Read<unknown>[], R>(parents: P, fwd: (vals: ReadValues<P>) => R, bwd: (target: R, vals: ReadValues<P>) => ReadValuesOrSkip<P>): Writable<Cell<R>>;
 export declare function lens<S extends Record<string, Read<unknown>>, R>(parents: S, fwd: (vals: {
@@ -287,8 +242,10 @@ export declare function lens<S extends Record<string, Read<unknown>>, R>(parents
 }) => Partial<{
     [K in keyof S]: Inner<S[K]> | Skip;
 }>): Writable<Cell<R>>;
-export declare function lens<P, R, C>(parent: Read<P>, spec: StatefulLensSpec1<P, R, C>): Writable<Cell<R>>;
-export declare function lens<P extends readonly Read<unknown>[], R, C>(parents: P, spec: StatefulLensSpec<ReadValues<P>, R, C>): Writable<Cell<R>>;
+export declare function lens<P, R>(parent: Read<P>, optic: AppliedOptic<P, R>): Writable<Cell<R>>;
+export declare function lens<P, V1, R>(parent: Read<P>, o1: AppliedOptic<P, V1>, o2: AppliedOptic<V1, R>): Writable<Cell<R>>;
+export declare function lens<P, V1, V2, R>(parent: Read<P>, o1: AppliedOptic<P, V1>, o2: AppliedOptic<V1, V2>, o3: AppliedOptic<V2, R>): Writable<Cell<R>>;
+export declare function lens<P extends readonly Read<unknown>[], R>(parents: P, optic: AppliedOptic<ReadValues<P>, R>): Writable<Cell<R>>;
 export declare function effect(fn: () => (() => void) | void): () => void;
 /** Run all pending effects now, synchronously — the escape hatch for code that
  *  must observe effect side-effects before yielding. Reads never need it. */