@wix/himalaya-cli 0.1544.0 → 0.1546.0

package/templates/branded-lite/tier5-src/_shared/collection-query-legacy.ts

@@ -0,0 +1,194 @@
+import { initialReadStatus, type ReadStatus } from '@himalaya/state';
+
+/** Backend collection lifecycle shared by domain workers. The domain supplies
+ * the query and row mapper; this layer never calls a domain API or mutates it. */
+export interface CollectionQuery {
+  query: string;
+  filter: string;
+  sort: 'default' | 'az' | 'za';
+  savedIds: string[];
+}
+export interface CollectionPage<Row> {
+  items: Row[];
+  nextCursor: string;
+  total?: number;
+  metadata?: Record<string, unknown>;
+  complete?: boolean;
+}
+export interface CollectionQueryState<Row> extends CollectionPage<Row> {
+  criteria: CollectionQuery;
+  status: 'idle' | 'loading' | 'ready' | 'error';
+  loadingMore: boolean;
+  pageError: boolean;
+  complete: boolean;
+  error: string;
+  read: ReadStatus;
+  /** The rows are the source's `cached` page, shown while the live read is still out. */
+  provisional?: boolean;
+}
+/** What a collection showed, as `shownPage` hands it out and `seed` takes it back on a restored boot. */
+export interface CollectionShownPage<Row> {
+  state: CollectionQueryState<Row>;
+  loadedPages: number;
+}
+export interface CollectionQuerySource<Row> {
+  fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
+  /** Optional public cache for immediate paint; always incomplete, never a paging authority. */
+  cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
+  id(row: Row): string;
+  errorMessage?(error: unknown): string;
+  /** Private collections must discard prior rows when access or identity changes. A revalidation keeps the
+   *  rows it shows through any other failure: safe because one worker never serves two identities (its pool
+   *  key carries the account, and a purge tears parked workers down). */
+  clearOnError?(error: unknown): boolean;
+}
+const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
+  query: typeof q.query === 'string' ? q.query.trim().slice(0, 256) : '',
+  filter: typeof q.filter === 'string' ? q.filter.slice(0, 256) : 'all',
+  sort: q.sort === 'az' || q.sort === 'za' ? q.sort : 'default',
+  savedIds: Array.isArray(q.savedIds) ? [...new Set(q.savedIds.filter(id => typeof id === 'string' && id.length > 0 && id.length <= 256))].slice(0, 500) : [],
+});
+const copyQuery = (q: CollectionQuery): CollectionQuery => ({ ...q, savedIds: [...q.savedIds] });
+
+/** New criteria cancel the old result logically, including an in-flight next
+ * page. Failures preserve the cursor and rows for an explicit retry. Callers
+ * publish each snapshot through their ordinary service reducer, so loading and
+ * filtered-empty never masquerade as a successfully completed query. */
+export function createLegacyCollectionQuery<Row>(source: CollectionQuerySource<Row>, publish: (state: CollectionQueryState<Row>) => void) {
+  let generation = 0, disposed = false;
+  let loadedPages = 0, restoringPages = 0;
+  let state: CollectionQueryState<Row> = { criteria: normalize({}), items: [], nextCursor: '', status: 'idle', loadingMore: false, pageError: false, complete: false, error: '', read: initialReadStatus() };
+  /** The query a revalidation is running under: its snapshots are held back until it is done. */
+  let revalidating = -1;
+  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
+   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
+   *  it leaves those rows on screen, so it is still this. */
+  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
+  let clearedByError = false;
+  const snapshot = (): CollectionQueryState<Row> => ({ ...state, read: { ...state.read }, criteria: copyQuery(state.criteria), items: [...state.items] });
+  const emit = () => {
+    if (disposed || revalidating === generation) return;
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept.
+    if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
+      lastShown = { state: snapshot(), loadedPages };
+    }
+    publish(snapshot());
+  };
+  const merge = (old: Row[], page: Row[]): Row[] => {
+    const positions = new Map<string, number>(), result: Row[] = [];
+    for (const item of [...old, ...page]) {
+      const id = source.id(item);
+      if (!id) throw new Error('A backend collection row requires an identity');
+      const index = positions.get(id);
+      if (index === undefined) { positions.set(id, result.length); result.push(item); }
+      else result[index] = item;
+    }
+    return result;
+  };
+  /** [keepRows]: a search typed over the rows on screen leaves them there until its answer arrives (status stays
+   *  `loading`, and nothing pages under the old answer), so the list is not blanked on each keystroke. */
+  const fetch = async (append: boolean, keepRows = false): Promise<void> => {
+    if (disposed || (append && (state.loadingMore || state.status === 'loading' || !state.nextCursor))) return;
+    const revision = append ? generation : ++generation;
+    const cursor = append ? state.nextCursor : '';
+    const criteria = copyQuery(state.criteria);
+    if (!append) loadedPages = 0;
+    state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
+      ...(append ? {} : keepRows ? { nextCursor: '', complete: false, provisional: false }
+        : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
+    emit();
+    try {
+      if (!append && source.cached) {
+        const cached = await source.cached(criteria).catch(() => undefined);
+        if (disposed || generation !== revision) return;
+        if (cached?.items.length) {
+          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
+          emit();
+        }
+      }
+      const page = await source.fetch(criteria, cursor);
+      if (disposed || generation !== revision) return;
+      if (!Array.isArray(page.items) || typeof page.nextCursor !== 'string' || (cursor && page.nextCursor === cursor)) throw new Error('Invalid collection page');
+      state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
+        total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
+        metadata: page.metadata ?? (append ? state.metadata : undefined),
+        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
+      loadedPages++;
+    } catch (error) {
+      if (disposed || generation !== revision) return;
+      const clear = source.clearOnError?.(error) === true;
+      // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
+      clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
+      if (clearedByError) lastShown = undefined;
+      if (clear) loadedPages = 0;
+      // The rows a typed search kept on screen while it ran were never its answer: a failed one shows none of them.
+      const drop = clear || keepRows;
+      state = { ...state, ...(drop ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
+        status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
+        provisional: false, error: source.errorMessage?.(error) ?? '' };
+    }
+    emit();
+  };
+  return {
+    getState: snapshot,
+    /** [revalidate]: a screen coming back re-queries the rows it shows. They stay on screen until every
+     *  page is in, and a failure keeps them; revoked access still clears them, and other criteria reset. */
+    async query(criteria: Partial<CollectionQuery>, restorePages = false, revalidate = false): Promise<void> {
+      if (disposed) return Promise.resolve();
+      const next = normalize(criteria);
+      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
+      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
+      restoringPages = count;
+      // Only the search text changed: the user is typing over the rows on screen, also while the last keystroke's
+      // search is still out.
+      const typing = !same && (state.status === 'ready' || state.status === 'loading')
+        && sameCriteria({ ...state.criteria, query: '' }, { ...next, query: '' });
+      state = { ...state, criteria: next };
+      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
+      const pending = fetch(false, typing);
+      const revision = generation;
+      await pending;
+      // Re-appearance revalidates every previously opened page using fresh
+      // cursors. A changed query, error or revoked access stops the restoration.
+      while (!disposed && generation === revision && loadedPages < count && state.status === 'ready'
+        && !state.pageError && !state.loadingMore && state.nextCursor) await fetch(true);
+      if (generation === revision) restoringPages = 0;
+      if (revalidating === revision) {
+        revalidating = -1;
+        if (generation !== revision) return;
+        if ((state.status !== 'ready' || state.pageError) && showing && !clearedByError) {
+          state = { ...showing.state, criteria: next };
+          loadedPages = showing.loadedPages;
+        }
+        emit();
+      }
+    },
+    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
+     *  state; undefined when it shows none. */
+    shownPage(): CollectionShownPage<Row> | undefined {
+      if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
+      const page = lastShown.state;
+      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+    },
+    /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
+     *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page. */
+    seed(page: unknown): boolean {
+      const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
+      const restored = candidate?.state;
+      if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
+        || !Array.isArray(restored.items) || typeof restored.nextCursor !== 'string') return false;
+      try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
+      state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
+        loadingMore: false, pageError: false, provisional: false, error: '', read: restored.read ? { ...restored.read } : initialReadStatus() };
+      loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      lastShown = { state: snapshot(), loadedPages };
+      return true;
+    },
+    refresh: () => { restoringPages = 0; return fetch(false); },
+    loadMore: () => fetch(true),
+    retry: () => fetch(state.pageError),
+    dispose() { disposed = true; generation++; },
+  };
+}

