@wix/himalaya-cli 0.1544.0 → 0.1546.0

package/templates/branded-lite/tier5-src/himi-branded-lite-shop/index.ts

@@ -10,28 +10,33 @@
 //
 // Opened with `category` = a category id or name; absent ⇒ All.
 import { getCurrentCart } from "@himalaya/wix-ecom";
-import { getAll, remove, upsert, type DbEntity } from "@himalaya/local-db";
+import { createReadController, initialReadStatus, connectivity, type ReadMetadata, type ReadStatus } from "@himalaya/state";
+import type { WixCallOptions } from "@himalaya/wix-stores";
 import { searchStoreProducts, type StoreProduct } from "../_shared/himi-store.js";
 import { withIapPresentation } from "../_shared/iap-presentation.js";
 import { stashCopy, copyParam, copyTemplate } from "../_shared/himi-copy.js";
 import { loadStoreCategories, type StoreCategoryCard } from "../_shared/himi-store-categories.js";
 import {
   FACETS_BOOT, PAGE_SIZE, applyFacets, countText, currencyOf, facetActions, idOf, option, readViewPrefs, selected, toRows, toggleSaved,
-  type FacetState, type Option, type ProductCard, type Row,
+  type FacetState, type Option, type Row,
 } from "../_shared/himi-store-facets.js";
 
 const ALL = "all";
 const PAGE = 100;
 const MAX_PRODUCTS = 500;
