@mmstack/primitives 22.4.0 → 22.5.0

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, isWritableSignal as isWritableSignal$2, 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, isWritableSignal as isWritableSignal$2, 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();
 }
 
 /**
@@ -446,6 +446,81 @@ 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, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "pending" }] : /* istanbul ignore next */ []));
+        return passthrough;
+    }
+    const schedule = resolveScheduler(opt?.strategy ?? 'afterRender', injector);
+    const out = signal(untracked(source), { ...(ngDevMode ? { debugName: "out" } : /* istanbul ignore next */ {}), 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" } : /* istanbul ignore next */ {}), 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()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "pending" }] : /* istanbul ignore next */ []));
+    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
@@ -545,6 +620,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))),
@@ -566,6 +652,7 @@ function createNoopScope() {
             // noop
         },
         commit: (value) => value,
+        abortPending: () => 0,
         holding: computed(() => false),
         beginHold: () => {
             // noop
@@ -577,9 +664,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 });
@@ -616,6 +743,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(),
@@ -627,7 +755,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) {
@@ -684,6 +819,138 @@ 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" } : /* istanbul ignore next */ {}), 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';
+    }), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "pending" }] : /* istanbul ignore next */ []));
+    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';
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const error = computed(() => {
+        const ev = evaluation();
+        return ev.kind === 'thrown' ? ev.thrown : ev.errors.at(0);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    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
@@ -946,6 +1213,221 @@ function injectStartTransaction() {
     };
 }
 
+/**
+ * Generic hold-and-swap: the non-router `TransitionRouterOutlet`. When the bound value changes,
+ * the OLD view stays mounted and visible (it keeps its old context value — that's the hold) while
+ * the NEW view mounts hidden with its **own transition scope**; resources created in the incoming
+ * subtree register into that scope just by existing, and once they've gone in flight and settled
+ * the views swap in one frame. Tabs, wizard steps, master-detail — any branch change that would
+ * otherwise flash a loading state.
+ *
+ * ```html
+ * <div *mmTransition="selectedTab(); let tab">
+ *   @switch (tab) { ... }
+ * </div>
+ * ```
+ *
+ * Distinct from `<mm-suspense>` (the readiness gate): suspense decides placeholder-vs-content
+ * *within* one branch, but can't stop an `@switch` from unmounting the old branch the instant the
+ * value flips. This directive is the swap itself — the old branch survives until the new one is
+ * ready. Compose them freely: suspense inside a transitioned branch handles its first load.
+ *
+ * Semantics mirror the outlet: the first render is immediate (nothing to hold); an interrupting
+ * value change mid-hold destroys the half-ready hidden view and re-targets; a branch that loads
+ * nothing swaps right after its first render. Per-view scopes mean the outgoing branch's
+ * background work can never delay the swap. Set `mmTransitionImmediate` to skip holding, and
+ * `mmTransitionViewTransition` to wrap the swap in `document.startViewTransition` (feature
+ * detected). On the server every change swaps immediately.
+ */
+class MmTransition {
+    tpl = inject(TemplateRef);
+    vcr = inject(ViewContainerRef);
+    parent = inject(Injector);
+    onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
+    /** The value whose changes are transitioned. Each view keeps the value it was created with. */
+    value = input.required({ ...(ngDevMode ? { debugName: "value" } : /* istanbul ignore next */ {}), alias: 'mmTransition' });
+    /** Skip holding entirely — every change swaps at once (the plain re-render behavior). */
+    immediate = input(false, { ...(ngDevMode ? { debugName: "immediate" } : /* istanbul ignore next */ {}), alias: 'mmTransitionImmediate' });
+    /** Wrap the swap in the View Transitions API for an animated cross-fade (feature detected). */
+    viewTransition = input(false, { ...(ngDevMode ? { debugName: "viewTransition" } : /* istanbul ignore next */ {}), alias: 'mmTransitionViewTransition' });
+    current = null;
+    incoming = null;
+    /** Bumped on every re-target/teardown so a superseded (possibly deferred) swap can't commit. */
+    swapEpoch = 0;
+    holding = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "holding" }] : /* istanbul ignore next */ []));
+    /** True while an incoming view is mounted hidden, waiting to settle. */
+    pending = this.holding.asReadonly();
+    static ngTemplateContextGuard(dir, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ctx) {
+        return true;
+    }
+    constructor() {
+        effect(() => {
+            const v = this.value();
+            untracked(() => this.onValue(v));
+        });
+        inject(DestroyRef).onDestroy(() => {
+            this.swapEpoch++; // a deferred view-transition callback must not touch destroyed state
+            this.dropIncoming();
+            // `current` is destroyed with the container
+        });
+    }
+    onValue(v) {
+        if (!this.current) {
+            // first render: nothing to hold yet — show immediately (also what SSR serializes)
+            this.current = this.createView(v).view;
+            return;
+        }
+        this.dropIncoming(); // an interrupting change supersedes the previous hold
+        this.swapEpoch++;
+        const epoch = this.swapEpoch;
+        if (this.onServer || this.immediate()) {
+            this.finishSwap(epoch, this.createView(v).view);
+            return;
+        }
+        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.
+        let sawPending = untracked(scope.pending);
+        const watcher = effect(() => {
+            const pending = scope.pending();
+            untracked(() => {
+                if (epoch !== this.swapEpoch)
+                    return;
+                if (pending)
+                    sawPending = true;
+                if (sawPending && !pending)
+                    this.commitSwap(epoch, view);
+            });
+        }, { ...(ngDevMode ? { debugName: "watcher" } : /* istanbul ignore next */ {}), injector: this.parent });
+        this.incoming = { view, watcher };
+        // Fallback for a branch that loads nothing.
+        afterNextRender(() => {
+            if (epoch === this.swapEpoch &&
+                !sawPending &&
+                !untracked(scope.pending)) {
+                this.commitSwap(epoch, view);
+            }
+        }, { injector: this.parent });
+    }
+    commitSwap(epoch, view) {
+        if (epoch !== this.swapEpoch)
+            return;
+        if (this.viewTransition() &&
+            typeof document !== 'undefined' &&
+            document.startViewTransition) {
+            // the browser snapshots the old frame first; the epoch guard covers the deferral
+            document.startViewTransition(() => this.finishSwap(epoch, view));
+        }
+        else {
+            this.finishSwap(epoch, view);
+        }
+    }
+    /** The actual swap: destroy the old view, reveal the new one. Always instant. */
+    finishSwap(epoch, view) {
+        if (epoch !== this.swapEpoch)
+            return; // superseded while deferred — not ours to commit
+        this.swapEpoch++; // consume: the watcher and the render fallback can both fire, one commits
+        this.current?.destroy();
+        this.setHidden(view, false);
+        this.current = view;
+        this.incoming?.watcher.destroy();
+        this.incoming = null;
+        this.holding.set(false);
+    }
+    dropIncoming() {
+        if (!this.incoming)
+            return;
+        this.incoming.watcher.destroy();
+        this.incoming.view.destroy();
+        this.incoming = null;
+        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()],
+        });
+        const scope = getTransitionScope(injector);
+        const view = this.vcr.createEmbeddedView(this.tpl, { $implicit: v, mmTransition: v }, { injector });
+        return { view, scope };
+    }
+    setHidden(view, hidden) {
+        for (const node of view.rootNodes) {
+            // covers HTML and SVG roots; text/comment roots can't be styled — prefer an element root
+            if (node instanceof HTMLElement || node instanceof SVGElement)
+                node.style.display = hidden ? 'none' : '';
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmTransition, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmTransition, isStandalone: true, selector: "[mmTransition]", inputs: { value: { classPropertyName: "value", publicName: "mmTransition", isSignal: true, isRequired: true, transformFunction: null }, immediate: { classPropertyName: "immediate", publicName: "mmTransitionImmediate", isSignal: true, isRequired: false, transformFunction: null }, viewTransition: { classPropertyName: "viewTransition", publicName: "mmTransitionViewTransition", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["mmTransition"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmTransition, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[mmTransition]',
+                    exportAs: 'mmTransition',
+                }]
+        }], 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(/* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "mmViewTransitionName" }] : /* istanbul ignore next */ []));
+    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: "22.0.2", ngImport: i0, type: MmViewTransitionName, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", 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: "22.0.2", 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
  */
