@wix/himalaya-cli 0.1441.0 → 0.1443.0

package/guides/hhp.md

@@ -15,6 +15,10 @@ himi hhp init home --content .
 himi run --watch --content .
 ```
 
+To see the compiled screens on an iOS Simulator or Android emulator, build Himi Player
+against your machine and open the package with `himi run --content . --port <port>`; the
+four-step recipe is in [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device).
+
 Choose a new screen id if `home` is already registered. Repo targets accept
 `--app <name>` instead. The scaffold contains `screens/home.html`, `home.css`, and
 `home.controller.ts`. `hhp.json` declares sources:

package/guides/himi-json-output.md

@@ -72,7 +72,7 @@ keeps its existing fields and adds the code:
 | `invalid_patch` | The selection cannot produce a valid patch. The existing `error` and plan details are preserved. |
 | `would_regress` | A partial push would revert unselected live changes. |
 | `not_carried_by_patch` | The package changed dependencies that a partial push cannot carry. |
-| `authoring_unavailable` | The bundled authoring runtime failed to load. |
+| `authoring_unavailable` | The bundled authoring runtime failed to load. Carries `cause` (the underlying error's message) and `module` (the import specifier that failed) when known, and `sourceCheckout`: when run from a source checkout the advice is `fix: "yarn install"` (stale dependencies), off-repo it is `upgrade` (an out-of-date CLI). |
 | `push_failed` | An otherwise unclassified exception stopped push (for example unreadable content). The original error is preserved. |
 
 The `ux_evidence_*` codes map to the existing typed `uxEvidence.state`; a successful

package/guides/himi-test.md

@@ -124,7 +124,8 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `nav-target-missing` | **warning** | A `himi.open` whose target is neither a baked screen, nor one of the app's declared `linkableScreens`, nor an instance of one (`course_detail_c1` under the base `course_detail`) — the tap opens nothing. Only judged when the caller supplies the app's exact linkable set; an absent set means no opinion, never a guess. A target still carrying an **unresolved** `$` token is dropped before it becomes an edge and is never judged — but one that RESOLVED to a concrete id is judged, which is the point: `$item.detailScreenId` resolving to `course_detail_c1` against the first row is exactly the case the instance rule exists for. |
 | `poll-action-missing` | error | A `_poll` directive every host will silently ignore — an action the bundle never declares, a malformed `action`, a missing `id`, or a non-positive `intervalMs`. Each ends the same way: a screen that never refreshes, with nothing saying why. Nothing in the descriptor names the polled action, so no static check can see it. (A merely too-small interval is legal — the host clamps it.) |
 | `no-request-issued` | **warning** | A worker that uses the Wix transport but never fetches — "the screen loaded with sample data." A warning: a conditional or tap-triggered fetch is legitimate. |
-| `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (one bad enum blanks the whole screen on device). |
+| `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (one bad enum blanks the whole screen on device) — or the release's `tokens.json`, reported with `screen: "tokens.json"`: both natives decode it in one strict pass, so a single fractional `typography.*.size` or a `motions.*.duration` written in seconds drops the whole theme. A token finding fails the run but never counts as a failed screen. |
+| `token-type-invalid` | error | The package's tokens file holds a value a native `Int` field rejects — `typography.<k>.size` or `.weight`, `motions.<k>.duration` (milliseconds: `0.3` → `300`), or a `spacing` / `radius` entry — in the base document or any `idiom.<overlay>`. Both natives decode tokens.json in one strict pass, so one such value drops the WHOLE theme (iOS "Theme unavailable"; Android default palette and fonts) while the web preview looks right. Reported with `screen: "tokens.json"`, never counted as a failed screen; `himi validate` reports the same finding. |
 | `capability-undeclared` | error | A `capability.<id>.<verb>` call the screen's gate denied — reported from the gate itself, so it is raised **even when the worker catches the rejection** (which on device leaves a control that silently does nothing). Fix: declare the id on that screen's `logicBundle.declaredCapabilities` and in `config.ts` `capabilities`. One per capability per screen. See [Capabilities](#capabilities). |
 | `journey-failed` | error | A `himi-test.json` journey named an action the screen lacks, threw, or never rendered its `expectText`. |
 | `inverse-pair-diverges` | **warning** | An action and the action that undoes it do not return to the state the boot settled on — `add` then `remove` leaving a different list, or a counter it forgot to put back. |
@@ -396,7 +397,7 @@ browser.
 | `--no-shots` | Skip the per-screen PNGs written to `.himi/shots/`. |
 | `--net <file>` | Use an explicit net-mocks file instead of the app's own. |
 | `--budget <ms>` | Per-action settle budget (default 2000). |
-| `--native` | Also decode every baked descriptor with the real native decoders; bare `--native` runs whichever toolchains are present, and `--native ios` or `--native android` selects one. **Source-checkout only** — the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship, so it cannot run this at all (and its coverage ledger stays silent about native decoding rather than suggesting it). |
+| `--native` | Also decode every baked descriptor, and the release's `tokens.json`, with the real native decoders; bare `--native` runs whichever toolchains are present and names each one it could NOT check in a top-level `skippedPlatforms: [{ platform, reason }]` (never a pass), while `--native ios` or `--native android` selects one and exits 2 when it is unavailable. The Android SDK is found from `ANDROID_HOME`, then `ANDROID_SDK_ROOT`, then `sdk.dir` in the source checkout's Android test harness `local.properties`, then the default install path (`~/Library/Android/sdk` on macOS, `~/Android/Sdk` on Linux). **Source-checkout only** — the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship, so it cannot run this at all (and its coverage ledger stays silent about native decoding rather than suggesting it). |
 | `--all-screens` | Crawl every templated instance instead of one representative per structure. |
 | `--browser` / `--no-open` / `--timeout <ms>` | Run the loop in your own browser tab (one screen per run; refuses record/net/offline/hostile/deep/budget/shots/native). |
 | `himi test <screenId>…` | Focus one or more screens — the record and shots passes scope with them. |

package/guides/sdk-reference.json

@@ -8,7 +8,7 @@
         "name": "ServiceDefinition",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface ServiceDefinition<S> {\n  /** Initial state for the service. Must be JSON-serializable. */\n  state: S;\n\n  /**\n   * Actions: pure functions of `(state, ...args) → newState` (or async). The\n   * platform wraps each action so calling it from JS or from `__invokeAction`\n   * (native side) updates the service's state and notifies subscribers.\n   */\n  actions?: Record<\n    string,\n    // `never[]`, not `unknown[]` — same reason as defineService's constraint below:\n    // parameters are contravariant, so `unknown[]` rejects every handler that narrows\n    // its payload. Leaving this one loose would reintroduce the same TS2344 for anyone\n    // who annotates a `ServiceDefinition<S>` explicitly instead of inferring it.\n    (state: S, ...args: never[]) => S | undefined | Promise<S | undefined>\n  >;\n\n  /**\n   * Keys a cold boot takes from `state`, never from the persisted snapshot (cold-boot\n   * hydration). For UI state that must describe THIS run — an editor's one-shot seed, a\n   * \"still loading\" gate, an open sheet — where last run's value would be wrong, not just stale.\n   * Runtimes that honour it set `himalaya.hydrationOptOut`; an older one ignores the option.\n   */\n  notHydrated?: readonly (keyof S & string)[];\n}"
+        "decl": "export interface ServiceDefinition<S> {\n  /** Initial state for the service. Must be JSON-serializable. */\n  state: S;\n\n  /**\n   * Actions: pure functions of `(state, ...args) → newState` (or async). The\n   * platform wraps each action so calling it from JS or from `__invokeAction`\n   * (native side) updates the service's state and notifies subscribers.\n   */\n  actions?: Record<\n    string,\n    // `never[]`, not `unknown[]` — same reason as defineService's constraint below:\n    // parameters are contravariant, so `unknown[]` rejects every handler that narrows\n    // its payload. Leaving this one loose would reintroduce the same TS2344 for anyone\n    // who annotates a `ServiceDefinition<S>` explicitly instead of inferring it.\n    (state: S, ...args: never[]) => S | undefined | Promise<S | undefined>\n  >;\n\n  /**\n   * Keys a cold boot takes from `state`, never from the persisted snapshot (cold-boot\n   * hydration). For UI state that must describe THIS run — an editor's one-shot seed, a\n   * \"still loading\" gate, an open sheet — where last run's value would be wrong, not just stale.\n   * Runtimes that honour it set `himalaya.hydrationOptOut`; an older one ignores the option.\n   */\n  notHydrated?: readonly (keyof S & string)[];\n\n  /**\n   * Keys that start each VISIT from `state`: when a cached embed shows the screen again (its warm worker\n   * reclaimed), these go back to their declared values before the screen reloads. For the same kind of\n   * per-run UI state as `notHydrated` (an editor's one-shot seed, an open sheet); never data a returning\n   * screen should keep showing. A full app's own screens and an uncached embed ignore it.\n   */\n  perVisit?: readonly (keyof S & string)[];\n}"
       },
       {
         "name": "ServiceHandle",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1441.0",
+  "version": "0.1443.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "a3e589b65f6239351e6445160aa5b26a14cc4056007292e973e036ab"
+  "falconPackageHash": "8a70f3bc09b20693d0d5f9f3f9412dc5cdbd20ee62407d59ff646f7f"
 }

package/templates/beauty-salon/tier5-src/_shared/collection-query.ts

@@ -27,7 +27,9 @@ export interface CollectionQuerySource<Row> {
   cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
   id(row: Row): string;
   errorMessage?(error: unknown): string;
-  /** Private collections must discard prior rows when access or identity changes. */
+  /** Private collections must discard prior rows when access or identity changes. A revalidation keeps the
+   *  rows it shows through any other failure: safe because one worker never serves two identities (its pool
+   *  key carries the account, and a purge tears parked workers down). */
   clearOnError?(error: unknown): boolean;
 }
 const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
@@ -46,8 +48,17 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   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;
+  /** What the screen shows: the last published state, restored when a revalidation fails. */
+  let shown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
-  const emit = () => { if (!disposed) publish(snapshot()); };
+  const emit = () => {
+    if (disposed || revalidating === generation) return;
+    shown = { state: snapshot(), loadedPages };
+    publish(snapshot());
+  };
   const merge = (old: Row[], page: Row[]): Row[] => {
     const positions = new Map<string, number>(), result: Row[] = [];
     for (const item of [...old, ...page]) {
@@ -88,6 +99,8 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     } 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 (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
@@ -97,13 +110,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   };
   return {
     getState: snapshot,
-    async query(criteria: Partial<CollectionQuery>, restorePages = false): Promise<void> {
+    /** [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 count = restorePages && JSON.stringify(next) === JSON.stringify(state.criteria)
-        ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
+      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const showing = shown && shown.state.status === 'ready' && shown.state.items.length > 0 && !shown.state.pageError
+        && !shown.state.loadingMore && JSON.stringify(shown.state.criteria) === JSON.stringify(next) ? shown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
+      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
       const pending = fetch(false);
       const revision = generation;
       await pending;
@@ -112,6 +130,15 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       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();
+      }
     },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),

package/templates/beauty-salon/tier5-src/_shared/collection-service.ts

@@ -299,7 +299,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     actions.load = (_s, arg) => {
       stashCopy(arg); syncSaved(); applyNavigationCriteria(arg, _s);
       backend.onLoad?.(arg);
-      return backend.controller.query(criteria(), backend.restorePagesOnLoad).then(() => undefined);
+      // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
+      return backend.controller.query(criteria(), backend.restorePagesOnLoad, true).then(() => undefined);
     };
     actions.refresh = (_s, arg) => {
       stashCopy(arg); syncSaved();

package/templates/beauty-salon-owner/tier5-src/_shared/collection-query.ts

@@ -27,7 +27,9 @@ export interface CollectionQuerySource<Row> {
   cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
   id(row: Row): string;
   errorMessage?(error: unknown): string;
-  /** Private collections must discard prior rows when access or identity changes. */
+  /** Private collections must discard prior rows when access or identity changes. A revalidation keeps the
+   *  rows it shows through any other failure: safe because one worker never serves two identities (its pool
+   *  key carries the account, and a purge tears parked workers down). */
   clearOnError?(error: unknown): boolean;
 }
 const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
@@ -46,8 +48,17 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   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;
+  /** What the screen shows: the last published state, restored when a revalidation fails. */
+  let shown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
-  const emit = () => { if (!disposed) publish(snapshot()); };
+  const emit = () => {
+    if (disposed || revalidating === generation) return;
+    shown = { state: snapshot(), loadedPages };
+    publish(snapshot());
+  };
   const merge = (old: Row[], page: Row[]): Row[] => {
     const positions = new Map<string, number>(), result: Row[] = [];
     for (const item of [...old, ...page]) {
@@ -88,6 +99,8 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     } 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 (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
@@ -97,13 +110,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   };
   return {
     getState: snapshot,
-    async query(criteria: Partial<CollectionQuery>, restorePages = false): Promise<void> {
+    /** [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 count = restorePages && JSON.stringify(next) === JSON.stringify(state.criteria)
-        ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
+      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const showing = shown && shown.state.status === 'ready' && shown.state.items.length > 0 && !shown.state.pageError
+        && !shown.state.loadingMore && JSON.stringify(shown.state.criteria) === JSON.stringify(next) ? shown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
+      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
       const pending = fetch(false);
       const revision = generation;
       await pending;
@@ -112,6 +130,15 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       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();
+      }
     },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),

package/templates/beauty-salon-owner/tier5-src/_shared/collection-service.ts

@@ -299,7 +299,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     actions.load = (_s, arg) => {
       stashCopy(arg); syncSaved(); applyNavigationCriteria(arg, _s);
       backend.onLoad?.(arg);
-      return backend.controller.query(criteria(), backend.restorePagesOnLoad).then(() => undefined);
+      // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
+      return backend.controller.query(criteria(), backend.restorePagesOnLoad, true).then(() => undefined);
     };
     actions.refresh = (_s, arg) => {
       stashCopy(arg); syncSaved();

package/templates/beauty-salon-owner/tier5-src/_shared/owner-editor-value.ts

@@ -91,6 +91,16 @@ export function editorRunKeys<K extends string>(key: K): [`${K}Json`, `${K}Pendi
   return [`${key}Json`, `${key}Pending`, `${key}Dirty`, `${key}Edits`];
 }
 
