@mmstack/primitives 22.0.2 → 22.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.0.2",
+  "version": "22.1.0",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -1,4 +1,6 @@
-import { ValueEqualityFn, Injector, Signal, CreateSignalOptions, DestroyRef, WritableSignal, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef } from '@angular/core';
+import * as i0 from '@angular/core';
+import { ValueEqualityFn, Injector, Signal, Provider, CreateComputedOptions, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, CreateSignalOptions, WritableSignal, ResourceRef, DestroyRef, ElementRef } from '@angular/core';
+import * as _mmstack_primitives from '@mmstack/primitives';
 
 type CreateChunkedOptions<T> = {
     /**
@@ -36,6 +38,302 @@ type CreateChunkedOptions<T> = {
  */
 declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;
 
+/**
+ * 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>
+ * ```
+ */
+declare class MmActivity {
+    private readonly tpl;
+    private readonly vcr;
+    private readonly parent;
+    /** When false, keep the content mounted but hidden + CD-detached. */
+    readonly visible: i0.InputSignal<boolean>;
+    /** Paused == not visible — handed to the kept subtree as PAUSED_CONTEXT. */
+    private readonly paused;
+    private view;
+    constructor();
+    private apply;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MmActivity, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MmActivity, "[mmActivity]", never, { "visible": { "alias": "mmActivity"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * 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.
+ */
+declare function injectPaused(): Signal<boolean>;
+/**
+ * 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).
+ */
+declare function providePaused(source: Signal<boolean>): Provider;
+
+/**
+ * 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).
+ */
+declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;
+
+/**
+ * How a pausable primitive decides whether it is currently paused:
+ *  - omitted (the default) or `true` — read the ambient {@link PAUSED_CONTEXT} (via `injector`, or the
+ *    current injection context). Reaching for a `pausable*` primitive means you want it pausable, so
+ *    this is the default; outside an Activity boundary there's no `PAUSED_CONTEXT`, so the primitive is
+ *    returned unwrapped (never pauses, zero overhead). On the server it never pauses either.
+ *  - a predicate `() => boolean` — used directly. A `Signal<boolean>` satisfies this (signals are
+ *    callable), and a plain function works OUTSIDE an injection context.
+ *  - `false` — the explicit opt-out: the primitive is returned UNWRAPPED (no `linkedSignal`, no gate),
+ *    i.e. exactly the plain primitive with zero overhead.
+ */
+type PauseOption = boolean | (() => boolean);
+type PausableOptions = {
+    /** Pause source — see {@link PauseOption}. Defaults to `true` (read the ambient `PAUSED_CONTEXT`). */
+    readonly pause?: PauseOption;
+    /**
+     * Injector used to resolve {@link PAUSED_CONTEXT} when `pause` is `true`/omitted and the primitive
+     * is created outside an injection context. Ignored for the `false` / predicate forms.
+     */
+    readonly injector?: Injector;
+};
+/**
+ * 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.
+ */
+declare function resolvePause(opt?: PausableOptions): (() => boolean) | null;
+/**
+ * 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.
+ */
+declare function pausableEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & PausableOptions): EffectRef;
+/**
+ * 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.
+ */
+declare function pausableSignal<T>(initialValue: T, options?: CreateSignalOptions<T> & PausableOptions): WritableSignal<T>;
+/**
+ * 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`.
+ */
+declare function pausableComputed<T>(computation: () => T, options?: CreateComputedOptions<T> & PausableOptions): Signal<T>;
+
+/**
+ * Handle for an in-progress transition: a `pending` signal (true while the transition's
+ * resources are in flight) and a `done` promise that resolves once they all settle.
+ */
+type TransitionRef = {
+    readonly pending: Signal<boolean>;
+    readonly done: Promise<void>;
+};
+/**
+ * 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.
+ */
+declare function injectStartTransition(): (fn: () => void) => TransitionRef;
+
+/**
+ * What "not ready" means for first-load suspense:
+ *  - `'value'`: the resource has no value yet (`!hasValue()`). With `keepPrevious`,
+ *    this stays false through a reload — the previous value holds — so a transition
+ *    does NOT re-suspend; only the genuine first load shows a placeholder.
+ *  - `'loading'`: any in-flight request suspends, even a background reload.
+ */
+type SuspendType = 'value' | 'loading';
+type RegisterOptions = {
+    /**
+     * Whether this resource blocks the boundary's first paint (`suspended()`).
+     * `true` for things the subtree can't render without (e.g. lazily-loaded component
+     * code); `false` for in-region data, which should drive the transition indicator
+     * (`pending`) and hold-stale, but NOT blank the whole boundary while it first loads.
+     */
+    readonly suspends?: boolean;
+};
+/**
+ * A transition scope: the set of resources whose async state a boundary coordinates.
+ * Provided per-boundary (so nested boundaries are independent — the transition-scoped,
+ * not global, registry) with a root default so registration always lands somewhere.
+ */
+type TransitionScope = {
+    /** The currently-registered resources (read-only view). */
+    readonly resources: Signal<readonly ResourceRef<any>[]>;
+    /**
+     * Any registered resource has a request in flight (`status` is `loading`/`reloading`).
+     * This is the transition indicator — true during a reload while `keepPrevious` holds
+     * the visible value, so the UI can show "updating…" without unmounting.
+     */
+    readonly pending: Signal<boolean>;
+    /** Any *suspending* resource is not ready — drives the first-load placeholder. */
+    suspended(type: SuspendType): boolean;
+    add(res: ResourceRef<any>, opt?: RegisterOptions): void;
+    remove(res: ResourceRef<any>): void;
+    /**
+     * Coordinated commit: wraps a value signal so it FREEZES at its last-settled value
+     * while the scope is `pending`, then reveals the current value once *everything*
+     * settles. Multiple values wrapped this way release together — one consistent frame,
+     * never a torn mix of new + stale across resources. Compose over a `keepPrevious`
+     * value: keepPrevious holds per-resource, `commit` gates the reveal on the aggregate.
+     */
+    commit<T>(value: Signal<T>): Signal<T>;
+    /**
+     * Whether a transaction is currently HOLDING this scope's synchronous display reads (Tier 3).
+     * A counter under the hood, so nested transactions compose. Distinct from `pending` (a resource
+     * is in flight): `holding` brackets a whole transaction from start to settle.
+     */
+    readonly holding: Signal<boolean>;
+    /** Begin a transaction hold (increment the counter). */
+    beginHold(): void;
+    /** End a transaction hold (decrement); reveals held values when the counter reaches 0. */
+    endHold(): void;
+    /**
+     * Tier 3 display hold: wraps a value so it FREEZES at its pre-hold value while the scope is
+     * `holding`, then reveals the live value when the hold ends. Unlike `commit` (gates on
+     * `pending`), this brackets the whole transaction — so a *synchronous* state write made inside
+     * the transaction stays visually held until the transaction settles, with no torn frame.
+     */
+    hold<T>(value: Signal<T>): Signal<T>;
+};
+declare function createTransitionScope(): TransitionScope;
+/** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
+declare function provideTransitionScope(): Provider;
+declare function injectTransitionScope(): TransitionScope;
+/**
+ * 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.
+ */
+declare function injectRegisterResource(): <T extends ResourceRef<any>>(res: T, opt?: RegisterOptions) => T;
+/** Convenience: register a resource with the nearest transition scope. Must run in an injection context. */
+declare function registerResource<T extends ResourceRef<any>>(res: T, opt?: RegisterOptions): T;
+
+/**
+ * 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).
+ */
+declare abstract class SuspenseBoundaryBase {
+    protected readonly scope: _mmstack_primitives.TransitionScope;
+    /** What counts as "not ready" for the first-load placeholder. Defaults to value-presence. */
+    readonly type: i0.InputSignal<SuspendType>;
+    protected readonly pending: i0.Signal<boolean>;
+    protected readonly suspended: i0.Signal<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspenseBoundaryBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SuspenseBoundaryBase, never, never, { "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * 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.
+ */
+declare class SuspenseBoundary extends SuspenseBoundaryBase {
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspenseBoundary, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SuspenseBoundary, "mm-suspense", never, {}, {}, never, ["[placeholder]", "[busy]", "*"], true, never>;
+}
+/**
+ * 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.
+ */
+declare class UnscopedSuspenseBoundary extends SuspenseBoundaryBase {
+    static ɵfac: i0.ɵɵFactoryDeclaration<UnscopedSuspenseBoundary, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UnscopedSuspenseBoundary, "mm-unscoped-suspense", never, {}, {}, never, ["[placeholder]", "[busy]", "*"], true, never>;
+}
+
+/**
+ * An undo log for a transactional transition. Stateful writes made while the transaction is the
+ * active one record their PRE-write value here (once, on first touch); `restore()` rolls them all
+ * back (abort), `clear()` keeps them (commit — the writes already landed live).
+ */
+type Transaction = {
+    /** Record a signal's current value as its rollback point (no-op if already recorded). */
+    record(sig: WritableSignal<unknown>): void;
+    /** Roll every recorded signal back to its pre-write value (abort). */
+    restore(): void;
+    /** Drop the log, keeping live writes (commit). */
+    clear(): void;
+};
+declare function createTransaction(): Transaction;
+/** The transaction in effect right now, or `null`. Stateful actions consult this to record undo. */
+declare function activeTransaction(): Transaction | null;
+/** Handle for an in-progress transaction (Tier 3): the transition `pending`/`done`, plus `abort`. */
+type TransactionRef = {
+    readonly pending: Signal<boolean>;
+    readonly done: Promise<void>;
+    /** Roll back the staged writes and release the hold without committing. */
+    abort(): void;
+};
+/**
+ * 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.
+ */
+declare function injectStartTransaction(): (fn: () => void) => TransactionRef;
+
 /**
  * Options for creating a debounced writable signal.
  * Extends Angular's `CreateSignalOptions` with a debounce time setting.
@@ -553,6 +851,24 @@ declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterF
     bindToFrame?: (parent: Frame | null) => Frame | null;
 }): EffectRef;
 
+/**
+ * Wraps a signal so it HOLDS its last defined value whenever the source becomes
+ * `undefined`, yielding that value instead of the gap. This is the foundation of
+ * stale-while-revalidate: a source that drops to `undefined` mid-reload keeps
+ * surfacing its previous result rather than flashing empty.
+ *
+ * Built on `linkedSignal` — the only primitive that hands a computation its own
+ * previous output, which is exactly what "hold the previous value" needs.
+ *
+ * If the source is writable, the wrapper forwards `set`/`update`/`asReadonly` to it,
+ * so it stays a drop-in replacement. (Angular's `resource` is itself linkedSignal-backed
+ * and exposes a writable `value` for optimistic updates; this preserves that.)
+ */
+declare function keepPrevious<T>(value: MutableSignal<T>, opt?: CreateSignalOptions<T>): MutableSignal<T>;
+declare function keepPrevious<T, U>(value: DerivedSignal<T, U>, opt?: CreateSignalOptions<U>): DerivedSignal<T, U>;
+declare function keepPrevious<T>(value: WritableSignal<T>, opt?: CreateSignalOptions<T>): WritableSignal<T>;
+declare function keepPrevious<T>(value: Signal<T>, opt?: CreateSignalOptions<T>): Signal<T>;
+
 /**
  * Reactively maps items from a source array to a new array, creating stable signals for each item.
  *
@@ -2028,7 +2344,32 @@ declare function opaque<T extends object>(value: T): Opaque<T>;
  *   // value: Opaque<object> — `store` would treat it as an indivisible leaf
  * }
  */
-declare function isOpaque(value: unknown): value is Opaque<object>;
+declare function isOpaque<T = object>(value: unknown): value is Opaque<T>;
+/**
+ * @internal Runtime brand carrying a store node's lazily-built leaf probe. Exported (like
+ * {@link OPAQUE}) only so the `{ readonly [LEAF]: () => boolean }` brand on the store types is
+ * nameable in the emitted declarations — not part of the supported surface; use {@link isLeaf}.
+ */
+declare const LEAF: unique symbol;
+/**
+ * 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
+ */
+declare function isLeaf<T = unknown>(value: unknown): value is Signal<T> & {
+    readonly [LEAF]: () => boolean;
+};
 /**
  * An object marked via {@link opaque} — the store treats it as an indivisible leaf
  * (like a `Date`), returning it whole instead of deep-proxying its keys.
@@ -2040,7 +2381,7 @@ type Opaque<T> = T & {
 type UnwrapOpqaue<T> = T extends {
     readonly [OPAQUE]: true;
 } ? Omit<T, typeof OPAQUE> : T;
-type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp | {
+type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
     readonly [OPAQUE]: true;
 };
 type Key = string | number;
@@ -2109,16 +2450,22 @@ type MutableSignalStoreObject<T> = Simplify<Readonly<{
         <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
     };
 }>;
-type SignalStore<T> = Signal<UnwrapOpqaue<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
+type SignalStore<T> = Signal<UnwrapOpqaue<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
 type WritableSignalStore<T> = WritableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
+} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
 type MutableSignalStore<T> = MutableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
-declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify): SignalStore<T>;
+} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -2136,6 +2483,14 @@ declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<
      * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
      */
     vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
 }): WritableSignalStore<T>;
 /**
  * Creates a MutableSignalStore from a value.
@@ -2154,8 +2509,93 @@ declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalO
      * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
      */
     vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
 }): MutableSignalStore<T>;
 
+/**
+ * A 3-way merge of a forked value against a changed base: given the common `ancestor` (the base
+ * value the fork last diverged from), `mine` (the fork's current value), and `theirs` (the base
+ * now), return the reconciled value. Used when the base changes mid-fork — and at `commit`.
+ */
+type ReconcileFn<T> = (ancestor: T, mine: T, theirs: T) => T;
+/**
+ * How a fork reconciles when the base changes underneath it:
+ *  - `'fine'` (default for immutable stores) — per-path 3-way merge ({@link merge3}): keep the
+ *    paths the fork edited, take the base's live values for paths it didn't. Survives concurrent
+ *    base changes. UNSUPPORTED on a mutable base (in-place mutation defeats `merge3`'s
+ *    reference-identity checks — `fork` warns and falls back to `'coarse'`).
+ *  - `'coarse'` — whole-value re-link: any base change resets the WHOLE fork (drops staged writes).
+ *    The cheapest strategy; correct when the base is held for the fork's lifetime (transitions).
+ *    The default for a MUTABLE base.
+ *  - a {@link ReconcileFn} — bring your own merge (e.g. Immer patches, array-by-id, CRDT-ish).
+ *    NOTE: any reference-based 3-way merge has the same mutable-store problem as `'fine'`; on a
+ *    mutable base a custom fn receives `ancestor === theirs` (the same mutated object).
+ */
+type ForkStrategy<T> = 'fine' | 'coarse' | ReconcileFn<T>;
+/**
+ * A forked store: an isolated, writable overlay on a base store. Writes stay LOCAL to the fork
+ * (the base is untouched); unedited paths read through to the base. `commit()` flushes the fork's
+ * value onto the base; `discard()` drops the staged writes.
+ *
+ * The mechanism is `linkedSignal`: it holds local writes until its source (the base) changes, then
+ * runs the {@link ForkStrategy} to reconcile. The store interface, deep reads, and deep
+ * copy-on-write writes all come from `toStore` unchanged — the only fork-specific logic is the
+ * reconcile on a base change.
+ *
+ * Reactivity note: the fork reads through a single staged signal, so a read subscribes to the
+ * whole record (coarser than the base store's per-leaf tracking) and the strategy re-runs on any
+ * base change. Free when the base is held (it never ticks); on a live base, `'fine'`'s {@link
+ * merge3} is identity-pruned so it only walks paths that both sides changed.
+ */
+type Fork<T> = {
+    /** The forked store — use it like any store (read/write/extend). */
+    readonly store: WritableSignalStore<T>;
+    /** Apply the fork's staged value onto the base, then re-link (fork now mirrors the base). */
+    commit(): void;
+    /** Drop staged writes — the fork reads through to the base again. */
+    discard(): void;
+};
+/**
+ * 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.
+ */
+declare function merge3<T>(ancestor: T, mine: T, theirs: T): T;
+declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: {
+    strategy?: ForkStrategy<T>;
+    injector?: Injector;
+    /**
+     * Store config for the FORK's store — NOT inherited from `base` (it's closed over inside
+     * the base's `toStore` and can't be read back). If the base was created with these, pass
+     * the same values or the fork's write semantics will differ:
+     *  - `vivify`: without it, a write through a `null`/`undefined` path is silently dropped on
+     *    the fork even though the base would have created the container. Match the base.
+     *  - `noUnionLeaves`: a perf promise; off just means the slower reactive leaf-probe. NOTE it
+     *    is a whole-store guarantee — a fork that flips a node's type (leaf↔substore) violates it,
+     *    and on `commit` the base receives the flipped value with stale cached leaf-ness.
+     */
+    vivify?: Vivify;
+    noUnionLeaves?: boolean;
+}): Fork<T>;
+
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
  * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
@@ -2583,5 +3023,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PipeableSignal, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };
+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 };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, Fork, ForkStrategy, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, ReconcileFn, RegisterOptions, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };