local-replica 0.0.1 → 0.0.3

package/dist/{index-CFbCHM7Q.d.ts → index-DsElitHD.d.ts}

@@ -1,18 +1,50 @@
+/** Address of one persisted row: the resource's row key inside an identity scope. */
+interface ReplicaRowKey {
+  queryKey: string;
+  scope: string;
+}
+interface ReplicaRow<T> {
+  data: T;
+  updatedAt: number;
+}
 /**
- * First-class pagination for replicas.
- *
- * Vocabulary (direction-agnostic):
- * - HEAD page: the newest window, what a refresh re-fetches (`cursor` undefined).
- * - NEXT pages: further pages in the paging direction (older history).
- *   - `forward`: the view is head-first, next pages append at the END
- *     (sidebar lists: newest topic first, "load more" below).
- *   - `backward`: the view is oldest-first, next pages PREPEND at the start
- *     (chat transcripts: newest message last, "load older" on scroll-up).
- * - `offset` mode: the cursor is the page index (0 = head).
- *   `cursor` mode: the server hands back an opaque `nextCursor`.
- *
- * Every function is pure; the store binding owns staleness and scope.
+ * Where a replica keeps its rows between sessions (IndexedDB, localStorage …).
+ * The server stays the durable source of truth, so `get` is best-effort: it
+ * swallows its own I/O failures and reports a miss. Writes are not: `set` and
+ * `remove` must reject when they did not land (see each method), so the
+ * engine can retry them instead of treating a dropped row as persisted.
  */
