@mmstack/primitives 19.3.11 → 19.4.0

package/index.d.ts

@@ -1,13 +1,15 @@
 export * from './lib/chunked';
+export * from './lib/concurrent';
 export * from './lib/debounced';
 export * from './lib/derived';
 export { nestedEffect } from './lib/effect';
+export * from './lib/keep-previous';
 export * from './lib/mappers';
 export * from './lib/mutable';
 export * from './lib/pipeable/public_api';
 export * from './lib/pooled';
 export * from './lib/sensors';
-export { isLeaf, isOpaque, isStore, mutableStore, opaque, store, toStore, type MutableSignalStore, type Opaque, type SignalStore, type WritableSignalStore, } from './lib/store';
+export * from './lib/store/public_api';
 export * from './lib/stored';
 export { tabSync } from './lib/tabSync';
 export * from './lib/throttled';

package/lib/concurrent/activity.d.ts

@@ -0,0 +1,52 @@
+import { InjectionToken, type Provider, type Signal } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * 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.
+ */
+export declare const PAUSED_CONTEXT: InjectionToken<Signal<boolean>>;
+/**
+ * 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>
+ * ```
+ */
+export declare class MmActivity {
+    private readonly tpl;
+    private readonly vcr;
+    private readonly parent;
+    /** When false, keep the content mounted but hidden + CD-detached. */
+    readonly visible: import("@angular/core").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.
+ */
+export 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).
+ */
+export declare function providePaused(source: Signal<boolean>): Provider;

package/lib/concurrent/hold-until-ready.d.ts

@@ -0,0 +1,14 @@
+import { type Signal } from '@angular/core';
+/**
+ * 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).
+ */
+export declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;

package/lib/concurrent/index.d.ts

@@ -0,0 +1,7 @@
+export { injectPaused, MmActivity, providePaused } from './activity';
+export * from './hold-until-ready';
+export * from './pausable';
+export * from './start-transition';
+export * from './suspense-boundary';
+export * from './transaction';
+export * from './transition-scope';

package/lib/concurrent/pausable.d.ts

@@ -0,0 +1,65 @@
+import { type CreateComputedOptions, type CreateEffectOptions, type CreateSignalOptions, type EffectCleanupRegisterFn, type EffectRef, type Injector, type Signal, type WritableSignal } from '@angular/core';
+/**
+ * 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.
+ */
+export type PauseOption = boolean | (() => boolean);
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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`.
+ */
+export declare function pausableComputed<T>(computation: () => T, options?: CreateComputedOptions<T> & PausableOptions): Signal<T>;

package/lib/concurrent/start-transition.d.ts

@@ -0,0 +1,20 @@
+import { type Signal } from '@angular/core';
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function injectStartTransition(): (fn: () => void) => TransitionRef;

package/lib/concurrent/suspense-boundary.d.ts

@@ -0,0 +1,46 @@
+import { type SuspendType } from './transition-scope';
+import * as i0 from "@angular/core";
+/**
+ * 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).
+ */
+export declare abstract class SuspenseBoundaryBase {
+    protected readonly scope: import("@mmstack/primitives").TransitionScope;
+    /** What counts as "not ready" for the first-load placeholder. Defaults to value-presence. */
+    readonly type: import("@angular/core").InputSignal<SuspendType>;
+    protected readonly pending: import("@angular/core").Signal<boolean>;
+    protected readonly suspended: import("@angular/core").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.
+ */
+export 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.
+ */
+export 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>;
+}

package/lib/concurrent/transaction.d.ts

@@ -0,0 +1,36 @@
+import { type Signal, type WritableSignal } from '@angular/core';
+/**
+ * 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).
+ */
+export 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;
+};
+export declare function createTransaction(): Transaction;
+/** The transaction in effect right now, or `null`. Stateful actions consult this to record undo. */
+export declare function activeTransaction(): Transaction | null;
+/** Handle for an in-progress transaction (Tier 3): the transition `pending`/`done`, plus `abort`. */
+export 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.
+ */
+export declare function injectStartTransaction(): (fn: () => void) => TransactionRef;

package/lib/concurrent/transition-scope.d.ts

@@ -0,0 +1,74 @@
+import { type Provider, type ResourceRef, type Signal } from '@angular/core';
+/**
+ * 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.
+ */
+export type SuspendType = 'value' | 'loading';
+export 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.
+ */
+export 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>;
+};
+export declare function createTransitionScope(): TransitionScope;
+/** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
+export declare function provideTransitionScope(): Provider;
+export 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.
+ */
+export 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. */
+export declare function registerResource<T extends ResourceRef<any>>(res: T, opt?: RegisterOptions): T;

package/lib/keep-previous.d.ts

@@ -0,0 +1,20 @@
+import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { type DerivedSignal } from './derived';
+import { type MutableSignal } from './mutable';
+/**
+ * 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.)
+ */
+export declare function keepPrevious<T>(value: MutableSignal<T>, opt?: CreateSignalOptions<T>): MutableSignal<T>;
+export declare function keepPrevious<T, U>(value: DerivedSignal<T, U>, opt?: CreateSignalOptions<U>): DerivedSignal<T, U>;
+export declare function keepPrevious<T>(value: WritableSignal<T>, opt?: CreateSignalOptions<T>): WritableSignal<T>;
+export declare function keepPrevious<T>(value: Signal<T>, opt?: CreateSignalOptions<T>): Signal<T>;

package/lib/store/fork-store.d.ts

@@ -0,0 +1,79 @@
+import { type Injector } from '@angular/core';
+import { type Vivify } from '../util';
+import { type WritableSignalStore } from './store';
+/**
+ * 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`.
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function merge3<T>(ancestor: T, mine: T, theirs: T): T;
+export 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>;

package/lib/store/public_api.d.ts

@@ -0,0 +1,2 @@
+export * from './fork-store';
+export { isLeaf, isOpaque, isStore, mutableStore, opaque, store, toStore, type MutableSignalStore, type Opaque, type SignalStore, type WritableSignalStore, } from './store';

package/lib/{store.d.ts → store/store.d.ts}

@@ -1,6 +1,7 @@
 import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
-import { type MutableSignal } from './mutable';
-import { type Vivify } from './util';
+import { type MutableSignal } from '../mutable';
+import { type Vivify } from '../util';
+export declare function isWritableSignal<T>(value: Signal<T>): value is WritableSignal<T>;
 /**
  * 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
@@ -156,17 +157,17 @@ type MutableSignalStoreObject<T> = Simplify<Readonly<{
 }>;
 export type SignalStore<T> = Signal<UnwrapOpqaue<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
-} : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
+} : NonNullable<T> extends any[] ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
 export type WritableSignalStore<T> = WritableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
 } & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
-} : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
+} : NonNullable<T> extends any[] ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
 export type MutableSignalStore<T> = MutableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
 } & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
-} : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
+} : NonNullable<T> extends any[] ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
 export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
 export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
 export declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;

package/package.json

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