@mmstack/primitives 20.9.1 → 20.10.1

package/fesm2022/mmstack-primitives.mjs

@@ -1,11 +1,11 @@
 import * as i0 from '@angular/core';
-import { isDevMode, inject, Injector, untracked, effect, DestroyRef, InjectionToken, TemplateRef, ViewContainerRef, PLATFORM_ID, input, computed, Directive, signal, runInInjectionContext, linkedSignal, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, InjectionToken, TemplateRef, ViewContainerRef, PLATFORM_ID, input, computed, Directive, signal, runInInjectionContext, linkedSignal, afterNextRender, PendingTasks, Component, ElementRef, isSignal, Injectable } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
-const frameStack = [];
+const frameStack$1 = [];
 function currentFrame() {
-    return frameStack.at(-1) ?? null;
+    return frameStack$1.at(-1) ?? null;
 }
 function clearFrame(frame, userCleanups) {
     frame.parent = null;
@@ -31,10 +31,10 @@ function clearFrame(frame, userCleanups) {
     frame.children.clear();
 }
 function pushFrame(frame) {
-    return frameStack.push(frame);
+    return frameStack$1.push(frame);
 }
 function popFrame() {
-    return frameStack.pop();
+    return frameStack$1.pop();
 }
 
 /**
@@ -457,6 +457,79 @@ function chunked(source, options) {
     return internal.asReadonly();
 }
 
+/**
+ * `useDeferredValue` for signals: returns a signal that HOLDS its previous value when
+ * `source` changes and catches up at lower priority (after paint / on idle), so an
+ * expensive subtree keyed off the deferred value never blocks the urgent update that
+ * caused the change — type into a filter, the input echoes instantly, the big list
+ * re-renders a beat later.
+ *
+ * ```ts
+ * const query = signal('');
+ * const deferredQuery = deferredValue(query);
+ * const results = computed(() => expensiveFilter(items(), deferredQuery()));
+ * // template: <input [(ngModel)]="query" /> stays responsive; results lag one paint
+ * // deferredQuery.pending() → dim the stale list while it catches up
+ * ```
+ *
+ * Rapid changes coalesce: each change reschedules the catch-up, so only the LATEST
+ * source value is ever applied (no intermediate churn in the expensive subtree).
+ * On the server this is a synchronous pass-through — SSR renders once, so deferral
+ * would just mean rendering stale content.
+ *
+ * This is a scheduling tool, not an async one — for async work compose `latest()`;
+ * for coordinated multi-resource reveals use a transition scope.
+ */
+function deferredValue(source, opt) {
+    const injector = opt?.injector ?? inject(Injector);
+    const equal = opt?.equal ?? Object.is;
+    if (injector.get(PLATFORM_ID) === 'server') {
+        const passthrough = computed(() => source());
+        passthrough.pending = computed(() => false, ...(ngDevMode ? [{ debugName: "pending" }] : []));
+        return passthrough;
+    }
+    const schedule = resolveScheduler(opt?.strategy ?? 'afterRender', injector);
+    const out = signal(untracked(source), ...(ngDevMode ? [{ debugName: "out", equal }] : [{ equal }]));
+    let cancel = null;
+    const watch = effect(() => {
+        const v = source();
+        cancel?.(); // latest wins: rapid changes coalesce into one catch-up
+        cancel = schedule(() => {
+            cancel = null;
+            out.set(v);
+        });
+    }, ...(ngDevMode ? [{ debugName: "watch", injector }] : [{ injector }]));
+    injector.get(DestroyRef).onDestroy(() => {
+        watch.destroy();
+        cancel?.();
+        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;
+}
+function resolveScheduler(strategy, injector) {
+    if (typeof strategy === 'function')
+        return strategy;
+    if (strategy === 'idle') {
+        return (cb) => {
+            const ric = globalThis.requestIdleCallback;
+            if (ric) {
+                const id = ric(() => cb());
+                return () => globalThis.cancelIdleCallback?.(id);
+            }
+            const id = setTimeout(cb, 0);
+            return () => clearTimeout(id);
+        };
+    }
+    return (cb) => {
+        const ref = afterNextRender({ read: cb }, { injector });
+        return () => ref.destroy();
+    };
+}
+
 /**
  * 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
@@ -553,6 +626,17 @@ function createTransitionScope() {
             source: () => ({ v: value(), settled: !pending() }),
             computation: (curr, prev) => curr.settled || prev === undefined ? curr.v : prev.value,
         }),
+        abortPending: () => untracked(() => {
+            let aborted = 0;
+            for (const { ref } of list()) {
+                const s = ref.status();
+                if ((s === 'loading' || s === 'reloading') && ref.abort) {
+                    ref.abort();
+                    aborted++;
+                }
+            }
+            return aborted;
+        }),
         holding,
         beginHold: () => untracked(() => holdCount.update((c) => c + 1)),
         endHold: () => untracked(() => holdCount.update((c) => (c > 0 ? c - 1 : 0))),
@@ -574,6 +658,7 @@ function createNoopScope() {
             // noop
         },
         commit: (value) => value,
+        abortPending: () => 0,
         holding: computed(() => false),
         beginHold: () => {
             // noop
@@ -585,9 +670,49 @@ function createNoopScope() {
     };
 }
 const TRANSITION_SCOPE = new InjectionToken('@mmstack/primitives:transition-scope');
+/**
+ * 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
+ * already do this via HttpClient, but CUSTOM loaders (a `latest()` over a hand-rolled
+ * promise, a non-HTTP resource) would otherwise let the server render a boundary
+ * mid-load. Wired automatically by `provideTransitionScope` /
+ * `provideForwardingTransitionScope`; call it yourself only for scopes you construct
+ * directly with `createTransitionScope()`.
+ *
+ * Server-only by design: on the browser, tying `ApplicationRef.isStable` to every load
+ * would stall stability-gated machinery (testability, hydration timing) for no benefit.
+ */
+function bridgeScopeToPendingTasks(scope, injector) {
+    const run = (fn) => injector ? runInInjectionContext(injector, fn) : fn();
+    run(() => {
+        if (inject(PLATFORM_ID) !== 'server')
+            return;
+        const tasks = inject(PendingTasks);
+        let done = null;
+        effect(() => {
+            if (scope.pending())
+                done ??= tasks.add();
+            else {
+                done?.();
+                done = null;
+            }
+        });
+        inject(DestroyRef).onDestroy(() => {
+            done?.();
+            done = null;
+        });
+    });
+}
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
 function provideTransitionScope() {
-    return { provide: TRANSITION_SCOPE, useFactory: createTransitionScope };
+    return {
+        provide: TRANSITION_SCOPE,
+        useFactory: () => {
+            const scope = createTransitionScope();
+            bridgeScopeToPendingTasks(scope);
+            return scope;
+        },
+    };
 }
 function injectTransitionScope() {
     const scope = inject(TRANSITION_SCOPE, { optional: true });
@@ -623,6 +748,7 @@ function createForwardingScope() {
             source: () => ({ v: value(), settled: !eff().pending() }),
             computation: (curr, prev) => curr.settled || prev === undefined ? curr.v : prev.value,
         }),
+        abortPending: () => (untracked(target) ?? own).abortPending(),
         holding: computed(() => eff().holding()),
         beginHold: () => (untracked(target) ?? own).beginHold(),
         endHold: () => (untracked(target) ?? own).endHold(),
@@ -634,7 +760,14 @@ function createForwardingScope() {
 }
 /** Provide a forwarding transition scope at a boundary (used by the transition outlet). */
 function provideForwardingTransitionScope() {
-    return { provide: TRANSITION_SCOPE, useFactory: createForwardingScope };
+    return {
+        provide: TRANSITION_SCOPE,
+        useFactory: () => {
+            const scope = createForwardingScope();
+            bridgeScopeToPendingTasks(scope);
+            return scope;
+        },
+    };
 }
 /** Read the transition scope reachable from `injector`, or null if none is provided there. */
 function getTransitionScope(injector) {
@@ -691,6 +824,141 @@ function registerResource(res, opt) {
     return injectRegisterResource()(res, opt);
 }
 
+const frameStack = [];
+/**
+ * Thrown by `use()` to short-circuit a computation whose input has no value yet; caught
+ * by the owning `latest()`. Identity-compared, so user code must not swallow it — avoid
+ * broad `try/catch` around `use()` calls.
+ */
+const BLOCKED = new Error('[mmstack/primitives] latest() blocked — internal sentinel, do not catch');
+/**
+ * Reads a resource inside a `latest()` computation: returns its value and reports it to
+ * the enclosing collector, so the derivation's aggregate `pending`/`status`/`error`
+ * include it. When the resource has no value yet (first load) or is in an error state,
+ * the computation short-circuits — code after this call simply doesn't run this round —
+ * which is what lets you write the happy path with no `undefined` checks:
+ *
+ * ```ts
+ * const fullName = latest(() => {
+ *   const u = use(user);          // waterfalls compose:
+ *   const org = use(orgFor(u));   // orgFor(u) is only read once `user` has a value
+ *   return `${u.name} @ ${org.name}`;
+ * });
+ * ```
+ *
+ * Must be called synchronously within `latest()` — like `inject()`, it throws elsewhere.
+ */
+function use(res) {
+    const frame = frameStack.at(-1);
+    if (!frame) {
+        throw new Error('[mmstack/primitives] use() must be called synchronously within a latest() computation');
+    }
+    if (!frame.seen.has(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;
+    }
+    if (!res.hasValue())
+        throw BLOCKED;
+    return res.value();
+}
+/**
+ * An async derivation over resources: evaluates `fn` inside a collector frame so that
+ * every `use()` read registers as a member, and exposes the result with resource
+ * semantics — the value holds its previous state while anything it read is in flight
+ * (never flashing empty), `pending` aggregates the members' in-flight state, and the
+ * whole thing is itself a `UseSource`, so `latest`s nest and propagate.
+ *
+ * ```ts
+ * const fullName = latest(() => `${use(user).name} @ ${use(org).name}`);
+ * fullName();          // held value — undefined only before the first successful run
+ * fullName.pending();  // true while user OR org (re)loads
+ * ```
+ *
+ * Evaluation is a plain `computed` under the hood: lazy, pure, no effects, usable
+ * outside any injection context (`register` is the only DI-touching option).
+ */
+function latest(fn, opt) {
+    const evaluation = computed(() => {
+        const frame = { deps: [], seen: new Set(), errors: [] };
+        frameStack.push(frame);
+        try {
+            const value = fn();
+            return { kind: 'value', value, deps: frame.deps, errors: frame.errors };
+        }
+        catch (e) {
+            if (e === BLOCKED)
+                return { kind: 'blocked', deps: frame.deps, errors: frame.errors };
+            return {
+                kind: 'thrown',
+                thrown: e,
+                deps: frame.deps,
+                errors: frame.errors,
+            };
+        }
+        finally {
+            frameStack.pop();
+        }
+    }, 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 }
+                : (prev?.value ?? { has: false, v: undefined }),
+            equal: (a, b) => a.has === b.has && (!a.has || equal(a.v, b.v)) }] : [{
+            source: evaluation,
+            computation: (ev, prev) => ev.kind === 'value'
+                ? { has: true, v: ev.value }
+                : (prev?.value ?? { has: false, v: undefined }),
+            equal: (a, b) => a.has === b.has && (!a.has || equal(a.v, b.v)),
+        }]));
+    const value = computed(() => held().v, opt?.debugName ? { debugName: opt.debugName } : undefined);
+    const pending = computed(() => evaluation().deps.some((d) => {
+        const s = d.status();
+        return s === 'loading' || s === 'reloading';
+    }), ...(ngDevMode ? [{ debugName: "pending" }] : []));
+    const status = computed(() => {
+        const ev = evaluation();
+        if (ev.kind === 'thrown' || ev.errors.length > 0)
+            return 'error';
+        if (pending())
+            return held().has ? 'reloading' : 'loading';
+        return ev.kind === 'value' ? 'resolved' : 'idle';
+    }, ...(ngDevMode ? [{ debugName: "status" }] : []));
+    const error = computed(() => {
+        const ev = evaluation();
+        return ev.kind === 'thrown' ? ev.thrown : ev.errors.at(0);
+    }, ...(ngDevMode ? [{ debugName: "error" }] : []));
+    const result = Object.assign(value, {
+        value,
+        status,
+        pending,
+        isLoading: pending,
+        error,
+        hasValue: () => held().has,
+    });
+    if (opt?.register) {
+        const register = () => {
+            const scope = injectTransitionScope();
+            scope.add(result, { suspends: opt.register === 'suspend' });
+            inject(DestroyRef).onDestroy(() => scope.remove(result));
+        };
+        if (opt.injector)
+            runInInjectionContext(opt.injector, register);
+        else
+            register();
+    }
+    return result;
+}
+
 /**
  * Returns a `startTransition(fn)` bound to the nearest transition scope. `fn` runs its state
  * mutations (which commit immediately); any resource that reloads as a result holds its value
@@ -1115,6 +1383,57 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                 }]
         }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmTransition", required: true }] }], immediate: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmTransitionImmediate", required: false }] }], viewTransition: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmTransitionViewTransition", required: false }] }] } });
 
+/**
+ * Per-element morphs on held swaps: assigns `view-transition-name` reactively, so when
+ * a swap wrapped in `document.startViewTransition` flips views (`*mmTransition`'s
+ * `mmTransitionViewTransition`, or the transition outlet's view-transition option), the
+ * browser pairs same-named elements across the outgoing and incoming views and MORPHS
+ * them instead of cross-fading the whole boundary.
+ *
+ * ```html
+ * <!-- outgoing view (list) and incoming view (detail) both name the hero image: -->
+ * <img [mmViewTransitionName]="'hero-' + item().id" [src]="item().img" />
+ * ```
+ *
+ * Why this works with holds: both views coexist in the DOM during a hold, but the
+ * incoming one is `display: none` — elements without boxes aren't captured, so the
+ * same name on both sides is legal at each capture point (old visible at snapshot,
+ * new visible after the swap). No arming/cleanup dance needed.
+ *
+ * The name is normalized to a valid CSS custom-ident (invalid characters → `-`, a
+ * leading digit gets a `_` prefix). An empty string / `'none'` clears the name — use
+ * that to opt an element out conditionally. One rule remains YOURS to keep: a name
+ * must be unique among elements VISIBLE at capture time (two rendered instances of the
+ * same named element make the browser skip the whole transition) — derive names from
+ * ids for anything that can repeat.
+ */
+class MmViewTransitionName {
+    mmViewTransitionName = input.required(...(ngDevMode ? [{ debugName: "mmViewTransitionName" }] : []));
+    constructor() {
+        const el = inject(ElementRef).nativeElement;
+        effect(() => {
+            const name = normalizeIdent(this.mmViewTransitionName());
+            if (name)
+                el.style.setProperty('view-transition-name', name);
+            else
+                el.style.removeProperty('view-transition-name');
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MmViewTransitionName, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "20.3.17", type: MmViewTransitionName, isStandalone: true, selector: "[mmViewTransitionName]", inputs: { mmViewTransitionName: { classPropertyName: "mmViewTransitionName", publicName: "mmViewTransitionName", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MmViewTransitionName, decorators: [{
+            type: Directive,
+            args: [{ selector: '[mmViewTransitionName]' }]
+        }], ctorParameters: () => [], propDecorators: { mmViewTransitionName: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmViewTransitionName", required: true }] }] } });
+/** @internal `''`/`'none'` clear; otherwise coerce into a valid custom-ident. */
+function normalizeIdent(raw) {
+    if (!raw || raw === 'none')
+        return null;
+    const cleaned = raw.replace(/[^a-zA-Z0-9_-]/g, '-');
+    return /^\d/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+
 /**
  * @internal
  */
@@ -3971,7 +4290,11 @@ function buildChildNode(target, prop, isMutableSource, options) {
 function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...rest } = {}) {
     if (isStore(source))
         return source;
-    if (!injector)
+    // injector is needed ONLY to resolve the two proxy-globals tokens; if a caller supplies the
+    // globals directly (createStoreContext — the worker-side seam with no DI), skip inject entirely
+    const sharedGlobals = rest[STORE_SHARED_GLOBALS];
+    const hasSharedGlobals = !!(sharedGlobals?.cache && sharedGlobals?.registry);
+    if (!injector && !hasSharedGlobals)
         injector = inject(Injector);
     const writableSource = isWritableSignal(source)
         ? source
@@ -3989,13 +4312,18 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
         return 'primitive';
     }, ...(ngDevMode ? [{ debugName: "kind" }] : []));
     const STORE_OPTIONS = {
-        injector,
+        // may be undefined in worker/DI-less mode; unused downstream once globals are resolved
+        // (children thread the resolved globals via STORE_SHARED_OPTIONS, derived needs no injector)
+        injector: injector,
         vivify,
         noUnionLeaves,
         [STORE_SHARED_GLOBALS]: {
-            cache: rest[STORE_SHARED_GLOBALS]?.cache ?? injector.get(PROXY_CACHE_TOKEN),
-            registry: rest[STORE_SHARED_GLOBALS]?.registry ??
-                injector.get(PROXY_CLEANUP_TOKEN),
+            // the `injector!` reads run only when a global is absent, which (per hasSharedGlobals) means
+            // an injector was resolved above
+            // 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
+            registry: sharedGlobals?.registry ?? injector.get(PROXY_CLEANUP_TOKEN),
         },
     };
     // built lazily so non-array nodes never allocate it
@@ -4067,7 +4395,14 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
                 return () => {
                     if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), { injector, vivify, noUnionLeaves }));
+                    return untracked(() => toStore(source.asReadonly(), {
+                        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],
+                    }));
                 };
             const k = untracked(kind);
             if (prop === 'extend' && k !== 'array')
@@ -4232,6 +4567,40 @@ function mutableStore(value, opt) {
         ...opt,
     });
 }
+/**
+ * Builds a DI-less store context — the shared proxy-cache and cleanup registry that {@link toStore}
+ * normally resolves from the injector — so a `store`/`toStore`/`opLog` graph can run with NO Angular
+ * injection context. Spread the result into the options:
+ *
+ * ```ts
+ * import { microtaskOpLogDriver } from '@mmstack/worker/host';
+ * const ctx = createStoreContext();
+ * const s = store({ todos: [] }, ctx);
+ * const log = opLog(s, { driver: microtaskOpLogDriver(), origin: 'worker' }); // no injector anywhere
+ * ```
+ *
+ * **This is a worker-only fallback — do NOT use it on the main thread.** DI is the default and
+ * correct path in an app: the injector scopes the proxy-cache/cleanup singletons per app instance,
+ * which on the SERVER keeps one request's store identity from bleeding into another's (the exact
+ * hazard a module-scope singleton would reintroduce). A Web Worker is safe because it is a single
+ * store graph per thread and never runs during SSR (spawn is a `PLATFORM_ID === 'server'` no-op),
+ * so there is no cross-request scope to contaminate. Never hoist a `createStoreContext()` to module
+ * scope on a shared/main thread.
+ *
+ * **Share ONE context across every store in a worker** — the same way `providedIn: 'root'` shares
+ * one cache across all of an app's stores. `@mmstack/worker/host` memoizes this per worker
+ * (`workerStoreContext()`); reach for `createStoreContext()` directly only in a bare
+ * (non-worker-host) DI-less setup, and hold the single instance yourself.
+ */
+function createStoreContext() {
+    const cache = new WeakMap();
+    const registry = new FinalizationRegistry(({ target, prop }) => {
+        const entry = cache.get(target);
+        if (entry)
+            entry.delete(prop);
+    });
+    return { [STORE_SHARED_GLOBALS]: { cache, registry } };
+}
 
 function isPlainRecord(value) {
     if (value === null || typeof value !== 'object')
@@ -4309,6 +4678,332 @@ function forkStore(base, opt) {
     };
 }
 
+function generateOrigin() {
+    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();
+    // 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 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();
+        },
+    };
+}
+
+const isPlainArray = (v) => Array.isArray(v) && !isOpaque(v);
+function keyOf(item, key) {
+    if (typeof key === 'function')
+        return key(item);
+    return isRecord(item) ? item[key] : item;
+}
+/**
+ * Produces a value equal to `next` but sharing as much of `prev`'s reference structure as possible:
+ * an object subtree that did not change keeps its `prev` reference, and array items are matched by
+ * `key` so a surviving item keeps its identity across a reorder/insert/remove (only added items are
+ * new, only removed items are dropped). This is what lets a derived store recompute without tearing
+ * down every downstream `computed` that reads an unchanged part of it.
+ */
+function reconcile(prev, next, key = 'id') {
+    return reconcileValue(prev, next, key);
+}
+function reconcileValue(prev, next, key) {
+    if (Object.is(prev, next))
+        return prev;
+    if (isPlainArray(prev) && isPlainArray(next)) {
+        const byKey = new Map();
+        for (const item of prev)
+            byKey.set(keyOf(item, key), item);
+        let changed = prev.length !== next.length;
+        const out = next.map((item, i) => {
+            const match = byKey.get(keyOf(item, key));
+            const rv = match !== undefined ? reconcileValue(match, item, key) : item;
+            if (rv !== prev[i])
+                changed = true;
+            return rv;
+        });
+        return changed ? out : prev;
+    }
+    if (isRecord(prev) && isRecord(next)) {
+        const nextKeys = Object.keys(next);
+        let changed = Object.keys(prev).length !== nextKeys.length;
+        const out = {};
+        for (const k of nextKeys) {
+            const rv = Object.hasOwn(prev, k)
+                ? reconcileValue(prev[k], next[k], key)
+                : next[k];
+            out[k] = rv;
+            if (rv !== prev[k])
+                changed = true;
+        }
+        return changed ? out : prev;
+    }
+    return next;
+}
+/**
+ * A derived STORE, the store-shaped counterpart to `computed`. `fn` receives a mutable draft seeded
+ * with the current value and either mutates it in place or returns a new value; whichever it does,
+ * the result is reconciled against the previous value (see {@link reconcile}) so unchanged subtrees
+ * keep reference identity and keyed array items keep their proxy identity. Reading through the
+ * returned store is fine-grained: a `computed` over one field only recomputes when that field
+ * actually changes, even though the whole projection re-ran.
+ *
+ * Recompute is pull-based, exactly like `computed`: the projection is memoized and re-runs on the
+ * first read after a signal `fn` depends on changes, so reads are always coherent (no waiting on an
+ * effect flush) and nothing recomputes while nobody reads. `fn` must be pure, it runs inside the
+ * reactive computation. Prefer `computed` for a plain value; reach for `projection` when you want
+ * the per-property tracking of a store on top of a derivation.
+ *
+ * ```ts
+ * const active = projection<User[]>(() => users().filter((u) => u.active), [], { key: 'id' });
+ * // active[0].name(); — surviving users keep identity across recomputes
+ * ```
+ *
+ * Needs an injection context (or an explicit `injector`) for the store layer's cleanup on the main
+ * thread; with an explicit store context (`createStoreContext()`) it is injector-free, so it also
+ * runs on a worker host.
+ *
+ * @param fn receives the current draft; mutate it, or return new data.
+ * @param seed the initial value, held before the first run.
+ */
+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);
+                return reconcile(base, next, key);
+            } }] : [{
+            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);
+                return reconcile(base, next, key);
+            },
+        }]));
+    return toStore(root, storeOpt).asReadonlyStore();
+}
+
 /**
  * @internal The plain-`effect` sibling of the public {@link pausableEffect} (which is built on
  * `nestedEffect`). For infra utilities that own a single top-level effect/subscription and don't
@@ -4843,5 +5538,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, MmTransition, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map