@wix/himalaya-cli 0.1543.0 → 0.1545.0

package/templates/retail-store/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(); },
   };
 }

package/templates/retail-store/tier5-src/_shared/collection-service.ts

@@ -12,6 +12,8 @@ export interface CollectionSaving {
 type State = Record<string, unknown>;
 interface BackendCollection {
   restorePagesOnLoad?: boolean;
+  /** Opt in only for templates whose generated screens adopt the shared read status. */
+  readLifecycle?: boolean;
   /** Sees the load action's argument (the screen's onAppear params) BEFORE the query runs. A returned
    *  `{ filter, sort }` resets the criteria for that load (a screen that always opens on one view). */
   onLoad?(arg: unknown): CollectionCriteriaReset | void;
@@ -83,6 +85,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     })
     : [];
   let pendingFilter = '';
+  const requestedReadLifecycle = (def as { readLifecycle?: { refreshAction: string; statusPath: string } }).readLifecycle;
+  const hasReadLifecycle = !!requestedReadLifecycle || backend?.readLifecycle === true;
   const applyNavigationCriteria = (arg: unknown, state: State): boolean => {
     const input = object(arg);
     let changed = false;
@@ -144,16 +148,18 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     if (previewId && !rows.some(row => collectionId(row) === previewId)) previewId = '';
     const filterChoices = [{ id: 'all', label: copyParam('collection.all', 'All') }, ...(config.rowStyle === 'flat' ? [] : [{ id: 'saved', label: copyParam('collection.saved', 'Saved') }]),
       ...projected.filters.map(label => ({ id: `value:${label}`, label: copyParam(`collection.filter.${label}`, label) }))];
-    const loading = s.status === 'loading' || s.isLoading === true;
+    const readStatus = hasReadLifecycle ? s.readStatus as { hasSnapshot?: boolean; refreshing?: boolean } | undefined : undefined;
+    const loading = readStatus ? readStatus.refreshing === true && readStatus.hasSnapshot !== true : s.status === 'loading' || s.isLoading === true;
     // Older domain reducers expose `errored` rather than `isErrored`; backend
     // adapters can also intentionally keep their display status "ready" while
     // the query controller carries a recoverable failure. Treat each shape as
     // one collection state so the shared UI never renders a blank catalog.
     const backendState = backend?.controller.getState();
+    const read = backend?.readLifecycle ? s.readStatus as { hasSnapshot?: boolean; offline?: boolean; error?: string } | undefined : undefined;
     const provisional = backendState?.provisional === true;
-    const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
+    const errored = !!read?.error || (backend?.readLifecycle === true && !!backendState?.error) || s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
     const domainError = typeof s.error === 'string' ? s.error.trim() : '';
-    const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
+    const queryError = read?.offline && !read.hasSnapshot ? 'This content isn’t available offline. Connect to load it.' : read?.error || (typeof backendState?.error === 'string' ? backendState.error.trim() : '');
     // Some domains carry their failure sentence in `emptyText` (portfolio, podcasts);
     // the screen folds that node into this block, so keep the domain's own words.
     const domainEmptyError = errored && typeof s.emptyText === 'string' ? s.emptyText.trim() : '';
@@ -178,7 +184,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // "All" and the collection's own default (e.g. Upcoming) are both un-narrowed: Clear
     // resets to "All", so showing it on either would offer a reset that changes nothing.
     const narrowed = !!prefs.query.trim() || (prefs.filter !== 'all' && prefs.filter !== initialCollection(config).filter) || domainNarrowed;
-    const sourceEmpty = !loading && !errored && rows.length === 0 &&
+    const sourceEmpty = (backend?.readLifecycle !== true || backendState?.read.hasSnapshot === true) && !loading && !errored && rows.length === 0 &&
       (!(backend && config.backendQuery) || !narrowed) && !domainNarrowed;
     const emptySourceText = (typeof s.emptyText === 'string' && s.emptyText.trim()) || copyParam('collection.emptySource', 'Nothing here yet');
     // Chrome is noise over a small un-narrowed list (fewer than COLLECTION_CHROME_MIN_ITEMS
@@ -196,14 +202,15 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       noPageError: s.pageError !== true,
       // Rows read from the device ahead of the live read are shown as they are: "saved offline" is what stays on
       // screen when the live read failed, not a first visit that is still loading.
-      noOffline: s.fromCache !== true || provisional,
+      noOffline: !(backend?.readLifecycle === true && backendState?.read.stale || s.fromCache === true) || provisional,
       noError: !errored,
       noRetry: !canRetry || signInRequired,
       noSignIn: !signInRequired,
       errorTitle: signInRequired ? copyParam('collection.signInTitle', 'Sign in to see this') : copyParam('collection.loadErrorTitle', 'This collection could not load'),
       errorMessage,
-      // A skeleton only with nothing to show: a search re-running over the rows on screen keeps them.
-      noLoading: !loading || rows.length > 0,
+      isLoading: loading, notLoading: !loading,
+      // Legacy searches retain visible rows; opted-in reads also retain valid empty snapshots.
+      noLoading: !loading || rows.length > 0 || (backend?.readLifecycle === true && backendState?.read.hasSnapshot === true),
       // De-dup against a domain that paints its OWN empty block (screen-kit emptyBlock is
       // gated on the domain's top-level `noEmpty`): only one empty state ever shows.
       noEmptySource: !sourceEmpty || s.noEmpty === false,
@@ -330,7 +337,11 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     };
     actions.refresh = (_s, arg) => {
       stashCopy(arg); syncSaved();
-      return backend.controller.query(criteria()).then(() => undefined);
+      // Reconnect refreshes the currently visible result. Rebuild every page the
+      // user had already opened, using fresh cursors, before replacing the snapshot.
+      return (backend.readLifecycle
+        ? backend.controller.query(criteria(), true, true)
+        : backend.controller.query(criteria())).then(() => undefined);
     };
     actions.loadMore = () => backend.controller.loadMore().then(() => undefined);
     actions.retry = actions.collectionRetry = () => backend.controller.retry().then(() => undefined);