@@ -4151,6 +4633,191 @@ function forkStore(base, opt) {
     };
 }
 
+function generateOrigin() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return Math.random().toString(36).substring(2);
+}
+const isPlainArray = (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(prev) && isPlainArray(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(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;
+}
+/**
+ * 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 injector = opt?.injector ?? inject(Injector);
+    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, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "latest" }] : /* istanbul ignore next */ []));
+    /** 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 ref = effect(() => {
+        source(); // track every commit…
+        untracked(flush); // …and emit the delta since the last flush
+    }, { ...(ngDevMode ? { debugName: "ref" } : /* istanbul ignore next */ {}), injector: opt?.injector });
+    return {
+        latest: latest.asReadonly(),
+        subscribe: (cb) => {
+            subscribers.add(cb);
+            return () => subscribers.delete(cb);
+        },
+        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();
+            let root = untracked(source);
+            for (const op of ops) {
+                if (op.path.length === 0) {
+                    if (op.kind === 'set')
+                        root = op.next;
+                    continue; // a root delete is meaningless — ignore
+                }
+                root = applyAt(root, op.path, 0, op);
+            }
+            source.set(root);
+            prevRoot = root; // baseline advance: an applied batch never echoes
+        },
+        destroy: () => {
+            destroyed = true;
+            subscribers.clear();
+            ref.destroy();
+        },
+    };
+}
+
 /**
  * @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
@@ -4679,5 +5346,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, 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, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, 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, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, 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