local-replica 0.0.1 → 0.0.3

package/dist/{keys-BTsqwfEa.js → createReplicaEngine-CdR-URHo.js}

@@ -1,5 +1,5 @@
 import isEqual from "fast-deep-equal";
-// src/core/defineReplica.ts
+// src/core/resource/storageKey.ts
 /** Persisted row key: one row per entry key and query. */
 const replicaStorageKey = (key, query) => query ? `${key}?${query}` : key;
 /**
@@ -25,47 +25,50 @@ const isReplicaStorageKeyOf = (storageKey, key) => {
 };
 /** Deterministic JSON: sorted keys, `undefined` dropped. */
 const stableQueryKey = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.keys(item).sort().filter((key) => item[key] !== void 0).map((key) => [key, item[key]])) : item) ?? "";
+// src/core/resource/queryKeys.ts
 /**
-* 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.
+* 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}.
 */
-const staticReplicaScope = (scope = "default") => ({
-	canPersist: () => true,
-	get: () => scope,
-	use: () => scope
-});
-const DEFAULT_SCOPE = staticReplicaScope();
-const defineReplica = (options) => {
-	const namespace = `replica:${options.name}:v${options.version}`;
-	const storage = typeof options.storage === "function" ? options.storage(namespace) : options.storage;
-	return {
-		fetcher: options.fetcher,
-		key: options.key,
-		maxPersistedEntries: options.persist?.maxEntries,
-		name: options.name,
-		namespace,
-		paging: options.paging,
-		persistKey: options.persistKey ?? (() => true),
-		persisted: !!storage,
-		query: (params) => options.query ? stableQueryKey(options.query(params)) : void 0,
-		storageKey: (params) => replicaStorageKey(options.key(params), options.query ? stableQueryKey(options.query(params)) : void 0),
-		scope: options.scope ?? DEFAULT_SCOPE,
-		syncKey: options.syncKey,
-		storage,
-		version: options.version
-	};
+const REPLICA_KEY_PREFIX = "replica:";
+const replicaKeys = {
+	/** One-shot read of the persisted row for `storageKey`. */
+	hydrate: (name, version, scope, storageKey) => [
+		"replica:hydrate",
+		name,
+		version,
+		scope,
+		storageKey
+	],
+	/** Network sync of the head of one entry. */
+	sync: (name, version, scope, key, params) => [
+		"replica:sync",
+		name,
+		version,
+		scope,
+		key,
+		params
+	]
 };
+/** Match a resource's sync keys, optionally narrowed to one scope and/or entry key. */
+const isReplicaSyncKey = (queryKey, name, filter = {}) => Array.isArray(queryKey) && queryKey[0] === "replica:sync" && queryKey[1] === name && (filter.scope === void 0 || queryKey[3] === filter.scope) && (filter.key === void 0 || queryKey[4] === filter.key);
+// src/core/paging/operations.ts
 /**
-* A resource whose value is a paged list ({@link ReplicaPagedData}). The
-* store view type may extend the paged shape with domain fields.
+* 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.
 */
-const definePagedReplica = (options) => defineReplica({
-	...options,
-	fetcher: options.fetchPage,
-	storage: options.storage
-});
-// src/core/paging.ts
 const dedupe = (items, getId, seen = /* @__PURE__ */ new Set()) => {
 	const out = [];
 	for (const item of items) {
@@ -395,7 +398,7 @@ const toPersistedPage = (data, config, ctx = {}) => {
 		}]
 	};
 };
-// src/core/writeQueue.ts
+// src/core/persistence/writeQueue.ts
 /**
 * 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
@@ -454,7 +457,7 @@ var ReplicaWriteQueue = class {
 		return settled;
 	};
 };
-// src/core/persistedRows.ts
+// src/core/persistence/persistedRows.ts
 /** Reserved storage key of the per-scope index of persisted rows. */
 const REPLICA_INDEX_KEY = "__replica:index";
 /** Returned by a `patchRow` transform to delete the row (`null` stays a value). */
