@mmstack/primitives 22.4.1 → 22.5.1

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, Injector, CreateComputedOptions, Signal, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, CreateSignalOptions, WritableSignal, Provider, ValueEqualityFn, ResourceRef, DestroyRef, ElementRef } from '@angular/core';
+import { InjectionToken, Injector, CreateComputedOptions, Signal, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, CreateSignalOptions, WritableSignal, Provider, ValueEqualityFn, ResourceStatus, DestroyRef, ElementRef } from '@angular/core';
 import * as _mmstack_primitives from '@mmstack/primitives';
 
 /**
@@ -174,6 +174,56 @@ declare function injectPaused(): Signal<boolean>;
  */
 declare function providePaused(source: Signal<boolean>): Provider;
 
+/**
+ * How the catch-up write is scheduled (the "lower priority" of the deferral):
+ * - `'afterRender'` (default): after the next render — the urgent update (e.g. the
+ *   keystroke echo) paints first, the expensive subtree catches up right after.
+ * - `'idle'`: `requestIdleCallback` (macrotask fallback) — catch up when the frame has
+ *   budget; keeps continuous input smooth at the cost of a laggier deferred view.
+ * - A function: custom scheduler — call the callback when it's time to catch up and
+ *   return a canceller (also the test seam).
+ */
+type DeferStrategy = 'afterRender' | 'idle' | ((cb: () => void) => () => void);
+type DeferredValueOptions<T> = {
+    readonly strategy?: DeferStrategy;
+    /** Equality for the deferred value — an equal catch-up never notifies consumers. */
+    readonly equal?: ValueEqualityFn<T>;
+    readonly injector?: Injector;
+};
+/**
+ * The deferred view of a source signal: callable as the lagging value, with `pending`
+ * reporting whether a catch-up is still owed (source has moved ahead) — the
+ * `useDeferredValue`/`isStale` pair.
+ */
+type DeferredSignal<T> = Signal<T> & {
+    /** True while the deferred value is behind the source (a catch-up is scheduled). */
+    readonly pending: Signal<boolean>;
+};
+/**
+ * `useDeferredValue` for signals: returns a signal that HOLDS its previous value when
+ * `source` changes and catches up at lower priority (after paint / on idle), so an
+ * expensive subtree keyed off the deferred value never blocks the urgent update that
+ * caused the change — type into a filter, the input echoes instantly, the big list
+ * re-renders a beat later.
+ *
+ * ```ts
+ * const query = signal('');
+ * const deferredQuery = deferredValue(query);
+ * const results = computed(() => expensiveFilter(items(), deferredQuery()));
+ * // template: <input [(ngModel)]="query" /> stays responsive; results lag one paint
+ * // deferredQuery.pending() → dim the stale list while it catches up
+ * ```
+ *
+ * Rapid changes coalesce: each change reschedules the catch-up, so only the LATEST
+ * source value is ever applied (no intermediate churn in the expensive subtree).
+ * On the server this is a synchronous pass-through — SSR renders once, so deferral
+ * would just mean rendering stale content.
+ *
+ * This is a scheduling tool, not an async one — for async work compose `latest()`;
+ * for coordinated multi-resource reveals use a transition scope.
+ */
+declare function deferredValue<T>(source: Signal<T>, opt?: DeferredValueOptions<T>): DeferredSignal<T>;
+
 /**
  * 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
@@ -188,6 +238,95 @@ declare function providePaused(source: Signal<boolean>): Provider;
  */
 declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;
 
