@mmstack/primitives 20.10.1 → 20.11.0

package/index.d.ts

@@ -224,6 +224,56 @@ type DeferredSignal<T> = Signal<T> & {
  */
 declare function deferredValue<T>(source: Signal<T>, opt?: DeferredValueOptions<T>): DeferredSignal<T>;
 
+/**
+ * Optional observability seam for the concurrency layer (idea/concurrency-devtools.md). A
+ * listener, provided via {@link provideConcurrencyInstrumentation}, receives events as
+ * transition scopes coordinate pending/suspense/transaction windows and register resources.
+ * Zero-cost when absent: the taps are `listener?.hook(...)` behind a once-resolved optional
+ * inject, so nothing is allocated or measured unless a listener is installed.
+ *
+ * Span-shaped hooks (`*Start`) return an opaque handle passed back to their `*End`, and carry
+ * `at` epoch-ms stamps — deliberately isomorphic to the telemetry `startSpan`/`SpanHandle` SPI,
+ * so a telemetry consumer maps one-to-one.
+ */
+type ConcurrencyInstrumentation = {
+    pendingStart?(e: {
+        scope: string;
+        resources: number;
+        at: number;
+    }): unknown;
+    pendingEnd?(handle: unknown, e: {
+        at: number;
+    }): void;
+    transactionStart?(e: {
+        scope: string;
+        at: number;
+    }): unknown;
+    transactionEnd?(handle: unknown, e: {
+        at: number;
+    }): void;
+    resourceRegistered?(e: {
+        scope: string;
+        suspends: boolean;
+    }): void;
+    resourceRemoved?(e: {
+        scope: string;
+    }): void;
+    abortPending?(e: {
+        scope: string;
+        aborted: number;
+        at: number;
+    }): void;
+};
+declare const CONCURRENCY_INSTRUMENTATION: InjectionToken<ConcurrencyInstrumentation>;
+declare function provideConcurrencyInstrumentation(listener: ConcurrencyInstrumentation): Provider;
+/**
+ * Chrome DevTools "Performance" custom-tracks preset (idea/concurrency-devtools.md): writes a
+ * `performance.measure` for each pending/transaction window onto an "mmstack" extension track,
+ * so reactive coordination shows up on the Performance panel timeline. Dev-only, zero backend,
+ * no dependencies. Give each measure the scope name for readability.
+ */
+declare function perfCustomTracks(track?: string): ConcurrencyInstrumentation;
+
 /**
  * Structural hold-and-swap as a signal. Given a `target` (the desired value — e.g. the
  * subtree/def/key you want to show) and a `ready` predicate, returns a signal that keeps
@@ -455,7 +505,13 @@ type TransitionScope = {
      */
     hold<T>(value: Signal<T>): Signal<T>;
 };
-declare function createTransitionScope(): TransitionScope;
+type CreateTransitionScopeOptions = {
+    /** Scope identity for instrumentation events (idea/concurrency-devtools.md). */
+    readonly name?: string;
+    /** Optional observability listener; taps are no-ops when omitted (zero cost). */
+    readonly instrumentation?: ConcurrencyInstrumentation;
+};
+declare function createTransitionScope(opt?: CreateTransitionScopeOptions): TransitionScope;
 /**
  * The scope→`PendingTasks` bridge: while `scope.pending()` is true, hold an Angular
  * pending task so SSR serialization waits for the scope's in-flight loads — HTTP loads
@@ -470,7 +526,7 @@ declare function createTransitionScope(): TransitionScope;
  */
 declare function bridgeScopeToPendingTasks(scope: TransitionScope, injector?: Injector): void;
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
-declare function provideTransitionScope(): Provider;
+declare function provideTransitionScope(opt?: CreateTransitionScopeOptions): Provider;
 declare function injectTransitionScope(): TransitionScope;
 /**
  * A transition scope that can be re-pointed at a delegate target at runtime. Reads and
@@ -837,23 +893,6 @@ type MutableSignal<T> = WritableSignal<T> & {
  * This is because a `.mutate()` call notifies its dependents that it has changed, but if the
  * reference to a derived object hasn't changed, the `computed` signal will not trigger its
  * own dependents by default.
- *
- * @example
- * ```ts
- * const state = mutable({ user: { name: 'John' }, lastUpdated: new Date() });
- *
- * // ✅ CORRECT: Deriving a primitive value works as expected.
- * const name = computed(() => state().user.name);
- *
- * // ❌ INCORRECT: This will not update reliably after the first change.
- * const userObject = computed(() => state().user);
- *
- * // ✅ CORRECT: For object derivations, `equal: false` is required.
- * const userObjectFixed = computed(() => state().user, { equal: false });
- *
- * // This mutation will now correctly trigger effects depending on `userObjectFixed`.
- * state.mutate(s => s.lastUpdated = new Date());
- * ```
  */
 declare function mutable<T>(): MutableSignal<T | undefined>;
 declare function mutable<T>(initial: T): MutableSignal<T>;