package/templates/branded-lite/tier5-src/_shared/collection-query.ts

@@ -1,3 +1,6 @@
+import { createReadController, initialReadStatus, type ReadMetadata, type ReadStatus } from '@himalaya/state';
+import { createLegacyCollectionQuery } from './collection-query-legacy';
+
 /** Backend collection lifecycle shared by domain workers. The domain supplies
  * the query and row mapper; this layer never calls a domain API or mutates it. */
 export interface CollectionQuery {
@@ -12,6 +15,9 @@ export interface CollectionPage<Row> {
   total?: number;
   metadata?: Record<string, unknown>;
   complete?: boolean;
+  provenance?: ReadMetadata;
+  /** A result derived entirely from local criteria/authored configuration (e.g. no saved IDs). */
+  local?: boolean;
 }
 export interface CollectionQueryState<Row> extends CollectionPage<Row> {
   criteria: CollectionQuery;
@@ -20,6 +26,7 @@ export interface CollectionQueryState<Row> extends CollectionPage<Row> {
   pageError: boolean;
   complete: boolean;
   error: string;
+  read: ReadStatus;
   /** The rows are the source's `cached` page, shown while the live read is still out. */
   provisional?: boolean;
 }
@@ -29,7 +36,9 @@ export interface CollectionShownPage<Row> {
   loadedPages: number;
 }
 export interface CollectionQuerySource<Row> {
-  fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
+  fetch(criteria: CollectionQuery, cursor: string, options?: CollectionReadOptions): Promise<CollectionPage<Row>>;
+  /** Source forwards cache mode and metadata to every SDK read. */
+  cacheRead?: boolean;
   /** Optional public cache for immediate paint; always incomplete, never a paging authority. */
   cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
   id(row: Row): string;
@@ -39,6 +48,10 @@ export interface CollectionQuerySource<Row> {
    *  key carries the account, and a purge tears parked workers down). */
   clearOnError?(error: unknown): boolean;
 }
+export interface CollectionReadOptions {
+  cache: 'only-if-cached' | 'reload';
+  onCacheResult(metadata: ReadMetadata): void;
+}
 const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
   query: typeof q.query === 'string' ? q.query.trim().slice(0, 256) : '',
   filter: typeof q.filter === 'string' ? q.filter.slice(0, 256) : 'all',
@@ -47,30 +60,33 @@ const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
 });
 const copyQuery = (q: CollectionQuery): CollectionQuery => ({ ...q, savedIds: [...q.savedIds] });
 
