local-replica 0.0.0 → 0.0.1

package/dist/index-CFbCHM7Q.d.ts

@@ -0,0 +1,871 @@
+/**
+ * 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.
+ */
+type ReplicaPagingMode = 'cursor' | 'offset';
+type ReplicaPagingDirection = 'backward' | 'forward';
+interface ReplicaPagingConfig<TItem, TCursor = any> {
+  /**
+   * Cursor mode: cursor to the page past `item`, the last cursor-eligible row
+   * on the far side, for a server that pages by row but reports no
+   * `nextCursor` (a plain list). Only safe when the row carries a lossless
+   * position; omit it when the server owns the cursor, and paging then waits
+   * for one.
+   */
+  deriveCursor?: (item: TItem) => TCursor;
+  direction: ReplicaPagingDirection;
+  /**
+   * Per-entry direction, for a resource whose entries read differently (a
+   * transcript read from its first round). Defaults to `direction`. Persisting
+   * an entry always uses `direction`, so keep such entries in memory.
+   */
+  directionOf?: (key: string) => ReplicaPagingDirection;
+  getId: (item: TItem) => string;
+  /**
+   * Rows that may anchor a join or derive a cursor. Synthetic rows the query
+   * injects (group / summary nodes) have no position of their own on the
+   * server, so they are skipped. Defaults to every row.
+   */
+  isCursorable?: (item: TItem) => boolean;
+  mode: ReplicaPagingMode;
+  /** Which part survives a reload. Defaults to the head page only. */
+  persist?: {
+    /** Hard cap on persisted items (taken from the head side). */
+    maxItems?: number;
+    /** Number of pages from the head side. Default 1. */
+    pages?: number;
+  };
+  /**
+   * Optional total order re-applied after every merge (e.g. messages by
+   * createdAt). The sort is stable: rows the comparator ties keep the order
+   * the server sent them in, so compare positions only — an id tie-break
+   * would reorder rows created within the same tick.
+   */
+  sort?: (a: TItem, b: TItem) => number;
+}
+interface ReplicaPageResult<TItem, TCursor> {
+  items: TItem[];
+  /**
+   * Cursor mode: next page cursor; `null` = exhausted, `undefined` = unknown.
+   * Offset mode: the server's own verdict — `null` = exhausted, any other
+   * value = more pages (the engine still advances by page index); `undefined`
+   * falls back to `total` / a full page. A server that filters rows after
+   * paging returns short pages that are not the end, so it must report this.
+   */
+  nextCursor?: TCursor | null;
+  total?: number;
+}
+interface ReplicaPageInfo<TCursor> {
+  /** Items this page contributed after de-duplication. */
+  count: number;
+  /** Cursor of the page after this one; `null` = exhausted, `undefined` = unknown. */
+  next?: TCursor | null;
+}
+/**
+ * The paged view a resource keeps in the store. Domain views extend it, so
+ * selectors read `items` / `hasMore` / `isLoadingMore` as before.
+ */
+interface ReplicaPagedData<TItem, TCursor = number> {
+  /**
+   * Boundary row of the head page once more pages are loaded (forward: its
+   * last row, backward: its first row). A refreshed head page that no longer
+   * contains it has slid past the loaded pages — merging would hide a gap.
+   */
+  anchorId?: string;
+  /** Index of the last merged page (0 = head only). */
+  currentPage: number;
+  hasMore: boolean;
+  /**
+   * Synthetic (non-cursorable) rows of the head page. A sort can place them
+   * among older pages, so a head refresh drops them by id rather than by
+   * position — the fresh head brings its own.
+   */
+  headSyntheticIds?: string[];
+  isLoadingMore?: boolean;
+  items: TItem[];
+  loadMoreError?: unknown;
+  /** Cursor for the next page (offset: page index). `null` = exhausted. */
+  nextCursor?: TCursor | null;
+  /** Per-page bookkeeping, head first. Missing on legacy data = one page. */
+  pages?: ReplicaPageInfo<TCursor>[];
+  pageSize: number;
+  total?: number;
+}
+interface ReplicaPagingContext<TItem> {
+  /**
+   * Client-only rows (optimistic inserts whose server row may not exist yet).
+   * They survive head refreshes and are never persisted.
+   */
+  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
+ * while the scope is still an optimistic guess (identity not resolved yet).
+ */
+interface ReplicaScope {
+  /**
+   * Whether this runtime may read the persisted projection back into memory.
+   * Defaults to `true`. A surface that never resolves an identity (e.g. a
+   * public embed that does not mount the user store) opts out: its scope is
+   * only the last-known guess, so hydrating it could paint a different — or a
+   * since-invalidated — session's private rows before authorization is checked.
+   */
+  canHydrate?: () => boolean;
+  canPersist: () => boolean;
+  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>;
+  key: (params: TParams) => string;
+  /** Cap of persisted rows per scope (LRU eviction, see `DefineReplicaOptions.persist`). */
+  maxPersistedEntries?: number;
+  name: string;
+  /** Storage namespace — `name` + `version`, so a version bump orphans old rows. */
+  namespace: string;
+  /** Present on paged resources (`definePagedReplica`). */
+  paging?: ReplicaPagingConfig<any, TCursor>;
+  /** Whether the resource survives a reload (it has a storage). */
+  persisted: boolean;
+  /** Whether an entry key may be hydrated and persisted (see `persistKey`). */
+  persistKey: (key: string) => boolean;
+  /**
+   * Query identity beyond `key` (filters, page size). Persisted rows are
+   * stored per query, so a different query never hydrates; in memory a query
+   * change resets loaded pages.
+   */
+  query: (params: TParams) => string | undefined;
+  scope: ReplicaScope;
+  storage?: ReplicaStorage<TData>;
+  /** Row key in `storage` for these params (`key`, plus `?query` when set). */
+  storageKey: (params: TParams) => string;
+  /** Custom query-cache key of the network sync (see `DefineReplicaOptions.syncKey`). */
+  syncKey?: (params: TParams) => readonly unknown[];
+  version: number;
+}
+/** Persisted row key: one row per entry key and query. */
+declare const replicaStorageKey: (key: string, query?: string) => string;
+/**
+ * Whether `storageKey` is a persisted row of entry `key`, under any query.
+ *
+ * Entry keys are free-form, so a `?` prefix alone cannot tell `foo` + a query
+ * from a plain entry `foo?bar`. A row only counts as a variant when it is
+ * exactly `replicaStorageKey(key, query)` for a query this module could have
+ * written: the rest after `key?` must be a canonical `stableQueryKey` (it
+ * parses as JSON and serializes back to itself). Row keys and the index keep
+ * their existing flat format, so rows already persisted on devices match the
+ * same way.
+ */
+declare const isReplicaStorageKeyOf: (storageKey: string, key: string) => boolean;
+/** 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.
+ */
+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>;
+  /**
+   * 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>;
+/**
+ * Pure transition core of a replica. It never touches the store
+ * or storage: it returns the next bookkeeping slot, the view writes the store
+ * binding must apply, and the persistence effects it must run.
+ *
+ * The VIEW (what selectors read) lives in the domain store, wherever the
+ * binding's lens puts it. The reducer only reads it through `readView`, so a
+ * domain can keep its existing state shape (e.g. `topicDataMap`).
+ */
+type ReplicaAction<T> = {
+  data: T;
+  key: string;
+  /**
+   * Repaint a slot that answers a *different* query from the persisted page
+   * (a navigation). Only the caller that knows the entry has moved on
+   * (the requested query changed) may ask for it; by default a hydrate only
+   * fills an empty slot.
+   */
+  overwrite?: boolean;
+  params?: unknown;
+  query?: string;
+  scope: string;
+  type: 'hydrate';
+  updatedAt?: number;
+} | {
+  /** Receives the confirmed value (base or view); `undefined` keeps it. */
+  data: (confirmed: T | undefined) => T | undefined;
+  key: string;
+  params?: unknown;
+  query?: string;
+  scope: string;
+  type: 'replace';
+} | {
+  apply: (data: T | undefined) => T | undefined;
+  key: string;
+  persist: boolean;
+  scope: string;
+  /** Marks a provisional write (`'seed'`); defaults to the entry's own source. */
+  source?: ReplicaSource;
+  /**
+   * Seed writes of one source (a list refresh, a session refresh). A later
+   * seed write supersedes an earlier one of the same tag since the last
+   * confirmed write, so a remembered seed history stays bounded.
+   */
+  seedTag?: string;
+  type: 'update';
+} | {
+  apply: (data: T) => T;
+  id: number;
+  key: string;
+  /** Query the overlay is started under (see `ReplicaPendingMutation`). */
+  query?: string;
+  scope: string;
+  type: 'optimistic';
+} | {
+  confirm?: (data: T) => T;
+  id: number;
+  key: string;
+  scope: string;
+  type: 'commit';
+} | {
+  id: number;
+  key: string;
+  scope: string;
+  type: 'rollback';
+} | {
+  key: string;
+  scope: string;
+  type: 'remove';
+} | {
+  scope: string;
+  type: 'resetScope';
+};
+type ReplicaEffect<T> = {
+  data: T;
+  key: string;
+  query?: string;
+  scope: string;
+  type: 'persist';
+} | {
+  key: string;
+  query?: string;
+  scope: string;
+  type: 'remove';
+};
+type ReplicaViewWrite<T> = {
+  data: T | undefined;
+  key: string;
+} | {
+  type: 'clear';
+};
+interface ReplicaTransition<T> {
+  effects: ReplicaEffect<T>[];
+  state: ReplicaState<T>;
+  writes: ReplicaViewWrite<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.
+ */
+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 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
+ * reads entries through `read` and hands every transition to `commit`.
+ */
+interface ReplicaStorePort<TData> {
+  /**
+   * Apply the view writes and the next bookkeeping slot as ONE host update, so
+   * subscribers never observe a view out of step with its bookkeeping.
+   */
+  commit: (writes: ReplicaViewWrite<TData>[], state: ReplicaState<TData>, label: string) => void;
+  /** Current bookkeeping slot. */
+  getState: () => ReplicaState<TData>;
+  /** Enumerate loaded keys (entity propagation). Defaults to the bookkeeping entries. */
+  keys?: () => string[];
+  /** 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;
+  /** Non-paged resources: how entities sit in the value (see `linkReplicaEntity`). */
+  entity?: ReplicaEntityAdapter<TData, any>;
+  /** Overrides `resource.fetcher` when the fetch needs store context. */
+  fetcher?: (params: TParams, cursor?: any) => Promise<TFetched>;
+  /** Paged: rows that only exist client-side (kept across refreshes, never persisted). */
+  isClientOnly?: (item: any) => boolean;
+  /** Reject a persisted value that cannot serve these params. Rarely needed: rows are stored per query. */
+  isHydratable?: (cached: TData, params: TParams) => boolean;
+  /**
+   * Non-paged: whether a head response means the entry no longer exists. Such a
+   * response is applied as an explicit removal (memory + persisted row) instead
+   * of through `merge` — otherwise a `null` would fall back to the confirmed
+   * value (the reducer resolves `action.data(confirmed) ?? confirmed`), so a
+   * deleted aggregate would be retained and re-persisted.
+   */
+  isMissing?: (incoming: TFetched) => boolean;
+  /**
+   * Non-paged: fold a server response into the confirmed value. Return
+   * `undefined` to keep the current value. Defaults to "the response is the value".
+   */
+  merge?: (incoming: TFetched, confirmed: TData | undefined, params: TParams) => TData | undefined;
+  /** Where the engine reads and commits the view. */
+  port: ReplicaStorePort<TData>;
+  /**
+   * Reconcile a server response with the value currently shown before it is
+   * folded in — e.g. keep a row the client knows is newer, or ignore a
+   * response that raced a newer local state. Return `undefined` to drop the
+   * response entirely.
+   */
+  prepareHead?: (incoming: TFetched, current: TData | undefined, params: TParams) => TFetched | undefined;
+  /** Re-run the network sync of one entry (or all); wired by the fetch adapter. */
+  revalidate?: (key?: string) => Promise<unknown>;
+  /**
+   * Strip transient / client-only parts before persisting.
+   *
+   * - a value → persisted
+   * - `undefined` → skip this write (keep whatever is already stored)
+   * - `null` → the entry is a server-confirmed absence: drop any prior
+   *   persisted projection, so a later hydrate cannot paint a value the server
+   *   no longer has (the view keeps the confirmed value).
+   */
+  toPersisted?: (data: TData) => TData | null | undefined;
+  /** Paged: domain fields derived from params, written with every head page. */
+  viewFields?: (params: TParams) => Partial<TData>;
+}
+/** What a head response did once folded in (see `applyHead`). */
+type ReplicaHeadOutcome = 'dropped' | 'missing' | 'replaced';
+interface OptimisticMutationOptions<TData, TResult> {
+  /** Turn the server result into the confirmed value; defaults to re-applying `apply`. */
+  confirm?: (result: TResult) => (data: TData) => TData;
+  /** Revalidate the entry after the server call settles. */
+  revalidate?: boolean;
+}
+/** Handle of an optimistic overlay that is settled later (see `beginOptimistic`). */
+interface ReplicaOptimisticToken<TData> {
+  commit: (confirm?: (data: TData) => TData) => void;
+  rollback: () => void;
+}
+/**
+ * The replica engine: every transition of one resource, independent of any
+ * UI framework or state library.
+ *
+ * It owns hydrate-if-empty, server replace, pagination, optimistic overlays
+ * with commit/rollback, entity propagation, scope isolation and serialized
+ * persistence. The host store keeps the rendered value (see
+ * {@link ReplicaStorePort}); fetch scheduling (when to sync, dedupe, focus
+ * revalidation) belongs to an adapter such as `local-replica/zustand`.
+ */
+declare const createReplicaEngine: <TParams, TData, TFetched = TData>(resource: ReplicaResource<TParams, TData, TFetched>, options: ReplicaEngineOptions<TParams, TData, TFetched>) => {
+  applyHead: (params: TParams, fetched: TFetched, scope?: string) => {
+    changed: boolean;
+    outcome: ReplicaHeadOutcome;
+  };
+  beginEntityOptimistic: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => ReplicaOptimisticToken<TData>[];
+  beginOptimistic: (key: string, apply: (data: TData) => TData, query?: string) => ReplicaOptimisticToken<TData>;
+  clear: () => Promise<boolean>;
+  clearGeneration: (scope: string) => number;
+  clearScope: (scope: string) => Promise<boolean>;
+  removalGeneration: (scope: string, key: string) => number;
+  collapse: (key: string) => boolean;
+  dispatch: (action: ReplicaAction<TData>) => boolean;
+  ensureScope: (scope: string) => void;
+  entityKeys: (id: string) => string[];
+  fetcher: ((params: TParams, cursor?: any) => Promise<TFetched>) | undefined;
+  getConfirmed: (key: string) => TData | undefined;
+  hydrate: (params: TParams, scope?: string, { overwrite }?: {
+    overwrite?: boolean;
+  }) => Promise<boolean>;
+  insertHead: <TItem>(key: string, items: TItem[], { persist }?: {
+    persist?: boolean | undefined;
+  }) => boolean;
+  isMissingHead: (incoming: TFetched) => boolean;
+  loadMore: (key: string, fallbackParams?: TParams) => 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>;
+  persist: (key: string) => void;
+  remove: (key: string, scope?: string) => boolean;
+  removeEntity: (id: string, options?: {
+    persist?: boolean;
+    scope?: string;
+  } | undefined) => void;
+  replace: (params: TParams, fetched: TFetched, scope?: string) => boolean;
+  resource: ReplicaResource<TParams, TData, TFetched, any>;
+  retain: (key: string, queryKey?: string) => () => void;
+  revalidate: (key?: string) => Promise<unknown>;
+  update: (key: string, apply: (data: TData | undefined) => TData | undefined, { persist, seedTag, source }?: {
+    persist?: boolean;
+    seedTag?: string;
+    source?: ReplicaSource;
+  }) => boolean;
+  updateEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined, options?: {
+    persist?: boolean;
+    scope?: string;
+  } | undefined) => void;
+  updateMany: (entries: {
+    apply: (data: TData | undefined) => TData | undefined;
+    key: string;
+  }[], { persist, seedTag, source }?: {
+    persist?: boolean;
+    seedTag?: string;
+    source?: ReplicaSource;
+  }) => boolean;
+};
+type ReplicaEngine<TParams, TData, TFetched = TData> = ReturnType<typeof createReplicaEngine<TParams, TData, TFetched>>;
+/** 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>[];
+  /** Wipe the resource in the active scope (memory + every persisted row). */
+  clear?: () => Promise<boolean>;
+  /** Patch persisted rows whose entry is not loaded in memory. */
+  patchStoredEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined) => Promise<void>;
+  /**
+   * Explicit entity removal that also guards later hydrates. Optional for
+   * custom targets; `linkReplicaEntity` falls back to `updateEntity`.
+   */
+  removeEntity?: (id: string, options?: {
+    persist?: boolean;
+    scope?: string;
+  }) => void;
+  revalidate: (key?: string) => Promise<unknown>;
+  updateEntity: <TItem>(id: string, fn: (item: TItem) => TItem | undefined, options?: {
+    persist?: boolean;
+  }) => void;
+}
+/**
+ * Link resources that hold copies of the same entity (e.g. a topic in the
+ * sidebar list, the management page and the detail cache).
+ *
+ * Each resource keeps exactly one store location and decides how the entity
+ * maps into its own shape (paged resources by `getId`, single-entity ones by
+ * their entity adapter). The link only fans an entity-level change out to the
+ * resources that currently hold it — no global event bus, no shared owner.
+ */
+declare const linkReplicaEntity: <TItem>(targets: ReplicaEntityTarget[]) => {
+  clear: () => Promise<boolean>;
+  optimistic: <TResult>(id: string, fn: ((item: TItem) => TItem) | 'remove', serverCall: () => Promise<TResult>) => Promise<TResult>;
+  remove: (id: string, options?: {
+    persist?: boolean;
+    scope?: string;
+  }) => void;
+  revalidate: () => Promise<unknown[]>;
+  update: (id: string, fn: (item: TItem) => TItem, options?: {
+    persist?: boolean;
+  }) => 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}.
+ */
+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;
+/**
+ * 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>;
+/**
+ * The entry storage keys this resource has a persisted row for in the active
+ * scope, oldest first.
+ *
+ * Storage has no key listing of its own; the engine keeps one index row per
+ * scope (`REPLICA_INDEX_KEY`) as it persists and drops entries, and this reads
+ * it. That is how code outside the owning store reaches rows an *earlier
+ * session* wrote — bounding how many survive a reload, or invalidating a row
+ * whose entry is not loaded in memory.
+ *
+ * The keys are storage keys (`key`, plus `?query` when the resource sets one),
+ * so a caller only matches them against entry keys when the resource leaves
+ * `query` unset.
+ */
+declare const readReplicaStoredKeys: (resource: Pick<ReplicaResource<any, any, any>, 'scope' | 'storage'>) => Promise<string[]>;
+/**
+ * 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
+ * given (structured clone), so the store decides what it can hold.
+ */
+interface ReplicaKeyValueStore {
+  /** Rejects when the delete did not land. A missing key is a success. */
+  delete: (key: string) => Promise<void>;
+  /** Rejects when the read failed; resolves `undefined` for a missing key. */
+  get: (key: string) => Promise<unknown>;
+  /** Opens the store; awaited before every operation. */
+  initialize?: () => Promise<void>;
+  /** Rejects when the write did not land. */
+  set: (key: string, value: unknown) => Promise<void>;
+}
+interface KeyValueReplicaStorageOptions {
+  /** Prefix of every row of this storage, usually the resource name. */
+  namespace: string;
+  store: ReplicaKeyValueStore;
+}
+/** Store key of one row: `<namespace>:<scope>:<queryKey>`, each part URI-encoded but the namespace. */
+declare const replicaRowStoreKey: (namespace: string, { queryKey, scope }: ReplicaRowKey) => string;
+/** {@link ReplicaStorage} over an async key-value store, one record per row. */
+declare class KeyValueReplicaStorage<T> implements ReplicaStorage<T> {
+  #private;
+  constructor({ namespace, store }: KeyValueReplicaStorageOptions);
+  get: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /** Like `get`, but rejects when the row could not be read (see `ReplicaStorage.getStrict`). */
+  getStrict: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /**
+   * Rejects when the delete did not land, unlike reads: a caller that removes a
+   * row the user deleted must be able to retry it.
+   */
+  remove: (key: ReplicaRowKey) => Promise<void>;
+  /**
+   * Rejects when the write did not land (see `ReplicaStorage.set`): the replica
+   * engine only treats a row as holding a value after a confirmed write, so a
+   * dropped write is retried by the next persist instead of being skipped as
+   * redundant.
+   */
+  set: (key: ReplicaRowKey, row: ReplicaRow<T>) => Promise<void>;
+}
+/** Turns a row into the string `localStorage` holds, and back. */
+interface ReplicaRowCodec<T> {
+  parse: (value: string) => ReplicaRow<T>;
+  stringify: (row: ReplicaRow<T>) => string;
+}
+interface LocalStorageReplicaStorageOptions<T> {
+  /** Defaults to JSON. Pass a richer codec (e.g. superjson) for `Date`, `Map` … */
+  codec?: ReplicaRowCodec<T>;
+  /** Prefix of every row of this storage, usually the resource name. */
+  namespace: string;
+}
+/**
+ * {@link ReplicaStorage} over `window.localStorage`. Small values only (the
+ * origin shares a ~5 MB quota), but the read is synchronous: `getSync` restores
+ * a row inside pre-paint initialization without yielding a frame. Outside a
+ * browser every operation is a no-op miss.
+ */
+declare class LocalStorageReplicaStorage<T> implements ReplicaStorage<T> {
+  #private;
+  constructor({ codec, namespace }: LocalStorageReplicaStorageOptions<T>);
+  get: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /** Restore a row inside pre-paint initialization without yielding a frame. */
+  getSync: (key: ReplicaRowKey) => ReplicaRow<T> | undefined;
+  /** Like `get`, but rejects when the row could not be read or parsed (see `ReplicaStorage.getStrict`). */
+  getStrict: (key: ReplicaRowKey) => Promise<ReplicaRow<T> | undefined>;
+  /**
+   * Rejects when the delete did not land (e.g. storage access denied), unlike
+   * reads: a caller removing a row the user deleted must be able to retry it.
+   */
+  remove: (key: ReplicaRowKey) => Promise<void>;
+  /**
+   * Rejects when the write did not land (a quota error, see `ReplicaStorage.set`):
+   * the replica engine only treats a row as holding a value after a confirmed
+   * write.
+   */
+  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