@@ -1800,10 +1839,10 @@ declare function clipboard(opt?: string | SensorRunOptions): ClipboardSignal;
 /**
  * Represents the size of an element.
  */
-interface ElementSize {
+type ElementSize = {
     width: number;
     height: number;
-}
+};
 /**
  * Options for configuring the `elementSize` sensor.
  */
@@ -2762,6 +2801,128 @@ type ResolvableTarget = EventTargetLike | Signal<EventTargetLike | null>;
 declare function signalFromEvent<TEvent extends Event>(target: ResolvableTarget, eventName: string, initial: TEvent | null, opt?: SignalFromEventOptions): Signal<TEvent | null>;
 declare function signalFromEvent<TEvent extends Event, U>(target: ResolvableTarget, eventName: string, initial: U, project: (event: TEvent) => U, opt?: SignalFromEventOptions): Signal<U>;
 
+type Key$2 = string | number;
+/**
+ * One structural operation. `set` on a key that did not previously exist carries NO `prev`
+ * property (an absent key is not the same as a key holding `undefined` — the merge3 lesson),
+ * which is what lets {@link invertBatch} invert an add into a delete.
+ */
+type StoreOp = {
+    kind: 'set';
+    path: readonly Key$2[];
+    next: unknown;
+    prev?: unknown;
+} | {
+    kind: 'delete';
+    path: readonly Key$2[];
+    prev: unknown;
+};
+/** One emission: every op derived from one commit window (a tick), in path order. */
+type OpBatch = {
+    /** Identifies the emitting log — filter your own batches on a shared transport. */
+    readonly origin: string;
+    /** Per-log monotonic batch counter. */
+    readonly version: number;
+    readonly ops: readonly StoreOp[];
+};
+/**
+ * Drives an {@link opLog}'s emission reaction. Given the `run` closure (which reads the source in
+ * a tracking context and flushes the delta), a driver arranges for `run` to execute now and again
+ * on every subsequent change, returning a handle that stops it. The default driver is an Angular
+ * `effect` (needs an injector). Supply a custom driver to run an opLog with NO injector; a
+ * renderer-independent one built on `@angular/core/primitives/signals` `createWatch` ships as
+ * `microtaskOpLogDriver` from `@mmstack/worker/host` (the Web Worker seam).
+ */
+type OpLogDriver = (run: () => void) => {
+    destroy(): void;
+};
+type CreateOpLogOptions = {
+    /** Transport identity for emitted batches. Defaults to a random id. */
+    readonly origin?: string;
+    /** Injection context for the default effect-based driver (required outside one). */
+    readonly injector?: Injector;
+    /**
+     * Replaces the default Angular-`effect` emission driver. Supply a custom driver (e.g.
+     * `microtaskOpLogDriver` from `@mmstack/worker/host`) to run an opLog with NO injector. When
+     * given, `injector` is ignored and no injection context is required.
+     */
+    readonly driver?: OpLogDriver;
+};
+type OpLog<T extends object> = {
+    /**
+     * Ordered, lossless delivery of every emitted batch. Synchronous — don't write back into
+     * the observed source from inside a callback (route remote data through {@link OpLog.apply}).
+     */
+    subscribe(cb: (batch: OpBatch) => void): () => void;
+    /** The most recent batch — a lossy sampling view (devtools); use `subscribe` for transport. */
+    readonly latest: Signal<OpBatch | null>;
+    /**
+     * Synchronously diff the source and emit any pending change NOW, rather than waiting for the
+     * driver's scheduled run (an app tick, or a custom driver's microtask). Idempotent
+     * and coalescing: writes since the last emission compose into one batch, and a `flush()` with
+     * nothing pending is a no-op. Use it to make emission deterministic — the worker host calls it
+     * to settle its mirror synchronously (tests), and it underpins the flush-before-apply honesty of
+     * {@link OpLog.apply}. Independent of the driver: a later scheduled run simply finds no diff.
+     */
+    flush(): void;
+    /**
+     * Applies ops (a remote batch, a persisted journal entry, an {@link invertBatch} result)
+     * atomically: ONE `set`, one notification wave. Also advances this log's diff baseline in
+     * the same step, so an applied batch produces NO echo emission — sync loops terminate by
+     * construction. Local writes pending in the current tick are flushed (emitted) first, so
+     * they are never silently folded into the applied baseline.
+     */
+    apply(ops: OpBatch | readonly StoreOp[]): void;
+    /** Stops observing and drops subscribers. Also happens when the injection context dies. */
+    destroy(): void;
+};
+/**
+ * Pure, store-free application of ops onto a plain root value, returning the next immutable root
+ * (structural-sharing along op paths, missing containers vivified `'auto'`-style). This is the
+ * same transform {@link OpLog.apply} runs, extracted so a replica can fold a received batch into
+ * a value WITHOUT owning a diffing {@link opLog} — e.g. the worker-graph read-replica seam.
+ * Accepts a batch or a bare op list.
+ */
+declare function applyOps<T>(root: T, ops: OpBatch | readonly StoreOp[]): T;
+/**
+ * Pure reference-pruned structural diff of two roots into minimal ops (the emission core of
+ * {@link opLog}, exported so code outside a log can produce a batch — e.g. diffing a scratch
+ * draft against a replica's current value to route a write to its owner). Trusts the
+ * copy-on-write contract: an untouched subtree that kept its reference is skipped.
+ */
+declare function diffOps(prev: unknown, next: unknown): StoreOp[];
+/**
+ * Inverts a batch for undo: reversed order, `set`↔its own inverse (an add — a `set` with no
+ * `prev` — inverts to a `delete`; a `delete` inverts to a `set` restoring `prev`). Feed the
+ * result to {@link OpLog.apply}. Requires the ops' `prev`s, which in-memory batches always
+ * carry — a wire-serialized batch that stripped them is not invertible.
+ */
+declare function invertBatch(batch: OpBatch | readonly StoreOp[]): StoreOp[];
+/**
+ * Observes a copy-on-write signal (a `store`'s root, or any `WritableSignal` holding
+ * immutably-updated objects) and emits its changes as minimal structural op batches — the
+ * shared substrate for sync (ship batches, `apply` remote ones), persistence (journal
+ * batches, replay on boot), undo ({@link invertBatch}), and devtools (`latest`).
+ *
+ * Zero store-core involvement and zero cost when unused: emission is a reference-pruned diff
+ * of the root value per tick (structural sharing makes it O(changed paths)), driven by one
+ * effect. A batch therefore coalesces everything written in one tick — for coarser,
+ * intentional units, stage writes on a `forkStore` and `commit()` (one set → one batch).
+ *
+ * NOT supported on mutable stores/signals: in-place mutation keeps reference identity, which
+ * defeats the diff (same reason `forkStore`'s `'fine'` strategy refuses them) — a dev-mode
+ * warning fires and nothing emits.
+ *
+ * ```ts
+ * const s = store({ todos: [{ done: false }] });
+ * const log = opLog(s, { origin: 'tab-a' });
+ * log.subscribe((b) => channel.postMessage(encode(b)));   // ship
+ * channel.onmessage = (m) => log.apply(decode(m.data));    // apply — echo-free
+ * s.todos[0].done.set(true); // → { kind: 'set', path: ['todos', 0, 'done'], … }
+ * ```
+ */
+declare function opLog<T extends object>(source: WritableSignal<T>, opt?: CreateOpLogOptions): OpLog<T>;
+
 /**
  * @internal Runtime brand carrying a store node's lazily-built leaf probe. Exported (like
  * {@link OPAQUE}) only so the `{ readonly [LEAF]: () => boolean }` brand on the store types is
@@ -3093,6 +3254,8 @@ type Fork<T> = {
     commit(): void;
     /** Drop staged writes — the fork reads through to the base again. */
     discard(): void;
