@wix/himalaya-cli 0.1619.0 → 0.1621.0

package/dist/cli.mjs

@@ -208648,13 +208648,19 @@ import { copyFileSync as copyFileSync3, mkdtempSync as mkdtempSync12, readFileSy
 import { tmpdir as tmpdir13 } from "node:os";
 import { basename as basename29, dirname as dirname66, join as join131, resolve as resolve93 } from "node:path";
 import { fileURLToPath as fileURLToPath39 } from "node:url";
-function parseVerdict(value2) {
+function parseVerdict(value2, captured) {
   const v2 = value2;
   if (!v2 || !VERDICTS.has(v2.design) || !VERDICTS.has(v2.parity) || !CONFIDENCE.has(v2.confidence) || !Array.isArray(v2.findings)) return null;
   for (const f2 of v2.findings) {
-    if (!f2 || !PANES.has(f2.surface) || typeof f2.region !== "string" || typeof f2.what !== "string") return null;
+    if (!f2 || !PANES.has(f2.surface) || !KINDS2.has(f2.kind) || typeof f2.region !== "string" || typeof f2.what !== "string") return null;
   }
-  return { verdict: worse(v2.design, v2.parity), design: v2.design, parity: v2.parity, findings: v2.findings, confidence: v2.confidence };
+  const findings = captured ? v2.findings.filter((f2) => captured.has(f2.surface)) : v2.findings;
+  const blank = (panes) => findings.some((f2) => f2.kind === "blank" && panes.includes(f2.surface));
+  const onlySkipped = (panes) => findings.length < v2.findings.length && v2.findings.some((f2) => panes.includes(f2.surface)) && !findings.some((f2) => panes.includes(f2.surface));
+  const own6 = (said, panes) => (said === "partial" || said === "mismatch") && onlySkipped(panes) ? "match" : said;
+  const design = blank(["web"]) ? worse(v2.design, "mismatch") : own6(v2.design, ["web"]);
+  const parity = blank(["ios", "android"]) ? worse(v2.parity, "mismatch") : own6(v2.parity, ["ios", "android"]);
+  return { verdict: worse(design, parity), design, parity, findings, confidence: v2.confidence };
 }
 function judgeArgs(schema2) {
   return [
@@ -208710,14 +208716,14 @@ async function judgeStrip(strip3, screen, variant, opts = {}) {
   } catch {
     return cannotTell("the judge's answer was not JSON");
   }
-  return parseVerdict(parsed) ?? cannotTell("the judge's answer did not match tools/judges/fidelity/verdict.schema.json");
+  return parseVerdict(parsed, opts.captured) ?? cannotTell("the judge's answer did not match tools/judges/fidelity/verdict.schema.json");
 }
-var SOURCE_JUDGE_DIR, JUDGE_MODEL, spawnProcess, cannotTell, SEVERITY, worse, VERDICTS, CONFIDENCE, PANES;
+var SOURCE_JUDGE_DIR, JUDGE_MODEL, spawnProcess, cannotTell, SEVERITY, worse, VERDICTS, CONFIDENCE, PANES, KINDS2;
 var init_judge = __esm({
   "src/fidelity/judge.ts"() {
     init_define_HHP_CATALOG();
     SOURCE_JUDGE_DIR = resolve93(dirname66(fileURLToPath39(import.meta.url)), "../../../judges/fidelity");
-    JUDGE_MODEL = "sonnet";
+    JUDGE_MODEL = "claude-sonnet-5-5";
     spawnProcess = (cmd, args, { cwd, input, timeoutMs }) => new Promise((done) => {
       let stdout = "", stderr = "", timedOut = false;
       const child = spawn7(cmd, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
@@ -208745,6 +208751,7 @@ var init_judge = __esm({
     VERDICTS = /* @__PURE__ */ new Set(["match", "partial", "mismatch", "cannot_tell"]);
     CONFIDENCE = /* @__PURE__ */ new Set(["low", "medium", "high"]);
     PANES = /* @__PURE__ */ new Set(["web", "ios", "android"]);
+    KINDS2 = /* @__PURE__ */ new Set(["blank", "missing", "colour", "clipping", "order", "type_scale"]);
   }
 });
 
@@ -209005,8 +209012,8 @@ async function runFidelity(root, opts = {}) {
             verdict = skippedJudge(!w2?.file ? "no web render, and web is the reference for both design and parity" : frames.some((f2) => f2.noReference) ? `the mockup does not style ${variant}, and there is no native pane to compare with web` : "fewer than two captured panes, so there is nothing to compare");
           } else {
             stripFile = await strip3(judged2, stripPath2);
-            verdict = await judge(stripFile, screen, variant, opts.judgeDir ? { judgeDir: opts.judgeDir } : {});
             const captured = new Set(frames.filter((f2) => f2.file).map((f2) => f2.surface));
+            verdict = await judge(stripFile, screen, variant, { captured, ...opts.judgeDir ? { judgeDir: opts.judgeDir } : {} });
             const parity = captured.has("ios") || captured.has("android") ? verdict.parity : "cannot_tell";
             verdict = { ...verdict, parity, verdict: worse(verdict.design, parity), findings: verdict.findings.filter((f2) => captured.has(f2.surface)) };
           }
@@ -209067,18 +209074,25 @@ var init_run2 = __esm({
 // src/fidelity/native.ts
 var native_exports = {};
 __export(native_exports, {
+  BLANK_CONTRAST: () => BLANK_CONTRAST,
   defaultRunner: () => defaultRunner3,
   deviceFor: () => deviceFor,
   nativeCapture: () => nativeCapture,
   parseAppLocales: () => parseAppLocales,
   parseNightMode: () => parseNightMode,
   parsePlistArray: () => parsePlistArray,
+  resumedPackages: () => resumedPackages,
   sameLocalOrigin: () => sameLocalOrigin,
   screenLink: () => screenLink
 });
 import { spawn as spawn9 } from "node:child_process";
 import { readFileSync as readFileSync143, writeFileSync as writeFileSync60 } from "node:fs";
 import { join as join135 } from "node:path";
+function resumedPackages(dumpsys) {
+  const lines = dumpsys.split("\n").filter((l2) => /\b(?:topResumedActivity|mResumedActivity|ResumedActivity)\b/.test(l2));
+  if (!lines.length) return void 0;
+  return lines.flatMap((l2) => [...l2.matchAll(/\s([A-Za-z0-9_.]+)\/[A-Za-z0-9_.$]+/g)].map((m2) => m2[1]));
+}
 function deviceFor(devices, platform, variant) {
   if (variant === "tablet") return platform === "ios" ? devices.iosTablet : devices.androidTablet;
   return platform === "ios" ? devices.ios : devices.android;
@@ -209100,12 +209114,18 @@ function nativeCapture(devices, opts) {
   const maxWaitMs = opts.maxWaitMs ?? 3e4;
   const iosBundle = opts.iosBundleId ?? "dev.himalaya.player.dev";
   const androidPackage = opts.androidPackage ?? "dev.himalaya.player.dev";
+  const packages = /* @__PURE__ */ new Map();
   const rtl = opts.rtlLanguage ?? "he";
   const picker = opts.pickerAppId ?? "himi-player";
   const blackFraction = opts.blackFraction ?? (async (file2) => {
     const r3 = await run2("magick", [file2, "-colorspace", "Gray", "-threshold", "5%", "-format", "%[fx:1-mean]", "info:"]);
     return r3.code === 0 ? Number(r3.stdout.toString().trim()) || 0 : 0;
   });
+  const contrast = opts.contrast ?? (async (file2) => {
+    const r3 = await run2("magick", [file2, "-gravity", "South", "-crop", "100%x90%+0+0", "+repage", "-colorspace", "Gray", "-format", "%[fx:standard_deviation]", "info:"]);
+    const v2 = r3.code === 0 ? Number.parseFloat(r3.stdout.toString()) : NaN;
+    return Number.isFinite(v2) ? v2 : 1;
+  });
   const saved = /* @__PURE__ */ new Map();
   const applied = /* @__PURE__ */ new Map();
   const originChecked = /* @__PURE__ */ new Map();
@@ -209114,6 +209134,18 @@ function nativeCapture(devices, opts) {
     if (r3.code !== 0) throw new Error(`${cmd} ${args.join(" ")} exited ${r3.code}`);
     return r3.stdout.toString().trim();
   };
+  async function playerPackage(id) {
+    const known = packages.get(id);
+    if (known) return known;
+    let pkg = androidPackage;
+    if (!opts.androidPackage) {
+      const r3 = await run2("adb", ["-s", id, "shell", "pm", "list", "packages", androidPackage]);
+      const listed = r3.code === 0 ? r3.stdout.toString().split("\n").map((l2) => l2.trim().replace(/^package:/, "")).filter(Boolean) : [];
+      pkg = listed.includes(androidPackage) ? androidPackage : listed.find((l2) => l2.startsWith(`${androidPackage}.`)) ?? androidPackage;
+    }
+    packages.set(id, pkg);
+    return pkg;
+  }
   async function remember(platform, id) {
     const key3 = `${platform}:${id}`;
     if (saved.has(key3)) return;
@@ -209123,7 +209155,7 @@ function nativeCapture(devices, opts) {
       saved.set(key3, { appearance, language: languages.code === 0 ? languages.stdout.toString().trim() : void 0 });
     } else {
       const night = await ok3("adb", ["-s", id, "shell", "cmd", "uimode", "night"]);
-      const locales = await run2("adb", ["-s", id, "shell", "cmd", "locale", "get-app-locales", androidPackage]);
+      const locales = await run2("adb", ["-s", id, "shell", "cmd", "locale", "get-app-locales", await playerPackage(id)]);
       saved.set(key3, { appearance: parseNightMode(night), language: locales.code === 0 ? parseAppLocales(locales.stdout.toString()) : void 0 });
     }
   }
@@ -209140,7 +209172,7 @@ function nativeCapture(devices, opts) {
     } else {
       await ok3("adb", ["-s", id, "shell", "cmd", "uimode", "night", dark ? "yes" : "no"]);
       const wasRtl = applied.get(key3) === "rtl";
-      if (right || wasRtl) await ok3("adb", ["-s", id, "shell", "cmd", "locale", "set-app-locales", androidPackage, "--locales", right ? rtl : ""]);
+      if (right || wasRtl) await ok3("adb", ["-s", id, "shell", "cmd", "locale", "set-app-locales", await playerPackage(id), "--locales", right ? rtl : ""]);
     }
     applied.set(key3, want);
   }
@@ -209169,19 +209201,31 @@ function nativeCapture(devices, opts) {
     writeFileSync60(file2, r3.stdout);
     return r3.stdout;
   }
+  async function notInFront(platform, id) {
+    if (platform !== "android") return "";
+    const r3 = await run2("adb", ["-s", id, "shell", "dumpsys", "activity", "activities"]);
+    const resumed = r3.code === 0 ? resumedPackages(r3.stdout.toString()) : void 0;
+    const player = await playerPackage(id);
+    return !resumed || resumed.includes(player) ? "" : `the Player was not in front (${resumed.join(", ") || "nothing resumed"})`;
+  }
   async function settle2(platform, id, file2, notFrame) {
     let previous;
+    let why = "the screen did not stop changing";
     for (let waited = 0; ; waited += settleMs) {
       const frame = await screenshot(platform, id, file2);
-      if (previous && frame.equals(previous) && !(notFrame && frame.equals(notFrame))) return frame;
-      if (waited >= maxWaitMs) return frame;
+      if (previous && frame.equals(previous)) {
+        const front = await notInFront(platform, id);
+        why = notFrame && frame.equals(notFrame) ? "the Player still showed the picker" : front ? front : await contrast(file2) < BLANK_CONTRAST ? "the screen was still blank or loading" : "";
+        if (!why) return { frame };
+      } else why = "the screen did not stop changing";
+      if (waited >= maxWaitMs) return { frame, unsettled: `${why} within ${Math.round(maxWaitMs / 1e3)}s` };
       previous = frame;
       await sleep(settleMs);
     }
   }
   async function open(platform, id, link) {
     if (platform === "ios") await ok3("xcrun", ["simctl", "openurl", id, link]);
-    else await ok3("adb", ["-s", id, "shell", "am", "start", "-W", "-a", "android.intent.action.VIEW", "-d", `'${link.replace(/'/g, "%27")}'`]);
+    else await ok3("adb", ["-s", id, "shell", "am", "start", "-W", "-a", "android.intent.action.VIEW", "-p", await playerPackage(id), "-d", `'${link.replace(/'/g, "%27")}'`]);
   }
   const capture = (async (screen, entry, variant, outDir) => {
     const frames = [];
@@ -209205,11 +209249,19 @@ function nativeCapture(devices, opts) {
         await apply(platform, id, variant);
         await open(platform, id, `himi://app/${encodeURIComponent(picker)}`);
         const file2 = join135(outDir, `${screen}.${variant}.${platform}.png`);
-        const pickerFrame = await settle2(platform, id, file2);
+        const pickerFrame = (await settle2(platform, id, file2)).frame;
         await open(platform, id, screenLink(opts.appId, screen, entry, opts.release));
-        await settle2(platform, id, file2, pickerFrame);
+        const { unsettled } = await settle2(platform, id, file2, pickerFrame);
+        if (unsettled) {
+          frames.push({ surface: platform, screen, variant, skipped: { reason: `capture_unsettled: ${unsettled}` } });
+          continue;
+        }
         if (platform === "android" && await blackFraction(file2) > 0.95) {
-          await settle2(platform, id, file2);
+          const retry = await settle2(platform, id, file2, pickerFrame);
+          if (retry.unsettled) {
+            frames.push({ surface: platform, screen, variant, skipped: { reason: `capture_unsettled: ${retry.unsettled}` } });
+            continue;
+          }
           if (await blackFraction(file2) > 0.95) {
             frames.push({ surface: platform, screen, variant, skipped: { reason: "black frame" } });
             continue;
@@ -209233,7 +209285,7 @@ function nativeCapture(devices, opts) {
           await run2("xcrun", ["simctl", "terminate", id, iosBundle]);
         } else {
           if (was.appearance) await run2("adb", ["-s", id, "shell", "cmd", "uimode", "night", was.appearance]);
-          await run2("adb", ["-s", id, "shell", "cmd", "locale", "set-app-locales", androidPackage, "--locales", was.language ?? ""]);
+          await run2("adb", ["-s", id, "shell", "cmd", "locale", "set-app-locales", packages.get(id) ?? androidPackage, "--locales", was.language ?? ""]);
         }
       } catch {
       }
@@ -209265,10 +209317,11 @@ function parseAppLocales(out2) {
 function parsePlistArray(out2) {
   return out2.replace(/^\s*\(|\)\s*$/g, "").split(",").map((s2) => s2.trim().replace(/^"|"$/g, "")).filter(Boolean);
 }
-var defaultRunner3;
+var BLANK_CONTRAST, defaultRunner3;
 var init_native = __esm({
   "src/fidelity/native.ts"() {
     init_define_HHP_CATALOG();
+    BLANK_CONTRAST = 0.03;
     defaultRunner3 = (cmd, args) => new Promise((resolve95) => {
       const child = spawn9(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
       const chunks = [];
@@ -215542,16 +215595,16 @@ WHAT A PATCH DOES NOT CARRY \u2014 all reported in the output, never silent
 async function patchCommand(ctx) {
   const { io: io2, pos, flags, client: client2, runReleasePatch, patchBlastRadius } = ctx;
   const PATCH_USAGE = "himi patch screen <id> --file <d.json> | bundle --file <b.js> (--for-screen <id>[,<id>]|--no-rebind) | tokens --file <t.json> | app-config --file <c.json> ; --app <a> (--draft|--live) [--from-release <id>] [--accept-regressions] [--notes <t>]";
-  const KINDS2 = ["screen", "bundle", "tokens", "app-config"];
+  const KINDS3 = ["screen", "bundle", "tokens", "app-config"];
   if (flags.help === true) {
     io2.log(PATCH_HELP);
     return 0;
   }
   const kind = pos[1];
-  if (!kind || !KINDS2.includes(kind)) {
+  if (!kind || !KINDS3.includes(kind)) {
     io2.error(JSON.stringify({
       error: kind ? `unknown patch kind "${kind}"` : "patch needs a <kind>",
-      kinds: KINDS2,
+      kinds: KINDS3,
       usage: PATCH_USAGE
     }));
     return 2;

package/guides/hhp.md

@@ -218,7 +218,7 @@ himi fidelity --content <dir> [--screen a,b] [--variant light,dark,rtl,tablet] [
 For each screen and variant (`light`, `dark`, `rtl`, `tablet`), the command does four things:
 
 1. **Captures the mockup.** It draws the page in Chromium at the variant's width. Dark mode is drawn by emulating `prefers-color-scheme`. RTL is drawn by setting `dir=rtl` on the page.
-2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the app's right-to-left language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` or `--serve <port>` the Player shows the app's **live** release, not your working copy. `--serve <port>` serves the working copy on `127.0.0.1:<port>` as `himi run` does, so native and web render the same release. The Player reads a local origin only from a Debug build that compiled it in (see [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device)): build it with `HIMALAYA_API_BASE_URL_INFO=http://127.0.0.1:<port>` on iOS and `-PhimalayaDevServeBaseUrl=http://10.0.2.2:<port>` on Android. An iOS device whose Player reads another origin is skipped with the rebuild to run. Android's origin cannot be read back from the installed app, so check that build yourself. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
+2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the app's right-to-left language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match, the frame is not a blank or loading page, and, on Android, the Player is the app in front rather than the launcher. A screen that has not settled that way after 30 seconds is reported `skipped` as `capture_unsettled`, never judged. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` or `--serve <port>` the Player shows the app's **live** release, not your working copy. `--serve <port>` serves the working copy on `127.0.0.1:<port>` as `himi run` does, so native and web render the same release. The Player reads a local origin only from a Debug build that compiled it in (see [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device)): build it with `HIMALAYA_API_BASE_URL_INFO=http://127.0.0.1:<port>` on iOS and `-PhimalayaDevServeBaseUrl=http://10.0.2.2:<port>` on Android. An iOS device whose Player reads another origin is skipped with the rebuild to run. Android's origin cannot be read back from the installed app, so check that build yourself. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
 3. **Scores mockup↔web** with ImageMagick SSIM, globally and per tile. The worst tile says where the screens differ most.
 4. **Asks a fresh model** two questions, using the repo's fidelity judge prompt. The model never ran in the session that wrote the app.
    - **Design:** does WEB look like the MOCKUP? This judges the port.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1619.0",
+  "version": "0.1621.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "d9d834feab74f884aec00e986ae13ed5dcb2f5fea15f6ea9ac2e5796"
+  "falconPackageHash": "c21c6aa4541e5ed5dda0d5f14934ad131349b6f6f125a9d5ff58315a"
 }

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

@@ -652,6 +652,20 @@ const register = withIapPresentation<S>({
   },
 });
 
+/** A read that answers at once (a cache, a local fixture, a headless run whose transport never
+ *  suspends) is over before the action that started it returns. Its `readChanged` is a dispatch
+ *  of this same service from a detached job, which a headless run never services after the active
+ *  action returns, and which on a device would commit under the skeleton the action is about to
+ *  return. Wait a bounded number of turns and fold the settled status into the action's own
+ *  result instead; a read that is still in flight keeps the skeleton and lands through
+ *  `readChanged` as before. `undefined` means a newer action took over while this one waited. */
+async function settledWithin(next: S, category: string, gen: number): Promise<S | undefined> {
+  const controller = reader(category);
+  for (let i = 0; i < 500 && controller.getStatus().refreshing; i++) await Promise.resolve();
+  if (gen !== generation) return undefined;
+  return controller.getStatus().refreshing ? next : currentReadState(next);
+}
+
 type A = (s: S, arg?: unknown) => S | undefined | Promise<S | undefined>;
 const svc = register<S, Record<string, A>>("himiBrandedShop", {
   state: BOOT,
@@ -659,8 +673,12 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
   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, true),
+    refresh: async (s, arg) => {
+      const next = await load(s, arg, true);
+      // The result owns its scope; another action may have changed the globals during load.
+      return next ? settledWithin(next, next.categorySelected, next.scopeGen) : undefined;
+    },
+    retry: (s) => settledWithin(showScope(s, s.categorySelected, true), s.categorySelected, generation),
     recover: async () => { await fetchScope(selectedCategory, generation, true); return undefined; },
     readChanged: (s, arg) => {
       if (!arg || typeof arg !== 'object') return undefined;
@@ -683,7 +701,7 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
     // A background page landed for the current scope.
     scopeGrew: (s) => derive(s),
     // Single-select: one chip is always chosen.
-    selectCategory: (s, arg) => {
+    selectCategory: async (s, arg) => {
       // The chip row sends { selectedIds }; a deselected chip falls back to All.
       const selection = arg as { selectedIds?: unknown; refresh?: boolean } | undefined;
       const id = selection?.selectedIds !== undefined ? selected(arg)[0] ?? ALL : idOf(arg);
@@ -691,12 +709,15 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
       const cancelsPendingRoute = !!pendingLink || selectedCategory !== id;
       categoryIntentVersion++;
       pendingLink = undefined;
-      if (id !== ALL && !categories.some((c) => c.id === id)) return s;
+      // undefined, not s: s is the snapshot from before any in-flight load, loading flag included.
+      if (id !== ALL && !categories.some((c) => c.id === id)) return undefined;
       // 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;
-      const next = showScope(s, id, refresh);
+      if (id === s.categorySelected) return cancelsPendingRoute || refresh ? settledWithin(showScope(s, id, refresh), id, generation) : undefined;
+      const shown = showScope(s, id, refresh);
+      const next = await settledWithin(shown, id, generation);
+      if (!next) return undefined;
       const pending = pendingAuxiliary;
       if (pending && pending.version === auxiliaryVersion && pending.cartCount >= 0) {
         pendingAuxiliary = undefined;

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

@@ -652,6 +652,20 @@ const register = withIapPresentation<S>({
   },
 });
 
+/** A read that answers at once (a cache, a local fixture, a headless run whose transport never
+ *  suspends) is over before the action that started it returns. Its `readChanged` is a dispatch
+ *  of this same service from a detached job, which a headless run never services after the active
+ *  action returns, and which on a device would commit under the skeleton the action is about to
+ *  return. Wait a bounded number of turns and fold the settled status into the action's own
+ *  result instead; a read that is still in flight keeps the skeleton and lands through
+ *  `readChanged` as before. `undefined` means a newer action took over while this one waited. */
+async function settledWithin(next: S, category: string, gen: number): Promise<S | undefined> {
+  const controller = reader(category);
+  for (let i = 0; i < 500 && controller.getStatus().refreshing; i++) await Promise.resolve();
+  if (gen !== generation) return undefined;
+  return controller.getStatus().refreshing ? next : currentReadState(next);
+}
+
 type A = (s: S, arg?: unknown) => S | undefined | Promise<S | undefined>;
 const svc = register<S, Record<string, A>>("himiBrandedShop", {
   state: BOOT,
@@ -659,8 +673,12 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
   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, true),
+    refresh: async (s, arg) => {
+      const next = await load(s, arg, true);
+      // The result owns its scope; another action may have changed the globals during load.
+      return next ? settledWithin(next, next.categorySelected, next.scopeGen) : undefined;
+    },
+    retry: (s) => settledWithin(showScope(s, s.categorySelected, true), s.categorySelected, generation),
     recover: async () => { await fetchScope(selectedCategory, generation, true); return undefined; },
     readChanged: (s, arg) => {
       if (!arg || typeof arg !== 'object') return undefined;
@@ -683,7 +701,7 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
     // A background page landed for the current scope.
     scopeGrew: (s) => derive(s),
     // Single-select: one chip is always chosen.
-    selectCategory: (s, arg) => {
+    selectCategory: async (s, arg) => {
       // The chip row sends { selectedIds }; a deselected chip falls back to All.
       const selection = arg as { selectedIds?: unknown; refresh?: boolean } | undefined;
       const id = selection?.selectedIds !== undefined ? selected(arg)[0] ?? ALL : idOf(arg);
@@ -691,12 +709,15 @@ const svc = register<S, Record<string, A>>("himiBrandedShop", {
       const cancelsPendingRoute = !!pendingLink || selectedCategory !== id;
       categoryIntentVersion++;
       pendingLink = undefined;
-      if (id !== ALL && !categories.some((c) => c.id === id)) return s;
+      // undefined, not s: s is the snapshot from before any in-flight load, loading flag included.
+      if (id !== ALL && !categories.some((c) => c.id === id)) return undefined;
       // 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;
-      const next = showScope(s, id, refresh);
+      if (id === s.categorySelected) return cancelsPendingRoute || refresh ? settledWithin(showScope(s, id, refresh), id, generation) : undefined;
+      const shown = showScope(s, id, refresh);
+      const next = await settledWithin(shown, id, generation);
+      if (!next) return undefined;
       const pending = pendingAuxiliary;
       if (pending && pending.version === auxiliaryVersion && pending.cartCount >= 0) {
         pendingAuxiliary = undefined;