+/** Does the form already hold `target` with its editor run in progress? A `load` for it then keeps the form as
+ *  it is: on the way back to a warm worker (its refresh and onAppear) a re-read would race an edit in flight and
+ *  reset the reported edit, and the editor, which seeds once, would show another document than the state holds.
+ *  An edit form holds its record once the editor loaded; a create form holds a draft once the owner edited. */
+export function holdsLoadedForm(state: object, target: { id: string; mode: string }, key: string): boolean {
+  const s = state as Record<string, unknown>;
+  if (s.status === 'error' || s.error || s.mode !== target.mode || (s.id ?? '') !== target.id) return false;
+  return target.mode === 'create' ? s[`${key}Dirty`] === true || Number(s[`${key}Edits`] ?? 0) > 0 : s[`${key}Pending`] === false;
+}
+
 /** The same keys on a runtime that ignores `notHydrated` (a binary from before #3644, still served new
  *  bundles over the air): reset them in place, before any action runs. A no-op where the runtime
  *  honours the option (`himalaya.hydrationOptOut`). */

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-manage/index.ts

@@ -214,6 +214,22 @@ let loadGeneration = 0;
 let newestStarted: State | undefined;
 let newestSettled: { generation: number; state: State } | undefined;
 
+/** A hub already showing its areas re-reads their summaries behind them, never back under the skeleton: the
+ *  screen coming back (a warm worker's refresh and its onAppear, at once) keeps what it shows until they land. */
+function revalidating(state: State, areas: State['areas'] = state.areas): State {
+  // The areas as delivered now (labels, routes), each still showing the summary it showed.
+  const shown = new Map(state.areas.map(area => [area.id, area]));
+  const next = areas.map(area => {
+    const was = shown.get(area.id);
+    return was ? { ...area, metricText: was.metricText, statusText: was.statusText, unavailable: was.unavailable } : area;
+  });
+  return derive({ ...state, areas: next, businessName: currentBusinessName, handoffError: '' }, next);
+}
+
+function sameAreas(shown: State['areas'], next: State['areas']): boolean {
+  return shown.length === next.length && shown.every((area, i) => area.id === next[i].id && area.metricKey === next[i].metricKey);
+}
+
 async function loadMetrics(state: State): Promise<State> {
   const generation = ++loadGeneration;
   newestStarted = state;
@@ -292,12 +308,11 @@ const svc = defineService<State, {
       // it must not settle (that derived "0 business areas" and painted the
       // filtered-empty state); once they are, it re-reads their summaries.
       if (!('areas' in read(arg))) {
-        return state.status === 'ready'
-          ? loadMetrics(derive({ ...state, isLoading: true, notLoading: false, summaryNote: '', handoffError: '' }))
-          : { ...state, businessName: currentBusinessName };
+        return state.status === 'ready' ? loadMetrics(revalidating(state)) : { ...state, businessName: currentBusinessName };
       }
       const parsed = (() => { try { return JSON.parse(str(arg, 'areas') || '[]'); } catch { return []; } })();
       const areas = parseAreas(parsed);
+      if (state.status === 'ready' && sameAreas(state.areas, areas)) return loadMetrics(revalidating(state, areas));
       return loadMetrics(derive({ ...state, status: 'ready', areas, isLoading: true, notLoading: false, summaryNote: '', handoffError: '' }, areas));
     },
     // Refresh re-reads summaries for KNOWN areas. Before the descriptor has

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-post/index.ts

@@ -340,6 +340,8 @@ const svc = defineService<PostState, {
 }>("himiOwnerLitePost", {
   state: shape({ status: "loading" }),
   notHydrated: [...DELETE_RUN_KEYS],
+  // perVisit: a cached embed's warm return starts this run fresh, as a cold boot does (`__resetRunState`).
+  perVisit: [...DELETE_RUN_KEYS],
   actions: {
     load: async (s0, arg) => {
       const s = disarm(s0);

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-post-form/index.ts

@@ -4,7 +4,7 @@
 // screen (himiOwnerLitePost.publish). Bound by buildForm ($service:himiOwnerLitePostForm.*).
 
 import { postBodyText, plainPostBody, postCoverUrl } from "../_shared/owner-post-content.js";
-import { editorSubmitValue, queuedDocument, editorChanged, editorRunKeys, resetHydratedEditorOnOlderRuntime, editorAfterSave, liveState, settleOverLive } from "../_shared/owner-editor-value.js";
+import { editorSubmitValue, queuedDocument, editorChanged, editorRunKeys, resetHydratedEditorOnOlderRuntime, editorAfterSave, liveState, settleOverLive, holdsLoadedForm } from "../_shared/owner-editor-value.js";
 import { ricosUploadService } from "@himalaya/wix-rich-content-editor";
 import { wixCall } from "@himalaya/wix-site-media";
 import { wixMediaUrl, WIX_DETAIL_IMAGE } from "../_shared/himi-store.js";
@@ -165,18 +165,24 @@ const svc = defineService<PostFormState, {
   bodyChanged: (s: PostFormState, arg?: unknown) => PostFormState;
   submit: (s: PostFormState, values?: Record<string, unknown>) => Promise<PostFormState>;
 }>("himiOwnerLitePostForm", {
-  state: shape({ mode: startMode, id: initialInput.id ?? "", bodyPending: startMode === "edit" }),
+  // The editor stays hidden until this run's load lands, however the form was opened (an id as input or in the params).
+  state: shape({ mode: startMode, id: initialInput.id ?? "", bodyPending: true }),
   // [rico] #3644 — this run's editor state and UI: a cold boot takes these from `state`, never from
   // the persisted snapshot (the editor seeds once; last run's sheet is not this run's).
   notHydrated: [...editorRunKeys("body"), "detailsOpen"],
+  // perVisit: a cached embed's warm return starts this run fresh, as a cold boot does (`__resetRunState`).
+  perVisit: [...editorRunKeys("body"), "detailsOpen"],
   actions: {
     load: async (s, arg) => {
       stashCopy(arg); // absorb the descriptor's onAppear copy-pack param
       // WS-C — nav-param input is PRIMARY (the canonical create-or-edit shell
       // bakes no id/mode); the onAppear `id` param is the #570 suffixed-build
       // fallback. An id ⇒ edit; no id anywhere ⇒ the create shell.
-      const id = navInputId() || idFrom(arg, s.id);
-      if (!id) return shape({ ...s, ...BODY_LOADED, mode: "create", id: "", bodyJson: "", status: "idle", error: "", demoNote: isOwnerPreviewDemo() ? copyParam("ownerCommon.demoSaveNote", DEMO_SAVE_NOTE) : "" });
+      // The held id is for the host's bare refresh only (no argument): an onAppear without an id is a create screen.
+      const id = navInputId() || idFrom(arg, arg === undefined ? s.id : "");
+      if (holdsLoadedForm(s, { id, mode: id ? "edit" : "create" }, "body")) return s;
+      // A form that held a record (the one just saved) opens blank.
+      if (!id) return shape({ ...(s.id ? {} : s), ...BODY_LOADED, mode: "create", id: "", bodyJson: "", status: "idle", error: "", demoNote: isOwnerPreviewDemo() ? copyParam("ownerCommon.demoSaveNote", DEMO_SAVE_NOTE) : "" });
       if (isOwnerPreviewDemo()) {
           const d = DEMO_POSTS.find((x) => x.id === id);
           if (d) {

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-product/index.ts

@@ -305,6 +305,8 @@ const svc = defineService<ProductState, {
 }>("himiOwnerLiteProduct", {
   state: shape({ status: "loading" }),
   notHydrated: [...DELETE_RUN_KEYS],
+  // perVisit: a cached embed's warm return starts this run fresh, as a cold boot does (`__resetRunState`).
+  perVisit: [...DELETE_RUN_KEYS],
   actions: {
     load: async (s0, arg) => {
       const s = disarm(s0);

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-product-form/index.ts

@@ -18,7 +18,7 @@ import {
 import { get as dbGet, upsert as dbUpsert, remove as dbRemove, type DbEntity } from "../_shared/owner-local-db.js";
 import { htmlIsTrivial, htmlPreviewText } from "../_shared/owner-rich-guard.js";
 import { postBodyText, plainPostBody } from "../_shared/owner-post-content.js";
-import { editorSubmitValue, queuedDocument, editorChanged, cachedRichVerdict, editorRunKeys, resetHydratedEditorOnOlderRuntime, editorAfterSave, liveState, settleOverLive } from "../_shared/owner-editor-value.js";
+import { editorSubmitValue, queuedDocument, editorChanged, cachedRichVerdict, editorRunKeys, resetHydratedEditorOnOlderRuntime, editorAfterSave, liveState, settleOverLive, holdsLoadedForm } from "../_shared/owner-editor-value.js";
 import { parseRicosJson } from "@himalaya/wix-rich-content";
 import { ricosUploadService } from "@himalaya/wix-rich-content-editor";
 import { ownerLoadError, isOwnerPreviewDemo, ownerDemoFallback, ownerWriteError } from "../_shared/owner-load-error.js";
@@ -195,17 +195,23 @@ const svc = defineService<ProductFormState, {
   submit: (s: ProductFormState, values?: Record<string, unknown>) => Promise<ProductFormState>;
   remove: (s: ProductFormState) => Promise<ProductFormState>;
 }>("himiOwnerLiteProductForm", {
-  state: shape({ mode: startMode, id: initialInput.id ?? "", descriptionPending: startMode === "edit" }),
+  // The editor stays hidden until this run's load lands, however the form was opened (an id as input or in the params).
+  state: shape({ mode: startMode, id: initialInput.id ?? "", descriptionPending: true }),
   // [rico] #3644 — this run's editor state: a cold boot takes it from `state`, never the snapshot.
   notHydrated: editorRunKeys("description"),
+  // perVisit: a cached embed's warm return starts this run fresh, as a cold boot does (`__resetRunState`).
+  perVisit: editorRunKeys("description"),
   actions: {
     load: async (s, arg) => {
       stashCopy(arg); // absorb the descriptor's onAppear copy-pack param
       // WS-C — nav-param input is PRIMARY (the canonical create-or-edit shell
       // bakes no id/mode); the onAppear `id` param is the #570 suffixed-build
       // fallback. An id ⇒ edit; no id anywhere ⇒ the create shell.
-      const id = navInputId() || idFrom(arg, s.id);
-      if (!id) return shape({ ...s, ...DESCRIPTION_LOADED, mode: "create", id: "", descriptionMode: "plain", descriptionJson: "", status: "idle", error: "", demoNote: isOwnerPreviewDemo() ? copyParam("ownerCommon.demoSaveNote", DEMO_SAVE_NOTE) : "" });
+      // The held id is for the host's bare refresh only (no argument): an onAppear without an id is a create screen.
+      const id = navInputId() || idFrom(arg, arg === undefined ? s.id : "");
+      if (holdsLoadedForm(s, { id, mode: id ? "edit" : "create" }, "description")) return s;
+      // A form that held a record (the one just saved) opens blank.
+      if (!id) return shape({ ...(s.id ? {} : s), ...DESCRIPTION_LOADED, mode: "create", id: "", descriptionMode: "plain", descriptionJson: "", status: "idle", error: "", demoNote: isOwnerPreviewDemo() ? copyParam("ownerCommon.demoSaveNote", DEMO_SAVE_NOTE) : "" });
       if (isOwnerPreviewDemo()) {
           const d = DEMO_PRODUCTS.find((p) => p.id === id);
           if (d) {

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-search/index.ts

@@ -254,6 +254,8 @@ const IDLE: State = {
 
 /** Rebuilt on `load`, because the allowlist arrives with the descriptor. */
 let coordinator: ReturnType<typeof createGroupedSearch> | undefined;
+/** The allowlist the coordinator was built for. */
+let coordinatorSources = "";
 let published: State = IDLE;
 const memory = localPreferences("ownerSearch", normalizeMemory);
 
@@ -279,6 +281,15 @@ const svc = defineService<State, {
   actions: {
     load: async (_state, arg) => {
       stashCopy(arg);
+      // The screen coming back re-runs its search behind what it shows: a warm worker's refresh calls `load` bare (no allowlist),
+      // and its onAppear repeats the allowlist the coordinator was built for.
+      const sources = str(arg, "sources");
+      if (coordinator && (!sources || sources === coordinatorSources)) {
+        await coordinator.revalidate();
+        remember();
+        return published;
+      }
+      coordinatorSources = sources;
       const allowed = (() => {
         try {
           return JSON.parse(str(arg, "sources") || "[]");

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-search/logic.ts

@@ -446,7 +446,13 @@ export function createGroupedSearch(
     };
   };
 
-  const emit = () => { if (!disposed) publish(snapshot()); };
+  /** The revalidation running behind the shown rows (0: none): its snapshots are held back until it is done. */
+  let holding = 0, holds = 0;
+  /** The depth the running revalidation restores, so one that overlaps it starts from the owner's depth, not
+   *  from its reset; and the revalidation itself, which a "look further" tapped meanwhile waits for. */
+  let heldDepth: Record<string, number> = {};
+  let revalidation: Promise<void> | undefined;
+  const emit = () => { if (!disposed && !holding) publish(snapshot()); };
 
   /** Identity merge: a re-fetched row REPLACES its predecessor in place, so a
    *  refresh cannot reorder the list under the user's finger or duplicate a row
@@ -604,6 +610,7 @@ export function createGroupedSearch(
      *  the wrong result set. */
     async search(raw: unknown): Promise<void> {
       if (disposed) return;
+      holding = 0;
       const next = normalizeQuery(raw);
       query = next;
       for (const id of order) {
@@ -627,6 +634,7 @@ export function createGroupedSearch(
      */
     async restore(raw: unknown, depth: Record<string, number> = {}): Promise<void> {
       if (disposed) return;
+      holding = 0;
       const next = normalizeQuery(raw);
       query = next;
       for (const id of order) {
@@ -637,8 +645,34 @@ export function createGroupedSearch(
       if (!next) return;
       await fanOut(order, depth);
     },
+    /** A returning screen (a cached embed's warm worker): the same search re-run to the depth each group
+     *  shows, behind the rows it shows, and published once. Rows are a live claim about records, so they
+     *  are re-fetched, never repainted; a search typed meanwhile takes over at once. */
+    async revalidate(): Promise<void> {
+      if (disposed || !query) return;
+      const depth: Record<string, number> = holding ? { ...heldDepth } : {};
+      for (const id of order) { const pages = groups.get(id)?.pages ?? 0; if (pages > Math.max(1, depth[id] ?? 0)) depth[id] = pages; }
+      heldDepth = depth;
+      const held = ++holds;
+      holding = held;
+      for (const id of order) {
+        groups.set(id, idleGroup(byId.get(id)!));
+        sourceGeneration.set(id, (sourceGeneration.get(id) ?? 0) + 1);
+      }
+      const run = (async () => {
+        try {
+          await fanOut(order, depth);
+        } finally {
+          if (holding === held) { holding = 0; heldDepth = {}; emit(); }
+        }
+      })();
+      revalidation = run;
+      await run;
+    },
     /** One group's next page. */
     async loadMore(id: unknown): Promise<void> {
+      // Tapped while a revalidation re-fetches behind the shown rows: page on from what it lands.
+      while (holding && revalidation) await revalidation;
       const adapter = typeof id === "string" ? byId.get(id) : undefined;
       if (!adapter || disposed || !query) return;
       await runSource(adapter, true);

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-service-form/index.ts

@@ -117,7 +117,8 @@ const svc = defineService<ServiceFormState, {
       stashCopy(arg); // absorb the descriptor's onAppear copy-pack param
       // WS-C — nav-param input is PRIMARY (the canonical form bakes no id); the
       // onAppear `id` param is the #570 suffixed-build fallback.
-      const id = navInputId() || idFrom(arg, s.id);
+      // The held id is for the host's bare refresh only (no argument): an onAppear without an id is a create screen.
+      const id = navInputId() || idFrom(arg, arg === undefined ? s.id : "");
       if (!id) return shape({ ...s, status: "error", error: copyParam("ownerServiceForm.errorNoService", "No service to edit.") });
       if (isOwnerPreviewDemo()) {
           const d = DEMO_SERVICES.find((x) => x.id === id);

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

@@ -27,7 +27,9 @@ export interface CollectionQuerySource<Row> {
   cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
   id(row: Row): string;
   errorMessage?(error: unknown): string;
-  /** Private collections must discard prior rows when access or identity changes. */
+  /** Private collections must discard prior rows when access or identity changes. A revalidation keeps the
+   *  rows it shows through any other failure: safe because one worker never serves two identities (its pool
+   *  key carries the account, and a purge tears parked workers down). */
   clearOnError?(error: unknown): boolean;
 }
 const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
@@ -46,8 +48,17 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   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;
+  /** What the screen shows: the last published state, restored when a revalidation fails. */
+  let shown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
-  const emit = () => { if (!disposed) publish(snapshot()); };
+  const emit = () => {
+    if (disposed || revalidating === generation) return;
+    shown = { state: snapshot(), loadedPages };
+    publish(snapshot());
+  };
   const merge = (old: Row[], page: Row[]): Row[] => {
     const positions = new Map<string, number>(), result: Row[] = [];
     for (const item of [...old, ...page]) {
@@ -88,6 +99,8 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     } 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 (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
@@ -97,13 +110,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   };
   return {
     getState: snapshot,
-    async query(criteria: Partial<CollectionQuery>, restorePages = false): Promise<void> {
+    /** [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 count = restorePages && JSON.stringify(next) === JSON.stringify(state.criteria)
-        ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
+      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const showing = shown && shown.state.status === 'ready' && shown.state.items.length > 0 && !shown.state.pageError
+        && !shown.state.loadingMore && JSON.stringify(shown.state.criteria) === JSON.stringify(next) ? shown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
+      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
       const pending = fetch(false);
       const revision = generation;
       await pending;
@@ -112,6 +130,15 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       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();
+      }
     },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),

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

@@ -299,7 +299,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     actions.load = (_s, arg) => {
       stashCopy(arg); syncSaved(); applyNavigationCriteria(arg, _s);
       backend.onLoad?.(arg);
-      return backend.controller.query(criteria(), backend.restorePagesOnLoad).then(() => undefined);
+      // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
+      return backend.controller.query(criteria(), backend.restorePagesOnLoad, true).then(() => undefined);
     };
     actions.refresh = (_s, arg) => {
       stashCopy(arg); syncSaved();