@@ -549,8 +552,11 @@ const createPersistedRows = ({ commit, getSlot, isRemoved, loadingMore, resource
 		for (const [key, entry] of Object.entries(slot.entries)) rows.set(replicaStorageKey(key, entry.query), key);
 		return rows;
 	};
-	/** A row on screen, or whose entry has writes / a page load in flight. */
-	const isPinned = (queryKey, entryKey) => retainedRows.has(queryKey) || entryKey !== void 0 && (retainedKeys.has(entryKey) || (getSlot().entries[entryKey]?.pending.length ?? 0) > 0 || loadingMore.has(entryKey));
+	/**
+	* A row on screen, or whose entry has writes / a page load in flight.
+	* `entryKey` comes from `loadedRows`, so its entry is in the slot.
+	*/
+	const isPinned = (queryKey, entryKey) => retainedRows.has(queryKey) || entryKey !== void 0 && (retainedKeys.has(entryKey) || getSlot().entries[entryKey].pending.length > 0 || loadingMore.has(entryKey));
 	/** The oldest unpinned rows past the cap (`keys` is oldest first). */
 	const pickEvictions = (scope, keys, touched) => {
 		const going = evicting.get(scope);
@@ -621,9 +627,8 @@ const createPersistedRows = ({ commit, getSlot, isRemoved, loadingMore, resource
 			if (picked.length > 0) evictRows(scope, picked);
 		});
 	};
-	/** Record a persisted row in the index (queued after the row write). */
+	/** Record a persisted row in the index (queued after the row write; see `writeRow`). */
 	const trackStorageKey = (scope, queryKey) => {
-		if (!writeQueue) return;
 		noteWrite(scope, queryKey);
 		if (maxEntries !== void 0) return touchStorageKey(scope, queryKey);
 		const known = indexed.get(scope) ?? /* @__PURE__ */ new Set();
@@ -813,7 +818,7 @@ const createPersistedRows = ({ commit, getSlot, isRemoved, loadingMore, resource
 		writeRow
 	};
 };
-// src/core/entityPropagation.ts
+// src/core/entity/propagation.ts
 /**
 * Entity propagation: a change to one entity (e.g. a topic) applied to every
 * entry that holds it — in memory, in persisted rows memory does not hold,
@@ -982,7 +987,7 @@ const createEntityPropagation = ({ beginOptimistic, entity, entityGuards, getSlo
 		withoutRemovedEntities
 	};
 };
-// src/core/reducer.ts
+// src/core/state/reducer.ts
 const createReplicaState = () => ({ entries: {} });
 const materialize = (base, pending) => base === void 0 ? void 0 : pending.reduce((data, mutation) => mutation.apply(data), base);
 const noop = (state) => ({
@@ -1197,7 +1202,124 @@ const replicaReducer = (state, action, readView, now = Date.now()) => {
 		};
 	}
 };
-// src/core/tombstones.ts
+// src/core/engine/pagination.ts
+/**
+* The engine's paged-resource transitions: folding a head page into the loaded
+* pages, fetching the next page, head inserts and collapsing back to the head.
+* The pure page math lives in `paging/operations.ts`; this adds the entry,
+* scope and in-flight bookkeeping around it. Every method is a no-op (or a
+* pass-through) for a non-paged resource.
+*/
+const createPagination = ({ fetcher, getSlot, loadingMore, options, port, resource, update }) => {
+	const paging = resource.paging;
+	const at = (key) => pagingFor(paging, key);
+	const pagingCtx = { isClientOnly: options.isClientOnly };
+	/** The persistable part of a paged value (the value itself when not paged). */
+	const toPersisted = (data) => paging ? toPersistedPage(data, paging, pagingCtx) : data;
+	/**
+	* An overwrite hydrate repaints the entry from another query's persisted page.
+	* Client-only rows (an in-flight upload / create) have no server row yet, so
+	* that page cannot contain them — keep the ones still in the view, so a
+	* same-pool query change (a re-sort, a view-mode switch) never drops them.
+	* A cross-pool navigate is not "client-only" for the new params and is dropped.
+	*/
+	const keepClientOnlyRows = (incoming, current, key) => {
+		if (!paging || !options.isClientOnly || !current) return incoming;
+		const page = incoming;
+		const currentItems = current.items ?? [];
+		const incomingIds = new Set(page.items.map((item) => paging.getId(item)));
+		const survivors = currentItems.filter((item) => options.isClientOnly(item) && !incomingIds.has(paging.getId(item)));
+		if (survivors.length === 0) return incoming;
+		const items = joinPages(survivors, page.items, at(key).direction);
+		return {
+			...incoming,
+			items
+		};
+	};
+	const viewMatchesFields = (current, params) => {
+		const fields = options.viewFields?.(params);
+		if (!current || !fields) return true;
+		const norm = (value) => stableQueryKey(value || null);
+		return Object.entries(fields).every(([field, value]) => norm(value) === norm(current[field]));
+	};
+	const mergeHead = (key, incoming, confirmed, params, reset) => {
+		const page = incoming;
+		const pageSize = params.pageSize ?? page.items.length;
+		const merged = {
+			...applyHeadPage(confirmed, page, {
+				pageSize,
+				reset
+			}, at(key), pagingCtx),
+			...options.viewFields?.(params),
+			isLoadingMore: loadingMore.has(key)
+		};
+		const next = {
+			...confirmed,
+			...merged
+		};
+		return confirmed !== void 0 && isEqual(next, confirmed) ? void 0 : next;
+	};
+	/**
+	* Fetch and merge the next page with the params of the loaded head page
+	* (`fallbackParams` covers views seeded outside `useSync`). In `cursor` mode
+	* paging only starts from a server-confirmed head page: a hydrated cursor
+	* may be stale. A result is dropped when the scope, the query or the loaded
+	* depth changed while it was in flight.
+	*/
+	const loadMore = async (key, fallbackParams) => {
+		if (!paging || !fetcher) return;
+		const entry = getSlot().entries[key];
+		const current = port.read(key);
+		if (!current || loadingMore.has(key)) return;
+		if (paging.mode === "cursor" && entry?.source === "storage") return;
+		const params = entry?.params ?? fallbackParams;
+		if (params === void 0) return;
+		const cursor = getNextPageCursor(current, at(key));
+		if (cursor === null || cursor === void 0) return;
+		const query = entry?.query;
+		const scope = resource.scope.get();
+		const depth = current.currentPage;
+		const setLoading = (patch) => update(key, (data) => data && {
+			...data,
+			...patch
+		}, { persist: false });
+		loadingMore.add(key);
+		setLoading({
+			isLoadingMore: true,
+			loadMoreError: void 0
+		});
+		const isCurrent = () => {
+			const latest = port.read(key);
+			return resource.scope.get() === scope && getSlot().entries[key]?.query === query && latest?.currentPage === depth;
+		};
+		try {
+			const page = await fetcher(params, cursor);
+			if (!isCurrent()) return void setLoading({ isLoadingMore: false });
+			update(key, (data) => data && applyNextPage(data, page, at(key), pagingCtx), { persist: (paging.persist?.pages ?? 1) > 1 });
+		} catch (error) {
+			setLoading({
+				isLoadingMore: false,
+				loadMoreError: isCurrent() ? error : void 0
+			});
+		} finally {
+			loadingMore.delete(key);
+		}
+	};
+	/** Insert rows at the head (new / streamed items). */
+	const insertHead = (key, items, { persist = false } = {}) => paging ? update(key, (data) => data && insertHeadItems(data, items, at(key)), { persist }) : false;
+	/** Drop loaded pages, keeping the head (e.g. after an edit inside older pages). */
+	const collapse = (key) => paging ? update(key, (data) => data && collapseToHead(data, at(key)), { persist: false }) : false;
+	return {
+		collapse,
+		insertHead,
+		keepClientOnlyRows,
+		loadMore,
+		mergeHead,
+		toPersisted,
+		viewMatchesFields
+	};
+};
+// src/core/engine/tombstones.ts
 /**
 * How many removal tombstones one engine remembers. The guards exist to win a
 * race with a hydrate that started around a removal, so a modest window is
@@ -1249,7 +1371,7 @@ const createTombstones = (limit = DEFAULT_REMOVAL_TOMBSTONE_LIMIT) => {
 		size: () => tracked
 	};
 };
-// src/core/removalGuards.ts
+// src/core/engine/removalGuards.ts
 /**
 * Removal guard of one engine.
 *
@@ -1377,7 +1499,87 @@ const createEntityRemovalGuards = () => {
 		startHydrate
 	};
 };
-// src/core/engine.ts
+// src/core/engine/scopeClear.ts
+/**
+* Resource-wide clear of one scope: memory, every persisted row and reads in
+* flight. A clear bumps the scope's generation so reads started before it are
+* dropped, and records its row purge so a later hydrate waits for it.
+*/
+const createScopeClear = ({ port, prefix, resource, rows, writeQueue }) => {
+	const { deleteRows, readIndex } = rows;
+	/** Bumped by every `clear()` of a scope; reads started before it are stale. */
+	const clearGenerations = /* @__PURE__ */ new Map();
+	const clearGeneration = (scope) => clearGenerations.get(scope) ?? 0;
+	/**
+	* The persisted-row purge of the last `clear()` per scope: `true` once every
+	* row delete landed. A hydrate waits for it, and refuses to read while the
+	* purge failed (an untrusted scope, a storage error) so a wiped resource can
+	* never paint a row that survived it.
+	*/
+	const scopePurges = /* @__PURE__ */ new Map();
+	const lastPurge = (scope) => scopePurges.get(scope);
+	/**
+	* Wipe the resource in the active scope: every entry leaves memory in one
+	* host commit, every persisted row (all keys, all query variants) and the
+	* index are deleted, and reads already in flight are dropped — a hydrate
+	* started before the clear never dispatches, and `useSync` discards head
+	* responses whose request started before it. Requests started afterwards
+	* apply normally. Resolves `true` once the persisted rows are gone.
+	*/
+	const clear = () => {
+		const scope = resource.scope.get();
+		clearGenerations.set(scope, clearGeneration(scope) + 1);
+		port.commit([{ type: "clear" }], {
+			entries: {},
+			scope
+		}, `${prefix}/clear`);
+		rows.forgetScope(scope);
+		const purge = purgeScope(scope);
+		scopePurges.set(scope, purge);
+		return purge;
+	};
+	/**
+	* `clear()` for any scope, including one that is not active (a user who
+	* switched away while their data was being deleted): every persisted row of
+	* `scope` and its index go, and for the active scope memory is wiped too
+	* (exactly `clear()`). An inactive scope's memory is not on screen and is
+	* left alone. The row deletes go through the write queue, so they land after
+	* any write this session already queued for that scope — a row (or index
+	* entry) written just before is purged rather than landing after the purge.
+	* A later hydrate of `scope` waits for the purge. Resolves `true` once the
+	* persisted rows are gone.
+	*/
+	const clearScope = (scope) => {
+		if (scope === resource.scope.get()) return clear();
+		clearGenerations.set(scope, clearGeneration(scope) + 1);
+		const purge = purgeScope(scope);
+		scopePurges.set(scope, purge);
+		return purge;
+	};
+	/** Delete every persisted row of `scope` (see `clear`). */
+	const purgeScope = async (scope) => {
+		if (!writeQueue) return true;
+		if (!resource.scope.canPersist()) return false;
+		const queued = deleteRows(scope, [...rows.indexedKeys(scope) ?? []]);
+		let persisted;
+		try {
+			persisted = await readIndex(scope);
+		} catch {
+			return false;
+		}
+		const known = rows.indexedKeys(scope);
+		const stale = persisted.filter((queryKey) => !known?.has(queryKey));
+		const [first, rest] = await Promise.all([queued, deleteRows(scope, stale)]);
+		return first && rest;
+	};
+	return {
+		clear,
+		clearGeneration,
+		clearScope,
+		lastPurge
+	};
+};
+// src/core/engine/createReplicaEngine.ts
 /**
 * The replica engine: every transition of one resource, independent of any
 * UI framework or state library.
@@ -1391,8 +1593,6 @@ const createEntityRemovalGuards = () => {
 const createReplicaEngine = (resource, options) => {
 	const { port } = options;
 	const paging = resource.paging;
-	const at = (key) => pagingFor(paging, key);
-	const pagingCtx = { isClientOnly: options.isClientOnly };
 	const prefix = options.actionPrefix ?? resource.name;
 	const writeQueue = resource.storage ? new ReplicaWriteQueue(resource.storage) : void 0;
 	const fetcher = options.fetcher ?? resource.fetcher;
@@ -1401,20 +1601,10 @@ const createReplicaEngine = (resource, options) => {
 	const loadingMore = /* @__PURE__ */ new Set();
 	const { clearRemoved, isPurged, isRemoved, markPurged, markRemoved, removalGeneration } = createRemovalGuards();
 	const entityGuards = createEntityRemovalGuards();
-	/** Bumped by every `clear()` of a scope; reads started before it are stale. */
-	const clearGenerations = /* @__PURE__ */ new Map();
-	const clearGeneration = (scope) => clearGenerations.get(scope) ?? 0;
-	/**
-	* The persisted-row purge of the last `clear()` per scope: `true` once every
-	* row delete landed. A hydrate waits for it, and refuses to read while the
-	* purge failed (an untrusted scope, a storage error) so a wiped resource can
-	* never paint a row that survived it.
-	*/
-	const scopePurges = /* @__PURE__ */ new Map();
 	const getSlot = port.getState;
 	const storageKey = (key, query) => ({ queryKey: replicaStorageKey(key, query) });
 	const toPersisted = (data) => {
-		const paged = paging ? toPersistedPage(data, paging, pagingCtx) : data;
+		const paged = pagination.toPersisted(data);
 		return options.toPersisted ? options.toPersisted(paged) : paged;
 	};
 	const rows = createPersistedRows({
@@ -1428,7 +1618,14 @@ const createReplicaEngine = (resource, options) => {
 		resource,
 		writeQueue
 	});
-	const { deleteRows, readIndex, removeStoredVariants, retain, touchStorageKey } = rows;
+	const { deleteRows, removeStoredVariants, retain, touchStorageKey } = rows;
+	const { clear, clearGeneration, clearScope, lastPurge } = createScopeClear({
+		port,
+		prefix,
+		resource,
+		rows,
+		writeQueue
+	});
 	const runEffects = (effects) => {
 		if (!writeQueue || effects.length === 0) return;
 		if (!resource.scope.canPersist()) return;
@@ -1522,26 +1719,6 @@ const createReplicaEngine = (resource, options) => {
 		const entry = getSlot().entries[key];
 		return entry?.pending.length ? entry.base : port.read(key);
 	};
-	/**
-	* An overwrite hydrate repaints the entry from another query's persisted page.
-	* Client-only rows (an in-flight upload / create) have no server row yet, so
-	* that page cannot contain them — keep the ones still in the view, so a
-	* same-pool query change (a re-sort, a view-mode switch) never drops them.
-	* A cross-pool navigate is not "client-only" for the new params and is dropped.
-	*/
-	const keepClientOnlyRows = (incoming, current, key) => {
-		if (!paging || !options.isClientOnly || !current) return incoming;
-		const page = incoming;
-		const currentItems = current.items ?? [];
-		const incomingIds = new Set(page.items.map((item) => paging.getId(item)));
-		const survivors = currentItems.filter((item) => options.isClientOnly(item) && !incomingIds.has(paging.getId(item)));
-		if (survivors.length === 0) return incoming;
-		const items = joinPages(survivors, page.items, at(key).direction);
-		return {
-			...incoming,
-			items
-		};
-	};
 	const hydrate = async (params, scope = resource.scope.get(), { overwrite = false } = {}) => {
 		if (!resource.storage) return false;
 		if (resource.scope.canHydrate && !resource.scope.canHydrate()) return false;
@@ -1558,7 +1735,7 @@ const createReplicaEngine = (resource, options) => {
 	const readAndHydrate = async (params, key, scope, overwrite) => {
 		const storage = resource.storage;
 		const generation = clearGeneration(scope);
-		const purge = scopePurges.get(scope);
+		const purge = lastPurge(scope);
 		if (purge && !await purge) return false;
 		const query = resource.query(params);
 		const { queryKey } = storageKey(key, query);
@@ -1573,7 +1750,7 @@ const createReplicaEngine = (resource, options) => {
 		if (options.isHydratable && !options.isHydratable(cached.data, params)) return false;
 		const stored = withoutRemovedEntities(scope, cached.data);
 		if (stored === void 0) return false;
-		const data = overwrite ? keepClientOnlyRows(stored, port.read(key), key) : stored;
+		const data = overwrite ? pagination.keepClientOnlyRows(stored, port.read(key), key) : stored;
 		const applied = dispatch({
 			data,
 			key,
@@ -1587,31 +1764,8 @@ const createReplicaEngine = (resource, options) => {
 		if (applied && resource.scope.canPersist()) touchStorageKey(scope, queryKey);
 		return applied;
 	};
-	const viewMatchesFields = (current, params) => {
-		const fields = options.viewFields?.(params);
-		if (!current || !fields) return true;
-		const norm = (value) => stableQueryKey(value || null);
-		return Object.entries(fields).every(([field, value]) => norm(value) === norm(current[field]));
-	};
 	/** Non-paged: whether a (prepared) head response is a terminal absence (`isMissing`). */
 	const isMissingHead = (incoming) => !paging && !!options.isMissing?.(incoming);
-	const mergeHead = (key, incoming, confirmed, params, reset) => {
-		const page = incoming;
-		const pageSize = params.pageSize ?? page.items.length;
-		const merged = {
-			...applyHeadPage(confirmed, page, {
-				pageSize,
-				reset
-			}, at(key), pagingCtx),
-			...options.viewFields?.(params),
-			isLoadingMore: loadingMore.has(key)
-		};
-		const next = {
-			...confirmed,
-			...merged
-		};
-		return confirmed !== void 0 && isEqual(next, confirmed) ? void 0 : next;
-	};
 	/**
 	* Fold a head response in and report what it was: dropped by `prepareHead`,
 	* a terminal absence (`isMissing`, applied as a removal) or a replacement.
@@ -1631,9 +1785,9 @@ const createReplicaEngine = (resource, options) => {
 		};
 		const query = resource.query(params);
 		const entry = getSlot().entries[key];
-		const reset = entry ? entry.query !== query : paging !== void 0 && !viewMatchesFields(port.read(key), params);
+		const reset = entry ? entry.query !== query : paging !== void 0 && !pagination.viewMatchesFields(port.read(key), params);
 		const applied = dispatch({
-			data: (confirmed) => paging ? mergeHead(key, incoming, confirmed, params, reset) : options.merge ? options.merge(incoming, confirmed, params) : incoming,
+			data: (confirmed) => paging ? pagination.mergeHead(key, incoming, confirmed, params, reset) : options.merge ? options.merge(incoming, confirmed, params) : incoming,
 			key,
 			params,
 			query,
@@ -1747,60 +1901,6 @@ const createReplicaEngine = (resource, options) => {
 			type: "persist"
 		}]);
 	};
-	/**
-	* Wipe the resource in the active scope: every entry leaves memory in one
-	* host commit, every persisted row (all keys, all query variants) and the
-	* index are deleted, and reads already in flight are dropped — a hydrate
-	* started before the clear never dispatches, and `useSync` discards head
-	* responses whose request started before it. Requests started afterwards
-	* apply normally. Resolves `true` once the persisted rows are gone.
-	*/
-	const clear = () => {
-		const scope = resource.scope.get();
-		clearGenerations.set(scope, clearGeneration(scope) + 1);
-		port.commit([{ type: "clear" }], {
-			entries: {},
-			scope
-		}, `${prefix}/clear`);
-		rows.forgetScope(scope);
-		const purge = purgeScope(scope);
-		scopePurges.set(scope, purge);
-		return purge;
-	};
-	/**
-	* `clear()` for any scope, including one that is not active (a user who
-	* switched away while their data was being deleted): every persisted row of
-	* `scope` and its index go, and for the active scope memory is wiped too
-	* (exactly `clear()`). An inactive scope's memory is not on screen and is
-	* left alone. The row deletes go through the write queue, so they land after
-	* any write this session already queued for that scope — a row (or index
-	* entry) written just before is purged rather than landing after the purge.
-	* A later hydrate of `scope` waits for the purge. Resolves `true` once the
-	* persisted rows are gone.
-	*/
-	const clearScope = (scope) => {
-		if (scope === resource.scope.get()) return clear();
-		clearGenerations.set(scope, clearGeneration(scope) + 1);
-		const purge = purgeScope(scope);
-		scopePurges.set(scope, purge);
-		return purge;
-	};
-	/** Delete every persisted row of `scope` (see `clear`). */
-	const purgeScope = async (scope) => {
-		if (!writeQueue) return true;
-		if (!resource.scope.canPersist()) return false;
-		const queued = deleteRows(scope, [...rows.indexedKeys(scope) ?? []]);
-		let persisted;
-		try {
-			persisted = await readIndex(scope);
-		} catch {
-			return false;
-		}
-		const known = rows.indexedKeys(scope);
-		const stale = persisted.filter((queryKey) => !known?.has(queryKey));
-		const [first, rest] = await Promise.all([queued, deleteRows(scope, stale)]);
-		return first && rest;
-	};
 	const revalidate = (key) => options.revalidate ? options.revalidate(key) : Promise.resolve();
 	/**
 	* Start an optimistic overlay now and settle it later (multi-resource flows).
@@ -1857,56 +1957,16 @@ const createReplicaEngine = (resource, options) => {
 			if (mutationOptions.revalidate) revalidate(key);
 		}
 	};
-	/**
-	* Fetch and merge the next page with the params of the loaded head page
-	* (`fallbackParams` covers views seeded outside `useSync`). In `cursor` mode
-	* paging only starts from a server-confirmed head page: a hydrated cursor
-	* may be stale. A result is dropped when the scope, the query or the loaded
-	* depth changed while it was in flight.
-	*/
-	const loadMore = async (key, fallbackParams) => {
-		if (!paging || !fetcher) return;
-		const entry = getSlot().entries[key];
-		const current = port.read(key);
-		if (!current || loadingMore.has(key)) return;
-		if (paging.mode === "cursor" && entry?.source === "storage") return;
-		const params = entry?.params ?? fallbackParams;
-		if (params === void 0) return;
-		const cursor = getNextPageCursor(current, at(key));
-		if (cursor === null || cursor === void 0) return;
-		const query = entry?.query;
-		const scope = resource.scope.get();
-		const depth = current.currentPage;
-		const setLoading = (patch) => update(key, (data) => data && {
-			...data,
-			...patch
-		}, { persist: false });
-		loadingMore.add(key);
-		setLoading({
-			isLoadingMore: true,
-			loadMoreError: void 0
-		});
-		const isCurrent = () => {
-			const latest = port.read(key);
-			return resource.scope.get() === scope && getSlot().entries[key]?.query === query && latest?.currentPage === depth;
-		};
-		try {
-			const page = await fetcher(params, cursor);
-			if (!isCurrent()) return void setLoading({ isLoadingMore: false });
-			update(key, (data) => data && applyNextPage(data, page, at(key), pagingCtx), { persist: (paging.persist?.pages ?? 1) > 1 });
-		} catch (error) {
-			setLoading({
-				isLoadingMore: false,
-				loadMoreError: isCurrent() ? error : void 0
-			});
-		} finally {
-			loadingMore.delete(key);
-		}
-	};
-	/** Insert rows at the head (new / streamed items). */
-	const insertHead = (key, items, { persist = false } = {}) => paging ? update(key, (data) => data && insertHeadItems(data, items, at(key)), { persist }) : false;
-	/** Drop loaded pages, keeping the head (e.g. after an edit inside older pages). */
-	const collapse = (key) => paging ? update(key, (data) => data && collapseToHead(data, at(key)), { persist: false }) : false;
+	const pagination = createPagination({
+		fetcher,
+		getSlot,
+		loadingMore,
+		options,
+		port,
+		resource,
+		update
+	});
+	const { collapse, insertHead, loadMore } = pagination;
 	const { beginEntityOptimistic, entityKeys, forgetRestoredEntities, patchStoredEntity, removeEntity, updateEntity, withoutRemovedEntities } = createEntityPropagation({
 		beginOptimistic,
 		entity: options.entity,
@@ -1953,34 +2013,6 @@ const createReplicaEngine = (resource, options) => {
 		updateMany
 	};
 };
-// src/core/keys.ts
-/**
-* 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}.
-*/
-const REPLICA_KEY_PREFIX = "replica:";
-const replicaKeys = {
-	/** One-shot read of the persisted row for `storageKey`. */
-	hydrate: (name, version, scope, storageKey) => [
-		"replica:hydrate",
-		name,
-		version,
-		scope,
-		storageKey
-	],
-	/** Network sync of the head of one entry. */
-	sync: (name, version, scope, key, params) => [
-		"replica:sync",
-		name,
-		version,
-		scope,
-		key,
-		params
-	]
-};
-/** Match a resource's sync keys, optionally narrowed to one scope and/or entry key. */
-const isReplicaSyncKey = (queryKey, name, filter = {}) => Array.isArray(queryKey) && queryKey[0] === "replica:sync" && queryKey[1] === name && (filter.scope === void 0 || queryKey[3] === filter.scope) && (filter.key === void 0 || queryKey[4] === filter.key);
-export { isReplicaStorageKeyOf as C, staticReplicaScope as E, defineReplica as S, stableQueryKey as T, joinPages as _, DEFAULT_REMOVAL_TOMBSTONE_LIMIT as a, toPersistedPage as b, REPLICA_INDEX_KEY as c, applyHeadPage as d, applyNextPage as f, insertHeadItems as g, hasPagedItem as h, createReplicaEngine as i, ReplicaWriteQueue as l, getNextPageCursor as m, isReplicaSyncKey as n, createReplicaState as o, collapseToHead as p, replicaKeys as r, replicaReducer as s, REPLICA_KEY_PREFIX as t, readReplicaRowStrict as u, mapPagedItem as v, replicaStorageKey as w, definePagedReplica as x, pagingFor as y };
+export { stableQueryKey as S, REPLICA_KEY_PREFIX as _, ReplicaWriteQueue as a, isReplicaStorageKeyOf as b, applyNextPage as c, hasPagedItem as d, insertHeadItems as f, toPersistedPage as g, pagingFor as h, REPLICA_INDEX_KEY as i, collapseToHead as l, mapPagedItem as m, createReplicaState as n, readReplicaRowStrict as o, joinPages as p, replicaReducer as r, applyHeadPage as s, createReplicaEngine as t, getNextPageCursor as u, isReplicaSyncKey as v, replicaStorageKey as x, replicaKeys as y };
 
-//# sourceMappingURL=keys-BTsqwfEa.js.map
+//# sourceMappingURL=createReplicaEngine-CdR-URHo.js.map