@@ -344,7 +355,10 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     const retry = actions.refresh ?? actions.load;
     if (retry) actions.collectionRetry = retry;
   }
-  return { state: derive(def.state), actions };
+  return { state: derive(def.state), actions,
+    ...(requestedReadLifecycle || backend?.readLifecycle ? { readPresentation: derive } : {}),
+    ...(requestedReadLifecycle ? { readLifecycle: requestedReadLifecycle }
+      : backend?.readLifecycle && runtime?.input?.__himiOwnerPreview !== 'sample' ? { readLifecycle: { refreshAction: 'refresh', statusPath: 'readStatus' } } : {}) };
 }
 
 /** Domain-owned page source with shared query controls. Publishing uses a normal
@@ -357,6 +371,8 @@ export function defineBackendCollection<S extends object, Row extends object>(na
   onlineWriteMessageFields?: readonly string[];
   /** Revalidate already opened pages on navigation return; explicit refresh resets. */
   restorePagesOnLoad?: boolean;
+  /** Opt this shared list into the read status and reconnect lifecycle. */
+  readLifecycle?: boolean;
   /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
    *  domain setting that rides the descriptor, e.g. My Bookings' `weeklyGoal`. */
   onLoad?(arg: unknown): CollectionCriteriaReset | void;
@@ -367,12 +383,16 @@ export function defineBackendCollection<S extends object, Row extends object>(na
   actions?: Record<string, (state: S, ...args: unknown[]) => S | undefined | Promise<S | undefined>>;
 }) {
   let publish: (() => unknown) | undefined;
-  const controller = createCollectionQuery(options.source, () => { publish?.(); });
+  const controller = createCollectionQuery({ ...options.source,
+    // Access-denial clearing belongs to the opt-in read lifecycle. Keep the legacy
+    // collection contract unchanged for templates that have not adopted it.
+    ...(options.readLifecycle ? { clearOnError: error => /HTTP (401|403)\b|forbidden|principal.changed|identity.changed/i.test(String(error)) || options.source.clearOnError?.(error) === true } : {}) }, () => { publish?.(); });
   const definition = decorateCollection(name, { state: options.state as State, actions: options.actions as Record<string, Reducer> | undefined }, options.saving, {
     restorePagesOnLoad: options.restorePagesOnLoad,
+    readLifecycle: options.readLifecycle,
     onLoad: options.onLoad,
     controller: controller as unknown as BackendCollection['controller'],
-    apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
+    apply: (state, page) => ({ ...options.apply(state as S, page as unknown as CollectionQueryState<Row>), ...(options.readLifecycle ? { readStatus: page.read } : {}) }) as State,
   });
   const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: options.onlineWriteMessageFields ?? ['actionMessage'] }) : (options.register ?? register);
   const handle = registerService(name, definition);

package/templates/retail-store/tier5-src/_shared/iap-presentation.ts

@@ -103,6 +103,8 @@ export function withIapPresentation<S extends object>(options: {
         // scopeLanded is the completion of the active load, not a stale load result. It
         // must publish even if another overlapping onAppear load advanced contentVersion.
         if (!next || (content && action !== "scopeLanded" && version !== contentVersion)) return undefined;
+        // A committed read projection supersedes older load results still carrying a skeleton.
+        if (action === "readChanged" && definition.readLifecycle) contentVersion++;
         if (content) {
           options.onContent?.(next);
           const nextItems = options.items(next);
@@ -130,9 +132,11 @@ export function withIapPresentation<S extends object>(options: {
       };
       try {
         const next = reduce(state, ...args);
-        // Keep synchronous sidecars synchronous. Adding an await lets their old
-        // catalog snapshot commit after a newer asynchronous refresh.
-        if (content || (next && typeof (next as Promise<S | undefined>).then === "function")) {
+        // A cached read projection must commit before another onAppear can consume it.
+        // Other content actions retain their scheduling: shop filters and panels can
+        // change while a load is pending, and their existing completion order matters.
+        const synchronousReadProjection = action === "readChanged" && !!definition.readLifecycle;
+        if ((content && !synchronousReadProjection) || (next && typeof (next as Promise<S | undefined>).then === "function")) {
           return (async () => {
             try { return presentResult(await next); }
             finally { finished(); }