-const ENTITY = "products";
+
 
 interface S extends FacetState {
+  readStatus: ReadStatus;
+  readMessage: string;
+  noReadMessage: boolean;
+  hasReadMessage: boolean;
   status: "loading" | "ready" | "error";
   isLoading: boolean;
   notLoading: boolean;
   isErrored: boolean;
   notErrored: boolean;
-  /** The rows are the last synced catalog, read from the device while offline. */
+  /** Response provenance comes from the shared policy-controlled read adapter. */
   fromCache: boolean;
   noOffline: boolean;
   categorySelected: string;
@@ -58,14 +63,20 @@ let pendingCategoriesRead: Promise<StoreCategoryCard[]> | undefined;
 /** Cart count can land while the first product scope is still pending. */
 let loadedCartCount: number | undefined;
 /** Each category's fetched rows, so switching back to a chip is instant. */
-const scopes = new Map<string, { rows: Row[]; complete: boolean; loading: boolean; fromCache?: boolean; currency?: string; total?: number }>();
+interface ScopeSnapshot {
+  rows: Row[]; complete: boolean; loading: boolean; fromCache?: boolean;
+  currency?: string; total?: number; cursor?: string; metadata: ReadMetadata;
+}
+const scopes = new Map<string, ScopeSnapshot>();
+const readers = new Map<string, ReturnType<typeof createReadController<ScopeSnapshot>>>();
+const publications = new Map<string, Promise<void>>();
+const publicationVersions = new Map<string, number>();
+const restFlights = new WeakSet<ScopeSnapshot>();
 const pendingScopes = new Map<string, number>();
 // A pull-to-refresh that loses the foreground generation still represents fresh data the
 // shopper asked for. Keep that intent until a current request for the scope lands, so a
 // quick trip away and back cannot present the old cached scope as the refresh result.
 const pendingRefreshScopes = new Map<string, number>();
-let cacheWriteGeneration = 0;
-let cacheWriteQueue: Promise<void> = Promise.resolve();
 /** Bumped on every scope change; a stale first page must never write over a newer scope. */
 let generation = 0;
 /** The category the screen shows. Module state, not action state: the boot load and the
@@ -79,20 +90,6 @@ let pendingAuxiliary: { cartCount: number; version: number } | undefined;
 let auxiliaryVersion = 0;
 let lastRouteActivation: string | undefined;
 let routeCategoryConsumed = false;
-let legacyCacheFacetResetDone = false;
-const LEGACY_CACHE_FACETS_KEY = "himi-store:legacy-cache-facets-reset:v1";
-
-function shouldResetLegacyCacheFacets(): boolean {
-  if (legacyCacheFacetResetDone) return false;
-  legacyCacheFacetResetDone = true;
-  try {
-    const store = (globalThis as { himalaya?: { storage?: { getItem(key: string): string | null; setItem(key: string, value: string): void } } }).himalaya?.storage;
-    if (store?.getItem(LEGACY_CACHE_FACETS_KEY) === "1") return false;
-    store?.setItem(LEGACY_CACHE_FACETS_KEY, "1");
-  } catch { /* one reset this boot even when storage is unavailable */ }
-  return true;
-}
-
 function input(arg?: unknown): { category?: string; categoryId?: string; categoryActivation?: string } {
   const fromArg = arg as { category?: unknown; categoryId?: unknown; categoryActivation?: unknown } | undefined;
   const route = (fromArg && typeof fromArg === "object" && (
@@ -113,6 +110,7 @@ function matchCategory(want: string): string | undefined {
 }
 
 async function cartItemCount(): Promise<number | undefined> {
+  if (!connectivity().online) return undefined;
   try {
     const cart = await getCurrentCart();
     return (cart.lineItems ?? []).reduce((n, li) => n + (li.quantity ?? 1), 0);
@@ -125,6 +123,7 @@ async function cartItemCount(): Promise<number | undefined> {
  *  supersede that refresh's category discovery. Cache reads share an in-flight catalog read;
  *  only the newest network read can replace the worker's current categories. */
 function readCategories(fresh: boolean): Promise<StoreCategoryCard[]> {
+  if (!connectivity().online) { categoriesAuthoritative = false; return Promise.resolve(categories); }
   // A network read already in flight is fresh enough for a refresh that starts before it
   // lands. Sharing it avoids discarding a good older response when a redundant newer read
   // fails, and lets a route load consume the same authoritative list.
@@ -169,52 +168,6 @@ function reconcileCategories(): { invalidatedSelection: boolean; intentVersion:
   return { invalidatedSelection, intentVersion: categoryIntentVersion };
 }
 
-type CachedCard = ProductCard & {
-  cachePrice?: number; cacheCreated?: string; cacheName?: string;
-  cacheOptions?: Record<string, string[]>; cacheCurrency?: string; legacyCache?: boolean;
-};
-
-/** Migrate the former himi-store-shop row shape in memory: the entity name stayed the same. */
-function cachedCard(value: unknown): CachedCard | undefined {
-  const raw = value as (ProductCard & { subtitle?: string; initial?: string }) | undefined;
-  if (!raw?.id || typeof raw.name !== "string") return undefined;
-  if (typeof raw.noTagRow === "boolean" && typeof raw.notOnSale === "boolean") return raw as CachedCard;
-  const image = typeof raw.image === "string" ? raw.image : "";
-  const price = typeof raw.commercePrice === "string" && raw.commercePrice ? raw.commercePrice : raw.subtitle ?? "";
-  return {
-    id: raw.id, name: raw.name, image, hasImage: typeof raw.hasImage === "boolean" ? raw.hasImage : !!image,
-    noImage: typeof raw.noImage === "boolean" ? raw.noImage : !image, initial: raw.initial ?? raw.name.slice(0, 1).toUpperCase(),
-    price, wasPrice: "", onSale: false, notOnSale: true, saved: false, notSaved: true,
-    swatch1: "", swatch2: "", swatch3: "", swatch4: "", swatch5: "",
-    swatch1Hidden: true, swatch2Hidden: true, swatch3Hidden: true, swatch4Hidden: true, swatch5Hidden: true,
-    noSwatches: true, noTagRow: true, commercePrice: raw.commercePrice ?? price,
-    detailScreenId: raw.detailScreenId || "himi_product", legacyCache: true,
-  };
-}
-
-async function readCachedCards(): Promise<CachedCard[]> {
-  try {
-    return ((await getAll(ENTITY)) as unknown[]).map(cachedCard).filter((c): c is CachedCard => !!c);
-  } catch { return []; }
-}
-function writeCachedCards(list: Row[], snapshotCurrency?: string): void {
-  const writeGeneration = ++cacheWriteGeneration;
-  const snapshot = list.map(r => ({
-    ...r.card, subtitle: r.card.price,
-    cachePrice: r.price, cacheCreated: r.created, cacheName: r.name, cacheOptions: r.options, cacheCurrency: snapshotCurrency,
-  } as unknown as DbEntity));
-  cacheWriteQueue = cacheWriteQueue.then(async () => {
-    if (writeGeneration !== cacheWriteGeneration) return;
-    const cached = await getAll(ENTITY);
-    if (writeGeneration !== cacheWriteGeneration) return;
-    // Once a snapshot starts writing, finish it. A later complete snapshot queues behind
-    // it; switching or refreshing categories cannot strand a half-replaced catalog.
-    const keep = new Set(snapshot.map(row => row.id));
-    for (const row of snapshot) await upsert(ENTITY, row);
-    for (const item of cached) if (!keep.has(item.id)) await remove(ENTITY, item.id);
-  }).catch(() => { /* capability not granted → online-only */ });
-}
-
 function derive(s: S): S {
   // The field keeps exactly what the shopper typed (a trailing space included); the match trims.
   const typed = s.query.trim();
@@ -222,6 +175,9 @@ function derive(s: S): S {
   const next = applyFacets(s, q ? rows.filter((r) => r.name.includes(q)) : rows, currency);
   const n = next.matched;
   const ready = s.status === "ready";
+  const readMessage = !s.readStatus.hasSnapshot && s.readStatus.offline
+    ? "This content isn’t available offline. Connect to load it."
+    : s.readStatus.error || "";
   const choices = [{ id: ALL, label: copyParam("shop.allChip", "All") }, ...categories.map((c) => ({ id: c.id, label: c.name }))];
   return {
     ...next,
@@ -229,7 +185,9 @@ function derive(s: S): S {
     notLoading: s.status !== "loading",
     isErrored: s.status === "error",
     notErrored: s.status !== "error",
-    noOffline: !s.fromCache,
+    // The shared shell owns offline/stale messages; this former local-DB note stays hidden.
+    noOffline: true,
+    readMessage, noReadMessage: !readMessage, hasReadMessage: !!readMessage,
     categoryOptions: choices.map((c) => option(c, c.id === s.categorySelected)),
     hideCategories: categories.length === 0,
     countLabel: ready ? countText(n) : "",
@@ -244,8 +202,94 @@ function derive(s: S): S {
   };
 }
 
-async function fetchPage(category: string, cursor?: string) {
-  return searchStoreProducts({ limit: PAGE, ...(category !== ALL ? { categoryId: category } : {}), ...(cursor ? { cursor } : {}) });
+/** Every content/price projection reads the active controller, not an older load's skeleton. */
+function currentReadState(state: S): S {
+  const controller = readers.get(selectedCategory);
+  if (!controller) return derive(state);
+  const readStatus = controller.getStatus();
+  return derive({ ...state, readStatus, categorySelected: selectedCategory, scopeGen: generation,
+    fromCache: readStatus.fromCache || readStatus.offline && readStatus.hasSnapshot,
+    status: readStatus.hasSnapshot ? "ready" : readStatus.error || readStatus.offline ? "error" : "loading" });
+}
+
+async function fetchPage(category: string, cursor?: string, options?: WixCallOptions) {
+  return searchStoreProducts({ limit: PAGE, ...(category !== ALL ? { categoryId: category } : {}), ...(cursor ? { cursor } : {}) }, options);
+}
+
+function combinedMetadata(a: ReadMetadata | undefined, b: ReadMetadata): ReadMetadata {
+  return !a ? b : { source: b.source, fetchedAt: Math.min(a.fetchedAt, b.fetchedAt),
+    cacheable: a.cacheable && b.cacheable,
+    expiresAt: a.expiresAt === undefined || b.expiresAt === undefined ? undefined : Math.min(a.expiresAt, b.expiresAt) };
+}
+
+async function readPolicyScope(category: string, cache: 'only-if-cached' | 'reload', depth: number): Promise<{ data: ScopeSnapshot; metadata: ReadMetadata }> {
+  const list: Row[] = [], seen = new Set<string>(), cursors = new Set<string>();
+  let metadata: ReadMetadata | undefined, cursor: string | undefined, scopeCurrency: string | undefined, total: number | undefined;
+  let hasPage = false;
+  do {
+    let pageMetadata: ReadMetadata | undefined;
+    let res: Awaited<ReturnType<typeof fetchPage>>;
+    try { res = await fetchPage(category, cursor, { cache, onCacheResult: value => { pageMetadata = value; } }); }
+    catch (error) {
+      // A later cache miss is an honest partial snapshot; it never sends a request.
+      if (cache === 'only-if-cached' && hasPage && /OFFLINE_CACHE_MISS/.test(String(error))) break;
+      throw error;
+    }
+    if (!pageMetadata) throw new Error('READ_LIFECYCLE_UNSUPPORTED: update the Himalaya runtime');
+    hasPage = true; metadata = combinedMetadata(metadata, pageMetadata);
+    const products = res.products ?? [];
+    scopeCurrency ??= products.map(currencyOf).find(Boolean);
+    total = Math.max(total ?? 0, res.pagingMetadata?.total ?? 0);
+    const added = toRows(products).filter(row => { if (seen.has(row.card.id)) return false; seen.add(row.card.id); return true; });
+    list.push(...added.slice(0, MAX_PRODUCTS - list.length));
+    cursor = res.pagingMetadata?.cursors?.next || undefined;
+    if (cursor && (!added.length || cursors.has(cursor) || cursors.size >= 100)) throw new Error('Product pagination did not advance');
+    if (cursor) cursors.add(cursor);
+    // A refresh stages fresh cursors to the depth the shopper has already loaded.
+    depth = Math.max(depth, cache === 'reload' ? scopes.get(category)?.rows.length ?? 0 : 0);
+  } while (cursor && list.length < Math.min(depth, MAX_PRODUCTS));
+  const data: ScopeSnapshot = { rows: list, complete: !cursor && list.length >= Math.min(total ?? 0, MAX_PRODUCTS),
+    loading: !!cursor, cursor, currency: scopeCurrency, total, fromCache: cache === 'only-if-cached', metadata: metadata! };
+  return { data, metadata: metadata! };
+}
+
+function publishRead(category: string, data: ScopeSnapshot | undefined, status: ReadStatus): void {
+  if (data) { data.fromCache = status.fromCache || status.offline; scopes.set(category, data); }
+  else scopes.delete(category);
+  if (category !== selectedCategory) return;
+  rows = data?.rows ?? []; currency = data?.currency;
+  const gen = generation, version = (publicationVersions.get(category) ?? 0) + 1;
+  publicationVersions.set(category, version);
+  const publication = (async () => {
+    await committed(gen);
+    if (gen !== generation || category !== selectedCategory || publicationVersions.get(category) !== version) return;
+    await svc.readChanged({ gen, category, readStatus: status });
+  })();
+  publications.set(category, publication);
+}
+
+function clearOnReadDenial(error: unknown, category: string): boolean {
+  if (!/HTTP (401|403)|PRINCIPAL_CHANGED/.test(String(error))) return false;
+  auxiliaryVersion++; categoryReadVersion++;
+  categories = []; categoriesAuthoritative = false; pendingCategoriesRead = undefined;
+  loadedCartCount = 0; pendingAuxiliary = undefined;
+  pendingScopes.clear(); pendingRefreshScopes.clear();
+  for (const [key, controller] of readers) if (key !== category) controller.invalidate();
+  return true;
+}
+
+function reader(category: string) {
+  let value = readers.get(category);
+  if (!value) {
+    value = createReadController<ScopeSnapshot>({
+      cached: key => readPolicyScope(key, 'only-if-cached', MAX_PRODUCTS),
+      fetch: key => readPolicyScope(key, 'reload', scopes.get(key)?.rows.length ?? 0),
+      publish: (data, status) => publishRead(category, data, status),
+      clearOnError: error => clearOnReadDenial(error, category),
+    });
+    readers.set(category, value);
+  }
+  return value;
 }
 
 /** Fetch the rest of a scope in the background, a page at a time. A page that lands while
@@ -254,16 +298,22 @@ async function fetchRest(category: string, cursor: string): Promise<void> {
   let next: string | undefined = cursor;
   let failed = false;
   const scope = scopes.get(category);
-  if (!scope) return;
+  if (!scope || restFlights.has(scope)) return;
+  restFlights.add(scope);
+  const controller = reader(category);
+  let revision = controller.getRevision();
+  const current = () => scopes.get(category) === scope && controller.getRevision() === revision;
   const seenCursors = new Set<string>();
   const seenProducts = new Set(scope.rows.map(row => row.card.id));
   try {
     while (next && scope.rows.length < MAX_PRODUCTS) {
-      if (scopes.get(category) !== scope) return;
+      if (!current()) return;
       if (seenCursors.has(next) || seenCursors.size >= 100) throw new Error("Product pagination did not advance");
       seenCursors.add(next);
-      const res = await fetchPage(category, next);
-      if (scopes.get(category) !== scope) return;
+      let metadata: ReadMetadata | undefined;
+      const res = await fetchPage(category, next, { cache: 'reload', onCacheResult: value => { metadata = value; } });
+      if (!metadata) throw new Error('READ_LIFECYCLE_UNSUPPORTED');
+      if (!current()) return;
       const added = toRows(res.products ?? []).filter(row => {
         if (seenProducts.has(row.card.id)) return false;
         seenProducts.add(row.card.id);
@@ -273,14 +323,28 @@ async function fetchRest(category: string, cursor: string): Promise<void> {
       next = res.pagingMetadata?.cursors?.next ?? undefined;
       if (!added.length && next) throw new Error("Product pagination made no progress");
       scope.rows.push(...added.slice(0, MAX_PRODUCTS - scope.rows.length));
-      if (category === selectedCategory) await svc.scopeGrew();
+      scope.metadata = combinedMetadata(scope.metadata, metadata);
+      scope.cursor = next;
+      controller.replace({ data: scope, metadata: scope.metadata }, category);
+      revision = controller.getRevision();
+      if (category === selectedCategory) await publications.get(category);
       if (!next && seenProducts.size < Math.min(scope.total, MAX_PRODUCTS)) throw new Error("Product pagination is incomplete");
     }
-  } catch { failed = true; /* keep what arrived; pull to refresh tries again */ }
-  if (scopes.get(category) !== scope) return;
+  } catch (error) {
+    if (!current()) return;
+    failed = true;
+    if (clearOnReadDenial(error, category)) reader(category).invalidate();
+    else if (scopes.get(category) === scope) publishRead(category, scope, {
+      ...reader(category).getStatus(), stale: true, refreshing: false, error: "Couldn’t refresh. Content may be outdated.",
+    });
+  } finally {
+    restFlights.delete(scope);
+    if (!current() && scopes.get(category) === scope) scope.loading = false;
+  }
+  if (!current()) return;
   scope.complete = !failed;
   scope.loading = false;
-  if (!failed && category === ALL) writeCachedCards(scope.rows, scope.currency);
+
 }
 
 /** Wait, a bounded number of turns, until the action that started fetch `gen` has committed
@@ -311,77 +375,17 @@ async function publishAuxiliaryIfReady(): Promise<void> {
 /** Fetch `category`'s first page and hand it to `scopeLanded`. The action that started the
  *  fetch has already returned: a search, a sort or another chip the shopper picks meanwhile
  *  is current state, and a state captured before this await must never overwrite it. */
-async function fetchScope(category: string, gen: number, refresh = false): Promise<void> {
-  // A pull to refresh keeps what is on screen until the new page is in hand.
-  const shown = refresh ? scopes.get(category) : undefined;
+async function fetchScope(category: string, gen: number, _refresh = false): Promise<void> {
   try {
-    const res = await fetchPage(category);
-    if (gen !== generation) return;
-    if (pendingRefreshScopes.get(category) === gen) pendingRefreshScopes.delete(category);
-    const products: StoreProduct[] = res.products ?? [];
-    const cursor = res.pagingMetadata?.cursors?.next;
-    const loaded = toRows(products);
-    const total = res.pagingMetadata?.total;
-    // Keep partial live rows visible, but neither cache them nor suppress a later retry.
-    const complete = !cursor && new Set(loaded.map(row => row.card.id)).size >= Math.min(total ?? 0, MAX_PRODUCTS);
-    const scope = { rows: loaded, complete, loading: !!cursor, fromCache: false, currency: products.map(currencyOf).find(Boolean), total };
-    // Fresh data for this scope: every other scope refetches when the shopper next opens it.
-    if (refresh) scopes.clear();
-    scopes.set(category, scope);
-    rows = scope.rows;
-    currency = scope.currency ?? currency;
-    if (cursor) void fetchRest(category, cursor);
-    else if (scope.complete && category === ALL) writeCachedCards(scope.rows, scope.currency);
-    await committed(gen);
-    if (gen === generation) {
-      await svc.scopeLanded({ gen, category, status: "ready", fromCache: false });
-      await publishAuxiliaryIfReady();
-    }
-  } catch (error) {
-    if (gen !== generation) return;
-    if (pendingRefreshScopes.get(category) === gen) pendingRefreshScopes.delete(category);
-    if (shown) {
-      // A failed refresh is not a failed screen: the cards the shopper was looking at stay.
-      await committed(gen);
-      if (gen === generation) {
-        await svc.scopeLanded({ gen, category, status: "ready", fromCache: !!shown?.fromCache });
-        await publishAuxiliaryIfReady();
-      }
-      return;
-    }
-    // Offline: paint the last synced catalog — only for All, and never over an auth refusal.
-    const status = /HTTP (\d{3})/.exec(String(error))?.[1];
-    if (category === ALL && status !== "401" && status !== "403") {
-      const cached = await readCachedCards();
-      if (gen !== generation) return;
-      if (cached.length) {
-        const legacyCache = cached.some((card) => card.legacyCache || typeof card.cachePrice !== "number" || !card.cacheOptions);
-        rows = cached.map((card) => {
-          const stored = card;
-          currency ??= stored.cacheCurrency;
-          return {
-            card, price: Number.isFinite(stored.cachePrice) ? stored.cachePrice! : 0,
-            created: stored.cacheCreated ?? "", name: stored.cacheName ?? card.name.toLowerCase(), options: stored.cacheOptions ?? {},
-          };
-        });
-        scopes.set(category, { rows, complete: true, loading: false, fromCache: true, currency });
-        await committed(gen);
-        if (gen === generation) {
-          await svc.scopeLanded({ gen, category, status: "ready", fromCache: true, resetFacets: legacyCache && shouldResetLegacyCacheFacets() });
-          await publishAuxiliaryIfReady();
-        }
-        return;
-      }
-    }
-    rows = [];
-    await committed(gen);
-    if (gen === generation) {
-      await svc.scopeLanded({ gen, category, status: "error", fromCache: false });
-      await publishAuxiliaryIfReady();
-    }
+    const controller = reader(category);
+    await controller.load(category);
+    await publications.get(category);
+    const scope = scopes.get(category), status = controller.getStatus();
+    if (scope?.cursor && !status.fromCache && !status.error && !status.offline) void fetchRest(category, scope.cursor);
+    if (gen === generation) await publishAuxiliaryIfReady();
   } finally {
     if (pendingScopes.get(category) === gen) pendingScopes.delete(category);
-    if (gen === generation && pendingRefreshScopes.get(category) === gen) pendingRefreshScopes.delete(category);
+    if (pendingRefreshScopes.get(category) === gen) pendingRefreshScopes.delete(category);
   }
 }
 
@@ -390,11 +394,19 @@ async function fetchScope(category: string, gen: number, refresh = false): Promi
  *  refresh) fetches again but leaves the current cards up until the new page is in hand. */
 function showScope(s: S, category: string, refresh = false): S {
   const pending = pendingScopes.get(category);
-  if (!refresh && category === selectedCategory && pending === generation) {
-    return derive({ ...s, status: "loading", fromCache: false, categorySelected: category, scopeGen: generation });
+  const reactivating = category !== selectedCategory;
+  if (!refresh && !reactivating && pending === generation) {
+    const readStatus = reader(category).getStatus();
+    return derive({ ...s, readStatus, status: readStatus.hasSnapshot ? "ready" : readStatus.error || readStatus.offline ? "error" : "loading",
+      fromCache: readStatus.fromCache, categorySelected: category, scopeGen: generation });
   }
   const known = scopes.get(category);
-  const needsRefresh = refresh || pendingRefreshScopes.has(category) || (!!known && !known.complete && !known.loading);
+  const status = known ? reader(category).getStatus() : undefined;
+  const needsRefresh = refresh || pendingRefreshScopes.has(category) || (!!known && (
+    known.fromCache || status?.stale || !!status?.error ||
+    (known.metadata.expiresAt !== undefined && known.metadata.expiresAt <= Date.now()) ||
+    (!known.complete && !known.loading)
+  ));
   selectedCategory = category;
   const gen = ++generation;
   if (known) {
@@ -402,15 +414,22 @@ function showScope(s: S, category: string, refresh = false): S {
     currency = known.currency ?? currency;
   }
   if (known && !needsRefresh) {
-    return derive({ ...s, status: "ready", fromCache: !!known.fromCache, categorySelected: category, scopeGen: gen,
+    return derive({ ...s, readStatus: reader(category).getStatus(), status: "ready", fromCache: !!known.fromCache, categorySelected: category, scopeGen: gen,
       visible: PAGE_SIZE, cursorEpoch: s.cursorEpoch + 1 });
   }
   pendingScopes.set(category, gen);
   if (needsRefresh) pendingRefreshScopes.set(category, gen);
+  if (reactivating && pending !== undefined) {
+    // An earlier visit's hung refresh must not own this visit. Keep its snapshot while
+    // fencing that flight, then start a current request with fresh pagination cursors.
+    const controller = reader(category);
+    if (known) controller.replace({ data: known, metadata: known.metadata }, category);
+    else controller.invalidate();
+  }
   void fetchScope(category, gen, needsRefresh);
   const keep = needsRefresh && !!known && s.status === "ready";
-  return derive({ ...s, status: keep ? "ready" : "loading", categorySelected: category, scopeGen: gen,
-    ...(keep ? {} : { visible: PAGE_SIZE, cursorEpoch: s.cursorEpoch + 1 }) });
+  return derive({ ...s, readStatus: reader(category).getStatus(), status: keep ? "ready" : "loading", categorySelected: category, scopeGen: gen,
+    ...(keep && category === s.categorySelected ? {} : { visible: PAGE_SIZE, cursorEpoch: s.cursorEpoch + 1 }) });
 }
 
 /** The categories and the cart count, then `loaded` — which reads the state as it is when
@@ -584,27 +603,30 @@ async function load(s: S, arg?: unknown, fresh = false): Promise<S | undefined>
 const view = readViewPrefs();
 const BOOT: S = derive({
   ...FACETS_BOOT, ...view,
+  readStatus: initialReadStatus(), readMessage: "", noReadMessage: true, hasReadMessage: false,
   status: "loading", isLoading: true, notLoading: false, isErrored: false, notErrored: true, fromCache: false, noOffline: true,
   categorySelected: ALL, scopeGen: 0, query: "", categoryOptions: [], hideCategories: true,
   countLabel: "", noEmpty: true, emptyText: "", cartCount: 0,
 });
 
 const facets = facetActions<S>(derive);
-const CONTENT = ["load", "refresh", "retry", "loaded", "scopeLanded", "scopeGrew", "selectCategory", "search", "toggleSave", "loadMore", ...Object.keys(facets)];
+const CONTENT = ["readChanged", "load", "refresh", "retry", "loaded", "scopeLanded", "scopeGrew", "selectCategory", "search", "toggleSave", "loadMore", ...Object.keys(facets)];
 const register = withIapPresentation<S>({
   // Restored from the last run, these painted a state this boot has not reached: a count over
   // no cards, an open sheet, a stale scope generation that defeats `committed`, a search
   // narrowing the list under an empty field. The shopper's view, sort and filters do persist.
   prefix: "shop",
-  transientKeys: ["results", "query", "scopeGen", "status", "isLoading", "notLoading", "isErrored", "notErrored", "fromCache", "noOffline",
+  transientKeys: ["readStatus", "readMessage", "noReadMessage", "hasReadMessage", "results", "query", "scopeGen", "status", "isLoading", "notLoading", "isErrored", "notErrored", "fromCache", "noOffline",
     "countLabel", "noEmpty", "emptyText", "cartCount", "panel", "filtersOpen", "sortOpen", "categorySelected", "categoryOptions", "hideCategories",
     "sortOptions", "sortLabel", "filterLabel", "activeFilters", "noActiveFilters", "priceChips", "priceSelected", "hidePrice",
     "opt1Name", "opt1Chips", "opt1Selected", "hideOpt1", "opt2Name", "opt2Chips", "opt2Selected", "hideOpt2", "opt3Name", "opt3Chips", "opt3Selected", "hideOpt3",
     "visible", "cursorEpoch", "matched", "nextCursor", "noMore", "showLabel", "hideGrid", "hideList", "hideComfortable", "hideCompact"],
   contentActions: CONTENT,
   forcePriceRefreshActions: ["load", "refresh", "retry"],
-  items: (state) => state.results.map((row) => ({ reference: { kind: "storesProduct", id: row.id }, commerceDisplayPrice: row.commercePrice })),
-  present: (state, price, _allowed, appleIapOrResolving) => ({ ...state, results: state.results.map((row) => {
+  items: (state) => currentReadState(state).results.map((row) => ({ reference: { kind: "storesProduct", id: row.id }, commerceDisplayPrice: row.commercePrice })),
+  present: (state, price, _allowed, appleIapOrResolving) => {
+    const current = currentReadState(state);
+    return { ...current, results: current.results.map((row) => {
     const stored = row as typeof row & { commerceWasPrice?: string; commerceOnSale?: boolean };
     const wasPrice = stored.commerceWasPrice ?? row.wasPrice;
     const onSale = stored.commerceOnSale ?? row.onSale;
@@ -626,17 +648,30 @@ const register = withIapPresentation<S>({
       notOnSale: !onSale,
       noTagRow: !onSale && row.noSwatches,
     };
-  }) }),
+    }) };
+  },
 });
 
 type A = (s: S, arg?: unknown) => S | undefined | Promise<S | undefined>;
 const svc = register<S, Record<string, A>>("himiBrandedShop", {
   state: BOOT,
+  readLifecycle: { refreshAction: "recover", statusPath: "readStatus" },
   actions: {
     load: (s, arg) => load(s, arg),
     // Pull to refresh: the categories and the scope again, from Wix.
     refresh: (s, arg) => load(s, arg, true),
-    retry: (s) => showScope(s, s.categorySelected),
+    retry: (s) => showScope(s, s.categorySelected, true),
+    recover: async () => { await fetchScope(selectedCategory, generation, true); return undefined; },
+    readChanged: (s, arg) => {
+      if (!arg || typeof arg !== 'object') return undefined;
+      const value = arg as { gen: number; category: string; readStatus: ReadStatus };
+      if (value.gen !== generation || value.category !== selectedCategory) return undefined;
+      const status = value.readStatus;
+      return derive({ ...s, ...(loadedCartCount === undefined ? {} : { cartCount: loadedCartCount }), readStatus: status, fromCache: status.fromCache || status.offline && status.hasSnapshot,
+        status: status.hasSnapshot ? "ready" : status.error || status.offline ? "error" : "loading",
+        categorySelected: value.category, scopeGen: value.gen });
+    },
+    identityChanged: (s) => derive({ ...s, ...FACETS_BOOT, readStatus: initialReadStatus(), scopeGen: generation, cartCount: 0, status: "loading" }),
     // The categories and the cart count landed (load / refresh).
     loaded: (s, arg) => loadedState(s, arg),
     // The first page of the scope on screen landed, or failed.
@@ -657,7 +692,7 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
       categoryIntentVersion++;
       pendingLink = undefined;
       if (id !== ALL && !categories.some((c) => c.id === id)) return s;
-      selectedCategory = id;
+      // showScope compares the prior selection before committing the requested category.
       // categorySelected is committed with the tap (showScope), so a tap back to the chip
       // on screen while another category loads is a no-op on the right scope.
       if (id === s.categorySelected) return cancelsPendingRoute || refresh ? showScope(s, id, refresh) : s;
@@ -687,5 +722,13 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
   },
 });
 
+(globalThis as { himalaya?: { __subscribeReadLifecycle?(listener: (signal: string) => void): () => void } }).himalaya?.__subscribeReadLifecycle?.(signal => {
+  if (signal !== 'invalidate') return;
+  generation++; auxiliaryVersion++; categoryReadVersion++;
+  rows = []; currency = undefined; categories = []; categoriesAuthoritative = false;
+  scopes.clear(); pendingScopes.clear(); pendingRefreshScopes.clear();
+  loadedCartCount = 0; pendingAuxiliary = undefined; pendingCategoriesRead = undefined;
+  void svc.identityChanged();
+});
 svc.load();
 export { svc };