+    /** The staged delta vs the CURRENT base, as structural ops (inspect, persist, invert). */
+    ops(): StoreOp[];
 };
 /**
  * Per-path 3-way merge. Reference-equality short-circuits do the work: a subtree the fork never
@@ -3119,127 +3282,313 @@ type ForkStoreOptions<T> = toStoreOptions & {
 };
 declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;
 
+/** Hybrid logical clock stamp: physical epoch ms + logical counter for same-ms ordering. */
+type Hlc = {
+    readonly p: number;
+    readonly l: number;
+};
+/** Total order over stamps alone; ties break on `writer` via {@link compareTotal}. */
+declare function compareHlc(a: Hlc, b: Hlc): number;
+/** The protocol's total order: (hlc.p, hlc.l, writer). Never returns 0 for distinct writers. */
+declare function compareTotal(a: Hlc, writerA: string, b: Hlc, writerB: string): number;
+type HlcClock = {
+    /** Stamp for a locally-emitted envelope: monotonic even when wall time stalls or rewinds. */
+    next(): Hlc;
+    /** Fold an observed remote stamp in, so subsequent local stamps sort after it. */
+    observe(remote: Hlc): void;
+};
+/**
+ * HLC per Kulkarni et al.: convergence never depends on wall clocks, but LWW fairness
+ * degrades under large skew, so observing a remote clock far ahead warns in dev mode.
+ */
+declare function createHlcClock(now?: () => number): HlcClock;
+
+declare const OP_PROTO_VERSION = 1;
 type Key = string | number;
 /**
- * One structural operation. `set` on a key that did not previously exist carries NO `prev`
- * property (an absent key is not the same as a key holding `undefined` — the merge3 lesson),
- * which is what lets {@link invertBatch} invert an add into a delete.
+ * The wire/journal record (op-protocol RFC §3). `writer` is an opaque principal pseudonym —
+ * natural identity never enters the envelope; `origin` identifies the emitting log instance.
  */