+interface ReplicaStorage<T> {
+  get: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /**
+   * Strict read for destructive passes: like `get`, but **rejects** when the
+   * row could not be read (I/O error, unparsable value) instead of reporting a
+   * miss. The engine reads its per-scope index (and every row it patches)
+   * through it before `remove` / `clear` / an entity patch / an eviction, so an
+   * unreadable index fails the pass rather than passing for an empty one.
+   *
+   * Optional only for compatibility: a storage without it still hydrates and
+   * persists, but every destructive pass **fails** (`clear()` resolves `false`,
+   * a removal stays unpurged and is retried, an entity guard is kept) because
+   * the engine cannot tell a miss from a failed read through `get`.
+   */
+  getStrict?: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /**
+   * Delete a row. Must **reject** when the delete did not land (a closed
+   * IndexedDB, a quota or security error): the engine keeps the row indexed
+   * and the removal unpurged, so the next `remove` / `clear` retries it instead
+   * of letting a row the user deleted hydrate again. A missing row is a success.
+   */
+  remove: (key: ReplicaRowKey) => Promise<void>;
+  /**
+   * Write a row. Should **reject** when the write did not land: the engine only
+   * treats a row as holding a value after `set` resolved, so a rejected write is
+   * retried by the next persist rather than skipped as redundant. A storage that
+   * swallows failures still works, but a dropped write then survives until the
+   * value changes or the next session.
+   */
+  set: (key: ReplicaRowKey, row: ReplicaRow<T>) => Promise<void>;
+}
 type ReplicaPagingMode = 'cursor' | 'offset';
 type ReplicaPagingDirection = 'backward' | 'forward';
 interface ReplicaPagingConfig<TItem, TCursor = any> {
@@ -109,115 +141,6 @@ interface ReplicaPagingContext<TItem> {
    */
   isClientOnly?: (item: TItem) => boolean;
 }
-/** Concatenate in view order: forward = head first, backward = head last. */
-declare const joinPages: <TItem>(head: TItem[], rest: TItem[], direction: ReplicaPagingDirection) => TItem[];
-/** The paging config one entry reads with: `directionOf` resolved for `key`. */
-declare const pagingFor: <TItem, TCursor>(config: ReplicaPagingConfig<TItem, TCursor>, key: string) => ReplicaPagingConfig<TItem, TCursor>;
-/**
- * Cursor to request the next page with; `null` → exhausted, `undefined` →
- * cannot page yet. Offset views without bookkeeping (seeded by legacy code or
- * an older persisted shape) derive it from `currentPage` / `hasMore`.
- */
-declare const getNextPageCursor: <TItem, TCursor>(data: ReplicaPagedData<TItem, TCursor> | undefined, config: Pick<ReplicaPagingConfig<TItem, TCursor>, 'deriveCursor' | 'direction' | 'isCursorable' | 'mode'>) => TCursor | null | undefined;
-/**
- * Fold a fresh HEAD page into the view.
- *
- * - First load, a query change (`reset`) or an unextended view → the head page.
- * - Extended view, `offset` mode → keep the loaded depth: fresh head first,
- *   then previously loaded rows not in it (shifted offsets self-heal by id).
- * - Extended view, `cursor` mode → keep older pages only when the fresh head
- *   still contains the join anchor and the next cursor is known; otherwise
- *   collapse to the head page (never show a hidden gap).
- *
- * Client-only rows still in the view are kept on the head side.
- */
-declare const applyHeadPage: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor> | undefined, page: ReplicaPageResult<TItem, TCursor>, options: {
-  pageSize: number;
-  reset?: boolean;
-}, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => ReplicaPagedData<TItem, TCursor>;
-/** Merge the NEXT page (fetched with `getNextPageCursor`) into the view. */
-declare const applyNextPage: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, page: ReplicaPageResult<TItem, TCursor>, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => ReplicaPagedData<TItem, TCursor>;
-/**
- * Insert new rows on the HEAD side (a streamed message, a created topic).
- * Cursors point at the far end, so they stay valid; offsets shift and are
- * healed by id de-duplication on the next page merge.
- */
-declare const insertHeadItems: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, items: TItem[], config: ReplicaPagingConfig<TItem, TCursor>) => ReplicaPagedData<TItem, TCursor>;
-/**
- * Patch (or remove, when `fn` returns `undefined`) one row by id. Returns the
- * same reference when the row is absent or unchanged.
- */
-declare const mapPagedItem: <TItem, TCursor, TData extends ReplicaPagedData<TItem, TCursor>>(current: TData, id: string, fn: (item: TItem) => TItem | undefined, config: Pick<ReplicaPagingConfig<TItem>, 'getId'>) => TData;
-/** Whether a paged view holds a row. */
-declare const hasPagedItem: <TItem>(data: ReplicaPagedData<TItem, unknown> | undefined, id: string, config: Pick<ReplicaPagingConfig<TItem>, 'getId'>) => boolean;
-/** Drop every loaded page but the head (e.g. after an edit inside older history). */
-declare const collapseToHead: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, config: ReplicaPagingConfig<TItem, TCursor>) => ReplicaPagedData<TItem, TCursor>;
-/**
- * What survives a reload: whole pages from the head side, bounded by
- * `persist.pages` and `persist.maxItems`, client-only rows and transient
- * flags stripped. Offset views are cut at page-size boundaries so the
- * persisted `currentPage` stays a valid offset; a cut inside a cursor page
- * forgets the cursor (pagination resumes after the next server head page).
- */
-declare const toPersistedPage: <TItem, TCursor, TData extends ReplicaPagedData<TItem, TCursor>>(data: TData, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => TData;
-/** Address of one persisted row: the resource's row key inside an identity scope. */
-interface ReplicaRowKey {
-  queryKey: string;
-  scope: string;
-}
-interface ReplicaRow<T> {
-  data: T;
-  updatedAt: number;
-}
-/**
- * Where a replica keeps its rows between sessions (IndexedDB, localStorage …).
- * The server stays the durable source of truth, so `get` is best-effort: it
- * swallows its own I/O failures and reports a miss. Writes are not: `set` and
- * `remove` must reject when they did not land (see each method), so the
- * engine can retry them instead of treating a dropped row as persisted.
- */
-interface ReplicaStorage<T> {
-  get: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
-  /**
-   * Strict read for destructive passes: like `get`, but **rejects** when the
-   * row could not be read (I/O error, unparsable value) instead of reporting a
-   * miss. The engine reads its per-scope index (and every row it patches)
-   * through it before `remove` / `clear` / an entity patch / an eviction, so an
-   * unreadable index fails the pass rather than passing for an empty one.
-   *
-   * Optional only for compatibility: a storage without it still hydrates and
-   * persists, but every destructive pass **fails** (`clear()` resolves `false`,
-   * a removal stays unpurged and is retried, an entity guard is kept) because
-   * the engine cannot tell a miss from a failed read through `get`.
-   */
-  getStrict?: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
-  /**
-   * Delete a row. Must **reject** when the delete did not land (a closed
-   * IndexedDB, a quota or security error): the engine keeps the row indexed
-   * and the removal unpurged, so the next `remove` / `clear` retries it instead
-   * of letting a row the user deleted hydrate again. A missing row is a success.
-   */
-  remove: (key: ReplicaRowKey) => Promise<void>;
-  /**
-   * Write a row. Should **reject** when the write did not land: the engine only
-   * treats a row as holding a value after `set` resolved, so a rejected write is
-   * retried by the next persist rather than skipped as redundant. A storage that
-   * swallows failures still works, but a dropped write then survives until the
-   * value changes or the next session.
-   */
-  set: (key: ReplicaRowKey, row: ReplicaRow<T>) => Promise<void>;
-}
-/**
- * Where the confirmed value of an entry came from.
- * - `storage`: hydrated from the persisted projection (may be stale)
- * - `server`: confirmed by a network response
- * - `local`: written locally before any hydrate/replace landed
- * - `seed`: a provisional local row (e.g. a list row standing in for a detail so
- *   an object stays resolvable). Unlike `local` it is *not* authoritative: a
- *   persisted `storage` value may replace it on hydrate, and it never persists —
- *   so it cannot overwrite the detail it is only standing in for.
- */
-type ReplicaSource = 'local' | 'seed' | 'server' | 'storage';
 /**
  * Identity partition of the persisted projection (user + workspace by default).
  * `use` feeds the sync hook, `get` imperative actions, `canPersist` gates writes
@@ -236,60 +159,6 @@ interface ReplicaScope {
   get: () => string;
   use: () => string;
 }
-interface ReplicaPendingMutation<T> {
-  apply: (data: T) => T;
-  id: number;
-  /**
-   * Query the overlay was started under. An entry key can be reused for another
-   * query (a navigation), and an overlay only ever describes the query that
-   * created it — carrying it over would apply (and later persist) one query's
-   * row inside another.
-   */
-  query?: string;
-}
-interface ReplicaEntryMeta<T> {
-  /**
-   * Confirmed snapshot. Only kept while optimistic mutations are in flight —
-   * otherwise the view itself is the confirmed value.
-   */
-  base?: T;
-  /** Params of the last hydrate/replace — what `loadMore` pages with. */
-  params?: unknown;
-  pending: ReplicaPendingMutation<T>[];
-  /** Stable query identity beyond the key (filters, page size). */
-  query?: string;
-  /**
-   * Every write made while the entry is still a `seed`, in order — the seed
-   * writes themselves and the confirmed writes made over them. A hydrate that
-   * replaces the seed replays them onto the stored value: the seed's fresher
-   * fields (a list row's renamed title) and a confirmed edit made before
-   * storage answered both survive, instead of storage painting older values.
-   */
-  seedPatches?: ReplicaSeedPatch<T>[];
-  source: ReplicaSource;
-  updatedAt: number;
-}
-interface ReplicaSeedPatch<T> {
-  /**
-   * Replayed onto the stored value, so a seed write must merge the fields it
-   * owns into its input rather than ignore it (its first run sees `undefined`).
-   */
-  apply: (data: T | undefined) => T | undefined;
-  persist: boolean;
-  /** A provisional seed write: replayed, but never makes the result confirmed. */
-  seed?: boolean;
-  /**
-   * Source of a seed write. A later seed of the same tag supersedes this one
-   * (since the last confirmed write), so it must carry every field this one set.
-   */
-  tag?: string;
-}
-/** Bookkeeping slot a replica keeps inside its domain store. */
-interface ReplicaState<T> {
-  entries: Record<string, ReplicaEntryMeta<T>>;
-  /** The scope every entry in memory belongs to. */
-  scope?: string;
-}
 interface ReplicaResource<TParams, TData, TFetched = TData, TCursor = any> {
   /** Paged resources receive the page cursor (`undefined` = head page). */
   fetcher?: (params: TParams, cursor?: TCursor) => Promise<TFetched>;
@@ -319,6 +188,89 @@ interface ReplicaResource<TParams, TData, TFetched = TData, TCursor = any> {
   syncKey?: (params: TParams) => readonly unknown[];
   version: number;
 }
+/** Builds the storage of one resource from its namespace (`replica:<name>:v<version>`). */
+type ReplicaStorageFactory<TData> = (namespace: string) => ReplicaStorage<TData> | undefined;
+interface DefineReplicaOptions<TParams, TData, TFetched = TData, TCursor = any> {
+  /** Default network fetcher; a store binding may override it. */
+  fetcher?: (params: TParams, cursor?: TCursor) => Promise<TFetched>;
+  /** Entry identity inside one scope (memory bucket + persisted row). */
+  key: (params: TParams) => string;
+  name: string;
+  paging?: ReplicaPagingConfig<any, TCursor>;
+  /**
+   * Bound what the resource keeps in storage. `maxEntries` caps the persisted
+   * rows (storage keys: one per entry key and query) per scope; past it the
+   * least recently used rows are evicted — their persisted row, index entry
+   * and, when nothing holds it, their memory entry. Use rows (a hydrate or a
+   * persist, including a skipped unchanged one) count as recent, and the order
+   * lives in the persisted index, so it survives reloads. A row on screen (a
+   * mounted `useSync`, see `retain`), with pending optimistic writes or a
+   * `loadMore` in flight is never evicted. Unbounded by default.
+   */
+  persist?: {
+    maxEntries?: number;
+  };
+  /**
+   * Entries that never touch storage (no hydrate, no persist) — e.g. scoped
+   * buckets whose rows must not land under an ordinary entry. Defaults to all.
+   */
+  persistKey?: (key: string) => boolean;
+  /**
+   * Query identity beyond `key` (filters, sort, page size) — anything that
+   * changes the rows without changing the key. Persisted rows are kept per
+   * query, so a projection taken under other filters never hydrates; in memory
+   * a query change resets loaded pages.
+   */
+  query?: (params: TParams) => unknown;
+  /** Identity partition of memory and persisted rows. Defaults to one static scope. */
+  scope?: ReplicaScope;
+  /** Persisted copy of the replica. Omit for a memory-only replica (no first-frame paint). */
+  storage?: ReplicaStorage<TData> | ReplicaStorageFactory<TData>;
+  /**
+   * Query-cache key of the network sync, for a resource adopting an existing
+   * key that other code already revalidates by. Defaults to `replicaKeys.sync`.
+   * With a custom key, revalidate through that key — `slice.revalidate` only
+   * matches default keys.
+   */
+  syncKey?: (params: TParams) => readonly unknown[];
+  /** Bump to invalidate every persisted row written by older shapes. */
+  version: number;
+}
+declare const defineReplica: <TParams, TData, TFetched = TData, TCursor = any>(options: DefineReplicaOptions<TParams, TData, TFetched, TCursor>) => ReplicaResource<TParams, TData, TFetched, TCursor>;
+interface DefinePagedReplicaOptions<TParams, TItem, TCursor> extends Omit<DefineReplicaOptions<TParams, ReplicaPagedData<TItem, TCursor>, ReplicaPageResult<TItem, TCursor>>, 'fetcher' | 'paging' | 'storage'> {
+  /** `cursor` is `undefined` for the head page. */
+  fetchPage?: (params: TParams, cursor: TCursor | undefined) => Promise<ReplicaPageResult<TItem, TCursor>>;
+  paging: ReplicaPagingConfig<TItem, TCursor>;
+  storage?: ReplicaStorage<any> | ReplicaStorageFactory<any>;
+}
+/**
+ * A resource whose value is a paged list ({@link ReplicaPagedData}). The
+ * store view type may extend the paged shape with domain fields.
+ */
+declare const definePagedReplica: <TParams, TItem, TCursor = number, TData extends ReplicaPagedData<TItem, TCursor> = ReplicaPagedData<TItem, TCursor>>(options: DefinePagedReplicaOptions<TParams, TItem, TCursor>) => ReplicaResource<TParams, TData, ReplicaPageResult<TItem, TCursor>, TCursor>;
+/**
+ * Keys of the queries a fetch adapter runs for a replica. Hosts that sweep
+ * their query cache by prefix (e.g. "refetch everything after a restore")
+ * match on {@link REPLICA_KEY_PREFIX}.
+ */
+declare const REPLICA_KEY_PREFIX = "replica:";
+declare const replicaKeys: {
+  /** One-shot read of the persisted row for `storageKey`. */
+  hydrate: (name: string, version: number, scope: string, storageKey: string) => readonly ['replica:hydrate', string, number, string, string];
+  /** Network sync of the head of one entry. */
+  sync: (name: string, version: number, scope: string, key: string, params: unknown) => readonly ['replica:sync', string, number, string, string, unknown];
+};
+/** Match a resource's sync keys, optionally narrowed to one scope and/or entry key. */
+declare const isReplicaSyncKey: (queryKey: unknown, name: string, filter?: {
+  key?: string;
+  scope?: string;
+}) => boolean;
+/**
+ * A fixed identity partition. The default for apps without accounts; an app
+ * with sign-in passes a scope derived from the signed-in user / workspace so
+ * one browser profile never mixes two identities' rows.
+ */
+declare const staticReplicaScope: (scope?: string) => ReplicaScope;
 /** Persisted row key: one row per entry key and query. */
 declare const replicaStorageKey: (key: string, query?: string) => string;
 /**
@@ -336,71 +288,70 @@ declare const isReplicaStorageKeyOf: (storageKey: string, key: string) => boolea
 /** Deterministic JSON: sorted keys, `undefined` dropped. */
 declare const stableQueryKey: (value: unknown) => string;
 /**
- * A fixed identity partition. The default for apps without accounts; an app
- * with sign-in passes a scope derived from the signed-in user / workspace so
- * one browser profile never mixes two identities' rows.
+ * Where the confirmed value of an entry came from.
+ * - `storage`: hydrated from the persisted projection (may be stale)
+ * - `server`: confirmed by a network response
+ * - `local`: written locally before any hydrate/replace landed
+ * - `seed`: a provisional local row (e.g. a list row standing in for a detail so
+ *   an object stays resolvable). Unlike `local` it is *not* authoritative: a
+ *   persisted `storage` value may replace it on hydrate, and it never persists —
+ *   so it cannot overwrite the detail it is only standing in for.
  */
-declare const staticReplicaScope: (scope?: string) => ReplicaScope;
-/** Builds the storage of one resource from its namespace (`replica:<name>:v<version>`). */
-type ReplicaStorageFactory<TData> = (namespace: string) => ReplicaStorage<TData> | undefined;
-interface DefineReplicaOptions<TParams, TData, TFetched = TData, TCursor = any> {
-  /** Default network fetcher; a store binding may override it. */
-  fetcher?: (params: TParams, cursor?: TCursor) => Promise<TFetched>;
-  /** Entry identity inside one scope (memory bucket + persisted row). */
-  key: (params: TParams) => string;
-  name: string;
-  paging?: ReplicaPagingConfig<any, TCursor>;
+type ReplicaSource = 'local' | 'seed' | 'server' | 'storage';
+interface ReplicaPendingMutation<T> {
+  apply: (data: T) => T;
+  id: number;
   /**
-   * Bound what the resource keeps in storage. `maxEntries` caps the persisted
-   * rows (storage keys: one per entry key and query) per scope; past it the
-   * least recently used rows are evicted — their persisted row, index entry
-   * and, when nothing holds it, their memory entry. Use rows (a hydrate or a
-   * persist, including a skipped unchanged one) count as recent, and the order
-   * lives in the persisted index, so it survives reloads. A row on screen (a
-   * mounted `useSync`, see `retain`), with pending optimistic writes or a
-   * `loadMore` in flight is never evicted. Unbounded by default.
+   * Query the overlay was started under. An entry key can be reused for another
+   * query (a navigation), and an overlay only ever describes the query that
+   * created it — carrying it over would apply (and later persist) one query's
+   * row inside another.
+   */
+  query?: string;
+}
+interface ReplicaEntryMeta<T> {
+  /**
+   * Confirmed snapshot. Only kept while optimistic mutations are in flight —
+   * otherwise the view itself is the confirmed value.
    */
-  persist?: {
-    maxEntries?: number;
-  };
+  base?: T;
+  /** Params of the last hydrate/replace — what `loadMore` pages with. */
+  params?: unknown;
+  pending: ReplicaPendingMutation<T>[];
+  /** Stable query identity beyond the key (filters, page size). */
+  query?: string;
   /**
-   * Entries that never touch storage (no hydrate, no persist) — e.g. scoped
-   * buckets whose rows must not land under an ordinary entry. Defaults to all.
+   * Every write made while the entry is still a `seed`, in order — the seed
+   * writes themselves and the confirmed writes made over them. A hydrate that
+   * replaces the seed replays them onto the stored value: the seed's fresher
+   * fields (a list row's renamed title) and a confirmed edit made before
+   * storage answered both survive, instead of storage painting older values.
    */
-  persistKey?: (key: string) => boolean;
+  seedPatches?: ReplicaSeedPatch<T>[];
+  source: ReplicaSource;
+  updatedAt: number;
+}
+interface ReplicaSeedPatch<T> {
   /**
-   * Query identity beyond `key` (filters, sort, page size) — anything that
-   * changes the rows without changing the key. Persisted rows are kept per
-   * query, so a projection taken under other filters never hydrates; in memory
-   * a query change resets loaded pages.
+   * Replayed onto the stored value, so a seed write must merge the fields it
+   * owns into its input rather than ignore it (its first run sees `undefined`).
    */
-  query?: (params: TParams) => unknown;
-  /** Identity partition of memory and persisted rows. Defaults to one static scope. */
-  scope?: ReplicaScope;
-  /** Persisted copy of the replica. Omit for a memory-only replica (no first-frame paint). */
-  storage?: ReplicaStorage<TData> | ReplicaStorageFactory<TData>;
+  apply: (data: T | undefined) => T | undefined;
+  persist: boolean;
+  /** A provisional seed write: replayed, but never makes the result confirmed. */
+  seed?: boolean;
   /**
-   * Query-cache key of the network sync, for a resource adopting an existing
-   * key that other code already revalidates by. Defaults to `replicaKeys.sync`.
-   * With a custom key, revalidate through that key — `slice.revalidate` only
-   * matches default keys.
+   * Source of a seed write. A later seed of the same tag supersedes this one
+   * (since the last confirmed write), so it must carry every field this one set.
    */
-  syncKey?: (params: TParams) => readonly unknown[];
-  /** Bump to invalidate every persisted row written by older shapes. */
-  version: number;
+  tag?: string;
 }
-declare const defineReplica: <TParams, TData, TFetched = TData, TCursor = any>(options: DefineReplicaOptions<TParams, TData, TFetched, TCursor>) => ReplicaResource<TParams, TData, TFetched, TCursor>;
-interface DefinePagedReplicaOptions<TParams, TItem, TCursor> extends Omit<DefineReplicaOptions<TParams, ReplicaPagedData<TItem, TCursor>, ReplicaPageResult<TItem, TCursor>>, 'fetcher' | 'paging' | 'storage'> {
-  /** `cursor` is `undefined` for the head page. */
-  fetchPage?: (params: TParams, cursor: TCursor | undefined) => Promise<ReplicaPageResult<TItem, TCursor>>;
-  paging: ReplicaPagingConfig<TItem, TCursor>;
-  storage?: ReplicaStorage<any> | ReplicaStorageFactory<any>;
+/** Bookkeeping slot a replica keeps inside its domain store. */
+interface ReplicaState<T> {
+  entries: Record<string, ReplicaEntryMeta<T>>;
+  /** The scope every entry in memory belongs to. */
+  scope?: string;
 }
-/**
- * A resource whose value is a paged list ({@link ReplicaPagedData}). The
- * store view type may extend the paged shape with domain fields.
- */
-declare const definePagedReplica: <TParams, TItem, TCursor = number, TData extends ReplicaPagedData<TItem, TCursor> = ReplicaPagedData<TItem, TCursor>>(options: DefinePagedReplicaOptions<TParams, TItem, TCursor>) => ReplicaResource<TParams, TData, ReplicaPageResult<TItem, TCursor>, TCursor>;
 /**
  * Pure transition core of a replica. It never touches the store
  * or storage: it returns the next bookkeeping slot, the view writes the store
@@ -500,41 +451,21 @@ interface ReplicaTransition<T> {
 declare const createReplicaState: <T>() => ReplicaState<T>;
 declare const replicaReducer: <T>(state: ReplicaState<T>, action: ReplicaAction<T>, readView: (key: string) => T | undefined, now?: number) => ReplicaTransition<T>;
 /**
- * Strict read of one row (see `ReplicaStorage.getStrict`). Rejects when the
- * storage has no strict read: its `get` swallows I/O failures into a miss, so a
- * destructive pass reading through it could take an unreadable row (the index)
- * for an empty one and report success for rows it never saw.
- */
-declare const readReplicaRowStrict: <T>(storage: ReplicaStorage<T>, key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
-/**
- * Serializes writes for one projection key. A later snapshot can never be overwritten by an
- * earlier, slower IndexedDB write.
+ * How entities (e.g. topics) appear inside a non-paged resource value. Paged
+ * resources get this for free from `paging.getId`. Build one with
+ * `singleEntity` (a detail value), `arrayEntity` (a plain list) or by hand for
+ * nested shapes (grouped lists).
  */
-declare class ReplicaWriteQueue<T> {
-  #private;
-  constructor(storage: ReplicaStorage<T>);
-  /** Resolves `false` when storage rejected the delete (see `ReplicaStorage.remove`). */
-  remove: (key: ReplicaRowKey) => Promise<boolean>;
-  set: (key: ReplicaRowKey, value: ReplicaRow<T>) => Promise<boolean>;
+interface ReplicaEntityAdapter<TData, TItem> {
+  /** Whether `data` holds the entity. */
+  has: (data: TData, id: string) => boolean;
   /**
-   * Serialized read-modify-write: `fn` sees the row as of every earlier queued
-   * write for this key. Return a projection to write it, `null` to remove the
-   * row, or `undefined` to leave it untouched (a missing row stays missing).
-   *
-   * `read` picks how the row is read:
-   * - `'get'` (default): best-effort `get`, a failed read passes for a miss.
-   * - `'prefer-strict'`: `getStrict` when the storage has one, so a read failure
-   *   fails the update (resolves `false`) instead of passing for a missing row
-   *   that `fn` would then overwrite; `get` otherwise.
-   * - `'strict'`: `getStrict` only; a storage without it fails the update.
-   *   Required for destructive passes (see `readReplicaRowStrict`).
+   * Map the entity inside `data` (`fn` returning `undefined` deletes it).
+   * Return `data` itself when nothing changed, or `undefined` when the whole
+   * value goes away with the entity (a detail value).
    */
-  update: (key: ReplicaRowKey, fn: (current: ReplicaRow<T> | undefined) => ReplicaRow<T> | null | undefined, { read }?: {
-    read?: 'get' | 'prefer-strict' | 'strict';
-  }) => Promise<boolean>;
+  map: (data: TData, id: string, fn: (item: TItem) => TItem | undefined) => TData | undefined;
 }
-/** Reserved storage key of the per-scope index of persisted rows. */
-declare const REPLICA_INDEX_KEY = "__replica:index";
 /**
  * The engine's view of the host store. The engine never owns the rendered
  * value — the host does (a Zustand slice, a signal, a plain object) — it only
@@ -553,22 +484,6 @@ interface ReplicaStorePort<TData> {
   /** Materialized value of one entry, as the UI sees it. */
   read: (key: string) => TData | undefined;
 }
-/**
- * How entities (e.g. topics) appear inside a non-paged resource value. Paged
- * resources get this for free from `paging.getId`. Build one with
- * `singleEntity` (a detail value), `arrayEntity` (a plain list) or by hand for
- * nested shapes (grouped lists).
- */
-interface ReplicaEntityAdapter<TData, TItem> {
-  /** Whether `data` holds the entity. */
-  has: (data: TData, id: string) => boolean;
-  /**
-   * Map the entity inside `data` (`fn` returning `undefined` deletes it).
-   * Return `data` itself when nothing changed, or `undefined` when the whole
-   * value goes away with the entity (a detail value).
-   */
-  map: (data: TData, id: string, fn: (item: TItem) => TItem | undefined) => TData | undefined;
-}
 interface ReplicaEngineOptions<TParams, TData, TFetched> {
   /** Label prefix of host updates (devtools action names). Defaults to the resource name. */
   actionPrefix?: string;
@@ -664,7 +579,7 @@ declare const createReplicaEngine: <TParams, TData, TFetched = TData>(resource:
     persist?: boolean | undefined;
   }) => boolean;
   isMissingHead: (incoming: TFetched) => boolean;
-  loadMore: (key: string, fallbackParams?: TParams) => Promise<void>;
+  loadMore: (key: string, fallbackParams?: TParams | undefined) => Promise<void>;
   optimistic: <TResult>(key: string, apply: (data: TData) => TData, serverCall: () => Promise<TResult>, mutationOptions?: OptimisticMutationOptions<TData, TResult>) => Promise<TResult>;
   patchStoredEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => Promise<void>;
   patchStoredRows: (fn: (data: TData) => TData | null | undefined) => Promise<void>;
@@ -697,6 +612,67 @@ declare const createReplicaEngine: <TParams, TData, TFetched = TData>(resource:
   }) => boolean;
 };
 type ReplicaEngine<TParams, TData, TFetched = TData> = ReturnType<typeof createReplicaEngine<TParams, TData, TFetched>>;
+/** Concatenate in view order: forward = head first, backward = head last. */
+declare const joinPages: <TItem>(head: TItem[], rest: TItem[], direction: ReplicaPagingDirection) => TItem[];
+/** The paging config one entry reads with: `directionOf` resolved for `key`. */
+declare const pagingFor: <TItem, TCursor>(config: ReplicaPagingConfig<TItem, TCursor>, key: string) => ReplicaPagingConfig<TItem, TCursor>;
+/**
+ * Cursor to request the next page with; `null` → exhausted, `undefined` →
+ * cannot page yet. Offset views without bookkeeping (seeded by legacy code or
+ * an older persisted shape) derive it from `currentPage` / `hasMore`.
+ */
+declare const getNextPageCursor: <TItem, TCursor>(data: ReplicaPagedData<TItem, TCursor> | undefined, config: Pick<ReplicaPagingConfig<TItem, TCursor>, 'deriveCursor' | 'direction' | 'isCursorable' | 'mode'>) => TCursor | null | undefined;
+/**
+ * Fold a fresh HEAD page into the view.
+ *
+ * - First load, a query change (`reset`) or an unextended view → the head page.
+ * - Extended view, `offset` mode → keep the loaded depth: fresh head first,
+ *   then previously loaded rows not in it (shifted offsets self-heal by id).
+ * - Extended view, `cursor` mode → keep older pages only when the fresh head
+ *   still contains the join anchor and the next cursor is known; otherwise
+ *   collapse to the head page (never show a hidden gap).
+ *
+ * Client-only rows still in the view are kept on the head side.
+ */
+declare const applyHeadPage: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor> | undefined, page: ReplicaPageResult<TItem, TCursor>, options: {
+  pageSize: number;
+  reset?: boolean;
+}, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => ReplicaPagedData<TItem, TCursor>;
+/** Merge the NEXT page (fetched with `getNextPageCursor`) into the view. */
+declare const applyNextPage: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, page: ReplicaPageResult<TItem, TCursor>, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => ReplicaPagedData<TItem, TCursor>;
+/**
+ * Insert new rows on the HEAD side (a streamed message, a created topic).
+ * Cursors point at the far end, so they stay valid; offsets shift and are
+ * healed by id de-duplication on the next page merge.
+ */
+declare const insertHeadItems: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, items: TItem[], config: ReplicaPagingConfig<TItem, TCursor>) => ReplicaPagedData<TItem, TCursor>;
+/**
+ * Patch (or remove, when `fn` returns `undefined`) one row by id. Returns the
+ * same reference when the row is absent or unchanged.
+ */
+declare const mapPagedItem: <TItem, TCursor, TData extends ReplicaPagedData<TItem, TCursor>>(current: TData, id: string, fn: (item: TItem) => TItem | undefined, config: Pick<ReplicaPagingConfig<TItem>, 'getId'>) => TData;
+/** Whether a paged view holds a row. */
+declare const hasPagedItem: <TItem>(data: ReplicaPagedData<TItem, unknown> | undefined, id: string, config: Pick<ReplicaPagingConfig<TItem>, 'getId'>) => boolean;
+/** Drop every loaded page but the head (e.g. after an edit inside older history). */
+declare const collapseToHead: <TItem, TCursor>(current: ReplicaPagedData<TItem, TCursor>, config: ReplicaPagingConfig<TItem, TCursor>) => ReplicaPagedData<TItem, TCursor>;
+/**
+ * What survives a reload: whole pages from the head side, bounded by
+ * `persist.pages` and `persist.maxItems`, client-only rows and transient
+ * flags stripped. Offset views are cut at page-size boundaries so the
+ * persisted `currentPage` stays a valid offset; a cut inside a cursor page
+ * forgets the cursor (pagination resumes after the next server head page).
+ */
+declare const toPersistedPage: <TItem, TCursor, TData extends ReplicaPagedData<TItem, TCursor>>(data: TData, config: ReplicaPagingConfig<TItem, TCursor>, ctx?: ReplicaPagingContext<TItem>) => TData;
+/**
+ * The value IS one entity, or wraps one (`{ project, members }`). Deleting the
+ * entity drops the whole value.
+ */
+declare const singleEntity: <TData, TItem = TData>(getId: (item: TItem) => string, lens?: {
+  get: (data: TData) => TItem;
+  set: (data: TData, item: TItem) => TData;
+}) => ReplicaEntityAdapter<TData, TItem>;
+/** The value is a plain list of entities; deleting one filters it out. */
+declare const arrayEntity: <TItem>(getId: (item: TItem) => string) => ReplicaEntityAdapter<TItem[], TItem>;
 /** The part of a slice entity propagation needs (structural, so any slice fits). */
 interface ReplicaEntityTarget {
   beginEntityOptimistic: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => ReplicaOptimisticToken<any>[];
@@ -739,40 +715,41 @@ declare const linkReplicaEntity: <TItem>(targets: ReplicaEntityTarget[]) => {
   }) => void;
 };
 /**
- * The value IS one entity, or wraps one (`{ project, members }`). Deleting the
- * entity drops the whole value.
- */
-declare const singleEntity: <TData, TItem = TData>(getId: (item: TItem) => string, lens?: {
-  get: (data: TData) => TItem;
-  set: (data: TData, item: TItem) => TData;
-}) => ReplicaEntityAdapter<TData, TItem>;
-/** The value is a plain list of entities; deleting one filters it out. */
-declare const arrayEntity: <TItem>(getId: (item: TItem) => string) => ReplicaEntityAdapter<TItem[], TItem>;
-/**
- * Keys of the queries a fetch adapter runs for a replica. Hosts that sweep
- * their query cache by prefix (e.g. "refetch everything after a restore")
- * match on {@link REPLICA_KEY_PREFIX}.
+ * Strict read of one row (see `ReplicaStorage.getStrict`). Rejects when the
+ * storage has no strict read: its `get` swallows I/O failures into a miss, so a
+ * destructive pass reading through it could take an unreadable row (the index)
+ * for an empty one and report success for rows it never saw.
  */
