@wix/himalaya-cli 0.1446.0 → 0.1448.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/state/src/index.d.ts

@@ -19,7 +19,8 @@ export interface ServiceDefinition<S> {
      * Keys that start each VISIT from `state`: when a cached embed shows the screen again (its warm worker
      * reclaimed), these go back to their declared values before the screen reloads. For the same kind of
      * per-run UI state as `notHydrated` (an editor's one-shot seed, an open sheet); never data a returning
-     * screen should keep showing. A full app's own screens and an uncached embed ignore it.
+     * screen should keep showing. A cold boot never restores them either. A full app's own screens and an
+     * uncached embed ignore the reset.
      */
     perVisit?: readonly (keyof S & string)[];
 }

package/dist/cli.mjs

@@ -8115,6 +8115,7 @@ function resolveTranslation(value, catalog3, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`
@@ -11110,6 +11111,16 @@ function responseBytes(value) {
     return 0;
   }
 }
+function restoredState(def, snapshot2) {
+  const declared = def?.state ?? {};
+  if (!snapshot2 || typeof snapshot2 !== "object" || Array.isArray(snapshot2)) return declared;
+  const fresh = [def?.notHydrated, def?.perVisit].flatMap((keys) => Array.isArray(keys) ? keys : []);
+  const merged = { ...declared };
+  for (const [key3, value] of Object.entries(snapshot2)) {
+    if (key3 !== "_error" && !fresh.includes(key3)) merged[key3] = value;
+  }
+  return merged;
+}
 async function bootBundleWorker(bundleJs, opts) {
   const budgetMs = opts.budgetMs && opts.budgetMs > 0 ? opts.budgetMs : 5e3;
   const calls = [];
@@ -11169,7 +11180,7 @@ async function bootBundleWorker(bundleJs, opts) {
     dispatch: dispatchHost,
     defineService: (name, def) => {
       const entry = {
-        state: def?.state ?? {},
+        state: restoredState(def, opts.persistedState?.[String(name)]),
         actions: def?.actions ?? {}
       };
       captured.push({ name: String(name), def: entry });
@@ -161512,32 +161523,32 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/DashboardHost-Hbp9cYDQ.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "67f18e346a0472d13699e34a121ad159ef72ff7070f022de0158ced1d8de8c9e" },
-      { key: "assets/DevDrawer-BCf5pKn3.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "4e3f8faeef44171c9991857b7a3954ad3ac35d7ba087c1714cca89b613ef575c" },
-      { key: "assets/IdiomCompare-Du8fy2bA.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "bf3251f0779f986ec17d132e2edee65187af52058ca152363672e8fa65c44c8a" },
-      { key: "assets/LightboxViewer-Bio4Uaf0.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "5c3563c1bf16c102bf176fadac3e1b3bfafd03f0791c7d5f8065182830ba6388" },
-      { key: "assets/PhonePreviewControl-rUJWm5D9.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "3ee2027d40341425a3fcf21e6b2222269e7e5be04ddd39581bfd66cd61fafa39" },
-      { key: "assets/SchemeCompare-cs9HGLIH.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "fece2c0e802fd153f570fd5ac97985ee9060bb2856f009953f1c476c07d1df85" },
-      { key: "assets/index-B4otl_lr.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1268353, sha256: "168c393f88d0fb0df94eae9b1c14958c5ba0d707df7db7fd11de1d4c12a4db84" },
-      { key: "assets/pdf-BZPM9uB7.js", contentType: "application/javascript; charset=utf-8", offset: 1337598, length: 488199, sha256: "0593e16766ca0d3ebf849836a109bb58c1c869cadd005436d9258f6e4027a7ef" },
-      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1825797, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
-      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1825870, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
-      { key: "assets/pdfDocument-6awpDNiQ.js", contentType: "application/javascript; charset=utf-8", offset: 3142904, length: 2868, sha256: "ce4700b049bccf122eac6666b8c83d6a2527cecc7ee6e358e96995554a9d3566" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3145772, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3150382, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3638966, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3729890, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3820874, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3911854, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4002726, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4093706, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4202342, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4311426, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4420474, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4528174, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4616282, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4623030, length: 4947, sha256: "9c692b83159ab0d8305f407bc0bc0dbdefa8db9e479d76ab86366b10282196c1" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4627977, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
+      { key: "assets/DashboardHost-C0zY6LXc.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "2ae0514356f33d624fbdea4f37763d9485585ae8c47efda81e9fd4976134aa66" },
+      { key: "assets/DevDrawer--HNffqm4.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "bc1aa20ec7d0244b30ee071da75acf380ebc7087013247c78a6a4f813ee42658" },
+      { key: "assets/IdiomCompare-BcPm59UD.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "e47795d60a59d872dc9d1a31cf166940f4eeb1683e2bc858b62da24f1d7835b2" },
+      { key: "assets/LightboxViewer-B3iMQPin.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "7a035923df5986b7775d3398725f9234d1d7ddf46e0a5af8e9f6bd74d771590d" },
+      { key: "assets/PhonePreviewControl-CRKLF95b.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "e65e0be6f821b3fd13c847c5ae7fff2880a39bf603a3bd426878af78e3d814a7" },
+      { key: "assets/SchemeCompare-Bn99KkCH.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "7f2f13e931a686d80e03ce3673dc16e93619c93326fb447d216ee2e5bffc4807" },
+      { key: "assets/index-DFazEEqa.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1268538, sha256: "3718cafcaf0cdc962f5d1c5d6bc3cf5e9ee2b1f11e918fb7e9c629e5b0a49576" },
+      { key: "assets/pdf-NnG-NcU-.js", contentType: "application/javascript; charset=utf-8", offset: 1337783, length: 488199, sha256: "f60ce93a839789588474a844c60da2ebc210efbd3f50f04cc4e44eb8e127cddc" },
+      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1825982, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
+      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1826055, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
+      { key: "assets/pdfDocument-MaeR1HVD.js", contentType: "application/javascript; charset=utf-8", offset: 3143089, length: 2868, sha256: "2752019f5f58a8818f6471de600ccfb647cfab7577501d19d0eface21e7820dc" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3145957, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3150567, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3639151, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3730075, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3821059, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3912039, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4002911, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4093891, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4202527, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4311611, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4420659, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4528359, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4616467, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4623215, length: 4947, sha256: "31e294c8a2eff7f23f4b24e1696713854eb517ad048ef9cc6967c90b9abca5ba" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4628162, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
     ];
   }
 });

package/guides/designing-himi-screens.md

@@ -176,11 +176,13 @@ responsive master/detail. *Reach for `Card` to cluster, not to wrap every single
 (`columns: 1, columnsMedium: 2`); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
 `Timeline` for chronological events. Compose rows as `ListItem` / `LabeledContent` / `DisclosureGroup`
 cells inside a `Card([VStack(spacing: 0)])`.
-> **Don't make `LazyList` the screen root.** The native `ScreenView` already wraps a screen's content
-> in a scroll view, so a `LazyList` as the (modifier-wrapped) root collapses to **zero height and
-> renders blank**. For a feed/list *screen*, use a plain `vstack` of `Card`s — it scrolls with the
-> screen. Reach for `LazyList` only *nested* inside a bounded-height slot (a fixed-height panel, a
-> horizontal rail) where its own virtualized scroll is what you want.
+> For a feed/list *screen*, prefer a root `VStack` with a direct vertical worker-bound `LazyList`
+> when the screen has the simple root shape supported by the native host; Android flattens that
+> shape into one lazy root so long lists do not compose every row. Other root shapes stay on the
+> eager screen path, as does a root list that sets `pagination`, `stickyHeader` or
+> `rowSwipeActions`. A `LazyList` nested deeper inside the screen's outer scroll is rendered
+> eagerly on Android to avoid nested-scroll measurement failures, even in a fixed-height panel. A
+> worker-bound horizontal `LazyList` is eager on Android too, so keep rails short.
 
 **Text** — `Text` for a single styled string (`maxLines` to truncate); `RichText` for inline mixed
 marks (bold/italic/link within one paragraph); `RichContent` for a Wix Ricos document with blocks,

package/guides/push-cli-onboarding.md

@@ -203,6 +203,37 @@ routes: [
 A notification whose link matches no route opens the app without navigating. `himi validate`
 warns when a declared route names a screen the app does not declare.
 
+### Notification action buttons
+
+Declare actionable categories in the app's source `config.ts`. The native shells render one
+button per category action on iOS and Android; the notification payload selects the category.
+This is structural app configuration, not a `himi notify send` flag:
+
+```ts
+push: {
+  categories: [{
+    id: "time.action-required",
+    actions: [
+      { id: "review", title: "Review" },
+      { id: "snooze", title: "Snooze 1h", input: true },
+    ],
+  }],
+  observerAction: "tier5.myNav.onNotification",
+},
+```
+
+The app-level worker action named by `observerAction` receives every notification through the
+existing observer path. Use `readNotificationEvent` from `@himalaya/push` to read its params:
+
+- `notificationAction` is the pressed action id, or `""` for a receipt or ordinary body tap.
+- `notificationText` is the inline reply for an `input: true` action, or `""` otherwise.
+- Action presses have `tapped: "false"`; they are responses to an already-observed notification,
+  not new arrivals. They never navigate. The body tap retains the existing link navigation.
+
+Each action has its own deduplication key, so a foreground receipt does not swallow a later button
+press and pressing the same button twice is reported once. A press received before the worker is
+configured is queued and replayed once the current site's configuration is ready.
+
 **Customer push QA builds use `himi dist --signing byo`.** After publishing an approved
 release, use a backend and reachable runner source that support the customer-signing flow.
 Use the app owner's account for both logins and explicitly select the deployed customer target:

package/guides/recipe-dynamic-list.md

@@ -14,6 +14,15 @@ the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi
 card grids). `Carousel` and `Menu` take `itemsPath` the same way. Do **not** hand-roll
 a "VStack of Cards" — that renders only static items and can't bind live data.
 
+For a long list screen, make the vertical `LazyList` a direct child of the root `VStack`
+when the rest of the root uses only the supported simple layout. Android can then flatten
+the root into one `LazyColumn` and compose only visible rows. This applies only to a plain
+list: a `LazyList` that sets `pagination`, `stickyHeader` or `rowSwipeActions` keeps the
+screen's own scroll on Android and composes every row. A list nested deeper inside the
+screen's outer scroll also stays eager, and a fixed-height panel inside that scroll does not
+change that on Android. A worker-bound horizontal list is also eager on Android: it renders
+every row in a plain `Row`, so keep rails short.
+
 **`Grid` is not a `LazyList` with one column.** It shares `itemsPath` and the row
 template, and nothing else: the gesture props in §5 (`onPullToRefresh`, `pagination`)
 and `stickyHeader`/`rowSwipeActions` are declared on `LazyListProps` only. A key `Grid`

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\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}"
+        "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 cold boot never restores them either. A full app's own screens and an\n   * uncached embed ignore the reset.\n   */\n  perVisit?: readonly (keyof S & string)[];\n}"
       },
       {
         "name": "ServiceHandle",

package/guides/wix-api-usage.md

@@ -104,6 +104,23 @@ response. The client holds **no** auth or HTTP —
 that's `WixApiCapability` (attaches auth per call, 401→refresh→retry). Import the domain by its canonical
 package `@himalaya/wix-<domain>` (unversioned name; the REST version is in the path — RFC 0043 D2).
 
+### Read an owner-created async job
+
+The first-party `@himalaya/wix-async-jobs` client exposes the current state of an async job through the
+Wix gateway. It is an owner-scoped read and requires `INFRA.ASYNC_JOB_READ`; visitor sessions receive
+403. Poll the returned `job.status` while it is `INITIALIZED` or `PROCESSING`, and stop at `FINISHED`
+or `FAILED`:
+
+```ts
+import { getAsyncJob } from "@himalaya/wix-async-jobs";
+
+const { job } = await getAsyncJob(jobId);
+const status = job?.status;
+```
+
+The client calls `GET /async-jobs/v1/async-jobs/{jobId}`. A missing job is an HTTP 404 with
+`JOB_NOT_FOUND`; do not treat that response as authorization evidence.
+
 > **Catalog V1 vs V3 — use V3 by default.** For a new Stores reader use
 > **`queryStoreProducts`** (POST
 > `/stores/v3/products/query`) and **`getStoreProduct`**, from the same `@himalaya/wix-stores`

package/guides/wix-sdk-overview.md

@@ -43,6 +43,7 @@ Same idea, one canonical entry — don't reach for the others:
 | I want to… | Canonical door | Layer |
 |---|---|---|
 | Read/write a Wix domain (products, bookings, members…) | `@himalaya/wix-<domain>` from a worker | L3 |
+| Read the state of an owner-created async job | `@himalaya/wix-async-jobs` → `getAsyncJob(jobId)` | L3 |
 | Emit a BI beacon | `wix-platform.bi` | L2 |
 | Conduct an experiment / read a flag | `wix-platform.experiments` / `wix-platform.flags` | L2 |
 | Translate a string / read the locale | `wix-platform.i18n` | L2 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1446.0",
+  "version": "0.1448.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": "880b0e52cdd4129fa90b221507dda4d96f5c2d0bc7780fcbb6503876"
+  "falconPackageHash": "ceeeb017afff0753eec531692afa7a5e7ca0bf9e38054ebdf2adf95f"
 }

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

@@ -20,6 +20,13 @@ export interface CollectionQueryState<Row> extends CollectionPage<Row> {
   pageError: boolean;
   complete: boolean;
   error: string;
+  /** The rows are the source's `cached` page, shown while the live read is still out. */
+  provisional?: boolean;
+}
+/** What a collection showed, as `shownPage` hands it out and `seed` takes it back on a restored boot. */
+export interface CollectionShownPage<Row> {
+  state: CollectionQueryState<Row>;
+  loadedPages: number;
 }
 export interface CollectionQuerySource<Row> {
   fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
@@ -50,13 +57,19 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   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;
+  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
+   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
+   *  it leaves those rows on screen, so it is still this. */
+  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
   let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
   const emit = () => {
     if (disposed || revalidating === generation) return;
-    shown = { state: snapshot(), loadedPages };
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept.
+    if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
+      lastShown = state.items.length > 0 ? { state: snapshot(), loadedPages } : undefined;
+    }
     publish(snapshot());
   };
   const merge = (old: Row[], page: Row[]): Row[] => {
@@ -77,14 +90,14 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     const criteria = copyQuery(state.criteria);
     if (!append) loadedPages = 0;
     state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
-      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false }) };
+      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
     emit();
     try {
       if (!append && source.cached) {
         const cached = await source.cached(criteria).catch(() => undefined);
         if (disposed || generation !== revision) return;
         if (cached?.items.length) {
-          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false };
+          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
           emit();
         }
       }
@@ -94,17 +107,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
         total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
         metadata: page.metadata ?? (append ? state.metadata : undefined),
-        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor };
+        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
       loadedPages++;
     } catch (error) {
       if (disposed || generation !== revision) return;
       const clear = source.clearOnError?.(error) === true;
       // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
       clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
+      if (clearedByError) lastShown = undefined;
       if (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
-        error: source.errorMessage?.(error) ?? '' };
+        provisional: false, error: source.errorMessage?.(error) ?? '' };
     }
     emit();
   };
@@ -117,8 +131,7 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       const next = normalize(criteria);
       const same = JSON.stringify(next) === JSON.stringify(state.criteria);
       const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
-      const showing = 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;
+      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
       if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
@@ -140,6 +153,27 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
         emit();
       }
     },
+    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
+     *  state; undefined when it shows none. */
+    shownPage(): CollectionShownPage<Row> | undefined {
+      if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
+      const page = lastShown.state;
+      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+    },
+    /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
+     *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page. */
+    seed(page: unknown): boolean {
+      const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
+      const restored = candidate?.state;
+      if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
+        || !Array.isArray(restored.items) || restored.items.length === 0 || typeof restored.nextCursor !== 'string') return false;
+      try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
+      state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
+        loadingMore: false, pageError: false, provisional: false, error: '' };
+      loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      lastShown = { state: snapshot(), loadedPages };
+      return true;
+    },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),
     retry: () => fetch(state.pageError),

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

@@ -142,6 +142,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // the query controller carries a recoverable failure. Treat each shape as
     // one collection state so the shared UI never renders a blank catalog.
     const backendState = backend?.controller.getState();
+    const provisional = backendState?.provisional === true;
     const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
     const domainError = typeof s.error === 'string' ? s.error.trim() : '';
     const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
@@ -177,13 +178,17 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // un-narrowed failure. A re-query while typing keeps it (and the search field's focus).
     const hideChrome = (!narrowed && !s.nextCursor && projected.loaded < COLLECTION_CHROME_MIN_ITEMS)
       || sourceEmpty || ((loading || errored) && rows.length === 0 && !narrowed);
-    return { ...s, collection: { ...prefs, ...projected,
+    // Kept with the state, so a cold boot restored from disk shows its last page and revalidates behind it.
+    const collectionShown = backend?.controller.shownPage();
+    return { ...s, ...(backend ? { collectionShown: collectionShown ?? null } : {}), collection: { ...prefs, ...projected,
       hideChrome, noActiveCriteria: !narrowed,
       viewName, viewMessage, saveMessage, noSavedViews: prefs.savedViews.length === 0,
       cursor: s.pageError === true || s.loadingMore === true ? '' : s.nextCursor,
       noMore: !s.nextCursor || s.pageError === true || s.loadingMore === true,
       noPageError: s.pageError !== true,
-      noOffline: s.fromCache !== true,
+      // Rows read from the device ahead of the live read are shown as they are: "saved offline" is what stays on
+      // screen when the live read failed, not a first visit that is still loading.
+      noOffline: s.fromCache !== true || provisional,
       noError: !errored,
       noRetry: !canRetry || signInRequired,
       noSignIn: !signInRequired,
@@ -202,7 +207,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       filtersPresented, previewPresented: !!previewId, preview: projected.items.filter(row => row.collectionId === previewId),
       persistenceLabel: persisted.available ? copyParam('collection.onDevice', 'Saved on this device') : copyParam('collection.sessionOnly', 'Choices last for this session'),
       noEmpty: loading || errored || sourceEmpty || domainNarrowed || projected.items.length > 0,
-      summary: backend && config.backendQuery && s.fromCache
+      summary: backend && config.backendQuery && s.fromCache && !provisional
         ? copyParam('collection.cached', 'Saved offline · may be outdated')
         : collectionSummary({ shown: projected.items.length, loaded: projected.loaded, backend: !!(backend && config.backendQuery),
           total: typeof s.total === 'number' ? s.total : undefined, noun: config.countNoun
@@ -345,6 +350,13 @@ export function defineBackendCollection<S extends object, Row extends object>(na
     apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
   });
   const handle = (options.register ?? register)(name, definition);
+  // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
+  // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)
+  // starts its first load as before, never from rows it chose not to restore.
+  const restored = (handle as { getState?: () => State }).getState?.();
+  const rowsKey = COLLECTIONS[name]?.rows;
+  const restoredRows = rowsKey ? restored?.[rowsKey] : undefined;
+  if (Array.isArray(restoredRows) && restoredRows.length > 0) controller.seed(restored?.collectionShown);
   publish = () => handle.collectionDataChanged();
   return handle;
 }

package/templates/beauty-salon/tier5-src/_shared/iap-presentation.ts

@@ -45,7 +45,9 @@ export function withIapPresentation<S extends object>(options: {
       return project(next);
     }]));
     const service = (options.register ?? defineService)(name, {
-      ...definition, notHydrated: [...(definition.notHydrated ?? []), ...options.transientKeys],
+      // The collection's shown page goes with the rows and chrome it copies: kept out of the restore with them.
+      ...definition, notHydrated: [...(definition.notHydrated ?? []), ...options.transientKeys,
+        ...((options.transientKeys as string[]).includes('collection') ? ['collectionShown' as keyof S & string] : [])],
       actions: { ...actions, iapPublish: project, iapPoll: async () => { await commerce.poll(); return undefined; },
         iapRefresh: async () => { await commerce.loadPrices(items); return undefined; } },
     });

package/templates/beauty-salon-owner/dev/index.ts

@@ -51696,20 +51696,6 @@ const SCREENS = runtimeSetting({
                                   }
                                 }
                               },
-                              {
-                                "id": "",
-                                "body": {
-                                  "package": "himalaya",
-                                  "type": "Text",
-                                  "props": {
-                                    "text": "$service:himiOwnerLiteManage.summaryNote",
-                                    "style": "caption",
-                                    "color": "textSecondary",
-                                    "maxLines": 2,
-                                    "collapseWhenEmpty": true
-                                  }
-                                }
-                              },
                               {
                                 "id": "",
                                 "body": {
@@ -52334,6 +52320,9 @@ const SCREENS = runtimeSetting({
                               }
                             ]
                           }
+                        },
+                        "modifiers": {
+                          "animateContentSize": true
                         }
                       }
                     }

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

@@ -20,6 +20,13 @@ export interface CollectionQueryState<Row> extends CollectionPage<Row> {
   pageError: boolean;
   complete: boolean;
   error: string;
+  /** The rows are the source's `cached` page, shown while the live read is still out. */
+  provisional?: boolean;
+}
+/** What a collection showed, as `shownPage` hands it out and `seed` takes it back on a restored boot. */
+export interface CollectionShownPage<Row> {
+  state: CollectionQueryState<Row>;
+  loadedPages: number;
 }
 export interface CollectionQuerySource<Row> {
   fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
@@ -50,13 +57,19 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
   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;
+  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
+   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
+   *  it leaves those rows on screen, so it is still this. */
+  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
   let clearedByError = false;
   const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
   const emit = () => {
     if (disposed || revalidating === generation) return;
-    shown = { state: snapshot(), loadedPages };
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept.
+    if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
+      lastShown = state.items.length > 0 ? { state: snapshot(), loadedPages } : undefined;
+    }
     publish(snapshot());
   };
   const merge = (old: Row[], page: Row[]): Row[] => {
@@ -77,14 +90,14 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
     const criteria = copyQuery(state.criteria);
     if (!append) loadedPages = 0;
     state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
-      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false }) };
+      ...(append ? {} : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
     emit();
     try {
       if (!append && source.cached) {
         const cached = await source.cached(criteria).catch(() => undefined);
         if (disposed || generation !== revision) return;
         if (cached?.items.length) {
-          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false };
+          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
           emit();
         }
       }
@@ -94,17 +107,18 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
         total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
         metadata: page.metadata ?? (append ? state.metadata : undefined),
-        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor };
+        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
       loadedPages++;
     } catch (error) {
       if (disposed || generation !== revision) return;
       const clear = source.clearOnError?.(error) === true;
       // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
       clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
+      if (clearedByError) lastShown = undefined;
       if (clear) loadedPages = 0;
       state = { ...state, ...(clear ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
         status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
-        error: source.errorMessage?.(error) ?? '' };
+        provisional: false, error: source.errorMessage?.(error) ?? '' };
     }
     emit();
   };
@@ -117,8 +131,7 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
       const next = normalize(criteria);
       const same = JSON.stringify(next) === JSON.stringify(state.criteria);
       const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
-      const showing = 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;
+      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
       restoringPages = count;
       state = { ...state, criteria: next };
       if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
@@ -140,6 +153,27 @@ export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, p
         emit();
       }
     },
+    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
+     *  state; undefined when it shows none. */
+    shownPage(): CollectionShownPage<Row> | undefined {
+      if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
+      const page = lastShown.state;
+      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+    },
+    /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
+     *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page. */
+    seed(page: unknown): boolean {
+      const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
+      const restored = candidate?.state;
+      if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
+        || !Array.isArray(restored.items) || restored.items.length === 0 || typeof restored.nextCursor !== 'string') return false;
+      try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
+      state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
+        loadingMore: false, pageError: false, provisional: false, error: '' };
+      loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      lastShown = { state: snapshot(), loadedPages };
+      return true;
+    },
     refresh: () => { restoringPages = 0; return fetch(false); },
     loadMore: () => fetch(true),
     retry: () => fetch(state.pageError),