+/**
+ * What `use()` accepts: any status-bearing async value — an Angular `ResourceRef`,
+ * an `@mmstack/resource` query/mutation, or another `latest()` result (so async
+ * derivations nest). Purely structural; no class or brand required.
+ */
+type UseSource<T> = {
+    readonly status: Signal<ResourceStatus>;
+    readonly value: Signal<T | undefined>;
+    hasValue(): boolean;
+    readonly error?: Signal<unknown>;
+};
+/**
+ * An async derivation: callable as a signal of the latest successfully-computed value
+ * (held through in-flight recomputes — the stale-while-revalidate atom), with the
+ * aggregate async state of everything it `use()`d. Satisfies both `UseSource` (so it
+ * nests inside another `latest`) and the transition scope's `ResourceLike` surface
+ * (so it registers into boundaries like any resource).
+ */
+type LatestSignal<T> = Signal<T | undefined> & {
+    /** The held value — same signal as the callable itself. */
+    readonly value: Signal<T | undefined>;
+    /**
+     * Aggregate status. `error` wins (any used member errored, or the computation threw);
+     * otherwise in-flight work maps to `reloading` (a value is held) / `loading` (first
+     * load); a completed computation is `resolved`; blocked-with-nothing-in-flight (e.g.
+     * a member is `idle`) is `idle`.
+     */
+    readonly status: Signal<ResourceStatus>;
+    /** Any used member has a request in flight (`loading`/`reloading`) — the aggregate transition indicator. */
+    readonly pending: Signal<boolean>;
+    /** Alias of `pending`, for the `ResourceRef`-shaped surface. */
+    readonly isLoading: Signal<boolean>;
+    /**
+     * The computation's own thrown error, or the first used member's error (in read
+     * order). `undefined` when healthy. The held value stays readable through an error.
+     */
+    readonly error: Signal<unknown>;
+    /** Whether a value has ever been produced (and is therefore held). */
+    hasValue(): boolean;
+};
+type CreateLatestOptions<T> = {
+    /** Equality for the held value: an in-flight cycle that recomputes to an equal value never notifies consumers (while `pending` still reports the flight). */
+    readonly equal?: ValueEqualityFn<T>;
+    /**
+     * Auto-registration into the nearest transition scope (same vocabulary as resource
+     * options): `'indicator'` drives `pending`/hold-stale only, `'suspend'` also gates the
+     * boundary's first-load placeholder. Requires an injection context (or `injector`).
+     */
+    readonly register?: false | 'indicator' | 'suspend';
+    /** Injection context for `register`, when created outside one. */
+    readonly injector?: Injector;
+    readonly debugName?: string;
+};
+/**
+ * Reads a resource inside a `latest()` computation: returns its value and reports it to
+ * the enclosing collector, so the derivation's aggregate `pending`/`status`/`error`
+ * include it. When the resource has no value yet (first load) or is in an error state,
+ * the computation short-circuits — code after this call simply doesn't run this round —
+ * which is what lets you write the happy path with no `undefined` checks:
+ *
+ * ```ts
+ * const fullName = latest(() => {
+ *   const u = use(user);          // waterfalls compose:
+ *   const org = use(orgFor(u));   // orgFor(u) is only read once `user` has a value
+ *   return `${u.name} @ ${org.name}`;
+ * });
+ * ```
+ *
+ * Must be called synchronously within `latest()` — like `inject()`, it throws elsewhere.
+ */
+declare function use<T>(res: UseSource<T>): T;
+/**
+ * An async derivation over resources: evaluates `fn` inside a collector frame so that
+ * every `use()` read registers as a member, and exposes the result with resource
+ * semantics — the value holds its previous state while anything it read is in flight
+ * (never flashing empty), `pending` aggregates the members' in-flight state, and the
+ * whole thing is itself a `UseSource`, so `latest`s nest and propagate.
+ *
+ * ```ts
+ * const fullName = latest(() => `${use(user).name} @ ${use(org).name}`);
+ * fullName();          // held value — undefined only before the first successful run
+ * fullName.pending();  // true while user OR org (re)loads
+ * ```
+ *
+ * Evaluation is a plain `computed` under the hood: lazy, pure, no effects, usable
+ * outside any injection context (`register` is the only DI-touching option).
+ */
+declare function latest<T>(fn: () => T, opt?: CreateLatestOptions<T>): LatestSignal<T>;
+
 /**
  * Handle for an in-progress transition: a `pending` signal (true while the transition's OWN
  * resources are in flight — loads already in flight when it started are not attributed) and a
@@ -214,6 +353,22 @@ type TransitionRef = {
  */
 declare function injectStartTransition(): (fn: () => void) => TransitionRef;
 