-declare const REPLICA_KEY_PREFIX = "replica:";
-declare const replicaKeys: {
-  /** One-shot read of the persisted row for `storageKey`. */
-  hydrate: (name: string, version: number, scope: string, storageKey: string) => readonly ['replica:hydrate', string, number, string, string];
-  /** Network sync of the head of one entry. */
-  sync: (name: string, version: number, scope: string, key: string, params: unknown) => readonly ['replica:sync', string, number, string, string, unknown];
-};
-/** Match a resource's sync keys, optionally narrowed to one scope and/or entry key. */
-declare const isReplicaSyncKey: (queryKey: unknown, name: string, filter?: {
-  key?: string;
-  scope?: string;
-}) => boolean;
+declare const readReplicaRowStrict: <T>(storage: ReplicaStorage<T>, key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
 /**
- * Resolve once `promise` settles or `ms` elapses — never rejects, never hangs.
- *
- * Bounds a pre-paint hydrate in a route loader: the persisted read is usually
- * sub-millisecond, and the deadline only fires on a pathological storage stall,
- * so a route transition never waits longer than `ms` for it.
+ * Serializes writes for one projection key. A later snapshot can never be overwritten by an
+ * earlier, slower IndexedDB write.
  */
-declare const settleWithin: (promise: Promise<unknown>, ms: number) => Promise<void>;
+declare class ReplicaWriteQueue<T> {
+  #private;
+  constructor(storage: ReplicaStorage<T>);
+  /** Resolves `false` when storage rejected the delete (see `ReplicaStorage.remove`). */
+  remove: (key: ReplicaRowKey) => Promise<boolean>;
+  set: (key: ReplicaRowKey, value: ReplicaRow<T>) => Promise<boolean>;
+  /**
+   * Serialized read-modify-write: `fn` sees the row as of every earlier queued
+   * write for this key. Return a projection to write it, `null` to remove the
+   * row, or `undefined` to leave it untouched (a missing row stays missing).
+   *
+   * `read` picks how the row is read:
+   * - `'get'` (default): best-effort `get`, a failed read passes for a miss.
+   * - `'prefer-strict'`: `getStrict` when the storage has one, so a read failure
+   *   fails the update (resolves `false`) instead of passing for a missing row
+   *   that `fn` would then overwrite; `get` otherwise.
+   * - `'strict'`: `getStrict` only; a storage without it fails the update.
+   *   Required for destructive passes (see `readReplicaRowStrict`).
+   */
+  update: (key: ReplicaRowKey, fn: (current: ReplicaRow<T> | undefined) => ReplicaRow<T> | null | undefined, { read }?: {
+    read?: 'get' | 'prefer-strict' | 'strict';
+  }) => Promise<boolean>;
+}
+/** Reserved storage key of the per-scope index of persisted rows. */
+declare const REPLICA_INDEX_KEY = "__replica:index";
 /**
  * The entry storage keys this resource has a persisted row for in the active
  * scope, oldest first.
@@ -788,6 +765,14 @@ declare const settleWithin: (promise: Promise<unknown>, ms: number) => Promise<v
  * `query` unset.
  */
 declare const readReplicaStoredKeys: (resource: Pick<ReplicaResource<any, any, any>, 'scope' | 'storage'>) => Promise<string[]>;
+/**
+ * Resolve once `promise` settles or `ms` elapses — never rejects, never hangs.
+ *
+ * Bounds a pre-paint hydrate in a route loader: the persisted read is usually
+ * sub-millisecond, and the deadline only fires on a pathological storage stall,
+ * so a route transition never waits longer than `ms` for it.
+ */
+declare const settleWithin: (promise: Promise<unknown>, ms: number) => Promise<void>;
 /**
  * An async key-value store a replica can persist into: an IndexedDB object
  * store, a SQLite table behind IPC, a `Map` in tests. Values are stored as
@@ -867,5 +852,5 @@ declare class LocalStorageReplicaStorage<T> implements ReplicaStorage<T> {
    */
   set: (key: ReplicaRowKey, row: ReplicaRow<T>) => Promise<void>;
 }
-export { ReplicaPageInfo as $, ReplicaTransition as A, replicaStorageKey as B, ReplicaStorePort as C, readReplicaRowStrict as D, ReplicaWriteQueue as E, DefineReplicaOptions as F, ReplicaResource as G, staticReplicaScope as H, ReplicaStorageFactory as I, ReplicaScope as J, ReplicaRow as K, definePagedReplica as L, createReplicaState as M, replicaReducer as N, ReplicaAction as O, DefinePagedReplicaOptions as P, ReplicaStorage as Q, defineReplica as R, ReplicaOptimisticToken as S, REPLICA_INDEX_KEY as T, ReplicaEntryMeta as U, stableQueryKey as V, ReplicaPendingMutation as W, ReplicaSource as X, ReplicaSeedPatch as Y, ReplicaState as Z, OptimisticMutationOptions as _, KeyValueReplicaStorageOptions as a, ReplicaPagingMode as at, ReplicaEntityAdapter as b, readReplicaStoredKeys as c, collapseToHead as ct, isReplicaSyncKey as d, insertHeadItems as dt, ReplicaPageResult as et, replicaKeys as f, joinPages as ft, linkReplicaEntity as g, ReplicaEntityTarget as h, toPersistedPage as ht, KeyValueReplicaStorage as i, ReplicaPagingDirection as it, ReplicaViewWrite as j, ReplicaEffect as k, settleWithin as l, getNextPageCursor as lt, singleEntity as m, pagingFor as mt, LocalStorageReplicaStorageOptions as n, ReplicaPagingConfig as nt, ReplicaKeyValueStore as o, applyHeadPage as ot, arrayEntity as p, mapPagedItem as pt, ReplicaRowKey as q, ReplicaRowCodec as r, ReplicaPagingContext as rt, replicaRowStoreKey as s, applyNextPage as st, LocalStorageReplicaStorage as t, ReplicaPagedData as tt, REPLICA_KEY_PREFIX as u, hasPagedItem as ut, ReplicaEngine as v, createReplicaEngine as w, ReplicaHeadOutcome as x, ReplicaEngineOptions as y, isReplicaStorageKeyOf as z };
-//# sourceMappingURL=index-CFbCHM7Q.d.ts.map
+export { DefinePagedReplicaOptions as $, ReplicaEngineOptions as A, replicaReducer as B, joinPages as C, ReplicaEngine as D, toPersistedPage as E, ReplicaAction as F, ReplicaState as G, ReplicaPendingMutation as H, ReplicaEffect as I, stableQueryKey as J, isReplicaStorageKeyOf as K, ReplicaTransition as L, ReplicaOptimisticToken as M, ReplicaStorePort as N, createReplicaEngine as O, ReplicaEntityAdapter as P, replicaKeys as Q, ReplicaViewWrite as R, insertHeadItems as S, pagingFor as T, ReplicaSeedPatch as U, ReplicaEntryMeta as V, ReplicaSource as W, REPLICA_KEY_PREFIX as X, staticReplicaScope as Y, isReplicaSyncKey as Z, applyHeadPage as _, KeyValueReplicaStorageOptions as a, ReplicaScope as at, getNextPageCursor as b, settleWithin as c, ReplicaPagedData as ct, ReplicaWriteQueue as d, ReplicaPagingDirection as dt, DefineReplicaOptions as et, readReplicaRowStrict as f, ReplicaPagingMode as ft, singleEntity as g, arrayEntity as h, ReplicaStorage as ht, KeyValueReplicaStorage as i, ReplicaResource as it, ReplicaHeadOutcome as j, OptimisticMutationOptions as k, readReplicaStoredKeys as l, ReplicaPagingConfig as lt, linkReplicaEntity as m, ReplicaRowKey as mt, LocalStorageReplicaStorageOptions as n, definePagedReplica as nt, ReplicaKeyValueStore as o, ReplicaPageInfo as ot, ReplicaEntityTarget as p, ReplicaRow as pt, replicaStorageKey as q, ReplicaRowCodec as r, defineReplica as rt, replicaRowStoreKey as s, ReplicaPageResult as st, LocalStorageReplicaStorage as t, ReplicaStorageFactory as tt, REPLICA_INDEX_KEY as u, ReplicaPagingContext as ut, applyNextPage as v, mapPagedItem as w, hasPagedItem as x, collapseToHead as y, createReplicaState as z };
+//# sourceMappingURL=index-DsElitHD.d.ts.map