-/** New criteria cancel the old result logically, including an in-flight next
- * page. Failures preserve the cursor and rows for an explicit retry. Callers
- * publish each snapshot through their ordinary service reducer, so loading and
- * filtered-empty never masquerade as a successfully completed query. */
+
+/** Refreshes stage a complete replacement at the currently loaded depth. Old rows
+ * and cursors remain usable until every replacement page succeeds. Query changes
+ * start a separate snapshot; they never reuse a subset from another query. */
 export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, publish: (state: CollectionQueryState<Row>) => void) {
-  let generation = 0, disposed = false;
-  let loadedPages = 0, restoringPages = 0;
-  let state: CollectionQueryState<Row> = { criteria: normalize({}), items: [], nextCursor: '', status: 'idle', loadingMore: false, pageError: false, complete: false, error: '' };
-  /** The query a revalidation is running under: its snapshots are held back until it is done. */
-  let revalidating = -1;
-  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
-   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
-   *  it leaves those rows on screen, so it is still this. */
-  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  // Only opted-in reads use the new snapshot/recovery controller. Other template collections
+  // keep their established query, pagination, and warm-return behavior.
+  if (!source.cacheRead) return createLegacyCollectionQuery(source, publish);
+  const sample = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiOwnerPreview === 'sample';
+  const cacheRead = source.cacheRead && !sample;
+  const shouldClearOnError = (error: unknown) => source.clearOnError?.(error) === true
+    || /HTTP 40[13]\b|forbidden|principal.changed|identity.changed/i.test(String(error));
+  let generation = 0, disposed = false, loadedPages = 1, wantedPages = 1, restoringPages = 1, key = '';
+  let pending: Promise<void> | undefined;
+  let suppressPublish = false;
+  let state: CollectionQueryState<Row> = { criteria: normalize({}), items: [], nextCursor: '', status: 'idle',
+    loadingMore: false, pageError: false, complete: false, error: '', read: initialReadStatus() };
+  let lastShown: CollectionShownPage<Row> | undefined;
   const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
-  let clearedByError = false;
-  const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
+  const snapshot = (): CollectionQueryState<Row> => ({ ...state, read: { ...state.read }, criteria: copyQuery(state.criteria), items: [...state.items] });
   const emit = () => {
-    if (disposed || revalidating === generation) return;
-    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept, and a list
-    // with nothing in it comes back as its empty state, never its loading look.
+    if (disposed) return;
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept.
     if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
       lastShown = { state: snapshot(), loadedPages };
     }
+    if (suppressPublish) return;
     publish(snapshot());
   };
   const merge = (old: Row[], page: Row[]): Row[] => {
@@ -84,91 +100,124 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     }
     return result;
   };
-  /** [keepRows]: a search typed over the rows on screen leaves them there until its answer arrives (status stays
-   *  `loading`, and nothing pages under the old answer), so the list is not blanked on each keystroke. */
-  const fetch = async (append: boolean, keepRows = false): Promise<void> => {
-    if (disposed || (append && (state.loadingMore || state.status === 'loading' || !state.nextCursor))) return;
-    const revision = append ? generation : ++generation;
-    const cursor = append ? state.nextCursor : '';
-    const criteria = copyQuery(state.criteria);
-    if (!append) loadedPages = 0;
-    state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
-      ...(append ? {} : keepRows ? { nextCursor: '', complete: false, provisional: false }
-        : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
-    emit();
-    try {
-      if (!append && source.cached) {
-        const cached = await source.cached(criteria).catch(() => undefined);
-        if (disposed || generation !== revision) return;
-        if (cached?.items.length) {
-          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
-          emit();
-        }
+  const combine = (a: ReadMetadata, b: ReadMetadata): ReadMetadata => ({
+    source: a.source === 'cache' || b.source === 'cache' ? 'cache' : 'network',
+    fetchedAt: Math.min(a.fetchedAt, b.fetchedAt), cacheable: a.cacheable && b.cacheable,
+    expiresAt: Math.min(a.expiresAt ?? 0, b.expiresAt ?? 0),
+  });
+  const readPage = async (criteria: CollectionQuery, cursor: string, cache: 'only-if-cached' | 'reload') => {
+    let provenance: ReadMetadata | undefined;
+    const page = await source.fetch(criteria, cursor, { cache, onCacheResult(value) { provenance = provenance ? combine(provenance, value) : value; } });
+    if (!Array.isArray(page.items) || typeof page.nextCursor !== 'string' || (cursor && page.nextCursor === cursor))
+      throw new Error('Invalid collection page');
+    if (page.local === true) provenance = { source: 'local', fetchedAt: 0, cacheable: false };
+    if (cacheRead && !provenance && !page.provenance) throw new Error('Read source did not provide response provenance');
+    // A legacy/error fallback is never a successful server refresh.
+    if (page.metadata?.fromCache && !provenance) throw new Error('Cache response has no policy provenance');
+    return { ...page, items: merge([], page.items), provenance: provenance ?? page.provenance ??
+      { source: 'network' as const, fetchedAt: Date.now(), cacheable: false } };
+  };
+  const reader = createReadController<CollectionPage<Row>>({
+    allowLocal: true,
+    ...(sample ? { online: () => true } : {}),
+    ...(!sample && (source.cached || cacheRead) ? { cached: async (readKey: string) => {
+      const criteria = JSON.parse(readKey) as CollectionQuery;
+      const page = cacheRead ? await readPage(criteria, '', 'only-if-cached') : await source.cached?.(criteria);
+      if (!page?.provenance || !['cache', 'local'].includes(page.provenance.source)) return undefined;
+      return { data: { ...page, nextCursor: '', complete: !page.nextCursor }, metadata: page.provenance };
+    } } : {}),
+    fetch: async (readKey) => {
+      const criteria = JSON.parse(readKey) as CollectionQuery, revision = generation, depth = wantedPages;
+      let page = await readPage(criteria, '', 'reload'), count = 1;
+      const seen = new Set<string>();
+      while (page.nextCursor && count < depth) {
+        if (disposed || revision !== generation) throw new Error('Read disposed');
+        if (seen.has(page.nextCursor)) throw new Error('Repeated collection cursor');
+        seen.add(page.nextCursor);
+        const next = await readPage(criteria, page.nextCursor, 'reload');
+        if (next.provenance.source !== 'network') throw new Error('Refresh returned cached data');
+        page = { ...page, items: merge(page.items, next.items), nextCursor: next.nextCursor, complete: next.complete, provenance: combine(page.provenance, next.provenance) };
+        count++;
       }
-      const page = await source.fetch(criteria, cursor);
-      if (disposed || generation !== revision) return;
-      if (!Array.isArray(page.items) || typeof page.nextCursor !== 'string' || (cursor && page.nextCursor === cursor)) throw new Error('Invalid collection page');
-      state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
-        total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
-        metadata: page.metadata ?? (append ? state.metadata : undefined),
-        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
+      if (!disposed && revision === generation) loadedPages = count;
+      return { data: page, metadata: page.provenance };
+    },
+    clearOnError: error => {
+      const clear = shouldClearOnError(error);
+      if (clear) lastShown = undefined;
+      return clear;
+    },
+    errorMessage: source.errorMessage,
+    publish: (page, read) => {
+      state = { ...state, ...(page ?? { items: [], nextCursor: '', total: undefined, metadata: undefined }),
+        metadata: page ? { ...page.metadata, fromCache: read.fromCache } : undefined,
+        read, status: read.hasSnapshot ? 'ready' : read.refreshing ? 'loading' : 'error',
+        complete: !!page && (page.complete ?? !page.nextCursor), loadingMore: false, pageError: false,
+        provisional: read.fromCache && read.refreshing,
+        error: read.offline && !read.hasSnapshot ? "This content isn’t available offline. Connect to load it." : read.error };
+      emit();
+    },
+  });
+  const query = (criteria: Partial<CollectionQuery>, restorePages = false, _revalidate = false): Promise<void> => {
+    if (disposed) return Promise.resolve();
+    const next = normalize(criteria), nextKey = JSON.stringify(next);
+    if (key === nextKey && pending) return pending;
+    const same = key === nextKey;
+    if (!same) { loadedPages = 1; restoringPages = 1; }
+    key = nextKey; generation++; wantedPages = same ? Math.max(1, loadedPages, restorePages ? restoringPages : 1) : 1;
+    state = { ...state, criteria: next };
+    const revision = generation;
+    pending = reader.load(key).finally(() => { if (revision === generation) pending = undefined; });
+    return pending;
+  };
+  const loadMore = async () => {
+    if (disposed || pending || state.loadingMore || !state.nextCursor) return;
+    const revision = generation, criteria = copyQuery(state.criteria), cursor = state.nextCursor;
+    state = { ...state, loadingMore: true, pageError: false }; emit();
+    try {
+      const page = await readPage(criteria, cursor, 'reload');
+      if (disposed || revision !== generation) return;
+      if (page.provenance.source !== 'network') throw new Error('Page returned cached data');
+      const provenance = state.provenance ? combine(state.provenance, page.provenance) : page.provenance;
+      state = { ...state, ...page, provenance, items: merge(state.items, page.items), total: page.total ?? state.total,
+        metadata: page.metadata ?? state.metadata, loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor };
       loadedPages++;
+      wantedPages = loadedPages;
+      // Keep the read controller's retained snapshot aligned with appended pages.
+      reader.replace({ data: state, metadata: provenance });
     } catch (error) {
-      if (disposed || generation !== revision) return;
-      const clear = source.clearOnError?.(error) === true;
-      // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
-      clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
-      if (clearedByError) lastShown = undefined;
-      if (clear) loadedPages = 0;
-      // The rows a typed search kept on screen while it ran were never its answer: a failed one shows none of them.
-      const drop = clear || keepRows;
-      state = { ...state, ...(drop ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
-        status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
-        provisional: false, error: source.errorMessage?.(error) ?? '' };
+      if (disposed || revision !== generation) return;
+      if (shouldClearOnError(error)) {
+        loadedPages = 1; wantedPages = 1; lastShown = undefined; reader.invalidate();
+        const message = source.errorMessage?.(error) || 'This content is unavailable for this account. Try signing in again.';
+        state = { ...state, status: 'error', loadingMore: false, pageError: false,
+          error: message, read: { ...state.read, error: message } };
+        emit();
+        return;
+      }
+      state = { ...state, loadingMore: false, pageError: true, complete: false,
+        error: source.errorMessage?.(error) || 'The next page could not load. Try again.' };
+      emit();
     }
-    emit();
   };
+  // A late page must not repopulate a cleared/private snapshot after logout or disconnect.
+  const host = (globalThis as { himalaya?: { __subscribeReadLifecycle?(listener: (signal: string) => void): () => void } }).himalaya;
+  const stop = host?.__subscribeReadLifecycle?.(signal => {
+    if (signal === 'invalidate' || signal === 'offline' || signal === 'dispose') {
+      generation++; pending = undefined;
+      if (signal !== 'offline') { loadedPages = 1; wantedPages = 1; lastShown = undefined; }
+      if (signal === 'dispose') disposed = true;
+    }
+  });
   return {
     getState: snapshot,
-    /** [revalidate]: a screen coming back re-queries the rows it shows. They stay on screen until every
-     *  page is in, and a failure keeps them; revoked access still clears them, and other criteria reset. */
-    async query(criteria: Partial<CollectionQuery>, restorePages = false, revalidate = false): Promise<void> {
-      if (disposed) return Promise.resolve();
-      const next = normalize(criteria);
-      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
-      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
-      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
-      restoringPages = count;
-      // Only the search text changed: the user is typing over the rows on screen, also while the last keystroke's
-      // search is still out.
-      const typing = !same && (state.status === 'ready' || state.status === 'loading')
-        && sameCriteria({ ...state.criteria, query: '' }, { ...next, query: '' });
-      state = { ...state, criteria: next };
-      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
-      const pending = fetch(false, typing);
-      const revision = generation;
-      await pending;
-      // Re-appearance revalidates every previously opened page using fresh
-      // cursors. A changed query, error or revoked access stops the restoration.
-      while (!disposed && generation === revision && loadedPages < count && state.status === 'ready'
-        && !state.pageError && !state.loadingMore && state.nextCursor) await fetch(true);
-      if (generation === revision) restoringPages = 0;
-      if (revalidating === revision) {
-        revalidating = -1;
-        if (generation !== revision) return;
-        if ((state.status !== 'ready' || state.pageError) && showing && !clearedByError) {
-          state = { ...showing.state, criteria: next };
-          loadedPages = showing.loadedPages;
-        }
-        emit();
-      }
+    query: (criteria: Partial<CollectionQuery>, restorePages = false, revalidate = false) => {
+      restoringPages = restorePages ? Math.max(1, loadedPages) : 1;
+      return query(criteria, restorePages, revalidate);
     },
-    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
-     *  state; undefined when it shows none. */
     shownPage(): CollectionShownPage<Row> | undefined {
       if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
-      const page = lastShown.state;
-      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+      return { state: { ...lastShown.state, read: { ...lastShown.state.read }, criteria: copyQuery(lastShown.state.criteria), items: [...lastShown.state.items] }, loadedPages: lastShown.loadedPages };
     },
     /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
      *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page; an
@@ -176,18 +225,28 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     seed(page: unknown): boolean {
       const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
       const restored = candidate?.state;
+      const provenance = restored?.provenance;
       if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
-        || !Array.isArray(restored.items) || typeof restored.nextCursor !== 'string') return false;
+        || !Array.isArray(restored.items) || typeof restored.nextCursor !== 'string'
+        || !provenance || !['cache', 'network'].includes(provenance.source) || !provenance.cacheable
+        || provenance.expiresAt === undefined || provenance.expiresAt <= Date.now()) return false;
       try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
       state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
         loadingMore: false, pageError: false, provisional: false, error: '' };
       loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      wantedPages = loadedPages;
+      const saved = state.provenance;
+      if (!saved) return false;
+      suppressPublish = true;
+      key = JSON.stringify(state.criteria);
+      reader.replace({ data: state, metadata: saved }, key);
+      suppressPublish = false;
       lastShown = { state: snapshot(), loadedPages };
       return true;
     },
-    refresh: () => { restoringPages = 0; return fetch(false); },
-    loadMore: () => fetch(true),
-    retry: () => fetch(state.pageError),
-    dispose() { disposed = true; generation++; },
+    refresh: () => query(state.criteria, true, true),
+    loadMore,
+    retry: () => state.pageError ? loadMore() : query(state.criteria, true, true),
+    dispose() { disposed = true; generation++; stop?.(); reader.dispose(); },
   };
 }