-type StoreOp = {
-    kind: 'set';
-    path: readonly Key[];
-    next: unknown;
-    prev?: unknown;
-} | {
-    kind: 'delete';
-    path: readonly Key[];
-    prev: unknown;
-};
-/** One emission: every op derived from one commit window (a tick), in path order. */
-type OpBatch = {
-    /** Identifies the emitting log — filter your own batches on a shared transport. */
+type OpEnvelope = {
+    readonly proto: number;
     readonly origin: string;
-    /** Per-log monotonic batch counter. */
+    readonly writer: string;
     readonly version: number;
+    readonly hlc: Hlc;
+    readonly policyVersion: number;
     readonly ops: readonly StoreOp[];
 };
+declare const CONFLICT_BRAND = "~mmstackConflict";
 /**
- * Drives an {@link opLog}'s emission reaction. Given the `run` closure (which reads the source in
- * a tracking context and flushes the delta), a driver arranges for `run` to execute now and again
- * on every subsequent change, returning a handle that stops it. The default driver is an Angular
- * `effect` (needs an injector). Supply a custom driver to run an opLog with NO injector; a
- * renderer-independent one built on `@angular/core/primitives/signals` `createWatch` ships as
- * `microtaskOpLogDriver` from `@mmstack/worker/host` (the Web Worker seam).
+ * A preserved (jj-style) conflict: both sides survive as data, sync never blocks, and
+ * resolution is just a later write. String-branded so it survives structured clone.
  */
-type OpLogDriver = (run: () => void) => {
-    destroy(): void;
+type Conflicted<T = unknown> = {
+    readonly [CONFLICT_BRAND]: true;
+    readonly mine: T;
+    readonly theirs: T;
+    readonly ancestor?: T;
 };
-type CreateOpLogOptions = {
-    /** Transport identity for emitted batches. Defaults to a random id. */
-    readonly origin?: string;
-    /** Injection context for the default effect-based driver (required outside one). */
-    readonly injector?: Injector;
+declare function isConflicted<T = unknown>(value: unknown): value is Conflicted<T>;
+type MergeContext = {
+    readonly path: readonly Key[];
+};
+/**
+ * Resolves a concurrent set-vs-set collision. Called with a deterministic argument order
+ * (`mine` = the side winning the total order) so every peer computes the same value.
+ */
+type MergeFn = (ancestor: unknown, mine: unknown, theirs: unknown, ctx: MergeContext) => unknown;
+type MergePolicyEntry = {
+    /** `'todos.*.title'` or a segment array; `'*'` matches exactly one segment. */
+    readonly path: string | readonly Key[];
+    readonly merge: MergeFn;
+};
+declare const lww: MergeFn;
+declare const mergeThree: MergeFn;
+declare const preserve: MergeFn;
+/**
+ * Identity-aware array merge (op-protocol RFC §12 v0): reconciles two concurrent versions of
+ * an array item-wise by a user-provided identity, instead of last-writer-wins on the whole
+ * array. Items are matched by key; per-item fields merge via `merge3` against the ancestor
+ * item; items added on either side survive; an item removed on either side and unedited on
+ * the other stays removed. Item ORDER follows `mine` (the total-order winner), with `theirs`-
+ * only additions appended — positional merging is out of scope (fractional indexing is the
+ * known upgrade if dogfooding demands it). Arrays still TRAVEL as whole-value sets; identity
+ * only shapes conflict resolution, so the wire format is untouched.
+ */
+declare function keyedArray(identity: (item: unknown) => unknown, opt?: {
+    item?: MergeFn;
+}): MergeFn;
+type ConvergingApply = {
     /**
-     * Replaces the default Angular-`effect` emission driver. Supply a custom driver (e.g.
-     * `microtaskOpLogDriver` from `@mmstack/worker/host`) to run an opLog with NO injector. When
-     * given, `injector` is ignored and no injection context is required.
+     * Fold an envelope into the register map and return the ops the local store must apply
+     * (post-dominance, post-policy, including replays of newer descendant winners). Pass
+     * `local: true` for envelopes this peer emitted itself: registered, nothing returned.
      */
+    ingest(env: OpEnvelope, opt?: {
+        local?: boolean;
+    }): StoreOp[];
+    /** Drop all registers (snapshot compaction / rehydration boundary). */
+    reset(): void;
+};
+/**
+ * The unsequenced-topology convergence core (op-protocol RFC §4): a per-path last-writer-wins
+ * register map over the total order (hlc, writer), with subtree dominance. Order-independent:
+ * any arrival order of the same envelope set yields the same state.
+ */
+declare function createConvergingApply(opt?: {
+    policies?: readonly MergePolicyEntry[];
+}): ConvergingApply;
+type RebaseResult<T = unknown> = {
+    root: T;
+    /** Pending batches re-based onto the remote state, `prev`s refreshed. */
+    pending: StoreOp[][];
+};
+/**
+ * The shared rebase routine (op-protocol RFC §5): invert pending, apply remote, re-apply
+ * pending through the merge policies. Pure — branching's `rebase()` and the sequenced relay
+ * client both call this.
+ */
+declare function rebaseOps<T>(root: T, pending: readonly (readonly StoreOp[])[], remote: readonly StoreOp[], policies?: readonly MergePolicyEntry[]): RebaseResult<T>;
+/**
+ * A per-path-policy `ForkStrategy` for `forkStore`: a three-way reconcile built from the
+ * shared rebase (invert mine → apply theirs' delta → re-apply mine through the policies).
+ * Paths only one side touched resolve like `merge3`; paths BOTH touched go through the
+ * matching {@link MergePolicyEntry} (`lww` default — fork wins, matching `'fine'`; or
+ * `mergeThree` / `preserve` / custom). Same copy-on-write contract as `'fine'`.
+ */
+declare function policyStrategy<T>(policies: readonly MergePolicyEntry[]): (ancestor: T, mine: T, theirs: T) => T;
+type OpSyncOptions = {
+    /** Opaque principal pseudonym — provided by the app, never minted here (RFC §3). */
+    readonly writer: string;
+    readonly origin?: string;
+    readonly policyVersion?: number;
+    readonly policies?: readonly MergePolicyEntry[];
+    readonly clock?: HlcClock;
+    readonly injector?: Injector;
     readonly driver?: OpLogDriver;
+    /** A version gap from a known origin (missed envelopes) — the resync hook. */
+    readonly onGap?: (origin: string, expected: number, got: number) => void;
 };
-type OpLog<T extends object> = {
+type OpSync<T = unknown> = {
+    readonly origin: string;
+    /** Locally-emitted envelopes, ready for a transport. */
+    subscribe(cb: (env: OpEnvelope) => void): () => void;
+    /** Converging apply of a remote envelope (echo-free; own-origin envelopes are ignored). */
+    receive(env: OpEnvelope): void;
+    /** Synchronously emit any pending local delta now. */
+    flush(): void;
+    /** Per-origin latest versions — the handshake watermark. */
+    watermark(): Record<string, number>;
+    /** The current root + watermark, for answering a peer's hello. */
+    snapshot(): {
+        root: T;
+        wm: Record<string, number>;
+    };
     /**
-     * Ordered, lossless delivery of every emitted batch. Synchronous — don't write back into
-     * the observed source from inside a callback (route remote data through {@link OpLog.apply}).
+     * Emit the CURRENT root as a root-set envelope — the fresh-room seed of the relay
+     * contract (a room's snapshot root becomes complete once seeded).
      */
-    subscribe(cb: (batch: OpBatch) => void): () => void;
-    /** The most recent batch — a lossy sampling view (devtools); use `subscribe` for transport. */
-    readonly latest: Signal<OpBatch | null>;
+    seed(): void;
     /**
-     * Synchronously diff the source and emit any pending change NOW, rather than waiting for the
-     * driver's scheduled run (an app tick, or a custom driver's microtask). Idempotent
-     * and coalescing: writes since the last emission compose into one batch, and a `flush()` with
-     * nothing pending is a no-op. Use it to make emission deterministic — the worker host calls it
-     * to settle its mirror synchronously (tests), and it underpins the flush-before-apply honesty of
-     * {@link OpLog.apply}. Independent of the driver: a later scheduled run simply finds no diff.
+     * Replace local state with a peer's snapshot, atomically (one notification wave).
+     * Local envelopes the snapshot doesn't cover (per its watermark) are re-applied on
+     * top, so writes made before hydration are never silently lost.
      */
-    flush(): void;
+    hydrate(root: T, wm?: Record<string, number>): void;
+    destroy(): void;
+};
+declare function opSync<T extends object>(source: WritableSignal<T>, opt: OpSyncOptions): OpSync<T>;
+
+type StoreHistory = {
+    readonly canUndo: Signal<boolean>;
+    readonly canRedo: Signal<boolean>;
+    /** Revert the most recent tracked change; a no-op when nothing is undoable. */
+    undo(): void;
+    /** Re-apply the most recently undone change. */
+    redo(): void;
+    /** Forget all tracked history (e.g. after a save boundary). */
+    clear(): void;
+    destroy(): void;
+};
+type StoreHistoryOptions = CreateOpLogOptions & {
+    /** Max entries kept per stack (default 100). */
+    readonly limit?: number;
     /**
-     * Applies ops (a remote batch, a persisted journal entry, an {@link invertBatch} result)
-     * atomically: ONE `set`, one notification wave. Also advances this log's diff baseline in
-     * the same step, so an applied batch produces NO echo emission — sync loops terminate by
-     * construction. Local writes pending in the current tick are flushed (emitted) first, so
-     * they are never silently folded into the applied baseline.
+     * The change stream to track. Defaults to self-diffing `source` (every change to the store
+     * becomes undoable). For collaborative-safe undo, pass a sync client's LOCAL envelope stream
+     * (e.g. an `opSync`'s `subscribe`, which fires only for this peer's own writes) — remote
+     * peers' changes then never land on your undo stack.
      */
-    apply(ops: OpBatch | readonly StoreOp[]): void;
-    /** Stops observing and drops subscribers. Also happens when the injection context dies. */
-    destroy(): void;
+    readonly track?: {
+        subscribe(cb: (batch: OpBatch) => void): () => void;
+    };
 };
 /**
- * Pure, store-free application of ops onto a plain root value, returning the next immutable root
- * (structural-sharing along op paths, missing containers vivified `'auto'`-style). This is the
- * same transform {@link OpLog.apply} runs, extracted so a replica can fold a received batch into
- * a value WITHOUT owning a diffing {@link opLog} — e.g. the worker-graph read-replica seam.
- * Accepts a batch or a bare op list.
+ * Undo/redo for a copy-on-write store, built on the op-log: each tracked change is stored as
+ * its inverse batch, so `undo()` is one `apply` and history costs only the diffs, not full
+ * snapshots. Redoing is invert-of-the-inverse. A new edit made after an undo clears the redo
+ * stack (linear history). Applying a redo/undo does not itself re-enter history.
+ *
+ * Composes with sync for collaborative undo: pass `track: syncClient` so only YOUR writes are
+ * undoable, while `undo()` emits a normal op that propagates to peers (it writes through the
+ * store, which the sync client picks up).
  */
-declare function applyOps<T>(root: T, ops: OpBatch | readonly StoreOp[]): T;
+declare function storeHistory<T extends object>(source: WritableSignal<T>, opt?: StoreHistoryOptions): StoreHistory;
+
+type MaybePromise<T> = T | Promise<T>;
 /**
- * Pure reference-pruned structural diff of two roots into minimal ops (the emission core of
- * {@link opLog}, exported so code outside a log can produce a batch — e.g. diffing a scratch
- * draft against a replica's current value to route a write to its owner). Trusts the
- * copy-on-write contract: an untouched subtree that kept its reference is skipped.
+ * The minimal async key/value contract persistence needs. Deliberately matches `idb-keyval`'s
+ * top-level `get`/`set`/`del` so its module drops in with no wrapper (`persist(s, { key, store:
+ * idbKeyval })`). Any store backed by structured clone (idb-keyval, Dexie) can hold complex values
+ * without a serialize hook. A Dexie table needs a tiny adapter because it names things differently:
+ *
+ * ```ts
+ * const table = db.table<{ key: string; value: unknown }>('kv');
+ * const asyncStore: AsyncStore = {
+ *   get: (k) => table.get(k).then((r) => r?.value),
+ *   set: (k, v) => table.put({ key: k, value: v }).then(() => undefined),
+ *   del: (k) => table.delete(k),
+ * };
+ * ```
  */
-declare function diffOps(prev: unknown, next: unknown): StoreOp[];
+type AsyncStore = {
+    get(key: string): MaybePromise<unknown>;
+    set(key: string, value: unknown): MaybePromise<void>;
+    del(key: string): MaybePromise<void>;
+};
+/** Persistence options — the reader-side settings, independent of how the store was created. */
+type PersistOptions<T> = {
+    /** Storage key for this store's snapshot. Required per call. */
+    readonly key: string;
+    /** The async backend. Falls back to the provided default (see {@link providePersistedStoreOptions}). */
+    readonly store?: AsyncStore;
+    /** Encode before writing. Default identity: structured-clone backends keep complex values. */
+    readonly serialize?: (value: T) => unknown;
+    /** Decode after reading. Default identity. */
+    readonly deserialize?: (raw: unknown) => T;
+    /**
+     * Current schema version of the persisted value. When set, snapshots are written wrapped in a
+     * small version envelope, and a snapshot stamped with an older version is passed through
+     * {@link PersistOptions.migrate} on boot before it is adopted. A snapshot from a *newer* version
+     * than this build is left untouched (a newer client wrote it).
+     */
+    readonly version?: number;
+    /**
+     * Bring a snapshot from an older `version` up to the current shape. It runs during boot, which
+     * is already async, so it may be async too: lazy-import the migration ladder here and only pay
+     * for it when there is old data to migrate. Receives the decoded old value and the version it
+     * was written with (`0` for a pre-versioning snapshot).
+     */
+    readonly migrate?: (data: unknown, fromVersion: number) => MaybePromise<T>;
+    /** Coalesce writes by this many ms (default 300). A flush/teardown always writes immediately. */
+    readonly writeDebounceMs?: number;
+    readonly injector?: Injector;
+};
+type PersistedStoreOptions<T extends object> = CreateSignalOptions<T> & toStoreOptions & PersistOptions<T>;
 /**
- * Inverts a batch for undo: reversed order, `set`↔its own inverse (an add — a `set` with no
- * `prev` — inverts to a `delete`; a `delete` inverts to a `set` restoring `prev`). Feed the
- * result to {@link OpLog.apply}. Requires the ops' `prev`s, which in-memory batches always
- * carry — a wire-serialized batch that stripped them is not invertible.
+ * App-wide defaults for {@link persist} / {@link persistedStore}. Only cross-type settings live
+ * here; `serialize`/`deserialize` are per-call because they depend on the store's value type.
  */
-declare function invertBatch(batch: OpBatch | readonly StoreOp[]): StoreOp[];
+type PersistedStoreDefaults = {
+    readonly store?: AsyncStore;
+    readonly writeDebounceMs?: number;
+};
+declare const PERSISTED_STORE_OPTIONS: InjectionToken<PersistedStoreDefaults>;
 /**
- * Observes a copy-on-write signal (a `store`'s root, or any `WritableSignal` holding
- * immutably-updated objects) and emits its changes as minimal structural op batches — the
- * shared substrate for sync (ship batches, `apply` remote ones), persistence (journal
- * batches, replay on boot), undo ({@link invertBatch}), and devtools (`latest`).
+ * Wire the {@link AsyncStore} backend (and any shared debounce) once, override per call. The
+ * typical use is to install idb-keyval at bootstrap so every `persist`/`persistedStore` persists
+ * without re-passing the backend.
  *
- * Zero store-core involvement and zero cost when unused: emission is a reference-pruned diff
- * of the root value per tick (structural sharing makes it O(changed paths)), driven by one
- * effect. A batch therefore coalesces everything written in one tick — for coarser,
- * intentional units, stage writes on a `forkStore` and `commit()` (one set → one batch).
+ * @example
+ * import * as idbKeyval from 'idb-keyval';
+ * providePersistedStoreOptions({ store: idbKeyval });
+ */
+declare function providePersistedStoreOptions(opt: PersistedStoreDefaults): Provider;
+/** Persistence controls for a store, from {@link persist}. */
+type PersistHandle = {
+    /**
+     * `false` until the first read from the backend settles (or immediately `true` on the server
+     * and when no backend is configured). Gate first paint on it if a stale-flash matters.
+     */
+    readonly hydrated: Signal<boolean>;
+    /** Force any pending debounced write to the backend now. */
+    flush(): Promise<void>;
+    /** Remove the snapshot from the backend and reset the store to the value it held when attached. */
+    clear(): Promise<void>;
+};
+/**
+ * A store plus its persistence controls. Shaped like {@link Fork} (a `.store` field, not the
+ * store itself) because the store is a proxy where any property access resolves a child path,
+ * so controls cannot live on it directly.
+ */
+type PersistedStore<T extends object> = {
+    /** The live store. Reads are synchronous; it holds the initial value until hydration lands. */
+    readonly store: WritableSignalStore<T>;
+} & PersistHandle;
+/**
+ * Attach durable local persistence to an EXISTING store: its whole-value snapshot is written to an
+ * async backend (IndexedDB via idb-keyval or Dexie) and restored on boot. A reader over the store,
+ * so it composes with the other op-log readers (`tabSync`, `@mmstack/mesh`) on the same store — a
+ * persisted, synced graph is just two readers. Local durability, not sync.
  *
- * NOT supported on mutable stores/signals: in-place mutation keeps reference identity, which
- * defeats the diff (same reason `forkStore`'s `'fine'` strategy refuses them) — a dev-mode
- * warning fires and nothing emits.
+ * Because the backend is async, hydration cannot precede the first read: the store keeps its current
+ * value, then adopts the persisted snapshot once the backend answers, UNLESS a write happened first
+ * (an explicit boot-time write wins over stale disk). Writes are coalesced and flushed on teardown
+ * and on page hide, so the last change is never lost. On the server it is a no-op.
  *
- * ```ts
- * const s = store({ todos: [{ done: false }] });
- * const log = opLog(s, { origin: 'tab-a' });
- * log.subscribe((b) => channel.postMessage(encode(b)));   // ship
- * channel.onmessage = (m) => log.apply(decode(m.data));    // apply — echo-free
- * s.todos[0].done.set(true); // → { kind: 'set', path: ['todos', 0, 'done'], … }
- * ```
+ * When the persisted shape evolves, pass `version` and a `migrate` hook: an older snapshot is
+ * brought forward on boot before it is adopted, then re-persisted in the new shape. Because boot is
+ * already async, `migrate` may be async, so the migration ladder can be lazy-imported.
  */
-declare function opLog<T extends object>(source: WritableSignal<T>, opt?: CreateOpLogOptions): OpLog<T>;
+declare function persist<T extends object>(source: WritableSignalStore<T>, opt: PersistOptions<T>): PersistHandle;
+/**
+ * A `store` with {@link persist} already attached: a whole-value snapshot persisted to an async
+ * backend and restored on boot. Equivalent to `const s = store(initial); persist(s, opt)` — reach
+ * for `persist` directly when you want persistence on a store you already have (e.g. to also
+ * `meshSync` it).
+ */
+declare function persistedStore<T extends object>(initial: T, opt: PersistedStoreOptions<T>): PersistedStore<T>;
 
 /** Identity selector for keyed array reconciliation: a property name, or a function per item. */
 type ReconcileKey = string | ((item: any) => unknown);
@@ -3448,10 +3797,25 @@ type SyncSignalOptions = {
      */
     injector?: Injector;
 };
+/**
+ * Store mode (`tabSync(store, …)`): syncs structural OPS instead of whole values — concurrent
+ * edits to different leaves merge instead of clobbering, and a joining tab hydrates from a
+ * peer via the hello exchange (up-to-date / snapshot; op-protocol RFC §6).
+ */
+type StoreTabSyncOptions = SyncSignalOptions & {
+    /** Principal pseudonym on emitted envelopes. Tabs share one user, so a default is fine. */
+    writer?: string;
+    /** Per-path merge policies (`lww` default; `mergeThree`, `preserve`, or custom). */
+    policies?: readonly MergePolicyEntry[];
+    /** How long a joining tab waits for a peer's answer before deciding it IS the base. */
+    helloTimeoutMs?: number;
+    /** Max response jitter — first responder wins, others cancel. */
+    jitterMs?: number;
+};
 /**
  * @example tabSync(signal('dark'), { id: 'theme' })
  */
-declare function tabSync<T extends WritableSignal<any>>(sig: T, opt: SyncSignalOptions | string): T;
+declare function tabSync<T extends WritableSignal<any>>(sig: T, opt: StoreTabSyncOptions | SyncSignalOptions | string): T;
 /**
  * @deprecated Use `tabSync` with `SyncSignalOptions` instead and pass the options as the second argument
  * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
@@ -3741,5 +4105,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { MmActivity, MmTransition, MmViewTransitionName, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, latest, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, projection, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
-export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, LatestSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpLog, OpLogDriver, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOp, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebaseOps, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncOptions, Opaque, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncSignalOptions, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };