@mmstack/primitives 20.10.1 → 20.11.0

package/fesm2022/mmstack-primitives.mjs

@@ -208,8 +208,7 @@ class MmActivity {
         if (this.onServer)
             return;
         for (const node of this.view.rootNodes) {
-            // covers HTML and SVG roots; text/comment roots can't be styled — their CD is still
-            // detached, but prefer an element root for true visual hiding
+            // covers HTML and SVG roots; text/comment roots can't be styled, their CD is still detached
             if (node instanceof HTMLElement || node instanceof SVGElement)
                 node.style.display = visible ? '' : 'none';
         }
@@ -227,8 +226,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                     selector: '[mmActivity]',
                 }]
         }], ctorParameters: () => [], propDecorators: { visible: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmActivity", required: true }] }] } });
-// Shared never-paused signal returned outside a boundary / on the server (SSR renders the full tree,
-// nothing is paused). Readonly so a consumer can't cast-and-`.set()` the shared default for everyone.
 const NEVER_PAUSED = signal(false).asReadonly();
 /**
  * Inject the nearest paused-state signal — `true` while the surrounding subtree is paused (hidden by
@@ -493,7 +490,7 @@ function deferredValue(source, opt) {
     let cancel = null;
     const watch = effect(() => {
         const v = source();
-        cancel?.(); // latest wins: rapid changes coalesce into one catch-up
+        cancel?.();
         cancel = schedule(() => {
             cancel = null;
             out.set(v);
@@ -505,8 +502,6 @@ function deferredValue(source, opt) {
         cancel = null;
     });
     const result = computed(() => out());
-    // "behind" is a value comparison, not a schedule flag: an equal-valued catch-up
-    // (e.g. type a char, delete it before the deferred view caught up) is not pending
     result.pending = computed(() => !equal(out(), source()), ...(ngDevMode ? [{ debugName: "pending" }] : []));
     return result;
 }
@@ -530,6 +525,46 @@ function resolveScheduler(strategy, injector) {
     };
 }
 
+const CONCURRENCY_INSTRUMENTATION = new InjectionToken('@mmstack/primitives:concurrency-instrumentation');
+function provideConcurrencyInstrumentation(listener) {
+    return { provide: CONCURRENCY_INSTRUMENTATION, useValue: listener };
+}
+const now = () => typeof globalThis.performance !== 'undefined'
+    ? globalThis.performance.now()
+    : Date.now();
+/**
+ * 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.
+ */
+function perfCustomTracks(track = 'mmstack concurrency') {
+    const canMeasure = typeof globalThis.performance !== 'undefined' &&
+        typeof globalThis.performance.measure === 'function';
+    const span = (name, start) => {
+        if (!canMeasure)
+            return;
+        try {
+            globalThis.performance.measure(name, {
+                start,
+                end: now(),
+                detail: {
+                    devtools: { dataType: 'track-entry', track, color: 'primary' },
+                },
+            });
+        }
+        catch {
+            // measure options with detail are unsupported on this engine — skip silently
+        }
+    };
+    return {
+        pendingStart: (e) => e.at,
+        pendingEnd: (handle, e) => span(`pending`, handle ?? e.at),
+        transactionStart: (e) => e.at,
+        transactionEnd: (handle, e) => span(`transaction`, handle ?? e.at),
+    };
+}
+
 /**
  * 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
@@ -604,8 +639,13 @@ function isMutable(value) {
     return 'mutate' in value && typeof value.mutate === 'function';
 }
 
-function createTransitionScope() {
+function createTransitionScope(opt) {
     const list = mutable([]);
+    const inst = opt?.instrumentation;
+    const name = opt?.name ?? 'scope';
+    const at = () => typeof globalThis.performance !== 'undefined'
+        ? globalThis.performance.now()
+        : Date.now();
     const pending = computed(() => list().some(({ ref }) => {
         const s = ref.status();
         return s === 'loading' || s === 'reloading';
@@ -616,11 +656,17 @@ function createTransitionScope() {
         resources: computed(() => list().map((e) => e.ref)),
         pending,
         suspended: (type) => list().some(({ ref, suspends }) => suspends && (type === 'loading' ? ref.isLoading() : !ref.hasValue())),
-        add: (ref, opt) => untracked(() => list.inline((c) => c.push({ ref, suspends: opt?.suspends ?? true }))),
+        add: (ref, o) => untracked(() => {
+            const suspends = o?.suspends ?? true;
+            list.inline((c) => c.push({ ref, suspends }));
+            inst?.resourceRegistered?.({ scope: name, suspends });
+        }),
         remove: (ref) => untracked(() => list.inline((c) => {
             const i = c.findIndex((e) => e.ref === ref);
-            if (i !== -1)
+            if (i !== -1) {
                 c.splice(i, 1);
+                inst?.resourceRemoved?.({ scope: name });
+            }
         })),
         commit: (value) => linkedSignal({
             source: () => ({ v: value(), settled: !pending() }),
@@ -635,6 +681,8 @@ function createTransitionScope() {
                     aborted++;
                 }
             }
+            if (aborted > 0)
+                inst?.abortPending?.({ scope: name, aborted, at: at() });
             return aborted;
         }),
         holding,
@@ -703,13 +751,59 @@ function bridgeScopeToPendingTasks(scope, injector) {
         });
     });
 }
+/**
+ * While a listener is installed, bracket each pending window of `scope` with a
+ * `pendingStart`/`pendingEnd` span (the reactive tap that needs an injection context). No-op
+ * when no listener is provided, so it stays zero-cost by default.
+ */
+function bridgeScopeToInstrumentation(scope, name, injector) {
+    const run = (fn) => injector ? runInInjectionContext(injector, fn) : fn();
+    run(() => {
+        const inst = inject(CONCURRENCY_INSTRUMENTATION, { optional: true });
+        if (!inst?.pendingStart && !inst?.pendingEnd)
+            return;
+        const at = () => typeof globalThis.performance !== 'undefined'
+            ? globalThis.performance.now()
+            : Date.now();
+        let handle;
+        let open = false;
+        effect(() => {
+            const pending = scope.pending();
+            untracked(() => {
+                if (pending && !open) {
+                    open = true;
+                    handle = inst.pendingStart?.({
+                        scope: name,
+                        resources: scope.resources().length,
+                        at: at(),
+                    });
+                }
+                else if (!pending && open) {
+                    open = false;
+                    inst.pendingEnd?.(handle, { at: at() });
+                }
+            });
+        });
+        inject(DestroyRef).onDestroy(() => {
+            if (open)
+                inst.pendingEnd?.(handle, { at: at() });
+        });
+    });
+}
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
-function provideTransitionScope() {
+function provideTransitionScope(opt) {
     return {
         provide: TRANSITION_SCOPE,
         useFactory: () => {
-            const scope = createTransitionScope();
+            const listener = opt?.instrumentation ??
+                inject(CONCURRENCY_INSTRUMENTATION, { optional: true }) ??
+                undefined;
+            const scope = createTransitionScope({
+                name: opt?.name,
+                instrumentation: listener,
+            });
             bridgeScopeToPendingTasks(scope);
+            bridgeScopeToInstrumentation(scope, opt?.name ?? 'scope');
             return scope;
         },
     };
@@ -857,8 +951,6 @@ function use(res) {
         frame.seen.add(res);
         frame.deps.push(res);
     }
-    // status() is read tracked even on the short-circuit paths, so the owning computed
-    // re-evaluates when the load settles / the error clears.
     if (res.status() === 'error') {
         frame.errors.push(res.error?.());
         throw BLOCKED;
@@ -906,9 +998,6 @@ function latest(fn, opt) {
         }
     }, opt?.debugName ? { debugName: `${opt.debugName}:evaluation` } : undefined);
     const equal = opt?.equal ?? Object.is;
-    // The stale-while-revalidate atom: holds the last successful result through blocked /
-    // errored rounds. `equal` gates notification, so an in-flight cycle that lands on an
-    // equal value never ripples to consumers — while `pending` (independent) still cycles.
     const held = linkedSignal(...(ngDevMode ? [{ debugName: "held", source: evaluation,
             computation: (ev, prev) => ev.kind === 'value'
                 ? { has: true, v: ev.value }
@@ -980,8 +1069,7 @@ function injectStartTransition() {
     const destroyRef = inject(DestroyRef);
     const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
-        // attributed: loads already in flight when the transition starts are not ours —
-        // they can neither settle this transition early nor block it forever
+        // attributed: loads already in flight when the transition starts are not ours
         const pending = createAttributedPending(scope);
         untracked(fn);
         let sawPending = false;
@@ -1006,8 +1094,7 @@ function injectStartTransition() {
                     settle();
                 return;
             }
-            // no-async fallback: once the reactive system has processed the writes (afterNextRender),
-            // if nothing ever went in flight, the transition is already complete.
+            // no-async fallback: once the reactive system has processed the writes,
             afterNextRender(() => {
                 if (!sawPending && !untracked(pending))
                     settle();
@@ -1112,9 +1199,6 @@ function createTransaction() {
         clear: () => log.clear(),
     };
 }
-// The currently-active transaction, set only for the synchronous duration of a `startTransaction`
-// body (so stateful actions running inside it can record their writes). Module-level + sync
-// set/reset is the honest shape: a transaction is call-scoped, not structural-per-injector.
 let active = null;
 /** The transaction in effect right now, or `null`. Stateful actions consult this to record undo. */
 function activeTransaction() {
@@ -1153,10 +1237,7 @@ function injectStartTransaction() {
     const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         const txn = createTransaction();
-        // attributed: loads already in flight when the transaction starts are not ours —
-        // they can neither commit this transaction early nor block its settle forever
         const pending = createAttributedPending(scope);
-        // Hold BEFORE the writes, so the display freezes at pre-transaction values.
         scope.beginHold();
         let finished = false;
         // eslint-disable-next-line prefer-const -- assigned in try/catch, but needs to be declared here for the `finally` block to see it
@@ -1165,9 +1246,6 @@ function injectStartTransaction() {
         const done = new Promise((resolve) => {
             resolveDone = resolve;
         });
-        // Every exit path funnels through here, so `done` always settles — including `abort()`
-        // and a throwing transaction body (which would otherwise leak the hold forever and
-        // freeze the boundary with no recovery).
         const finish = (restore) => {
             if (finished)
                 return;
@@ -1181,9 +1259,6 @@ function injectStartTransaction() {
             scope.endHold();
             resolveDone();
         };
-        // The scope may outlive the calling context (a component transacting on an ancestor
-        // boundary): a destroy mid-flight kills the settle watcher, so without this the hold
-        // would leak and freeze the surviving scope forever. Keep the writes — they landed live.
         const releaseDestroy = destroyRef.onDestroy(() => finish(false));
         try {
             runInTransaction(txn, fn);
@@ -1205,7 +1280,7 @@ function injectStartTransaction() {
                 finish(false);
         }
         else {
-            // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
+            // no-async fallback
             afterNextRender(() => {
                 if (!sawPending && !untracked(pending))
                     finish(false);
@@ -1283,7 +1358,6 @@ class MmTransition {
     }
     onValue(v) {
         if (!this.current) {
-            // first render: nothing to hold yet — show immediately (also what SSR serializes)
             this.current = this.createView(v).view;
             return;
         }
@@ -1297,8 +1371,7 @@ class MmTransition {
         const { view, scope } = this.createView(v);
         this.setHidden(view, true);
         this.holding.set(true);
-        // Registration happens synchronously during view creation, so a resource already in
-        // flight counts from the start; later kickoffs are caught by the watcher.
+        // Registration happens synchronously during view creation, so a resource already incl. later kickoffs are caught by the watcher.
         let sawPending = untracked(scope.pending);
         const watcher = effect(() => {
             const pending = scope.pending();
@@ -1355,8 +1428,6 @@ class MmTransition {
         this.holding.set(false);
     }
     createView(v) {
-        // Each view gets its own scope, so its subtree's resources register here by existing —
-        // and the outgoing view's background work can't block the swap (per-view isolation).
         const injector = Injector.create({
             parent: this.parent,
             providers: [provideTransitionScope()],
@@ -1442,7 +1513,7 @@ function getSignalEquality(sig) {
     if (internal && typeof internal.equal === 'function') {
         return internal.equal;
     }
-    return Object.is; // Default equality check
+    return Object.is;
 }
 
 /**
@@ -1590,8 +1661,6 @@ function isIndexProp(prop) {
     return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
 }
 
-// Container resolvers used by createVivify: each returns the current value when present and
-// only creates a new container when it is null/undefined.
 function identity(x) {
     return x;
 }
@@ -1749,11 +1818,6 @@ function derived(source, optOrKey, opt) {
             cnt++;
             try {
                 sig.update(updater);
-                // The wrapped computed evaluates its `equal` lazily — at the next read, which would
-                // normally happen after `cnt` has already dropped back to 0. For a reference-stable
-                // mutation that read compares the same object to itself and the version never bumps,
-                // so dependents are never notified. Reading here, while equality is still suppressed,
-                // forces the recompute (and version bump) inside the mutate window.
                 untracked(sig);
             }
             finally {
@@ -1841,8 +1905,6 @@ function createSetter(source) {
 
 function keepPrevious(src, opt) {
     const mutableSrc = isWritableSignal(src) && isMutable(src);
-    // For a mutable source the linkedSignal's equality must be suppressible: a forwarded
-    // `mutate` keeps the same reference, which default equality would otherwise swallow.
     let cnt = 0;
     const baseEqual = opt?.equal;
     const equal = mutableSrc
@@ -1860,16 +1922,11 @@ function keepPrevious(src, opt) {
     if (isWritableSignal(src)) {
         persisted.set = src.set;
         persisted.update = src.update;
-        // NOTE: `asReadonly` deliberately stays the linkedSignal's own — returning the
-        // source's readonly view would reintroduce the `undefined` flashes this wrapper exists
-        // to prevent.
         if (mutableSrc) {
             persisted.mutate = (updater) => {
                 cnt++;
                 try {
                     src.mutate(updater);
-                    // force the recompute while equality is suppressed, so the reference-stable
-                    // mutation bumps the wrapper's version (see derived.ts for the same pattern)
                     untracked(persisted);
                 }
                 finally {
@@ -1912,8 +1969,7 @@ function indexArray(source, map, opt = {}) {
         : toWritable(data, () => {
             // noop
         });
-    // copy before defaulting `equal` — assigning onto `opt` would mutate a caller-owned
-    // (possibly shared/reused) options object
+    // copy before defaulting `equal` — assigning onto `opt` would mutate a caller-owned (possibly shared/reused) options object
     if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
         opt = {
             ...opt,
@@ -2608,8 +2664,7 @@ function observerSupported$1() {
  */
 function elementSize(target, opt) {
     return runInSensorContext(opt?.injector, () => 
-    // the host-element default must resolve INSIDE the sensor context, not as a
-    // parameter default (which would run before the injector wrapper)
+    // the host-element default must resolve INSIDE the sensor context
     createElementSize(target ?? inject(ElementRef), opt));
 }
 function createElementSize(target, opt) {
@@ -2746,10 +2801,7 @@ function observerSupported() {
  * ```
  */
 function elementVisibility(target, opt) {
-    return runInSensorContext(opt?.injector, () => 
-    // the host-element default must resolve INSIDE the sensor context, not as a
-    // parameter default (which would run before the injector wrapper)
-    createElementVisibility(target ?? inject(ElementRef), opt));
+    return runInSensorContext(opt?.injector, () => createElementVisibility(target ?? inject(ElementRef), opt));
 }
 function createElementVisibility(target, opt) {
     if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
@@ -2820,10 +2872,7 @@ function unwrap$1(target) {
  * ```
  */
 function focusWithin(target, opt) {
-    return runInSensorContext(opt?.injector, () => 
-    // the host-element default must resolve INSIDE the sensor context, not as a
-    // parameter default (which would run before the injector wrapper)
-    createFocusWithin(target ?? inject(ElementRef), opt));
+    return runInSensorContext(opt?.injector, () => createFocusWithin(target ?? inject(ElementRef), opt));
 }
 function createFocusWithin(target, opt) {
     const debugName = opt?.debugName ?? 'focusWithin';
@@ -3300,8 +3349,6 @@ function createMousePosition(opt) {
         }
         pos.set({ x, y });
     };
-    // passive: the handler never calls preventDefault, and a non-passive touchmove on
-    // window forces the browser to wait on JS before scrolling (scroll jank on touch)
     const attach = (el) => {
         const controller = new AbortController();
         el.addEventListener('mousemove', updatePosition, {
@@ -3317,7 +3364,7 @@ function createMousePosition(opt) {
         return () => controller.abort();
     };
     if (isSignal(target)) {
-        // re-attach whenever the signal resolves to a (new) element — covers viewChild
+        // covers viewChild case
         effect((cleanup) => {
             const el = resolve(target());
             if (!el)
@@ -3770,7 +3817,6 @@ function createScrollPosition(opt) {
         ms: throttle,
     });
     if (isSignal(target)) {
-        // re-attach whenever the signal resolves to a (new) element — covers viewChild
         effect((cleanup) => {
             const el = resolve(target());
             if (!el)
@@ -3964,7 +4010,6 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
             state.set(event);
     };
     const { destroyRef: providedDestroyRef, 
-    // strip non-listener keys so they don't leak into addEventListener options
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     injector: _injector, 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -3978,8 +4023,7 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
             resolved.addEventListener(eventName, handler, listenerOpts);
             cleanup(() => resolved.removeEventListener(eventName, handler, listenerOpts));
         }, ...(ngDevMode ? [{ debugName: "effectRef", injector }] : [{ injector }]));
-        // honor an explicit destroyRef for signal targets too — the effect would otherwise
-        // only follow the injector's lifetime, contradicting the documented option
+        // honor an explicit destroyRef for signal targets
         providedDestroyRef?.onDestroy(() => effectRef.destroy());
     }
     else {
@@ -4148,6 +4192,228 @@ function createFallbackOnChange(target, prop, vivifyFn, isMutableSource) {
         : (newValue) => target.update(write(newValue));
 }
 
+function generateOrigin$1() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return Math.random().toString(36).substring(2);
+}
+const isPlainArray$1 = (v) => Array.isArray(v) && !isOpaque(v);
+/**
+ * Reference-identity-pruned structural diff — the same short-circuit discipline as `merge3`:
+ * an untouched subtree kept its reference (the store's copy-on-write contract), so the walk
+ * descends only where refs differ. O(changed paths), not O(tree).
+ */
+function diffNode(prev, next, path, ops) {
+    if (Object.is(prev, next))
+        return;
+    if (isRecord(prev) && isRecord(next)) {
+        for (const key of Object.keys(prev)) {
+            if (!Object.hasOwn(next, key))
+                ops.push({ kind: 'delete', path: [...path, key], prev: prev[key] });
+        }
+        for (const key of Object.keys(next)) {
+            if (!Object.hasOwn(prev, key)) {
+                // added key: deliberately NO `prev` property (absent ≠ undefined)
+                ops.push({ kind: 'set', path: [...path, key], next: next[key] });
+            }
+            else {
+                diffNode(prev[key], next[key], [...path, key], ops);
+            }
+        }
+        return;
+    }
+    if (isPlainArray$1(prev) && isPlainArray$1(next)) {
+        // same length → per-index descent (matches `arr[i].x.set(...)` writes); a length
+        // change is a whole unit — index attribution lies under insert/remove/reorder
+        if (prev.length === next.length) {
+            for (let i = 0; i < next.length; i++)
+                diffNode(prev[i], next[i], [...path, i], ops);
+            return;
+        }
+        ops.push({ kind: 'set', path, prev, next });
+        return;
+    }
+    // leaf / type change / opaque — one unit, prev present (the slot existed)
+    ops.push({ kind: 'set', path, prev, next });
+}
+/** Immutably applies one op along its path, vivifying missing containers `'auto'`-style. */
+function applyAt(container, path, idx, op) {
+    const seg = path[idx];
+    const base = isPlainArray$1(container)
+        ? container.slice()
+        : isRecord(container)
+            ? { ...container }
+            : typeof seg === 'number'
+                ? []
+                : {};
+    if (idx === path.length - 1) {
+        if (op.kind === 'delete') {
+            // arrays never receive deletes (length changes travel as whole-array sets)
+            delete base[seg];
+        }
+        else {
+            base[seg] = op.next;
+        }
+        return base;
+    }
+    base[seg] = applyAt(base[seg], path, idx + 1, op);
+    return base;
+}
+/**
+ * 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.
+ */
+function applyOps(root, ops) {
+    const list = Array.isArray(ops) ? ops : ops.ops;
+    let next = root;
+    for (const op of list) {
+        if (op.path.length === 0) {
+            if (op.kind === 'set')
+                next = op.next;
+            continue; // a root delete is meaningless — ignore (mirrors OpLog.apply)
+        }
+        next = applyAt(next, op.path, 0, op);
+    }
+    return next;
+}
+/**
+ * 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.
+ */
+function diffOps(prev, next) {
+    const ops = [];
+    diffNode(prev, next, [], ops);
+    return ops;
+}
+/**
+ * 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.
+ */
+function invertBatch(batch) {
+    const ops = Array.isArray(batch) ? batch : batch.ops;
+    const inverted = [];
+    for (let i = ops.length - 1; i >= 0; i--) {
+        const op = ops[i];
+        if (op.kind === 'delete') {
+            inverted.push({
+                kind: 'set',
+                path: op.path,
+                next: op.prev,
+                prev: undefined,
+            });
+            continue;
+        }
+        if (!Object.hasOwn(op, 'prev')) {
+            inverted.push({ kind: 'delete', path: op.path, prev: op.next });
+        }
+        else {
+            inverted.push({
+                kind: 'set',
+                path: op.path,
+                next: op.prev,
+                prev: op.next,
+            });
+        }
+    }
+    return inverted;
+}
+/**
+ * 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'], … }
+ * ```
+ */
+function opLog(source, opt) {
+    const origin = opt?.origin ?? generateOrigin$1();
+    const storeKind = source[STORE_KIND];
+    const mutableSource = storeKind ? storeKind === 'mutable' : isMutable(source);
+    if (isDevMode() && mutableSource) {
+        console.warn('[@mmstack/primitives] opLog observes copy-on-write updates via reference identity — a MUTABLE store/signal mutates in place, so changes are invisible to it. Use an immutable store, or set whole values.');
+    }
+    let prevRoot = untracked(source);
+    let version = 0;
+    let destroyed = false;
+    const subscribers = new Set();
+    const latest = signal(null, ...(ngDevMode ? [{ debugName: "latest" }] : []));
+    /** Diff now, emit if there's a delta, advance the baseline. */
+    const flush = () => {
+        if (destroyed)
+            return;
+        const next = untracked(source);
+        if (Object.is(prevRoot, next))
+            return;
+        const ops = [];
+        diffNode(prevRoot, next, [], ops);
+        prevRoot = next;
+        if (!ops.length)
+            return; // fresh refs, equal values — spurious-write tolerance
+        const batch = { origin, version: ++version, ops };
+        latest.set(batch);
+        for (const cb of [...subscribers])
+            cb(batch);
+    };
+    const run = () => {
+        source(); // track every commit…
+        untracked(flush); // …and emit the delta since the last flush
+    };
+    // default driver is an Angular effect (needs an injector); a supplied driver runs injector-free
+    // (the worker-side seam, e.g. microtaskOpLogDriver from @mmstack/worker/host)
+    const ref = opt?.driver
+        ? opt.driver(run)
+        : effect(run, { injector: opt?.injector ?? inject(Injector) });
+    return {
+        latest: latest.asReadonly(),
+        subscribe: (cb) => {
+            subscribers.add(cb);
+            return () => subscribers.delete(cb);
+        },
+        // the emission core, callable on demand — reads the source untracked, so it never disturbs the
+        // driver's subscription; a subsequent scheduled run just finds the baseline already advanced
+        flush: () => flush(),
+        apply: (batchOrOps) => {
+            const ops = Array.isArray(batchOrOps)
+                ? batchOrOps
+                : batchOrOps.ops;
+            if (!ops.length)
+                return;
+            // pending local writes must emit BEFORE the baseline advances past them
+            flush();
+            const root = applyOps(untracked(source), ops); // one atomic root, structural-shared
+            source.set(root);
+            prevRoot = root; // baseline advance: an applied batch never echoes
+        },
+        destroy: () => {
+            destroyed = true;
+            subscribers.clear();
+            ref.destroy();
+        },
+    };
+}
+
 /**
  * @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
@@ -4318,8 +4584,7 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
         vivify,
         noUnionLeaves,
         [STORE_SHARED_GLOBALS]: {
-            // the `injector!` reads run only when a global is absent, which (per hasSharedGlobals) means
-            // an injector was resolved above
+            // the `injector!` reads run only when a global is absent
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             cache: sharedGlobals?.cache ?? injector.get(PROXY_CACHE_TOKEN),
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -4399,8 +4664,6 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
                         injector,
                         vivify,
                         noUnionLeaves,
-                        // forward the resolved globals — re-resolving from the injector both re-injects
-                        // needlessly and breaks in DI-less (worker) mode where injector is undefined
                         [STORE_SHARED_GLOBALS]: STORE_OPTIONS[STORE_SHARED_GLOBALS],
                     }));
                 };
@@ -4416,8 +4679,6 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
                     return arrayLength();
                 if (prop === Symbol.iterator)
                     return function* () {
-                        // read length reactively: a spread/for-of inside a computed/effect must re-run
-                        // when items are added or removed, not only when already-read elements change
                         const len = arrayLength();
                         for (let i = 0; i < len(); i++)
                             yield receiver[i];
@@ -4664,9 +4925,6 @@ function forkStore(base, opt) {
             source: () => base(),
             computation: (theirs, prev) => prev === undefined ? theirs : merge(prev.source, prev.value, theirs),
         }]));
-    // Inherit the base's shared options (injector, vivify, noUnionLeaves + the
-    // proxy cache/registry), same as extendStore — a fork should vivify like its
-    // base and share its injector-scoped cache. `opt` overrides (advanced use).
     const store = toStore(staged, {
         ...base[STORE_SHARED_OPTIONS],
         ...opt,
@@ -4675,233 +4933,678 @@ function forkStore(base, opt) {
         store,
         commit: () => base.set(untracked(staged)),
         discard: () => staged.set(untracked(base)),
+        ops: () => diffOps(untracked(base), untracked(staged)),
     };
 }
 
-function generateOrigin() {
-    if (globalThis.crypto?.randomUUID)
-        return globalThis.crypto.randomUUID();
-    return Math.random().toString(36).substring(2);
+/** Total order over stamps alone; ties break on `writer` via {@link compareTotal}. */
+function compareHlc(a, b) {
+    return a.p !== b.p ? a.p - b.p : a.l - b.l;
+}
+/** The protocol's total order: (hlc.p, hlc.l, writer). Never returns 0 for distinct writers. */
+function compareTotal(a, writerA, b, writerB) {
+    const byClock = compareHlc(a, b);
+    if (byClock !== 0)
+        return byClock;
+    return writerA < writerB ? -1 : writerA > writerB ? 1 : 0;
+}
+const SKEW_WARN_MS = 5 * 60_000;
+/**
+ * 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.
+ */
+function createHlcClock(now = Date.now) {
+    let p = 0;
+    let l = 0;
+    const advance = (wall, observed) => {
+        const nextP = Math.max(p, wall, observed?.p ?? 0);
+        if (nextP === p) {
+            l = Math.max(l, observed && observed.p === nextP ? observed.l : 0) + 1;
+        }
+        else {
+            p = nextP;
+            l = observed && observed.p === nextP ? observed.l + 1 : 0;
+        }
+    };
+    return {
+        next: () => {
+            advance(now());
+            return { p, l };
+        },
+        observe: (remote) => {
+            const wall = now();
+            if (isDevMode() && remote.p - wall > SKEW_WARN_MS) {
+                console.warn(`[@mmstack/primitives] observed remote clock ${Math.round((remote.p - wall) / 1000)}s ahead — convergence holds, but last-writer-wins fairness degrades under clock skew`);
+            }
+            advance(wall, remote);
+        },
+    };
 }
-const isPlainArray$1 = (v) => Array.isArray(v) && !isOpaque(v);
+
+const OP_PROTO_VERSION = 1;
+const CONFLICT_BRAND = '~mmstackConflict';
+function isConflicted(value) {
+    return typeof value === 'object' && value !== null && CONFLICT_BRAND in value;
+}
+const lww = (_ancestor, mine) => mine;
+const mergeThree = (ancestor, mine, theirs) => merge3(ancestor, mine, theirs);
+const preserve = (ancestor, mine, theirs) => ({ [CONFLICT_BRAND]: true, mine, theirs, ancestor });
 /**
- * Reference-identity-pruned structural diff — the same short-circuit discipline as `merge3`:
- * an untouched subtree kept its reference (the store's copy-on-write contract), so the walk
- * descends only where refs differ. O(changed paths), not O(tree).
+ * 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.
  */
-function diffNode(prev, next, path, ops) {
-    if (Object.is(prev, next))
-        return;
-    if (isRecord(prev) && isRecord(next)) {
-        for (const key of Object.keys(prev)) {
-            if (!Object.hasOwn(next, key))
-                ops.push({ kind: 'delete', path: [...path, key], prev: prev[key] });
+function keyedArray(identity, opt) {
+    const mergeItem = opt?.item ?? mergeThree;
+    return (ancestor, mine, theirs, ctx) => {
+        if (!Array.isArray(mine) || !Array.isArray(theirs)) {
+            return mine; // type conflict → total-order winner, like lww
         }
-        for (const key of Object.keys(next)) {
-            if (!Object.hasOwn(prev, key)) {
-                // added key: deliberately NO `prev` property (absent ≠ undefined)
-                ops.push({ kind: 'set', path: [...path, key], next: next[key] });
+        const anc = Array.isArray(ancestor) ? ancestor : [];
+        const byKey = (arr) => {
+            const map = new Map();
+            for (const item of arr)
+                map.set(identity(item), item);
+            return map;
+        };
+        const ancMap = byKey(anc);
+        const mineMap = byKey(mine);
+        const theirsMap = byKey(theirs);
+        const out = [];
+        for (const item of mine) {
+            const key = identity(item);
+            const other = theirsMap.get(key);
+            const base = ancMap.get(key);
+            if (theirsMap.has(key)) {
+                out.push(structuralEq(item, other)
+                    ? item
+                    : mergeItem(base, item, other, ctx));
             }
-            else {
-                diffNode(prev[key], next[key], [...path, key], ops);
+            else if (!ancMap.has(key) || !structuralEq(item, base)) {
+                out.push(item); // added by mine, or edited by mine while theirs removed it → keep
             }
+            // else: theirs removed it and mine left it untouched → stays removed
         }
-        return;
-    }
-    if (isPlainArray$1(prev) && isPlainArray$1(next)) {
-        // same length → per-index descent (matches `arr[i].x.set(...)` writes); a length
-        // change is a whole unit — index attribution lies under insert/remove/reorder
-        if (prev.length === next.length) {
-            for (let i = 0; i < next.length; i++)
-                diffNode(prev[i], next[i], [...path, i], ops);
-            return;
+        for (const item of theirs) {
+            const key = identity(item);
+            if (mineMap.has(key))
+                continue;
+            if (!ancMap.has(key) || !structuralEq(item, ancMap.get(key))) {
+                out.push(item); // added by theirs, or edited by theirs while mine removed it → keep
+            }
         }
-        ops.push({ kind: 'set', path, prev, next });
-        return;
-    }
-    // leaf / type change / opaque — one unit, prev present (the slot existed)
-    ops.push({ kind: 'set', path, prev, next });
+        return out;
+    };
 }
-/** Immutably applies one op along its path, vivifying missing containers `'auto'`-style. */
-function applyAt(container, path, idx, op) {
-    const seg = path[idx];
-    const base = isPlainArray$1(container)
-        ? container.slice()
-        : isRecord(container)
-            ? { ...container }
-            : typeof seg === 'number'
-                ? []
-                : {};
-    if (idx === path.length - 1) {
-        if (op.kind === 'delete') {
-            // arrays never receive deletes (length changes travel as whole-array sets)
-            delete base[seg];
+function compilePolicies(entries) {
+    return entries.map((e) => ({
+        segments: typeof e.path === 'string' ? e.path.split('.') : e.path.map(String),
+        merge: e.merge,
+    }));
+}
+function policyFor(policies, path) {
+    outer: for (const p of policies) {
+        if (p.segments.length !== path.length)
+            continue;
+        for (let i = 0; i < path.length; i++) {
+            if (p.segments[i] !== '*' && p.segments[i] !== String(path[i]))
+                continue outer;
         }
-        else {
-            base[seg] = op.next;
+        return p.merge;
+    }
+    return lww;
+}
+const SEP = '';
+const keyOf$1 = (path) => path.map(String).join(SEP);
+function structuralEq(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' ||
+        typeof b !== 'object' ||
+        a === null ||
+        b === null ||
+        Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka) {
+        if (!Object.hasOwn(b, k))
+            return false;
+        if (!structuralEq(a[k], b[k])) {
+            return false;
         }
-        return base;
     }
-    base[seg] = applyAt(base[seg], path, idx + 1, op);
-    return base;
+    return true;
 }
+// total order (hlc, writer, origin): two origins can share a writer AND a stamp
+// (independent clocks, same ms), so only origin makes the order strict
+const compareStamp = (a, b) => {
+    const byTotal = compareTotal(a.hlc, a.writer, b.hlc, b.writer);
+    if (byTotal !== 0)
+        return byTotal;
+    return a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0;
+};
+const beats = (a, b) => compareStamp(a, b) > 0;
 /**
- * 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.
+ * 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.
  */
-function applyOps(root, ops) {
-    const list = Array.isArray(ops) ? ops : ops.ops;
-    let next = root;
-    for (const op of list) {
-        if (op.path.length === 0) {
-            if (op.kind === 'set')
-                next = op.next;
-            continue; // a root delete is meaningless — ignore (mirrors OpLog.apply)
+function createConvergingApply(opt) {
+    const registers = new Map();
+    const policies = compilePolicies(opt?.policies ?? []);
+    const resolveConcurrent = (winner, loser, path) => {
+        const merge = policyFor(policies, path);
+        if (merge === lww || winner.kind === 'delete' || loser.kind === 'delete') {
+            return winner;
         }
-        next = applyAt(next, op.path, 0, op);
+        const resolved = merge(loser.prev, winner.next, loser.next, { path });
+        if (Object.is(resolved, winner.next))
+            return winner;
+        return { kind: 'set', path, next: resolved, prev: winner.next };
+    };
+    // a sequential edit carries the value it overwrote; a mismatch means neither saw the other.
+    // Structural, not referential: identity never survives the wire, so a peer that built on
+    // the replicated copy of a value must still count as sequential.
+    const concurrentWith = (incoming, registered) => {
+        if (incoming.kind === 'delete' || registered.kind === 'delete')
+            return false;
+        if (!Object.hasOwn(incoming, 'prev'))
+            return true;
+        return !structuralEq(incoming.prev, registered.next);
+    };
+    return {
+        ingest: (env, o) => {
+            const stamp = { hlc: env.hlc, writer: env.writer, origin: env.origin };
+            const out = [];
+            for (const op of env.ops) {
+                const key = keyOf$1(op.path);
+                let dominated = false;
+                let exact;
+                for (let len = 0; len <= op.path.length; len++) {
+                    const reg = registers.get(keyOf$1(op.path.slice(0, len)));
+                    if (!reg)
+                        continue;
+                    if (len === op.path.length)
+                        exact = reg;
+                    else if (beats(reg, stamp)) {
+                        dominated = true;
+                        break;
+                    }
+                }
+                if (dominated)
+                    continue;
+                if (exact && beats(exact, stamp)) {
+                    if (concurrentWith(op, exact.op)) {
+                        const resolved = resolveConcurrent(exact.op, op, op.path);
+                        if (resolved !== exact.op) {
+                            exact.op = resolved;
+                            if (!o?.local)
+                                out.push(resolved);
+                        }
+                    }
+                    continue;
+                }
+                let accepted = op;
+                if (exact && concurrentWith(op, exact.op)) {
+                    accepted = resolveConcurrent(op, exact.op, op.path);
+                }
+                const isDescendant = key === ''
+                    ? (k) => k !== ''
+                    : (k) => k.startsWith(key + SEP);
+                const replays = [];
+                for (const [k, reg] of registers) {
+                    if (!isDescendant(k))
+                        continue;
+                    if (beats(stamp, reg))
+                        registers.delete(k);
+                    else
+                        replays.push(reg);
+                }
+                replays.sort(compareStamp);
+                registers.set(key, { hlc: env.hlc, writer: env.writer, origin: env.origin, op: accepted });
+                if (!o?.local) {
+                    out.push(accepted);
+                    for (const r of replays)
+                        out.push(r.op);
+                }
+            }
+            return out;
+        },
+        reset: () => registers.clear(),
+    };
+}
+function getAtPath(root, path) {
+    let cur = root;
+    for (const seg of path) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
     }
-    return next;
+    return cur;
 }
 /**
- * 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 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.
  */
-function diffOps(prev, next) {
-    const ops = [];
-    diffNode(prev, next, [], ops);
-    return ops;
+function rebaseOps(root, pending, remote, policies) {
+    const compiled = compilePolicies(policies ?? []);
+    let base = root;
+    for (let i = pending.length - 1; i >= 0; i--) {
+        base = applyOps(base, invertBatch(pending[i]));
+    }
+    base = applyOps(base, remote);
+    const rebased = [];
+    for (const batch of pending) {
+        const next = [];
+        for (const op of batch) {
+            const cur = getAtPath(base, op.path);
+            if (op.kind === 'delete') {
+                next.push({ kind: 'delete', path: op.path, prev: cur });
+            }
+            else if (cur === undefined) {
+                next.push({ kind: 'set', path: op.path, next: op.next });
+            }
+            else if (Object.hasOwn(op, 'prev') && !structuralEq(op.prev, cur)) {
+                const merge = policyFor(compiled, op.path);
+                const resolved = merge(op.prev, op.next, cur, { path: op.path });
+                next.push({ kind: 'set', path: op.path, next: resolved, prev: cur });
+            }
+            else {
+                next.push({ kind: 'set', path: op.path, next: op.next, prev: cur });
+            }
+        }
+        base = applyOps(base, next);
+        rebased.push(next);
+    }
+    return { root: base, pending: rebased };
 }
 /**
- * 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.
+ * 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'`.
  */
-function invertBatch(batch) {
-    const ops = Array.isArray(batch) ? batch : batch.ops;
-    const inverted = [];
-    for (let i = ops.length - 1; i >= 0; i--) {
-        const op = ops[i];
-        if (op.kind === 'delete') {
-            inverted.push({
-                kind: 'set',
-                path: op.path,
-                next: op.prev,
-                prev: undefined,
-            });
-            continue;
-        }
-        if (!Object.hasOwn(op, 'prev')) {
-            inverted.push({ kind: 'delete', path: op.path, prev: op.next });
-        }
-        else {
-            inverted.push({
-                kind: 'set',
-                path: op.path,
-                next: op.prev,
-                prev: op.next,
-            });
-        }
-    }
-    return inverted;
+function policyStrategy(policies) {
+    return (ancestor, mine, theirs) => rebaseOps(mine, [diffOps(ancestor, mine)], diffOps(ancestor, theirs), policies).root;
+}
+function generateOrigin() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return Math.random().toString(36).substring(2);
 }
 /**
- * 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'], … }
- * ```
+ * Wires a copy-on-write signal (a `store` root) to the op protocol: local writes emit
+ * stamped envelopes, received envelopes fold in through the converging apply. The
+ * unsequenced-topology client core that `tabSync(store)` and P2P transports build on.
  */
-function opLog(source, opt) {
-    const origin = opt?.origin ?? generateOrigin();
-    // a store proxy's `has` trap answers for the VALUE's keys, so `isMutable`'s `'mutate' in`
-    // probe can't see the brand — ask the store's own kind symbol first
-    const storeKind = source[STORE_KIND];
-    const mutableSource = storeKind ? storeKind === 'mutable' : isMutable(source);
-    if (isDevMode() && mutableSource) {
-        console.warn('[@mmstack/primitives] opLog observes copy-on-write updates via reference identity — a MUTABLE store/signal mutates in place, so changes are invisible to it. Use an immutable store, or set whole values.');
-    }
-    let prevRoot = untracked(source);
-    let version = 0;
-    let destroyed = false;
+const RECENT_LOCAL_CAP = 64;
+function opSync(source, opt) {
+    const origin = opt.origin ?? generateOrigin();
+    const clock = opt.clock ?? createHlcClock();
+    const conv = createConvergingApply({ policies: opt.policies });
     const subscribers = new Set();
-    const latest = signal(null, ...(ngDevMode ? [{ debugName: "latest" }] : []));
-    /** Diff now, emit if there's a delta, advance the baseline. */
-    const flush = () => {
-        if (destroyed)
-            return;
-        const next = untracked(source);
-        if (Object.is(prevRoot, next))
-            return;
-        const ops = [];
-        diffNode(prevRoot, next, [], ops);
-        prevRoot = next;
-        if (!ops.length)
-            return; // fresh refs, equal values — spurious-write tolerance
-        const batch = { origin, version: ++version, ops };
-        latest.set(batch);
+    const versions = new Map();
+    const recentLocal = [];
+    let version = 0;
+    const log = opLog(source, opt.driver
+        ? { origin, driver: opt.driver }
+        : { origin, injector: opt.injector ?? inject(Injector) });
+    const emitLocal = (ops) => {
+        const env = {
+            proto: OP_PROTO_VERSION,
+            origin,
+            writer: opt.writer,
+            version: ++version,
+            hlc: clock.next(),
+            policyVersion: opt.policyVersion ?? 0,
+            ops,
+        };
+        versions.set(origin, env.version);
+        conv.ingest(env, { local: true });
+        recentLocal.push(env);
+        if (recentLocal.length > RECENT_LOCAL_CAP)
+            recentLocal.shift();
         for (const cb of [...subscribers])
-            cb(batch);
-    };
-    const run = () => {
-        source(); // track every commit…
-        untracked(flush); // …and emit the delta since the last flush
+            cb(env);
     };
-    // default driver is an Angular effect (needs an injector); a supplied driver runs injector-free
-    // (the worker-side seam, e.g. microtaskOpLogDriver from @mmstack/worker/host)
-    const ref = opt?.driver
-        ? opt.driver(run)
-        : effect(run, { injector: opt?.injector ?? inject(Injector) });
+    const unsub = log.subscribe((batch) => emitLocal(batch.ops));
     return {
-        latest: latest.asReadonly(),
+        origin,
         subscribe: (cb) => {
             subscribers.add(cb);
             return () => subscribers.delete(cb);
         },
-        // the emission core, callable on demand — reads the source untracked, so it never disturbs the
-        // driver's subscription; a subsequent scheduled run just finds the baseline already advanced
-        flush: () => flush(),
-        apply: (batchOrOps) => {
-            const ops = Array.isArray(batchOrOps)
-                ? batchOrOps
-                : batchOrOps.ops;
-            if (!ops.length)
+        receive: (env) => {
+            if (env.origin === origin)
                 return;
-            // pending local writes must emit BEFORE the baseline advances past them
-            flush();
-            const root = applyOps(untracked(source), ops); // one atomic root, structural-shared
-            source.set(root);
-            prevRoot = root; // baseline advance: an applied batch never echoes
+            if (env.proto !== OP_PROTO_VERSION) {
+                if (isDevMode()) {
+                    console.warn(`[@mmstack/primitives] dropped envelope with proto ${env.proto} (expected ${OP_PROTO_VERSION})`);
+                }
+                return;
+            }
+            clock.observe(env.hlc);
+            const known = versions.get(env.origin);
+            if (known !== undefined && env.version <= known)
+                return; // duplicate/covered — idempotent
+            if (known !== undefined && env.version !== known + 1) {
+                opt.onGap?.(env.origin, known + 1, env.version);
+            }
+            versions.set(env.origin, env.version);
+            log.flush();
+            const ops = conv.ingest(env);
+            if (ops.length)
+                log.apply(ops);
+        },
+        flush: () => log.flush(),
+        watermark: () => Object.fromEntries(versions),
+        snapshot: () => {
+            log.flush();
+            return { root: untracked(source), wm: Object.fromEntries(versions) };
+        },
+        seed: () => {
+            log.flush();
+            emitLocal([{ kind: 'set', path: [], next: untracked(source) }]);
+        },
+        hydrate: (root, wm) => {
+            log.flush();
+            const covered = wm?.[origin] ?? 0;
+            const pending = recentLocal.filter((e) => e.version > covered);
+            conv.reset();
+            let next = root;
+            for (const e of pending)
+                next = applyOps(next, e.ops);
+            log.apply([{ kind: 'set', path: [], next }]);
+            for (const [o, v] of Object.entries(wm ?? {})) {
+                versions.set(o, Math.max(versions.get(o) ?? 0, v));
+            }
+            for (const e of pending)
+                conv.ingest(e, { local: true });
         },
         destroy: () => {
-            destroyed = true;
+            unsub();
             subscribers.clear();
-            ref.destroy();
+            log.destroy();
         },
     };
 }
 
+/**
+ * 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).
+ */
+function storeHistory(source, opt) {
+    const limit = opt?.limit ?? 100;
+    const logOpt = { origin: opt?.origin };
+    if (opt?.driver)
+        logOpt.driver = opt.driver;
+    else
+        logOpt.injector = opt?.injector ?? inject(Injector);
+    const log = opLog(source, logOpt);
+    const undoStack = [];
+    const redoStack = [];
+    const version = signal(0, ...(ngDevMode ? [{ debugName: "version" }] : [])); // monotonic: bumps on every mutation so the computeds recompute
+    let applying = false;
+    const push = (stack, inverse) => {
+        stack.push(inverse);
+        if (stack.length > limit)
+            stack.shift();
+    };
+    const record = (batch) => {
+        if (applying)
+            return; // an undo/redo's own emission must not re-enter history
+        if (!batch.ops.length)
+            return;
+        push(undoStack, invertBatch(batch));
+        redoStack.length = 0; // a fresh edit forks the timeline
+        version.update((v) => v + 1);
+    };
+    // track the sync client's local stream when given, else self-diff every store change
+    const unsub = (opt?.track ?? log).subscribe(record);
+    const run = (from, to) => {
+        const inverse = from.pop();
+        if (!inverse)
+            return;
+        log.flush(); // settle pending local writes before applying
+        applying = true;
+        try {
+            log.apply(inverse);
+        }
+        finally {
+            applying = false;
+        }
+        push(to, invertBatch(inverse)); // the inverse of what we applied restores the other direction
+        version.update((v) => v + 1);
+    };
+    return {
+        canUndo: computed(() => (version(), undoStack.length > 0)),
+        canRedo: computed(() => (version(), redoStack.length > 0)),
+        undo: () => run(undoStack, redoStack),
+        redo: () => run(redoStack, undoStack),
+        clear: () => {
+            undoStack.length = 0;
+            redoStack.length = 0;
+            version.update((v) => v + 1);
+        },
+        destroy: () => {
+            unsub();
+            log.destroy();
+        },
+    };
+}
+
+const PERSISTED_STORE_OPTIONS = new InjectionToken('@mmstack/primitives:persisted-store-options');
+/**
+ * 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.
+ *
+ * @example
+ * import * as idbKeyval from 'idb-keyval';
+ * providePersistedStoreOptions({ store: idbKeyval });
+ */
+function providePersistedStoreOptions(opt) {
+    return { provide: PERSISTED_STORE_OPTIONS, useValue: opt };
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+function persist(source, opt) {
+    const injector = opt.injector ?? inject(Injector);
+    const defaults = injector.get(PERSISTED_STORE_OPTIONS, null);
+    const key = opt.key;
+    const backend = opt.store ?? defaults?.store;
+    const serialize = opt.serialize ?? ((v) => v);
+    const deserialize = opt.deserialize ?? ((r) => r);
+    const version = opt.version;
+    const debounceMs = opt.writeDebounceMs ?? defaults?.writeDebounceMs ?? 300;
+    const read = source;
+    const setRoot = (value) => source.set(value);
+    const VERSION_KEY = '__mmstack_pv';
+    const encode = (value) => version === undefined
+        ? serialize(value)
+        : { [VERSION_KEY]: version, data: serialize(value) };
+    const isServer = isPlatformServer(injector.get(PLATFORM_ID));
+    const initialRef = untracked(read); // copy-on-write: an untouched store keeps this reference
+    const hydrated = signal(false, ...(ngDevMode ? [{ debugName: "hydrated" }] : []));
+    if (isServer || !backend) {
+        if (!backend && !isServer && isDevMode()) {
+            console.warn(`[@mmstack/primitives] persist("${key}"): no AsyncStore backend (pass { store } or providePersistedStoreOptions). Running in-memory, not persisted.`);
+        }
+        hydrated.set(true);
+        return {
+            hydrated: hydrated.asReadonly(),
+            flush: () => Promise.resolve(),
+            clear: () => {
+                setRoot(initialRef);
+                return Promise.resolve();
+            },
+        };
+    }
+    let persistedRef = initialRef;
+    void (async () => {
+        try {
+            const raw = await backend.get(key);
+            // apply the snapshot only if nothing wrote in the boot window (explicit write wins)
+            if (raw !== undefined && raw !== null && untracked(read) === initialRef) {
+                let fromVersion = 0;
+                let payload = raw;
+                if (typeof raw === 'object' &&
+                    raw !== null &&
+                    VERSION_KEY in raw) {
+                    const env = raw;
+                    fromVersion =
+                        typeof env[VERSION_KEY] === 'number'
+                            ? env[VERSION_KEY]
+                            : 0;
+                    payload = env['data'];
+                }
+                const target = version ?? 0;
+                if (fromVersion > target) {
+                    if (isDevMode()) {
+                        console.warn(`[@mmstack/primitives] persist("${key}"): stored snapshot is version ${fromVersion} but this build is ${target}; leaving it untouched (a newer build wrote it).`);
+                    }
+                }
+                else {
+                    const migrated = !!(opt.migrate && fromVersion < target);
+                    let value = deserialize(payload);
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    if (migrated)
+                        value = await opt.migrate(value, fromVersion);
+                    if (untracked(read) === initialRef) {
+                        setRoot(value);
+                        if (!migrated)
+                            persistedRef = value;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (isDevMode()) {
+                console.warn(`[@mmstack/primitives] persist("${key}") hydrate failed`, err);
+            }
+        }
+        finally {
+            hydrated.set(true);
+        }
+    })();
+    let timer;
+    const write = async (value) => {
+        try {
+            await backend.set(key, encode(value));
+            persistedRef = value;
+        }
+        catch (err) {
+            if (isDevMode()) {
+                console.warn(`[@mmstack/primitives] persist("${key}") write failed`, err);
+            }
+        }
+    };
+    const cancelTimer = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    const flush = async () => {
+        cancelTimer();
+        const current = untracked(read);
+        if (!untracked(hydrated) ||
+            current === initialRef ||
+            current === persistedRef)
+            return;
+        await write(current);
+    };
+    effect(() => {
+        if (!hydrated())
+            return;
+        const value = read();
+        untracked(() => {
+            cancelTimer();
+            // untouched / reset-to-initial, or already the value on disk (e.g. just hydrated): skip
+            if (value === initialRef || value === persistedRef)
+                return;
+            timer = setTimeout(() => {
+                timer = undefined;
+                void write(value);
+            }, debounceMs);
+        });
+    }, { injector });
+    const onHide = () => {
+        void flush();
+    };
+    if (typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', onHide);
+        window.addEventListener('pagehide', onHide);
+    }
+    injector.get(DestroyRef).onDestroy(() => {
+        void flush();
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', onHide);
+            window.removeEventListener('pagehide', onHide);
+        }
+    });
+    return {
+        hydrated: hydrated.asReadonly(),
+        flush,
+        clear: async () => {
+            cancelTimer();
+            setRoot(initialRef); // back to initialRef, so the persist effect skips (no re-write over the delete)
+            persistedRef = initialRef; // disk is now empty
+            try {
+                await backend.del(key);
+            }
+            catch (err) {
+                if (isDevMode()) {
+                    console.warn(`[@mmstack/primitives] persist("${key}") clear failed`, err);
+                }
+            }
+        },
+    };
+}
+/**
+ * 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).
+ */
+function persistedStore(initial, opt) {
+    const injector = opt.injector ?? inject(Injector);
+    // store() reads only the signal/store opts it knows; the persistence keys ride along harmlessly
+    const s = store(initial, { ...opt, injector });
+    const handle = persist(s, { ...opt, injector });
+    return { store: s, ...handle };
+}
+
 const isPlainArray = (v) => Array.isArray(v) && !isOpaque(v);
 function keyOf(item, key) {
     if (typeof key === 'function')
@@ -4979,13 +5682,9 @@ function reconcileValue(prev, next, key) {
  */
 function projection(fn, seed, opt) {
     const { key = 'id', ...storeOpt } = opt ?? {};
-    // linkedSignal rather than an effect-driven signal: the computation runs in the tracked
-    // context (fn's reads are dependencies) and `previous` hands back the last emitted value for
-    // the reconcile, so the projection is glitch-free, lazy, and needs no effect scheduler.
     const root = linkedSignal(...(ngDevMode ? [{ debugName: "root", source: () => undefined,
             computation: (_, previous) => {
                 const base = previous ? previous.value : seed;
-                // a plain mutable scratch seeded with the current value; fn mutates it or returns new data
                 const draft = structuredClone(base);
                 const returned = fn(draft);
                 const next = (returned === undefined ? draft : returned);
@@ -4994,7 +5693,6 @@ function projection(fn, seed, opt) {
             source: () => undefined,
             computation: (_, previous) => {
                 const base = previous ? previous.value : seed;
-                // a plain mutable scratch seeded with the current value; fn mutates it or returns new data
                 const draft = structuredClone(base);
                 const returned = fn(draft);
                 const next = (returned === undefined ? draft : returned);
@@ -5200,6 +5898,85 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
+/** Op-mode sync for a writable store: hello exchange, then live envelopes (RFC §6 tab flavor). */
+function storeTabSync(sig, opt, bus, injector) {
+    const sync = opSync(sig, {
+        writer: opt.writer ?? 'local',
+        policies: opt.policies,
+        injector,
+    });
+    const helloTimeoutMs = opt.helloTimeoutMs ?? 250;
+    const jitterMs = opt.jitterMs ?? 25;
+    let phase = 'joining';
+    const joinBuffer = [];
+    const responseTimers = new Map();
+    let helloTimer;
+    function goLive() {
+        if (phase === 'live')
+            return;
+        phase = 'live';
+        if (helloTimer !== undefined) {
+            clearTimeout(helloTimer);
+            helloTimer = undefined;
+        }
+        for (const env of joinBuffer.splice(0))
+            sync.receive(env);
+    }
+    const { unsub, post } = bus.subscribe(opt.id, (msg) => {
+        if (!msg || typeof msg !== 'object')
+            return;
+        switch (msg.t) {
+            case 'env':
+                if (phase === 'joining')
+                    joinBuffer.push(msg.env);
+                else
+                    sync.receive(msg.env);
+                return;
+            case 'hello': {
+                if (phase !== 'live' || msg.from === sync.origin)
+                    return;
+                // first responder wins: jittered answer, cancelled when someone else answers first
+                const timer = setTimeout(() => {
+                    responseTimers.delete(msg.from);
+                    const snap = sync.snapshot();
+                    const covered = Object.entries(snap.wm).every(([origin, v]) => (msg.wm[origin] ?? 0) >= v);
+                    post(covered
+                        ? { t: 'uptodate', to: msg.from }
+                        : { t: 'state', to: msg.from, root: snap.root, wm: snap.wm });
+                }, Math.random() * jitterMs);
+                responseTimers.set(msg.from, timer);
+                return;
+            }
+            case 'state':
+            case 'uptodate': {
+                const scheduled = responseTimers.get(msg.to);
+                if (scheduled !== undefined) {
+                    clearTimeout(scheduled);
+                    responseTimers.delete(msg.to);
+                }
+                if (msg.to !== sync.origin || phase !== 'joining')
+                    return;
+                if (msg.t === 'state')
+                    sync.hydrate(msg.root, msg.wm);
+                goLive();
+                return;
+            }
+        }
+    });
+    const unsubEnv = sync.subscribe((env) => post({ t: 'env', env }));
+    post({ t: 'hello', from: sync.origin, wm: sync.watermark() });
+    helloTimer = setTimeout(goLive, helloTimeoutMs);
+    injector.get(DestroyRef).onDestroy(() => {
+        if (helloTimer !== undefined)
+            clearTimeout(helloTimer);
+        for (const timer of responseTimers.values())
+            clearTimeout(timer);
+        responseTimers.clear();
+        unsubEnv();
+        unsub();
+        sync.destroy();
+    });
+}
 class MessageBus {
     channel = new BroadcastChannel('mmstack-tab-sync-bus');
     listeners = new Map();
@@ -5311,6 +6088,20 @@ function tabSync(sig, opt) {
         return sig;
     const id = typeof opt === 'string' ? opt : (opt?.id ?? generateDeterministicID());
     const bus = injector.get(MessageBus);
+    const storeKind = sig[STORE_KIND];
+    if (storeKind === 'writable') {
+        storeTabSync(sig, { ...optObj, id }, bus, injector);
+        return sig;
+    }
+    if (storeKind === 'readonly') {
+        if (isDevMode()) {
+            console.warn('[@mmstack/primitives] tabSync: a readonly store cannot receive remote ops — not synced.');
+        }
+        return sig;
+    }
+    if (storeKind === 'mutable' && isDevMode()) {
+        console.warn('[@mmstack/primitives] tabSync: mutable stores fall back to whole-value sync (op diffing needs copy-on-write).');
+    }
     const NONE = Symbol();
     let received = NONE;
     const { unsub, post } = bus.subscribe(id, (next) => {
@@ -5538,5 +6329,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map