+/**
+ * The structural surface a transition scope actually reads — everything a `ResourceRef`
+ * has, so any resource (query, mutation, plain Angular `resource`) passes as-is, but also
+ * satisfied by status-bearing derivations like `latest()`, so those register too.
+ *
+ * `abort` is the optional cancellation seam: a resource that knows how to tear down its
+ * in-flight work exposes it (`queryResource` does; mutations deliberately don't — a POST
+ * can't be unsent), and {@link TransitionScope.abortPending} calls it. Resources without
+ * it are simply left to settle.
+ */
+type ResourceLike = {
+    readonly status: Signal<ResourceStatus>;
+    readonly isLoading: Signal<boolean>;
+    hasValue(): boolean;
+    abort?(): void;
+};
 /**
  * What "not ready" means for first-load suspense:
  *  - `'value'`: the resource has no value yet (`!hasValue()`). With `keepPrevious`,
@@ -238,7 +393,7 @@ type RegisterOptions = {
  */
 type TransitionScope = {
     /** The currently-registered resources (read-only view). */
-    readonly resources: Signal<readonly ResourceRef<any>[]>;
+    readonly resources: Signal<readonly ResourceLike[]>;
     /**
      * Any registered resource has a request in flight (`status` is `loading`/`reloading`).
      * This is the transition indicator — true during a reload while `keepPrevious` holds
@@ -247,8 +402,8 @@ type TransitionScope = {
     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;
+    add(res: ResourceLike, opt?: RegisterOptions): void;
+    remove(res: ResourceLike): 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*
@@ -257,6 +412,31 @@ type TransitionScope = {
      * value: keepPrevious holds per-resource, `commit` gates the reveal on the aggregate.
      */
     commit<T>(value: Signal<T>): Signal<T>;
+    /**
+     * THE CANCELLATION CONTRACT, and its manual lever for shared-scope cases.
+     *
+     * What holds by construction (no call needed):
+     * - **View-scoped work dies with its view.** A superseded transition (outlet or
+     *   `*mmTransition`) destroys the hidden incoming view and its injector; resources
+     *   created there are destroyed, which aborts their in-flight loads.
+     * - **Abort is real, all the way down.** Deduped HTTP requests are refCounted — when
+     *   the last consumer lets go the request itself is torn down — and an aborted
+     *   response can never settle into the query cache (cache writes happen on the
+     *   subscriber side of the interceptor chain).
+     *
+     * What this method adds: resources registered in a scope that OUTLIVES the transition
+     * (a shared/root scope) aren't view-scoped, so nothing destroys them on supersede.
+     * `abortPending()` walks the registered resources and calls `abort()` on every
+     * in-flight one that exposes it ({@link ResourceLike.abort} — queries do, mutations
+     * deliberately don't, and a shared resource aborts for ALL its readers, so call this
+     * on interactions that invalidate the pending work, not as a reflex).
+     *
+     * Honest limit (true for every JS framework): only I/O is cancellable — an
+     * already-running synchronous computation cannot be preempted.
+     *
+     * @returns how many resources were actually aborted.
+     */
+    abortPending(): number;
     /**
      * 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
@@ -276,6 +456,19 @@ type TransitionScope = {
     hold<T>(value: Signal<T>): Signal<T>;
 };
 declare function createTransitionScope(): TransitionScope;
+/**
+ * The scope→`PendingTasks` bridge: while `scope.pending()` is true, hold an Angular
+ * pending task so SSR serialization waits for the scope's in-flight loads — HTTP loads
+ * already do this via HttpClient, but CUSTOM loaders (a `latest()` over a hand-rolled
+ * promise, a non-HTTP resource) would otherwise let the server render a boundary
+ * mid-load. Wired automatically by `provideTransitionScope` /
+ * `provideForwardingTransitionScope`; call it yourself only for scopes you construct
+ * directly with `createTransitionScope()`.
+ *
+ * Server-only by design: on the browser, tying `ApplicationRef.isStable` to every load
+ * would stall stability-gated machinery (testability, hydration timing) for no benefit.
+ */
+declare function bridgeScopeToPendingTasks(scope: TransitionScope, injector?: Injector): void;
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
 declare function provideTransitionScope(): Provider;
 declare function injectTransitionScope(): TransitionScope;
@@ -307,9 +500,9 @@ declare function createAttributedPending(scope: TransitionScope): Signal<boolean
  * 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;
+declare function injectRegisterResource(): <T extends ResourceLike>(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;
+declare function registerResource<T extends ResourceLike>(res: T, opt?: RegisterOptions): T;
 
 /**
  * Shared **suspense** (readiness) boundary behaviour: reads the *nearest* transition scope and exposes
@@ -464,6 +657,37 @@ declare class MmTransition<T> {
     static ɵdir: i0.ɵɵDirectiveDeclaration<MmTransition<any>, "[mmTransition]", ["mmTransition"], { "value": { "alias": "mmTransition"; "required": true; "isSignal": true; }; "immediate": { "alias": "mmTransitionImmediate"; "required": false; "isSignal": true; }; "viewTransition": { "alias": "mmTransitionViewTransition"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Per-element morphs on held swaps: assigns `view-transition-name` reactively, so when
+ * a swap wrapped in `document.startViewTransition` flips views (`*mmTransition`'s
+ * `mmTransitionViewTransition`, or the transition outlet's view-transition option), the
+ * browser pairs same-named elements across the outgoing and incoming views and MORPHS
+ * them instead of cross-fading the whole boundary.
+ *
+ * ```html
+ * <!-- outgoing view (list) and incoming view (detail) both name the hero image: -->
+ * <img [mmViewTransitionName]="'hero-' + item().id" [src]="item().img" />
+ * ```
+ *
+ * Why this works with holds: both views coexist in the DOM during a hold, but the
+ * incoming one is `display: none` — elements without boxes aren't captured, so the
+ * same name on both sides is legal at each capture point (old visible at snapshot,
+ * new visible after the swap). No arming/cleanup dance needed.
+ *
+ * The name is normalized to a valid CSS custom-ident (invalid characters → `-`, a
+ * leading digit gets a `_` prefix). An empty string / `'none'` clears the name — use
+ * that to opt an element out conditionally. One rule remains YOURS to keep: a name
+ * must be unique among elements VISIBLE at capture time (two rendered instances of the
+ * same named element make the browser skip the whole transition) — derive names from
+ * ids for anything that can repeat.
+ */
+declare class MmViewTransitionName {
+    readonly mmViewTransitionName: i0.InputSignal<string>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<MmViewTransitionName, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MmViewTransitionName, "[mmViewTransitionName]", never, { "mmViewTransitionName": { "alias": "mmViewTransitionName"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
  * Options for creating a debounced writable signal.
  * Extends Angular's `CreateSignalOptions` with a debounce time setting.
@@ -2612,8 +2836,8 @@ type UnwrapOpaque<T> = T extends {
 type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
     readonly [OPAQUE]: true;
 };
-type Key = string | number;
-type AnyRecord = Record<Key, any>;
+type Key$1 = string | number;
+type AnyRecord = Record<Key$1, any>;
 /**
  * @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
@@ -2800,6 +3024,32 @@ declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalO
      */
     noUnionLeaves?: boolean;
 }): MutableSignalStore<T>;
+/**
+ * Builds a DI-less store context — the shared proxy-cache and cleanup registry that {@link toStore}
+ * normally resolves from the injector — so a `store`/`toStore`/`opLog` graph can run with NO Angular
+ * injection context. Spread the result into the options:
+ *
+ * ```ts
+ * import { microtaskOpLogDriver } from '@mmstack/worker/host';
+ * const ctx = createStoreContext();
+ * const s = store({ todos: [] }, ctx);
+ * const log = opLog(s, { driver: microtaskOpLogDriver(), origin: 'worker' }); // no injector anywhere
+ * ```
+ *
+ * **This is a worker-only fallback — do NOT use it on the main thread.** DI is the default and
+ * correct path in an app: the injector scopes the proxy-cache/cleanup singletons per app instance,
+ * which on the SERVER keeps one request's store identity from bleeding into another's (the exact
+ * hazard a module-scope singleton would reintroduce). A Web Worker is safe because it is a single
+ * store graph per thread and never runs during SSR (spawn is a `PLATFORM_ID === 'server'` no-op),
+ * so there is no cross-request scope to contaminate. Never hoist a `createStoreContext()` to module
+ * scope on a shared/main thread.
+ *
+ * **Share ONE context across every store in a worker** — the same way `providedIn: 'root'` shares
+ * one cache across all of an app's stores. `@mmstack/worker/host` memoizes this per worker
+ * (`workerStoreContext()`); reach for `createStoreContext()` directly only in a bare
+ * (non-worker-host) DI-less setup, and hold the single instance yourself.
+ */
+declare function createStoreContext(): toStoreOptions;
 
 /**
  * A 3-way merge of a forked value against a changed base: given the common `ancestor` (the base
@@ -2869,6 +3119,170 @@ type ForkStoreOptions<T> = toStoreOptions & {
 };
 declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;
 
+type Key = string | number;
+/**
+ * One structural operation. `set` on a key that did not previously exist carries NO `prev`
+ * property (an absent key is not the same as a key holding `undefined` — the merge3 lesson),
+ * which is what lets {@link invertBatch} invert an add into a delete.
+ */
+type StoreOp = {
+    kind: 'set';
+    path: readonly Key[];
+    next: unknown;
+    prev?: unknown;
+} | {
+    kind: 'delete';
+    path: readonly Key[];
+    prev: unknown;
+};
+/** One emission: every op derived from one commit window (a tick), in path order. */
+type OpBatch = {
+    /** Identifies the emitting log — filter your own batches on a shared transport. */
+    readonly origin: string;
+    /** Per-log monotonic batch counter. */
+    readonly version: number;
+    readonly ops: readonly StoreOp[];
+};
+/**
+ * Drives an {@link opLog}'s emission reaction. Given the `run` closure (which reads the source in
+ * a tracking context and flushes the delta), a driver arranges for `run` to execute now and again
+ * on every subsequent change, returning a handle that stops it. The default driver is an Angular
+ * `effect` (needs an injector). Supply a custom driver to run an opLog with NO injector; a
+ * renderer-independent one built on `@angular/core/primitives/signals` `createWatch` ships as
+ * `microtaskOpLogDriver` from `@mmstack/worker/host` (the Web Worker seam).
+ */
+type OpLogDriver = (run: () => void) => {
+    destroy(): void;
+};
+type CreateOpLogOptions = {
+    /** Transport identity for emitted batches. Defaults to a random id. */
+    readonly origin?: string;
+    /** Injection context for the default effect-based driver (required outside one). */
+    readonly injector?: Injector;
+    /**
+     * Replaces the default Angular-`effect` emission driver. Supply a custom driver (e.g.
+     * `microtaskOpLogDriver` from `@mmstack/worker/host`) to run an opLog with NO injector. When
+     * given, `injector` is ignored and no injection context is required.
+     */
+    readonly driver?: OpLogDriver;
+};
+type OpLog<T extends object> = {
+    /**
+     * Ordered, lossless delivery of every emitted batch. Synchronous — don't write back into
+     * the observed source from inside a callback (route remote data through {@link OpLog.apply}).
+     */
+    subscribe(cb: (batch: OpBatch) => void): () => void;
+    /** The most recent batch — a lossy sampling view (devtools); use `subscribe` for transport. */
+    readonly latest: Signal<OpBatch | null>;
+    /**
+     * Synchronously diff the source and emit any pending change NOW, rather than waiting for the
+     * driver's scheduled run (an app tick, or a custom driver's microtask). Idempotent
+     * and coalescing: writes since the last emission compose into one batch, and a `flush()` with
+     * nothing pending is a no-op. Use it to make emission deterministic — the worker host calls it
+     * to settle its mirror synchronously (tests), and it underpins the flush-before-apply honesty of
+     * {@link OpLog.apply}. Independent of the driver: a later scheduled run simply finds no diff.
+     */
+    flush(): void;
+    /**
+     * Applies ops (a remote batch, a persisted journal entry, an {@link invertBatch} result)
+     * atomically: ONE `set`, one notification wave. Also advances this log's diff baseline in
+     * the same step, so an applied batch produces NO echo emission — sync loops terminate by
+     * construction. Local writes pending in the current tick are flushed (emitted) first, so
+     * they are never silently folded into the applied baseline.
+     */
+    apply(ops: OpBatch | readonly StoreOp[]): void;
+    /** Stops observing and drops subscribers. Also happens when the injection context dies. */
+    destroy(): void;
+};
+/**
+ * Pure, store-free application of ops onto a plain root value, returning the next immutable root
+ * (structural-sharing along op paths, missing containers vivified `'auto'`-style). This is the
+ * same transform {@link OpLog.apply} runs, extracted so a replica can fold a received batch into
+ * a value WITHOUT owning a diffing {@link opLog} — e.g. the worker-graph read-replica seam.
+ * Accepts a batch or a bare op list.
+ */
+declare function applyOps<T>(root: T, ops: OpBatch | readonly StoreOp[]): T;
+/**
+ * Pure reference-pruned structural diff of two roots into minimal ops (the emission core of
+ * {@link opLog}, exported so code outside a log can produce a batch — e.g. diffing a scratch
+ * draft against a replica's current value to route a write to its owner). Trusts the
+ * copy-on-write contract: an untouched subtree that kept its reference is skipped.
+ */
+declare function diffOps(prev: unknown, next: unknown): StoreOp[];
+/**
+ * Inverts a batch for undo: reversed order, `set`↔its own inverse (an add — a `set` with no
+ * `prev` — inverts to a `delete`; a `delete` inverts to a `set` restoring `prev`). Feed the
+ * result to {@link OpLog.apply}. Requires the ops' `prev`s, which in-memory batches always
+ * carry — a wire-serialized batch that stripped them is not invertible.
+ */
+declare function invertBatch(batch: OpBatch | readonly StoreOp[]): StoreOp[];
+/**
+ * Observes a copy-on-write signal (a `store`'s root, or any `WritableSignal` holding
+ * immutably-updated objects) and emits its changes as minimal structural op batches — the
+ * shared substrate for sync (ship batches, `apply` remote ones), persistence (journal
+ * batches, replay on boot), undo ({@link invertBatch}), and devtools (`latest`).
+ *
+ * Zero store-core involvement and zero cost when unused: emission is a reference-pruned diff
+ * of the root value per tick (structural sharing makes it O(changed paths)), driven by one
+ * effect. A batch therefore coalesces everything written in one tick — for coarser,
+ * intentional units, stage writes on a `forkStore` and `commit()` (one set → one batch).
+ *
+ * NOT supported on mutable stores/signals: in-place mutation keeps reference identity, which
+ * defeats the diff (same reason `forkStore`'s `'fine'` strategy refuses them) — a dev-mode
+ * warning fires and nothing emits.
+ *
+ * ```ts
+ * const s = store({ todos: [{ done: false }] });
+ * const log = opLog(s, { origin: 'tab-a' });
+ * log.subscribe((b) => channel.postMessage(encode(b)));   // ship
+ * channel.onmessage = (m) => log.apply(decode(m.data));    // apply — echo-free
+ * s.todos[0].done.set(true); // → { kind: 'set', path: ['todos', 0, 'done'], … }
+ * ```
+ */
+declare function opLog<T extends object>(source: WritableSignal<T>, opt?: CreateOpLogOptions): OpLog<T>;
+
+/** Identity selector for keyed array reconciliation: a property name, or a function per item. */
+type ReconcileKey = string | ((item: any) => unknown);
+/**
+ * Produces a value equal to `next` but sharing as much of `prev`'s reference structure as possible:
+ * an object subtree that did not change keeps its `prev` reference, and array items are matched by
+ * `key` so a surviving item keeps its identity across a reorder/insert/remove (only added items are
+ * new, only removed items are dropped). This is what lets a derived store recompute without tearing
+ * down every downstream `computed` that reads an unchanged part of it.
+ */
+declare function reconcile<T>(prev: T, next: T, key?: ReconcileKey): T;
+type ProjectionOptions = toStoreOptions & {
+    /** Identity key for reconciling array items (default `'id'`). */
+    readonly key?: ReconcileKey;
+};
+/**
+ * A derived STORE, the store-shaped counterpart to `computed`. `fn` receives a mutable draft seeded
+ * with the current value and either mutates it in place or returns a new value; whichever it does,
+ * the result is reconciled against the previous value (see {@link reconcile}) so unchanged subtrees
+ * keep reference identity and keyed array items keep their proxy identity. Reading through the
+ * returned store is fine-grained: a `computed` over one field only recomputes when that field
+ * actually changes, even though the whole projection re-ran.
+ *
+ * Recompute is pull-based, exactly like `computed`: the projection is memoized and re-runs on the
+ * first read after a signal `fn` depends on changes, so reads are always coherent (no waiting on an
+ * effect flush) and nothing recomputes while nobody reads. `fn` must be pure, it runs inside the
+ * reactive computation. Prefer `computed` for a plain value; reach for `projection` when you want
+ * the per-property tracking of a store on top of a derivation.
+ *
+ * ```ts
+ * const active = projection<User[]>(() => users().filter((u) => u.active), [], { key: 'id' });
+ * // active[0].name(); — surviving users keep identity across recomputes
+ * ```
+ *
+ * Needs an injection context (or an explicit `injector`) for the store layer's cleanup on the main
+ * thread; with an explicit store context (`createStoreContext()`) it is injector-free, so it also
+ * runs on a worker host.
+ *
+ * @param fn receives the current draft; mutate it, or return new data.
+ * @param seed the initial value, held before the first run.
+ */
+declare function projection<T extends object>(fn: (draft: T) => void | T, seed: T, opt?: ProjectionOptions): SignalStore<T>;
+
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
  * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
@@ -3327,5 +3741,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { MmActivity, MmTransition, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
-export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export { MmActivity, MmTransition, MmViewTransitionName, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, latest, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, projection, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, LatestSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpLog, OpLogDriver, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOp, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };