@mmstack/primitives 19.5.1 → 19.6.0

package/lib/chunked.d.ts

@@ -1,4 +1,5 @@
 import { type Injector, type Signal, type ValueEqualityFn } from '@angular/core';
+import { type PauseOption } from './concurrent/pausable';
 export type CreateChunkedOptions<T> = {
     /**
      * The number of items to process in each chunk.
@@ -18,6 +19,12 @@ export type CreateChunkedOptions<T> = {
      * An optional `Injector` to use for the internal effect. This allows the effect to have access to dependency injection if needed.
      */
     injector?: Injector;
+    /**
+     * Opt-in pause: gate the chunk-scheduling effect on an ambient Activity boundary (`true`), a
+     * custom predicate, or `false` (default — no pausing). While paused, scheduling stops and resumes
+     * from the current chunk on resume. See {@link PauseOption}.
+     */
+    pause?: PauseOption;
 };
 /**
  * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.

package/lib/concurrent/pausable-pure.d.ts

@@ -0,0 +1,12 @@
+import { type CreateEffectOptions, type EffectCleanupRegisterFn, type EffectRef } from '@angular/core';
+import { type PausableOptions } from './pausable';
+/**
+ * @internal The plain-`effect` sibling of the public {@link pausableEffect} (which is built on
+ * `nestedEffect`). For infra utilities that own a single top-level effect/subscription and don't
+ * need frame/nesting semantics. Opt-in (default off): with no `pause` (call site or
+ * `providePausableOptions` default) it returns a bare `effect` (zero overhead, byte-identical to
+ * today); otherwise it gates the body on the resolved predicate — read FIRST so the dependency set
+ * collapses to just the predicate while paused, re-tracking on resume. Deliberately NOT re-exported
+ * from the public barrel.
+ */
+export declare function pausablePureEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & PausableOptions): EffectRef;

package/lib/concurrent/pausable.d.ts

