@mmstack/primitives 19.3.10 → 19.4.0

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isSignal, PLATFORM_ID, ElementRef, Injectable, runInInjectionContext } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, InjectionToken, TemplateRef, ViewContainerRef, input, computed, Directive, signal, PLATFORM_ID, runInInjectionContext, ResourceStatus, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -214,6 +214,559 @@ function chunked(source, options) {
     return internal.asReadonly();
 }
 
+/**
+ * Whether the subtree a resource/component lives in is currently PAUSED, for Activity / keep-alive.
+ * Provided by an Activity boundary (`MmActivity`, or the app-builder's per-branch injector) and read
+ * — only at instantiation — by anything that should pause its background work while paused (a resource
+ * returning its `paused` token, a `<video>` pausing playback, the pausable primitives, …). Absent
+ * unless an Activity boundary provides one — read it via `injectPaused()`, which falls back to a
+ * never-paused signal, so code that isn't inside an Activity boundary is unaffected.
+ */
+const PAUSED_CONTEXT = new InjectionToken('@mmstack/primitives:paused-context');
+/**
+ * Keep-alive (the Angular analog of React's `<Activity>` / Vue's `<keep-alive>`): the wrapped
+ * subtree is mounted ONCE and kept — when `[mmActivity]` is false it's hidden (`display:none`) and
+ * its change detection is paused, preserving state (scroll, inputs, a video's position, loaded
+ * data); when true it's shown and CD resumes. It is never destroyed until the directive is.
+ *
+ * It also provides {@link PAUSED_CONTEXT} to the content (= the negation of `visible`), so descendants
+ * can pause *effect-driven* or *Observable* work while hidden (CD-detach alone pauses pull-based/template work, not
+ * effects/polling). If you're using the pausable primitives this is done automatically
+ *
+ * ```html
+ * <section *mmActivity="tab() === 'editor'"> ...heavy stateful editor... </section>
+ * ```
+ */
+class MmActivity {
+    tpl = inject(TemplateRef);
+    vcr = inject(ViewContainerRef);
+    parent = inject(Injector);
+    /** When false, keep the content mounted but hidden + CD-detached. */
+    visible = input.required({ alias: 'mmActivity' });
+    /** Paused == not visible — handed to the kept subtree as PAUSED_CONTEXT. */
+    paused = computed(() => !this.visible());
+    view = null;
+    constructor() {
+        effect(() => {
+            const visible = this.visible();
+            untracked(() => this.apply(visible));
+        });
+    }
+    apply(visible) {
+        if (!this.view) {
+            // Created once, kept for the directive's lifetime. The content gets PAUSED_CONTEXT = !visible,
+            // so resources/components inside can pause their effect-driven work while hidden.
+            this.view = this.vcr.createEmbeddedView(this.tpl, {}, {
+                injector: Injector.create({
+                    parent: this.parent,
+                    providers: [providePaused(this.paused)],
+                }),
+            });
+        }
+        for (const node of this.view.rootNodes) {
+            if (node instanceof HTMLElement)
+                node.style.display = visible ? '' : 'none';
+        }
+        if (visible)
+            this.view.reattach();
+        else
+            this.view.detach();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "19.2.19", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MmActivity, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[mmActivity]',
+                }]
+        }], ctorParameters: () => [] });
+// 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
+ * an Activity boundary). Defaults to a never-paused signal, so callers outside an Activity are
+ * unaffected; on the server it is always never-paused, so server-side work (e.g. connector fetches)
+ * isn't suppressed. This is the public way to read pause state; the underlying token is intentionally
+ * not exported.
+ */
+function injectPaused() {
+    if (isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser'))
+        return NEVER_PAUSED;
+    return inject(PAUSED_CONTEXT, { optional: true }) ?? NEVER_PAUSED;
+}
+/**
+ * Build a provider that supplies a paused-state signal to a subtree — the public way to set up an
+ * Activity-style pause boundary (used by `MmActivity` and the app-builder's per-branch injectors).
+ */
+function providePaused(source) {
+    return { provide: PAUSED_CONTEXT, useValue: source };
+}
+
+/**
+ * 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
+ * yielding its PREVIOUS value until `ready()` is true, then swaps to the current target.
+ *
+ * This is the structural counterpart to `keepPrevious`/`commit`: where those hold a *value*
+ * through a reload, this holds a *structure* through a swap. The caller mounts the incoming
+ * structure off to the side (so its resources can settle and flip `ready`), keeps showing the
+ * held previous structure meanwhile, and lets the old one go once `ready` releases the swap.
+ *
+ * The very first value passes straight through (nothing to hold yet).
+ */
+function holdUntilReady(target, ready) {
+    return linkedSignal({
+        source: () => ({ t: target(), ready: ready() }),
+        computation: (curr, prev) => (prev === undefined || curr.ready ? curr.t : prev.value),
+    });
+}
+
+/**
+ * Resolve a {@link PauseOption} into a pause predicate, or `null` meaning "do not pause".
+ * `null` tells the caller to return the bare primitive — no wrapper is created.
+ *
+ *  - omitted/`true` → the ambient {@link PAUSED_CONTEXT} if an Activity boundary provides one (via
+ *    `opt.injector` or the current injection context), else `null` (the bare primitive, no allocation).
+ *    The default, because an explicit `pausable*` call wants to be pausable. An explicit `pause: true`
+ *    with no boundary dev-warns; the omitted default stays quiet. SSR → `null`.
+ *  - a function → returned as-is (covers `Signal<boolean>`; usable outside an injection context).
+ *    SSR → `null` here too, detected via `opt.injector` if given, else a `globalThis.window` probe.
+ *  - `false` → `null` (the explicit opt-out).
+ *
+ * Encapsulating this here keeps every pausable primitive's branching identical and in one place.
+ */
+function resolvePause(opt) {
+    const explicit = opt?.pause; // distinguish explicit `true` from the omitted default
+    const pause = explicit ?? true; // explicit pausable* calls default to pausing
+    if (pause === false)
+        return null;
+    const run = (fn) => opt?.injector ? runInInjectionContext(opt.injector, fn) : fn();
+    const onServer = () => typeof pause === 'function' && !opt?.injector
+        ? typeof globalThis.window === 'undefined'
+        : run(() => isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser'));
+    if (typeof pause === 'function')
+        return onServer() ? null : pause;
+    if (onServer())
+        return null;
+    const paused = run(() => inject(PAUSED_CONTEXT, { optional: true }));
+    if (!paused) {
+        if (explicit === true && isDevMode())
+            console.warn('[pausable] `pause: true` but no PAUSED_CONTEXT in scope — not pausing. Provide one via an ' +
+                'Activity boundary (`MmActivity` / `providePaused`), or pass a predicate / `pause: false`.');
+        return null;
+    }
+    return paused;
+}
+/**
+ * Like {@link nestedEffect}, but pausable. While paused the effect does NOT run its body — and,
+ * crucially, it reads the pause predicate FIRST, so while paused its dependency set collapses to just
+ * the predicate (no churn from the real deps); on resume it re-runs and re-tracks. With no `pause`
+ * option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain `nestedEffect`
+ * with zero added overhead.
+ */
+function pausableEffect(effectFn, options) {
+    const paused = resolvePause(options);
+    if (!paused)
+        return nestedEffect(effectFn, options);
+    return nestedEffect((registerCleanup) => {
+        if (paused())
+            return; // read FIRST → while paused, deps collapse to just the predicate
+        effectFn(registerCleanup);
+    }, options);
+}
+/**
+ * Like `signal`, but pausable. While paused, READS hold the last value; writes still land on the
+ * underlying signal and surface on resume. Built on the `keepPrevious`/`hold` shape — a
+ * `linkedSignal` gated on the pause predicate, with `set`/`update`/`asReadonly` forwarded to the
+ * source signal. With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
+ * makes it a plain `signal` — no `linkedSignal` is created.
+ *
+ * NOTE: while paused, `set(x)` followed by a read returns the *held* (pre-pause) value, not `x` — the
+ * write lands on the source and surfaces on resume. That is the "freeze the displayed value while
+ * hidden" semantics; do not rely on read-after-write while paused.
+ */
+function pausableSignal(initialValue, options) {
+    const paused = resolvePause(options);
+    const src = signal(initialValue, options);
+    if (!paused)
+        return src;
+    const read = linkedSignal({
+        source: () => ({ v: src(), paused: paused() }),
+        computation: (curr, prev) => prev !== undefined && curr.paused ? prev.value : curr.v,
+        equal: options?.equal,
+    });
+    read.set = src.set;
+    read.update = src.update;
+    read.asReadonly = src.asReadonly;
+    return read;
+}
+/**
+ * Like `computed`, but pausable. While paused it holds its last value AND does not recompute: the
+ * computation's dependencies are not read while paused, so a dependency change can't trigger work —
+ * on resume it recomputes and re-tracks. The very first read always computes, to seed a value. With
+ * no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain
+ * `computed`.
+ */
+function pausableComputed(computation, options) {
+    const paused = resolvePause(options);
+    if (!paused)
+        return computed(computation, options);
+    const HELD = Symbol('paused-hold');
+    const ls = linkedSignal({
+        source: () => (paused() ? HELD : computation()),
+        computation: (next, prev) => next !== HELD ? next : prev !== undefined ? prev.value : computation(),
+        equal: options?.equal,
+    });
+    return ls.asReadonly();
+}
+
+const { is } = Object;
+function mutable(initial, opt) {
+    const baseEqual = opt?.equal ?? is;
+    let cnt = 0;
+    const equal = (a, b) => {
+        if (cnt > 0)
+            return false;
+        return baseEqual(a, b);
+    };
+    const sig = signal(initial, {
+        ...opt,
+        equal,
+    });
+    const internalUpdate = sig.update;
+    sig.mutate = (updater) => {
+        cnt++;
+        internalUpdate(updater);
+        cnt--;
+    };
+    sig.inline = (updater) => {
+        sig.mutate((prev) => {
+            updater(prev);
+            return prev;
+        });
+    };
+    return sig;
+}
+/**
+ * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
+ * for situations where you need to conditionally use the `mutate` or `inline` methods.
+ *
+ * @typeParam T - The type of the signal's value (optional, defaults to `any`).
+ * @param value - The `WritableSignal` to check.
+ * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
+ *
+ * @example
+ * const mySignal = signal(0);
+ * const myMutableSignal = mutable(0);
+ *
+ * if (isMutable(mySignal)) {
+ *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
+ * }
+ *
+ * if (isMutable(myMutableSignal)) {
+ *   myMutableSignal.mutate(x => x + 1); // This is safe.
+ * }
+ */
+function isMutable(value) {
+    return 'mutate' in value && typeof value.mutate === 'function';
+}
+
+function createTransitionScope() {
+    const list = mutable([]);
+    const pending = computed(() => list().some(({ ref }) => {
+        const s = ref.status();
+        return s === ResourceStatus.Loading || s === ResourceStatus.Reloading;
+    }));
+    const holdCount = signal(0);
+    const holding = computed(() => holdCount() > 0);
+    return {
+        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 }))),
+        remove: (ref) => untracked(() => list.inline((c) => {
+            const i = c.findIndex((e) => e.ref === ref);
+            if (i !== -1)
+                c.splice(i, 1);
+        })),
+        commit: (value) => linkedSignal({
+            source: () => ({ v: value(), settled: !pending() }),
+            computation: (curr, prev) => curr.settled || prev === undefined ? curr.v : prev.value,
+        }),
+        holding,
+        beginHold: () => untracked(() => holdCount.update((c) => c + 1)),
+        endHold: () => untracked(() => holdCount.update((c) => (c > 0 ? c - 1 : 0))),
+        hold: (value) => linkedSignal({
+            source: () => ({ v: value(), held: holding() }),
+            computation: (curr, prev) => prev !== undefined && curr.held ? prev.value : curr.v,
+        }),
+    };
+}
+function createNoopScope() {
+    return {
+        resources: computed(() => []),
+        pending: computed(() => false),
+        suspended: () => false,
+        add: () => {
+            // noop
+        },
+        remove: () => {
+            // noop
+        },
+        commit: (value) => value,
+        holding: computed(() => false),
+        beginHold: () => {
+            // noop
+        },
+        endHold: () => {
+            // noop
+        },
+        hold: (value) => value,
+    };
+}
+const TRANSITION_SCOPE = new InjectionToken('@mmstack/resource:transition-scope');
+/** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
+function provideTransitionScope() {
+    return { provide: TRANSITION_SCOPE, useFactory: createTransitionScope };
+}
+function injectTransitionScope() {
+    const scope = inject(TRANSITION_SCOPE, { optional: true });
+    if (!scope) {
+        if (isDevMode())
+            console.warn('[mmstack/resource] No transition scope in context — registration/tracking here is a no-op. ' +
+                'Use a <mm-suspense> boundary or provideTransitionScope() in an ancestor.');
+        return createNoopScope();
+    }
+    return scope;
+}
+/**
+ * Returns a register function bound to the nearest transition scope: it adds a resource
+ * to the scope and removes it when the caller's injection context is destroyed. Pass any
+ * `ResourceRef` (a query, mutation, or plain Angular resource) through it.
+ */
+function injectRegisterResource() {
+    const scope = injectTransitionScope();
+    const destroyRef = inject(DestroyRef);
+    return (res, opt) => {
+        scope.add(res, opt);
+        destroyRef.onDestroy(() => scope.remove(res));
+        return res;
+    };
+}
+/** Convenience: register a resource with the nearest transition scope. Must run in an injection context. */
+function registerResource(res, opt) {
+    return injectRegisterResource()(res, opt);
+}
+
+/**
+ * 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
+ * (when `coordinate`/`commit`-wrapped) and reveals together once everything settles. The
+ * returned handle exposes a unified `pending` + `done` for the whole operation — for imperative
+ * coordination (disable a control, await completion) on top of the declarative hold-and-commit.
+ *
+ * Must be called in an injection context. This is the *async* generalization (Tier 2): it adds
+ * no rendering cost and needs no fork — holding direct/sync readers is a separate, deferred tier.
+ */
+function injectStartTransition() {
+    const scope = injectTransitionScope();
+    const injector = inject(Injector);
+    return (fn) => {
+        untracked(fn);
+        let sawPending = false;
+        const done = new Promise((resolve) => {
+            const watcher = effect(() => {
+                const p = scope.pending();
+                if (p)
+                    sawPending = true;
+                // settle: requests went in flight and then drained
+                if (sawPending && !p) {
+                    watcher.destroy();
+                    resolve();
+                }
+            }, { injector });
+            // no-async fallback: once the reactive system has processed the writes (afterNextRender),
+            // if nothing ever went in flight, the transition is already complete.
+            afterNextRender(() => {
+                if (!sawPending && !untracked(scope.pending)) {
+                    watcher.destroy();
+                    resolve();
+                }
+            }, { injector });
+        });
+        return { pending: scope.pending, done };
+    };
+}
+
+/**
+ * Shared **suspense** (readiness) boundary behaviour: reads the *nearest* transition scope and exposes
+ * its `pending`/`suspended` state. This is the readiness gate — distinct from the hold-stale *swap*
+ * primitives (`TransitionRouterOutlet`, `ab-transition`), which are the actual "transitions". The two
+ * concrete components below differ only by whether they provide their own scope, so the logic (and
+ * template) live here once.
+ *
+ *  - **First load** (`suspended()`): no value yet → show the `[placeholder]` fallback.
+ *  - **Reload** (`pending()` but a value is held via `keepPrevious`): keep the real content mounted and
+ *    surface a busy indicator (`aria-busy`, and an optional `[busy]` slot) instead of flashing back to
+ *    the placeholder.
+ *
+ * `type` selects what "not ready" means: `'value'` (default) suspends only until a first value lands
+ * then holds through reloads; `'loading'` suspends on every in-flight load (strict suspense).
+ */
+class SuspenseBoundaryBase {
+    scope = injectTransitionScope();
+    /** What counts as "not ready" for the first-load placeholder. Defaults to value-presence. */
+    type = input('value');
+    pending = this.scope.pending;
+    suspended = computed(() => this.scope.suspended(this.type()));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "19.2.19", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
+            type: Directive
+        }] });
+const SUSPENSE_TEMPLATE = `
+  @if (suspended()) {
+    <ng-content select="[placeholder]"><span>Loading…</span></ng-content>
+  } @else {
+    @if (pending()) {
+      <ng-content select="[busy]" />
+    }
+    <ng-content />
+  }
+`;
+// `display: contents` so the boundary adds no box of its own.
+const SUSPENSE_STYLES = `
+  :host {
+    display: contents;
+  }
+`;
+const SUSPENSE_HOST = {
+    '[attr.aria-busy]': 'pending() ? true : null',
+};
+/**
+ * Standalone suspense boundary — **provides its own scope**, so dropping a `<mm-suspense>` anywhere
+ * just works: the resources created in its subtree register into it without any extra
+ * `provideTransitionScope()`. The common case.
+ */
+class SuspenseBoundary extends SuspenseBoundaryBase {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.19", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: SuspenseBoundary, decorators: [{
+            type: Component,
+            args: [{ selector: 'mm-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, providers: [provideTransitionScope()], styles: [":host{display:contents}\n"] }]
+        }] });
+/**
+ * Unscoped suspense boundary — **reads the ambient scope** instead of providing one. For cases where
+ * the resources to coordinate are registered *above* the boundary (e.g. an app-builder page whose
+ * manifests/connectors register at a higher injector), so the boundary observes that outer scope
+ * rather than opening a fresh one. Pair with a `provideTransitionScope()` (or another boundary) in an
+ * ancestor.
+ */
+class UnscopedSuspenseBoundary extends SuspenseBoundaryBase {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.19", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
+            type: Component,
+            args: [{ selector: 'mm-unscoped-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, styles: [":host{display:contents}\n"] }]
+        }] });
+
+function createTransaction() {
+    const log = new Map();
+    return {
+        record: (sig) => {
+            if (!log.has(sig))
+                log.set(sig, untracked(sig));
+        },
+        restore: () => untracked(() => {
+            for (const [sig, old] of log)
+                sig.set(old);
+            log.clear();
+        }),
+        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() {
+    return active;
+}
+function runInTransaction(txn, fn) {
+    const prev = active;
+    active = txn;
+    try {
+        untracked(fn);
+    }
+    finally {
+        active = prev;
+    }
+}
+/**
+ * Returns a `startTransaction(fn)` bound to the nearest transition scope — the Tier 3 sibling of
+ * `injectStartTransition`. It HOLDS the scope's synchronous display reads from before `fn` runs
+ * (so a state write inside `fn` doesn't flash through), records those writes in an undo log, then:
+ *  - on settle (the scope's resources go in flight and drain) → release the hold + keep the writes;
+ *  - on `abort()` → roll the writes back and release the hold.
+ *
+ * The writes land on LIVE state immediately (so derived variables and connector requests see the
+ * new values and refetch); only the *display* is held, via `scope.hold`. Must run in an injection
+ * context.
+ */
+function injectStartTransaction() {
+    const scope = injectTransitionScope();
+    const injector = inject(Injector);
+    return (fn) => {
+        const txn = createTransaction();
+        // Hold BEFORE the writes, so the display freezes at pre-transaction values.
+        scope.beginHold();
+        let finished = false;
+        let watcher;
+        const finish = (restore) => {
+            if (finished)
+                return;
+            finished = true;
+            watcher?.destroy();
+            if (restore)
+                txn.restore();
+            else
+                txn.clear();
+            scope.endHold();
+        };
+        runInTransaction(txn, fn);
+        let sawPending = false;
+        const done = new Promise((resolve) => {
+            watcher = effect(() => {
+                const p = scope.pending();
+                if (p)
+                    sawPending = true;
+                if (sawPending && !p) {
+                    finish(false);
+                    resolve();
+                }
+            }, { injector });
+            // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
+            afterNextRender(() => {
+                if (!sawPending && !untracked(scope.pending)) {
+                    finish(false);
+                    resolve();
+                }
+            }, { injector });
+        });
+        return {
+            pending: scope.pending,
+            done,
+            abort: () => finish(true),
+        };
+    };
+}
+
 /**
  * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
  * This can be useful for creating controlled write access to a signal that is otherwise read-only.
@@ -348,57 +901,6 @@ function debounce(source, opt) {
     return writable;
 }
 
-const { is } = Object;
-function mutable(initial, opt) {
-    const baseEqual = opt?.equal ?? is;
-    let cnt = 0;
-    const equal = (a, b) => {
-        if (cnt > 0)
-            return false;
-        return baseEqual(a, b);
-    };
-    const sig = signal(initial, {
-        ...opt,
-        equal,
-    });
-    const internalUpdate = sig.update;
-    sig.mutate = (updater) => {
-        cnt++;
-        internalUpdate(updater);
-        cnt--;
-    };
-    sig.inline = (updater) => {
-        sig.mutate((prev) => {
-            updater(prev);
-            return prev;
-        });
-    };
-    return sig;
-}
-/**
- * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
- * for situations where you need to conditionally use the `mutate` or `inline` methods.
- *
- * @typeParam T - The type of the signal's value (optional, defaults to `any`).
- * @param value - The `WritableSignal` to check.
- * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
- *
- * @example
- * const mySignal = signal(0);
- * const myMutableSignal = mutable(0);
- *
- * if (isMutable(mySignal)) {
- *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
- * }
- *
- * if (isMutable(myMutableSignal)) {
- *   myMutableSignal.mutate(x => x + 1); // This is safe.
- * }
- */
-function isMutable(value) {
-    return 'mutate' in value && typeof value.mutate === 'function';
-}
-
 /**
  * @internal
  * Type guard for an array-index-like property key: a non-empty string that parses to a finite
@@ -622,7 +1124,7 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
-function isWritableSignal(value) {
+function isWritableSignal$1(value) {
     return 'set' in value && typeof value.set === 'function';
 }
 /**
@@ -632,7 +1134,7 @@ function isWritableSignal(value) {
  * @returns
  */
 function createSetter(source) {
-    if (!isWritableSignal(source))
+    if (!isWritableSignal$1(source))
         return () => {
             // noop;
         };
@@ -648,6 +1150,27 @@ function createSetter(source) {
     };
 }
 
+function keepPrevious(src, opt) {
+    const persisted = linkedSignal({
+        ...opt,
+        source: () => src(),
+        computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next,
+    });
+    if (isWritableSignal$1(src)) {
+        persisted.set = src.set;
+        persisted.update = src.update;
+        persisted.asReadonly = src.asReadonly;
+        if (isMutable(src)) {
+            persisted.mutate = src.mutate;
+            persisted.inline = src.inline;
+        }
+        if (isDerivation(src)) {
+            persisted.from = src.from;
+        }
+    }
+    return persisted;
+}
+
 /**
  * Helper to create the derived signal for a specific index.
  * Extracts the cast logic to keep the main loop clean.
@@ -665,12 +1188,12 @@ function indexArray(source, map, opt = {}) {
     const data = isSignal(source) ? source : computed(source);
     const len = computed(() => data().length);
     const setter = createSetter(data);
-    const writableData = isWritableSignal(data)
+    const writableData = isWritableSignal$1(data)
         ? data
         : toWritable(data, () => {
             // noop
         });
-    if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
+    if (isWritableSignal$1(data) && isMutable(data) && !opt.equal) {
         opt.equal = (a, b) => {
             if (typeof a !== typeof b)
                 return false;
@@ -880,7 +1403,7 @@ function pooledKeys(src) {
 }
 function mapObject(source, mapFn, options = {}) {
     const src = isSignal(source) ? source : computed(source);
-    const writable = (isWritableSignal(src)
+    const writable = (isWritableSignal$1(src)
         ? src
         : toWritable(src, () => {
             // noop
@@ -2402,6 +2925,9 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
     return untracked(() => state.asReadonly());
 }
 
+function isWritableSignal(value) {
+    return isSignal(value) && typeof value.set === 'function';
+}
 /**
  * Runtime marker + compile-time brand for an opaque value. A `const`-declared `Symbol`
  * has a `unique symbol` type, so the same symbol serves as both the property key written
@@ -2443,6 +2969,82 @@ function isOpaque(value) {
         value !== null &&
         value[OPAQUE] === true);
 }
+/**
+ * @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
+ * nameable in the emitted declarations — not part of the supported surface; use {@link isLeaf}.
+ */
+const LEAF = Symbol('@mmstack/primitives::store/LEAF');
+/**
+ * @internal Whether a value is a terminal leaf: a concrete non-record/non-array value always is;
+ * `null`/`undefined` is a leaf only when vivification is disabled (with vivify on it can still
+ * materialize a container, so it stays a descendable substore).
+ */
+function isLeafValue(value, vivifyEnabled) {
+    if (value == null)
+        return !vivifyEnabled;
+    if (isOpaque(value))
+        return true; // opaque always wins — even arrays
+    return !Array.isArray(value) && !isRecord(value);
+}
+/**
+ * @internal Constant leaf probes for nodes whose leaf-ness is statically known, so the reactive
+ * `computed` can be skipped entirely.
+ */
+function alwaysTrue() {
+    return true;
+}
+function alwaysFalse() {
+    return false;
+}
+/**
+ * @internal Attaches a lazy, memoized leaf probe to a store node. The probe (`() => boolean`)
+ * closes over the node's value signal and its (stable) vivify setting, building the backing
+ * `computed` on first call so leaf-ness tracks the live value reactively without taxing every
+ * node access. Idempotent.
+ */
+function markAsLeaf(sig, value, vivifyEnabled, noUnionLeaves) {
+    if (typeof sig[LEAF] !== 'function') {
+        let memo;
+        const probe = () => {
+            if (memo)
+                return memo();
+            const v = untracked(value);
+            memo =
+                isOpaque(v) || (v == null && !vivifyEnabled) || noUnionLeaves
+                    ? isLeafValue(v, vivifyEnabled)
+                        ? alwaysTrue
+                        : alwaysFalse
+                    : computed(() => isLeafValue(value(), vivifyEnabled));
+            return memo();
+        };
+        Object.defineProperty(sig, LEAF, {
+            value: probe,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    return sig;
+}
+/**
+ * Reports whether a store node is currently a **leaf** — a terminal value the store does not
+ * descend into (a primitive, `Date`, `RegExp`, {@link opaque} object, class instance, or a
+ * `null`/`undefined` hole when vivification is off) rather than a record/array substore.
+ *
+ * Leaf-ness reflects the node's **live** value: the probe is reactive and memoized, so calling
+ * `isLeaf` inside a `computed`/`effect` re-evaluates when the node's shape changes.
+ *
+ * @internal Exposed for advanced/niche interop only — not part of the supported public surface
+ * and may change without a major version bump.
+ *
+ * @example
+ * const s = store({ name: 'Ada', address: { city: 'London' } });
+ * isLeaf(s.name);    // true
+ * isLeaf(s.address); // false — a substore
+ */
+function isLeaf(value) {
+    return isStore(value) && value[LEAF]?.() === true;
+}
 const IS_STORE = Symbol('@mmstack/primitives::store/IS_STORE');
 const SCOPE_PARENT = Symbol('@mmstack/primitives::store/SCOPE_PARENT');
 /**
@@ -2505,7 +3107,7 @@ function hasOwnKey(value, key) {
  * @internal
  * Makes an array store
  */
-function toArrayStore(source, injector, vivify) {
+function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
     if (isStore(source))
         return source;
     const isMutableSource = isMutable(source);
@@ -2615,9 +3217,10 @@ function toArrayStore(source, injector, vivify) {
                     });
                 const childSample = untracked(computation);
                 const childVivify = resolveVivify(childSample, vivify);
-                const proxy = Array.isArray(childSample)
-                    ? toArrayStore(computation, injector, childVivify)
-                    : toStore(computation, injector, childVivify);
+                const proxy = Array.isArray(childSample) && !isOpaque(childSample)
+                    ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
+                    : toStore(computation, injector, childVivify, noUnionLeaves);
+                markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
                 const ref = new WeakRef(proxy);
                 storeCache.set(idx, ref);
                 PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
@@ -2634,7 +3237,7 @@ function toArrayStore(source, injector, vivify) {
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
-function toStore(source, injector, vivify = false) {
+function toStore(source, injector, vivify = false, noUnionLeaves = false) {
     if (isStore(source))
         return source;
     if (!injector)
@@ -2675,7 +3278,7 @@ function toStore(source, injector, vivify = false) {
                 return () => {
                     if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), injector, vivify));
+                    return untracked(() => toStore(source.asReadonly(), injector, vivify, noUnionLeaves));
                 };
             if (prop === 'extend')
                 return (seed) => scopedStore(s, seed, isMutableSource
@@ -2728,9 +3331,10 @@ function toStore(source, injector, vivify = false) {
                 });
             const childSample = untracked(computation);
             const childVivify = resolveVivify(childSample, vivify);
-            const proxy = Array.isArray(childSample)
-                ? toArrayStore(computation, injector, childVivify)
-                : toStore(computation, injector, childVivify);
+            const proxy = Array.isArray(childSample) && !isOpaque(childSample)
+                ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
+                : toStore(computation, injector, childVivify, noUnionLeaves);
+            markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
             const ref = new WeakRef(proxy);
             storeCache.set(prop, ref);
             PROXY_CLEANUP.register(proxy, { target, prop }, ref);
@@ -2774,7 +3378,9 @@ function scopedStore(parent, seed, kind, injector) {
             layer[key].set(next[key]);
         }
     };
-    const base = toWritable(view, kind === 'readonly' ? () => undefined : splitSet, undefined, { pure: false });
+    const base = toWritable(view, kind === 'readonly' ? () => undefined : splitSet, undefined, {
+        pure: false,
+    });
     if (kind === 'mutable') {
         base.mutate = (updater) => splitSet(updater(untracked(view)));
         base.inline = (updater) => base.mutate((prev) => {
@@ -2823,14 +3429,78 @@ function scopedStore(parent, seed, kind, injector) {
  * @see {@link toStore}
  */
 function store(value, opt) {
-    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false);
+    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
 }
 /**
  * Creates a MutableSignalStore from a value.
  * @see {@link toStore}
  */
 function mutableStore(value, opt) {
-    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false);
+    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
+}
+
+function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Per-path 3-way merge. Reference-equality short-circuits do the work: a subtree the fork never
+ * touched satisfies `mine === ancestor` (structural sharing keeps its identity) → take the live
+ * base; a subtree the base never changed satisfies `theirs === ancestor` → keep the fork's. So it
+ * only deep-walks paths that BOTH sides changed, and on a leaf/array conflict the fork wins.
+ * Arrays are treated atomically (no positional merge — index shifts make that unsafe); supply a
+ * {@link ReconcileFn} for array-aware merging.
+ *
+ * CONTRACT: "unchanged" is detected by REFERENCE identity, not deep equality. `mine` must be a
+ * copy-on-write derivative of `ancestor` — i.e. untouched nodes keep their reference — which the
+ * fork guarantees because writes flow through `toStore` (it rebuilds only the edited path and
+ * shares everything else). Feed it a structurally-equal-but-fresh-reference node for an untouched
+ * path and it will treat that node as edited (recursion/leaf-value checks usually still reconcile,
+ * but a fresh-ref clean node vs a base type-change resolves to the fork's stale value). Primitive
+ * leaves compare by value, so equal primitives are correctly seen as unchanged.
+ */
+function merge3(ancestor, mine, theirs) {
+    if (Object.is(mine, theirs) || Object.is(mine, ancestor))
+        return theirs; // unedited → live base
+    if (Object.is(theirs, ancestor))
+        return mine; // base unchanged here → keep the fork's edit
+    if (isPlainRecord(mine) && isPlainRecord(theirs) && isPlainRecord(ancestor)) {
+        const out = { ...theirs };
+        for (const key of new Set([...Object.keys(mine), ...Object.keys(theirs)])) {
+            out[key] = merge3(ancestor[key], mine[key], theirs[key]);
+        }
+        return out;
+    }
+    return mine; // leaf / array / type-mismatch conflict → local wins
+}
+function forkStore(base, opt) {
+    // A mutable base mutates in place, so its value reference is stable across changes — which defeats merge3's identity-based change detection
+    const mutableBase = typeof base.mutate === 'function';
+    let strategy = opt?.strategy ?? (mutableBase ? 'coarse' : 'fine');
+    if (mutableBase && strategy === 'fine') {
+        if (isDevMode())
+            console.warn("[fork] strategy 'fine' relies on reference-identity change detection, but the base is a " +
+                "mutable store (in-place mutation keeps the same reference) — falling back to 'coarse'.");
+        strategy = 'coarse';
+    }
+    const reconcile = strategy === 'coarse'
+        ? (_ancestor, _mine, theirs) => theirs // re-link to the new base (whole-value reset)
+        : strategy === 'fine'
+            ? merge3
+            : strategy;
+    const merge = reconcile;
+    const staged = linkedSignal({
+        source: () => base(),
+        computation: (theirs, prev) => prev === undefined ? theirs : merge(prev.source, prev.value, theirs),
+    });
+    const store = toStore(staged, opt?.injector, opt?.vivify, opt?.noUnionLeaves);
+    return {
+        store,
+        commit: () => base.set(untracked(staged)),
+        discard: () => staged.set(untracked(base)),
+    };
 }
 
 // Internal dummy store for server-side rendering
@@ -3309,5 +3979,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isMutable, isOpaque, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { MmActivity, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, forkStore, geolocation, 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, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map