@@ -1,4 +1,4 @@
-import { type CreateComputedOptions, type CreateEffectOptions, type CreateSignalOptions, type EffectCleanupRegisterFn, type EffectRef, type Injector, type Signal, type WritableSignal } from '@angular/core';
+import { type CreateComputedOptions, type CreateEffectOptions, type CreateSignalOptions, type EffectCleanupRegisterFn, type EffectRef, InjectionToken, type Injector, type Provider, 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
@@ -20,6 +20,27 @@ export type PausableOptions = {
      */
     readonly injector?: Injector;
 };
+/**
+ * @internal Token carrying an app-wide default {@link PauseOption}, set via
+ * {@link providePausableOptions}. {@link resolvePause} consults it when the call site didn't
+ * specify `pause`, so users can opt every pausable-aware primitive in (or out) from one place.
+ */
+export declare const PAUSABLE_OPTIONS: InjectionToken<{
+    pause?: PauseOption;
+}>;
+/**
+ * Provides an app-wide default {@link PauseOption} for every pausable-aware primitive (the public
+ * `pausable*` family plus the opt-in integrations like `stored` / `chunked`). A call-site `pause`
+ * always wins; this only fills in when the call didn't specify one.
+ *
+ * @example
+ * // Make everything that can pause honour the ambient Activity boundary by default:
+ * providePausableOptions({ pause: true })
+ */
+export declare function providePausableOptions(opt: {
+    /** Default pause source for pausable-aware primitives that don't set their own. */
+    pause?: PauseOption;
+}): Provider;
 /**
  * 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.
@@ -34,7 +55,7 @@ export type PausableOptions = {
  *
  * Encapsulating this here keeps every pausable primitive's branching identical and in one place.
  */
-export declare function resolvePause(opt?: PausableOptions): (() => boolean) | null;
+export declare function resolvePause(opt?: PausableOptions, defaultPause?: PauseOption): (() => 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

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

@@ -14,6 +14,12 @@ import * as i0 from "@angular/core";
  *
  * `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).
+ *
+ * SSR: the server serializes whatever the scope reports at stabilization, so a registered resource
+ * must keep the app unstable until it settles or the placeholder is what gets serialized (then
+ * flashes/mismatches on hydration). HttpClient-backed resources, httpResource & all of `@mmstack/resource`
+ * do this automatically via the HTTP layer's `PendingTasks` + transfer cache. A custom loader (raw
+ * `fetch`/promise/timer) must opt in itself: wrap it with `inject(PendingTasks).run(() => promise)`.
  */
 export declare abstract class SuspenseBoundaryBase {
     protected readonly scope: import("@mmstack/primitives").TransitionScope;

package/lib/sensors/index.d.ts

@@ -10,6 +10,7 @@ export * from './media-query';
 export * from './mouse-position';
 export * from './network-status';
 export * from './orientation';
+export * from './pointer-drag';
 export * from './page-visibility';
 export * from './scroll-position';
 export * from './sensor';

package/lib/sensors/pointer-drag.d.ts

@@ -0,0 +1,88 @@
+import { ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
+export type PointerPoint = {
+    x: number;
+    y: number;
+};
+export type PointerModifiers = {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+};
+export type PointerDragState = {
+    /** A gesture is past the activation threshold (distinguishes a drag from a click). */
+    active: boolean;
+    /** Pointer position at the pointerdown that began the gesture. */
+    start: PointerPoint;
+    /** Latest pointer position. */
+    current: PointerPoint;
+    /** `current - start`, computed on the same update as `current` (never torn). */
+    delta: PointerPoint;
+    /** The captured pointer id, or `null` when idle. */
+    pointerId: number | null;
+    /** Modifier keys at the latest update. */
+    modifiers: PointerModifiers;
+    /** Mouse button that started the gesture (`-1` when idle). */
+    button: number;
+    /** The pointing device: `'mouse' | 'touch' | 'pen'` (`''` when idle). */
+    pointerType: string;
+    /**
+     * The element the gesture started on: the `handleSelector` match when one is
+     * set (so a single delegated listener can tell which child started the drag),
+     * otherwise the listener's element. `null` when idle.
+     */
+    origin: HTMLElement | null;
+};
+export type PointerDragOptions = SensorRunOptions & {
+    /**
+     * Element that receives `pointerdown`. An `HTMLElement`, `ElementRef`, or a
+     * `Signal` of one (listeners re-attach when it changes). Defaults to the host
+     * `ElementRef`.
+     */
+    target?: HTMLElement | ElementRef<HTMLElement> | Signal<HTMLElement | ElementRef<HTMLElement> | null | undefined>;
+    /** `'client'` (viewport) or `'page'` coordinates. @default 'client' */
+    coordinateSpace?: 'client' | 'page';
+    /** Pixels the pointer must travel before `active` flips true. @default 3 */
+    activationThreshold?: number;
+    /**
+     * Throttle (ms) for `current`/`delta` updates. @default 16
+     *
+     * Note: a final sub-throttle move right before `pointerup` may not surface on
+     * the throttled view (it coalesces into the terminal idle). Logic that must act
+     * on the *exact* release position should read {@link PointerDragSignal.unthrottled}.
+     */
+    throttle?: number;
+    /** Only start when the pointerdown target matches this selector (delegated handles). */
+    handleSelector?: string;
+    /** Mouse buttons that may start a gesture. @default [0] (primary) */
+    buttons?: number[];
+    /**
+     * Stop the `pointerdown` from propagating once this sensor claims it. Lets an
+     * inner sensor win over an outer one on the same element tree (e.g. a nested
+     * sortable inside another). @default false
+     */
+    stopPropagation?: boolean;
+};
+/** A gesture signal with an `unthrottled` view and an imperative `cancel()`. */
+export type PointerDragSignal = Signal<PointerDragState> & {
+    readonly unthrottled: Signal<PointerDragState>;
+    /** Abort the current gesture and reset to idle (e.g. on Escape / programmatically). */
+    cancel: () => void;
+};
+/**
+ * Tracks a pointer *gesture* (pointerdown → capture → move → up) as a signal —
+ * the foundation for pointer-based drag/move/resize/marquee on a canvas. Unlike
+ * native HTML5 drag, pointer events fire continuously and coordinates are
+ * reliable. SSR-safe; cleans up its listeners automatically.
+ *
+ * @example
+ * ```ts
+ * const drag = pointerDrag({ activationThreshold: 4 });
+ * const position = computed(() => {
+ *   const d = drag();
+ *   return d.active ? { x: base.x + d.delta.x, y: base.y + d.delta.y } : base;
+ * });
+ * ```
+ */
+export declare function pointerDrag(opt?: PointerDragOptions): PointerDragSignal;

package/lib/sensors/sensor.d.ts

@@ -8,6 +8,7 @@ import { type GeolocationOptions, type GeolocationSignal } from './geolocation';
 import { type IdleOptions, type IdleSignal } from './idle';
 import { type MousePositionOptions, type MousePositionSignal } from './mouse-position';
 import { type NetworkStatusSignal } from './network-status';
+import { type PointerDragOptions, type PointerDragSignal } from './pointer-drag';
 import { type ScreenOrientationState } from './orientation';
 import { type ScrollPositionOptions, type ScrollPositionSignal } from './scroll-position';
 import { type WindowSizeOptions, type WindowSizeSignal } from './window-size';
@@ -28,6 +29,10 @@ type SensorTypedOptions = {
         opt: MousePositionOptions;
         returnType: MousePositionSignal;
     };
+    pointerDrag: {
+        opt: PointerDragOptions;
+        returnType: PointerDragSignal;
+    };
     networkStatus: {
         opt: SensorRunOptions;
         returnType: NetworkStatusSignal;
@@ -112,6 +117,15 @@ export declare function sensor(type: 'elementSize', options?: SensorTypedOptions
  * @example const pos = sensor('mousePosition', { coordinateSpace: 'page', throttle: 50 });
  */
 export declare function sensor(type: 'mousePosition', options?: SensorTypedOptions['mousePosition']['opt']): MousePositionSignal;
+/**
+ * Creates a sensor signal tracking a pointer drag gesture (down → move → up).
+ * @param type Must be `'pointerDrag'`.
+ * @param options Optional configuration (target, activationThreshold, throttle, …).
+ * @returns A `PointerDragSignal` with `active`/`start`/`current`/`delta`, plus `unthrottled` and `cancel()`.
+ * @see {pointerDrag} for detailed documentation and examples.
+ * @example const drag = sensor('pointerDrag', { activationThreshold: 4 });
+ */
+export declare function sensor(type: 'pointerDrag', options?: SensorTypedOptions['pointerDrag']['opt']): PointerDragSignal;
 /**
  * Creates a sensor signal that tracks the browser's online/offline status.
  * @param type Must be `'networkStatus'`.

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

@@ -1,6 +1,5 @@
-import { type Injector } from '@angular/core';
-import { type Vivify } from '../util';
-import { type WritableSignalStore } from './store';
+import { type toStoreOptions } from './store';
+import type { WritableSignalStore } from './types';
 /**
  * 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
@@ -61,19 +60,10 @@ export type Fork<T> = {
  * 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?: {
+/**
+ * ForkStoreOptions, vivify/noUnionLeaves should remain the same & are automatically inherited, override carefully (advanced usecases)
+ */
+export type ForkStoreOptions<T> = toStoreOptions & {
     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>;
+};
+export declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;

package/lib/store/internals.d.ts

@@ -0,0 +1,34 @@
+import { InjectionToken, type Signal } from '@angular/core';
+import { type SignalStore } from './types';
+export declare const IS_STORE: unique symbol;
+export declare const SCOPE_PARENT: unique symbol;
+export declare const STORE_SHARED_GLOBALS: unique symbol;
+export declare const STORE_SHARED_OPTIONS: unique symbol;
+/**
+ * @internal Brand carrying a store's writability ('mutable' | 'writable' | 'readonly'), stamped
+ * on every store proxy. Read by `extendStore` instead of re-deriving via `isWritableSignal`,
+ * which would mis-classify a readonly scoped store (its backing `toWritable` still has a `set`).
+ */
+export declare const STORE_KIND: unique symbol;
+export type StoreKind = 'mutable' | 'writable' | 'readonly';
+export declare const SIGNAL_FN_PROP: Set<string>;
+/**
+ * @internal
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
+export type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
+/**
+ * @internal
+ * Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
+export type ProxyCleanupRegistry = FinalizationRegistry<{
+    target: object;
+    prop: PropertyKey;
+}>;
+export declare const PROXY_CACHE_TOKEN: InjectionToken<ProxyCache>;
+export declare const PROXY_CLEANUP_TOKEN: InjectionToken<ProxyCleanupRegistry>;
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+export declare function isStore<T>(value: unknown): value is SignalStore<T>;

package/lib/store/leaf.d.ts

@@ -0,0 +1,36 @@
+import { type Signal } from '@angular/core';
+/**
+ * @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}.
+ */
+export declare const LEAF: unique symbol;
+/**
+ * @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. Under `noUnionLeaves` the caller promises shapes never flip, so the probe is
+ * resolved once from the first sample and frozen as a constant. Idempotent.
+ */
+export declare function markAsLeaf<TSig>(sig: TSig, value: Signal<unknown>, vivifyEnabled: boolean, noUnionLeaves: boolean): TSig & {
+    readonly [LEAF]: () => boolean;
+};
+/**
+ * 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
+ */
+export declare function isLeaf<T = unknown>(value: unknown): value is Signal<T> & {
+    readonly [LEAF]: () => boolean;
+};

package/lib/store/opaque.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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
+ * by {@link opaque} and the type-level brand carried by {@link Opaque}.
+ */
+export declare const OPAQUE: unique symbol;
+/**
+ * Marks a plain object as opaque so {@link store} treats it as an indivisible leaf
+ * (returned whole, never deep-proxied) — the same way it treats a `Date` or `RegExp`.
+ * The marker is a non-enumerable symbol, so it never appears in spreads or iteration.
+ * Idempotent. Call before freezing (`defineProperty` fails on a frozen object).
+ *
+ * @example
+ * const s = store({ config: opaque({ theme: 'dark', nested: { a: 1 } }) });
+ * s.config();        // the whole object, not a child store
+ * s.config.set(opaque({ theme: 'light', nested: { a: 2 } }));
+ */
+export declare function opaque<T extends object>(value: T): Opaque<T>;
+/**
+ * Type guard companion to {@link opaque}: returns `true` when `value` carries the
+ * {@link OPAQUE} brand, narrowing it to {@link Opaque}. This is the same check the
+ * store uses to route opaque values to its leaf branch (alongside `Date`/`RegExp`).
+ *
+ * @internal Exposed for advanced/niche interop only — not part of the supported public
+ * surface and may change without a major version bump. Reach for {@link opaque} for
+ * normal usage.
+ *
+ * @example
+ * if (isOpaque(value)) {
+ *   // value: Opaque<object> — `store` would treat it as an indivisible leaf
+ * }
+ */
+export declare function isOpaque<T = object>(value: unknown): value is Opaque<T>;
+/**
+ * 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.
+ */
+export type Opaque<T> = T & {
+    readonly [OPAQUE]: true;
+};
+/** @internal Strips the opaque brand from the value a leaf signal carries. */
+export type UnwrapOpaque<T> = T extends {
+    readonly [OPAQUE]: true;
+} ? Omit<T, typeof OPAQUE> : T;

package/lib/store/predicates.d.ts

@@ -0,0 +1,28 @@
+import { type WritableSignal } from '@angular/core';
+import { type MutableSignal } from '../mutable';
+import { type Vivify, type VivifyFn } from '../util';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * @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).
+ */
+export declare function isLeafValue(value: unknown, vivifyEnabled: boolean): boolean;
+/**
+ * @internal
+ * Resolves the vivify shape for a node from its current value: a present record/array is a
+ * certainty we keep (cached in the derivation, so it survives the value being nulled); an
+ * unknown value (`null`/`undefined`) defers to the caller's option. Off stays off.
+ */
+export declare function resolveVivify(sample: unknown, option: Vivify): Vivify;
+export declare function hasOwnKey(value: object | null | undefined, key: PropertyKey): boolean;
+/**
+ * @internal
+ * Builds the `onChange` for the fallback (non-record container) derivation branch. For an
+ * immutable source the container is copied before the write — returning the same mutated
+ * reference would let the source's equality cut propagation (leaving child signals permanently
+ * stale) and alias the caller's original object, breaking the structural-sharing contract
+ * `forkStore` relies on. For a mutable source the write goes through `mutate`, so the chain's
+ * force-notify engages (plain `update` with the same reference would never notify).
+ */
+export declare function createFallbackOnChange(target: WritableSignal<any> | MutableSignal<any>, prop: PropertyKey, vivifyFn: VivifyFn<any>, isMutableSource: boolean): (newValue: any) => void;

package/lib/store/public_api.d.ts

@@ -1,2 +1,6 @@
 export * from './fork-store';
-export { isLeaf, isOpaque, isStore, mutableStore, opaque, store, toStore, type MutableSignalStore, type Opaque, type SignalStore, type WritableSignalStore, } from './store';
+export { isStore } from './internals';
+export { isLeaf } from './leaf';
+export { isOpaque, opaque, type Opaque } from './opaque';
+export { extendStore, mutableStore, store, toStore, type ExtendStoreOptions, type StoreOptions, type toStoreOptions, } from './store';
+export type { MutableSignalStore, SignalStore, WritableSignalStore, } from './types';

package/lib/store/store.d.ts

@@ -1,176 +1,46 @@
 import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
 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
- * by {@link opaque} and the type-level brand carried by {@link Opaque}.
- */
-export declare const OPAQUE: unique symbol;
-/**
- * Marks a plain object as opaque so {@link store} treats it as an indivisible leaf
- * (returned whole, never deep-proxied) — the same way it treats a `Date` or `RegExp`.
- * The marker is a non-enumerable symbol, so it never appears in spreads or iteration.
- * Idempotent. Call before freezing (`defineProperty` fails on a frozen object).
- *
- * @example
- * const s = store({ config: opaque({ theme: 'dark', nested: { a: 1 } }) });
- * s.config();        // the whole object, not a child store
- * s.config.set(opaque({ theme: 'light', nested: { a: 2 } }));
- */
-export declare function opaque<T extends object>(value: T): Opaque<T>;
-/**
- * Type guard companion to {@link opaque}: returns `true` when `value` carries the
- * {@link OPAQUE} brand, narrowing it to {@link Opaque}. This is the same check the
- * store uses to route opaque values to its leaf branch (alongside `Date`/`RegExp`).
- *
- * @internal Exposed for advanced/niche interop only — not part of the supported public
- * surface and may change without a major version bump. Reach for {@link opaque} for
- * normal usage.
- *
- * @example
- * if (isOpaque(value)) {
- *   // value: Opaque<object> — `store` would treat it as an indivisible leaf
- * }
- */
-export 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}.
- */
-export 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
- */
-export 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.
- */
-export type Opaque<T> = T & {
-    readonly [OPAQUE]: true;
-};
-/** @internal Strips the opaque brand from the value a leaf signal carries. */
-export type UnwrapOpaque<T> = T extends {
-    readonly [OPAQUE]: true;
-} ? Omit<T, typeof OPAQUE> : T;
-type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
-    readonly [OPAQUE]: true;
-};
-type Key = string | number;
-type AnyRecord = Record<Key, any>;
-/**
- * @internal
- * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
- * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
- */
-export declare const PROXY_CACHE: WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
-/**
- * @internal
- * Test-only handle on the finalization registry (deliberately NOT re-exported from the public
- * barrel). Prunes a cache entry once its proxy is reclaimed by the GC.
- */
-export declare const PROXY_CLEANUP: FinalizationRegistry<{
-    target: object;
-    prop: PropertyKey;
-}>;
-/**
- * @internal
- * Validates whether a value is a Signal Store.
- */
-export declare function isStore<T>(value: unknown): value is SignalStore<T>;
-type SignalArrayStore<T extends any[]> = Signal<T> & {
-    readonly [index: number]: SignalStore<T[number]>;
-    readonly length: Signal<number>;
-    [Symbol.iterator](): Iterator<SignalStore<T[number]>>;
-};
-type WritableArrayStore<T extends any[]> = WritableSignal<T> & {
-    readonly asReadonlyStore: () => SignalArrayStore<T>;
-    readonly [index: number]: WritableSignalStore<T[number]>;
-    readonly length: Signal<number>;
-    [Symbol.iterator](): Iterator<WritableSignalStore<T[number]>>;
-};
-type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
-    readonly asReadonlyStore: () => SignalArrayStore<T>;
-    readonly [index: number]: MutableSignalStore<T[number]>;
-    readonly length: Signal<number>;
-    [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
-};
-/**
- * @internal Resolves to `true` only for `any`. In a conditional type, `any` distributes across
- * *both* branches (`unknown | object`), and `unknown | X` collapses to `unknown` — which would
- * erase a store's property access and `extend`. Guarding on this routes an `any`-typed store to
- * the full object shape instead.
- */
-type IsAny<T> = 0 extends 1 & T ? true : false;
-/**
- * @internal Flattens an intersection (`A & B & C`) into a single object literal so editor
- * tooltips show the resolved members instead of the raw intersection chain. Display-only —
- * structurally identical to its input.
- */
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-/** @internal The object shape of a readonly store: a child store per key, plus `extend`. */
-type SignalStoreObject<T> = Simplify<Readonly<{
-    [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
-}> & {
-    readonly extend: {
-        <L extends AnyRecord>(source: Signal<L>): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-        <L extends AnyRecord>(props: L): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-    };
-}>;
-/** @internal The object shape of a writable store. */
-type WritableSignalStoreObject<T> = Simplify<Readonly<{
-    [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
-}> & {
-    readonly extend: {
-        <L extends AnyRecord>(source: WritableSignal<L>): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-        <L extends AnyRecord>(props: L): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-    };
-}>;
-/** @internal The object shape of a mutable store. */
-type MutableSignalStoreObject<T> = Simplify<Readonly<{
-    [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
-}> & {
-    readonly extend: {
-        <L extends AnyRecord>(source: MutableSignal<L>): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-        <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+import { STORE_SHARED_GLOBALS, type ProxyCache, type ProxyCleanupRegistry } from './internals';
+import { type AnyRecord, type MutableSignalStore, type SignalStore, type Simplify, type WritableSignalStore } from './types';
+export type toStoreOptions = {
+    injector?: Injector;
+    /**
+     * Opt-in autovivification: when writing through a `null`/`undefined` path, create the
+     * missing intermediate containers instead of dropping the write. Off by default.
+     *
+     * Levels whose current value is a known object/array re-vivify as that same shape — the
+     * knowledge is captured when the path is first accessed and cached, so it holds even after
+     * the value is later nulled. This option governs only genuinely-unknown (currently
+     * `null`/`undefined`) levels: `'auto'` (an array for index keys, an object otherwise), an
+     * 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;
+    /**
+     * @internal
+     * Shared cleanup singletons, they get injected/passed automatically
+     */
+    [STORE_SHARED_GLOBALS]?: {
+        cache: ProxyCache;
+        registry: ProxyCleanupRegistry;
     };
-}>;
-export type SignalStore<T> = Signal<UnwrapOpaque<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
-    readonly [LEAF]: () => boolean;
-} : NonNullable<T> extends any[] ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
-export type WritableSignalStore<T> = WritableSignal<UnwrapOpaque<T>> & {
-    readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
-    readonly [LEAF]: () => boolean;
-} : NonNullable<T> extends any[] ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
-export type MutableSignalStore<T> = MutableSignal<UnwrapOpaque<T>> & {
-    readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
-    readonly [LEAF]: () => boolean;
-} : 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>;
+};
+export type StoreOptions<T> = CreateSignalOptions<T> & toStoreOptions;
+export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, options?: toStoreOptions): MutableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, options?: toStoreOptions): WritableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: Signal<T>, options?: toStoreOptions): SignalStore<T>;
+export type ExtendStoreOptions = Omit<toStoreOptions, 'vivify' | 'noUnionLeaves' | typeof STORE_SHARED_GLOBALS>;
+export declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: MutableSignalStore<T>, source: MutableSignal<L> | L, options?: ExtendStoreOptions): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+export declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: WritableSignalStore<T>, source: WritableSignal<L> | L, options?: ExtendStoreOptions): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+export declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: SignalStore<T>, source: Signal<L> | L, options?: ExtendStoreOptions): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -223,4 +93,3 @@ export declare function mutableStore<T extends AnyRecord>(value: T, opt?: Create
      */
     noUnionLeaves?: boolean;
 }): MutableSignalStore<T>;
-export {};