@wix/himalaya-cli 0.1543.0 → 0.1545.0

package/fixtures/wix-canned.json

@@ -195,8 +195,8 @@
           "title": "Pour-Over Masterclass",
           "slot": {
             "serviceId": "svc-0001",
-            "startDate": "2026-08-08T10:00:00.000Z",
-            "endDate": "2026-08-08T11:30:00.000Z"
+            "startDate": "2027-08-08T10:00:00.000Z",
+            "endDate": "2027-08-08T11:30:00.000Z"
           }
         }
       },
@@ -290,8 +290,8 @@
         "eventType": "RSVP",
         "scheduling": {
           "config": {
-            "startDate": "2026-09-12T18:00:00.000Z",
-            "endDate": "2026-09-12T20:00:00.000Z"
+            "startDate": "2027-09-12T18:00:00.000Z",
+            "endDate": "2027-09-12T20:00:00.000Z"
           },
           "formatted": {
             "dateAndTimeTbdMessage": ""
@@ -317,8 +317,8 @@
         "eventType": "TICKETS",
         "scheduling": {
           "config": {
-            "startDate": "2026-10-03T19:00:00.000Z",
-            "endDate": "2026-10-03T22:00:00.000Z"
+            "startDate": "2027-10-03T19:00:00.000Z",
+            "endDate": "2027-10-03T22:00:00.000Z"
           },
           "formatted": {
             "dateAndTimeTbdMessage": ""
@@ -1632,8 +1632,8 @@
       "eventType": "RSVP",
       "scheduling": {
         "config": {
-          "startDate": "2026-09-12T18:00:00.000Z",
-          "endDate": "2026-09-12T20:00:00.000Z"
+          "startDate": "2027-09-12T18:00:00.000Z",
+          "endDate": "2027-09-12T20:00:00.000Z"
         },
         "formatted": {
           "dateAndTimeTbdMessage": ""

package/guides/dynamic-list.service.ts

@@ -12,8 +12,8 @@
 // Because this worker rides the Wix transport (globalThis.himalaya.wixApi), the
 // descriptor's logicBundle.declaredCapabilities MUST include "wix_api" (RFC 0043 D4).
 
-import { defineService } from "@wix/himalaya/state";
-import { productPrice, queryStoreProducts, type StoreProduct } from "@wix/himalaya/wix-stores";
+import { defineService, createReadController, initialReadStatus, type ReadMetadata, type ReadStatus } from "@wix/himalaya/state";
+import { productPrice, searchStoreProducts, type StoreProduct } from "@wix/himalaya/wix-stores";
 
 // FLAT strings only — the row template binds `$item.name`, never `$item.priceData.…`.
 // All shaping happens here in normalize(), not at the binding site.
@@ -30,6 +30,7 @@ type ErrorKind = "" | "offline" | "server" | "signIn" | "membership" | "permissi
 type ShownKind = Exclude<ErrorKind, "" | "signIn">;
 
 interface ProductsState {
+  readStatus: ReadStatus;
   status: "loading" | "ready" | "error";
   items: ProductRow[]; // ← itemsPath binds here; MUST initialize as an array
   errorKind: "" | ShownKind; // why the last load failed; "" unless status is "error"
@@ -64,10 +65,11 @@ function normalize(raw: StoreProduct): ProductRow {
 function shape(s: Partial<ProductsState>): ProductsState {
   const status = s.status ?? "ready";
   const items = s.items ?? [];
-  const errorKind: "" | ShownKind = status === "error" ? (s.errorKind || "server") : "";
+  const errorKind: "" | ShownKind = s.errorKind ?? (status === "error" ? "server" : "");
   const blank = items.length === 0; // nothing on screen to keep
   return {
     status,
+    readStatus: s.readStatus ?? initialReadStatus(),
     items,
     errorKind,
     hideLoading: !(status === "loading" && blank),
@@ -81,8 +83,13 @@ function shape(s: Partial<ProductsState>): ProductsState {
   };
 }
 
-// The classifier below is `himi docs recipe-four-state`'s, VERBATIM — a test holds
-// the two byte-identical, so the rules an agent copies from here are the documented ones.
+async function readProducts(cache: "only-if-cached" | "reload") {
+  let metadata: ReadMetadata | undefined;
+  const response = await searchStoreProducts({ limit: 50 }, { cache, onCacheResult: value => { metadata = value; } });
+  if (!metadata) throw new Error("Read provenance unavailable");
+  return { data: (response.products ?? []).filter(p => p?.id).map(normalize), metadata };
+}
+
 // The HTTP status rides in the message: `HTTP 503: …` on a device, `Wix 503 for …`
 // under `himi test` / `himi render`.
 const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
@@ -140,34 +147,36 @@ function shownKind(e: unknown): ShownKind {
   return kind === "signIn" ? "permission" : kind || "server";
 }
 
-async function loadList(s: Partial<ProductsState>): Promise<ProductsState> {
-  try {
-    const res = await queryStoreProducts(50);
-    const items = (res.products ?? []).filter((p) => p?.id).map(normalize);
-    return shape({ status: "ready", items, selectedId: s.selectedId });
-  } catch (e) {
-    const errorKind = shownKind(e);
-    // Keep the rows on a refresh failure; clear them when access is gone.
-    const lostAccess = errorKind === "membership" || errorKind === "permission";
-    const items = lostAccess ? [] : s.items ?? [];
-    return shape({ ...s, status: "error", items, errorKind });
-  }
-}
+// Keep the classified cause beside the controller's safe user message. Reclassifying
+// that message would turn every transport failure into a generic server error.
+let lastReadError: ShownKind = "server";
+const reads = createReadController<ProductRow[]>({
+  cached: () => readProducts("only-if-cached"),
+  fetch: () => readProducts("reload"),
+  clearOnError: error => {
+    lastReadError = shownKind(error);
+    return lastReadError === "permission" || lastReadError === "membership";
+  },
+  publish(items, readStatus) { void svc.publishRead({ items, readStatus }); },
+});
 
-const svc = defineService<ProductsState, {
-  load: (s: ProductsState) => Promise<ProductsState>;
-  retry: (s: ProductsState) => Promise<ProductsState>;
-  open: (s: ProductsState, arg?: unknown) => ProductsState;
-}>("products", {
+const svc = defineService("products", {
   state: shape({ status: "loading" }),
+  readLifecycle: { refreshAction: "refreshRead", statusPath: "readStatus" },
   actions: {
-    load: async (s) => loadList(s),
-    retry: async (s) => loadList(s),
-    // Row tap — receives the template's params ({ id: "$item.id" }, substituted per row).
-    // Stash the identity; wire real navigation per the tier-5 guide (detail screens).
-    open: (s, arg) => ({ ...s, selectedId: String((arg as { id?: string })?.id ?? "") }),
+    load: async () => { await reads.load("products:first-50"); return undefined; },
+    refreshRead: async () => { await reads.refresh(); return undefined; },
+    retry: async () => { await reads.refresh(); return undefined; },
+    publishRead: (state: ProductsState, value: { items?: ProductRow[]; readStatus: ReadStatus }) => {
+      const read = value.readStatus;
+      const errorKind = read.error ? lastReadError : read.offline ? "offline" : "";
+      return shape({ ...state, items: value.items ?? (read.hasSnapshot ? state.items : []), readStatus: read, errorKind,
+        status: read.hasSnapshot ? "ready" : read.refreshing ? "loading" : "error",
+      });
+    },
+    open: (state: ProductsState, arg?: unknown) => ({ ...state, selectedId: String((arg as { id?: string })?.id ?? "") }),
   },
 });
 
-svc.load(); // kick the fetch at worker boot — the screen opens on the loading state
+svc.load();
 export { svc };

package/guides/form-submit.service.ts

@@ -12,7 +12,7 @@
 // The write rides the Wix transport → the descriptor's logicBundle MUST declare
 // "wix_api" (RFC 0043 D4).
 
-import { defineService } from "@wix/himalaya/state";
+import { defineService, requireConnectivity } from "@wix/himalaya/state";
 import { createDraftPost, type WixDraftPostWrite, type WixRichContent } from "@wix/himalaya/wix-blog";
 
 interface PostFormState {
@@ -129,6 +129,7 @@ const svc = defineService<PostFormState, {
       const body = String(values?.body ?? "").trim();
       if (!title) return shape({ ...s, status: "error", error: "Title is required", savedMessage: "" });
       try {
+        requireConnectivity(); // Before optimistic state or a request; reconnect never submits.
         const r = await createDraftPost({
           title,
           richContent: toRichContent(body || title),

package/guides/index.json

@@ -32,6 +32,12 @@
     "User-facing copy is CONFIGURATION, never hardcoded in a descriptor: route every string through a copy key with a stock fallback — `copyOf(key, fallback)` — and feed worker-emitted strings in as descriptor params, so any app/template consumer can retheme ALL copy without touching descriptors. Wire the seam yourself: declare a local `const COPY: Record<string,string> = {…}` in your content package plus `export const copyOf = (k, fallback) => COPY[k] ?? fallback;`, keyed `<screen>.<element>` so a later template publish is mechanical. Either way the rule is the same: no user-facing string baked into a descriptor literal."
   ],
   "guides": [
+    {
+      "id": "offline-reading",
+      "title": "Offline reading and recovery",
+      "category": "Tier-5 Screens",
+      "file": "offline-reading.md"
+    },
     {
       "id": "hhp",
       "title": "Responsive HTML to native Himi",

package/guides/offline-reading.md

@@ -0,0 +1,63 @@
+# Offline reading and recovery
+
+Himalaya provides connectivity monitoring, an accessible shell bar, policy-controlled response caches, and a read lifecycle for generated screens. Offline support covers reading. Saving still requires connectivity and an explicit submission after reconnect.
+
+## User-facing states
+
+| State | Behavior |
+| --- | --- |
+| Offline with an eligible snapshot | Keep the content, including a successfully loaded empty result. Show “You’re offline. Showing previously loaded content.” |
+| Offline without an eligible snapshot | Show “This content isn’t available offline. Connect to load it.” Never infer an empty result from a failed request. |
+| Reconnected | Keep the content while showing “Refreshing…”. Refresh the visible read participant in place. |
+| Refresh failed | Keep the snapshot and show “Couldn’t refresh. Content may be outdated.” with Retry. Without a snapshot, show an unavailable state with Retry. |
+| Refresh succeeded | Apply the server result and clear the stale/error indication. Connectivity alone never means content is current. |
+
+The shared shell owns the bar and reserves layout space for it. Do not add app-owned banners, reload the application, reset navigation, or recreate workers on reconnect. Presented screens participate too. Recovery is deferred while a screen or application is inactive.
+
+For steps to adopt this contract in another starter, see [Add offline reading to a starter template](offline-reading-template-adoption.md).
+
+## Register a safe read
+
+Use `createReadController` from `@wix/himalaya/state` for a custom collection or detail screen. Register `readLifecycle: { refreshAction: "refreshRead", statusPath: "readStatus" }` on its service. Only the declared action participates in automatic recovery; it must perform reads only. Never register a submit, checkout, queue-draining, or generic action dispatcher as a refresh action.
+
+The controller distinguishes `hasSnapshot` from the length of a list. Its status includes `refreshing`, `fromCache`, `stale`, `offline`, `lastSuccessAt`, and `error`. Publish status changes without clearing existing rows. Change its key when the route or server criteria change; never treat an unfiltered cached subset as a successful server search. Dispose the controller when its scope ends. Managed worker teardown and identity changes also notify controllers automatically.
+
+The runnable dynamic-list example demonstrates keeping rows during a failed refresh. Shared starter collections additionally stage replacement pages using new cursors and commit the whole loaded depth together. A failed replacement leaves the previous pages, filters, and selection intact. Keep item IDs stable so renderers retain scroll anchors where those items still exist.
+
+## SDK reads and cache policy
+
+Wix call options accept `cache: "only-if-cached"` and `cache: "reload"`, plus `onCacheResult(metadata)`. Business response payloads are unchanged. Existing calls without options retain their default behavior.
+
+* `only-if-cached` never sends a network request. Ineligible, absent, expired, or insufficiently scoped entries reject with `OFFLINE_CACHE_MISS`.
+* `reload` waits for the network. Use it for reconnect and Retry; another cache hit is not recovery.
+* Metadata describes `source` (`cache` or `network`), `fetchedAt`, `expiresAt`, and `cacheable`. Cache-only snapshots need cache provenance, eligibility, and a future expiry. For a screen composed of multiple required reads, combine the earliest expiry and require eligibility for every response.
+
+Initial loads can paint an eligible cache response before network revalidation. Keep the existing endpoint allowlist and retention limits. Optional enrichment can be omitted offline; a failed primary read must reject. Do not substitute sample data after errors. Explicitly selected sample previews remain separate from live data.
+
+## Identity and persistence
+
+Use the host's response cache, scoped by app, site, principal, release, and request criteria. Do not persist network responses in unscoped local database rows or generic worker snapshots. Managed read services are excluded from worker persistence and hydration. Legacy worker snapshots are not hydrated by the new hosts. Unrelated local preferences and authored content remain local.
+
+Clear private visible state on sign-out or access denial, and reject delayed results from a departed identity. Unknown identity is not permission to reuse the last signed-in user's cache. Ordinary transport/server failures retain content; access denial does not. Custom adapters should supply `clearOnError` for their typed authorization errors and invalidate their controller when their own scope changes.
+
+## Writes and runtime compatibility
+
+Call `requireConnectivity()` before optimistic changes or queue insertion. Keep entered values on failure, explain that saving requires connectivity, and let the user submit again explicitly. Reconnect never submits a draft or drains a queue. Shared starter editor loads use the same read lifecycle while keeping an open draft and its concurrency revision together; recovery must not silently replace typed fields or rebase a draft onto a newer revision. A new unsaved form is explicitly local content, not a cached server response.
+
+Services using the contract require `himalaya.readLifecycleVersion >= 1` and the Wix read bridge. The state SDK refuses unsupported runtimes with `READ_LIFECYCLE_UNSUPPORTED`; silently ignoring the contract would expose stale content. Ship the updated native runtime and web host before publishing starter bundles that use it. This does not make an unloaded browser application available offline.
+
+## Verification recipe
+
+1. Load a real list online, choose a filter, scroll, and load another page.
+2. Disconnect. Confirm the same content remains, with an accessible offline announcement and an unobstructed bar. A successful empty response must remain distinguishable from missing data.
+3. Open an uncached route or change server criteria. Confirm an honest unavailable state, with no demo rows or mismatched cached results.
+4. Change server data, reconnect, and confirm visible content updates without navigation, filter, selection, or page-depth reset. Repeat while backgrounded and with a presented detail screen.
+5. Reconnect to a failing backend. Confirm stale content and Retry remain until a successful network response. Rapid connectivity changes must coalesce reads and never replay writes.
+6. Relaunch native apps offline within cache retention. Check expiry, policy changes, app/site/account switches, sign-out during hydration or refresh, revoked access, and delayed responses.
+7. Submit a starter form offline. Confirm values remain, no optimistic record or success message appears, nothing is queued, and reconnect alone does not submit it.
+
+Run controller, bridge/cache, identity, collection, starter-generation, and authoring tests. Drive iOS, Android, macOS, and web preview, and record native offline relaunch. Recovery telemetry uses the existing `offline_read_recovery` event with outcome only; never include response contents or user identifiers.
+
+<!-- platform-lint-ok: This guide covers the native shared shells and loaded web preview requested by this change; React Native host adoption is outside this rollout. -->
+
+Initial adoption is limited to product lists and product details in Branded Lite and Retail Store. Other screen adoption is deferred; see [the follow-up scope](offline-reading-follow-up.md).

package/guides/one-app-to-himi-app.md

@@ -414,10 +414,12 @@ auth: WixConsumerAuthProvider({
 ```
 
 Every surface reads the site with it: the native apps, the hosted draft preview, and
-`himi run`, `himi render --live` and `himi test --record`. It is a visitor: member
-sign-in still needs a Headless OAuth client.
+`himi run`, `himi render --live` and `himi test --record`. On iOS and Android the same
+binding also signs a site member in with email and password (the Branded app's own
+member flow), still without a client. Google sign-in, registration, password reset and change, and member
+sign-in on the web still need a Headless OAuth client.
 
-**Only when the site owner wants member sign-in now**, and with their agreement,
+**Only when the site owner wants those (Google, registration, web member sign-in)**, and with their agreement,
 resolve the site's mobile OAuth client with the existing idempotent command (it is
 an owner-scoped write to the customer's site):
 

package/guides/recipe-dynamic-list.md

@@ -1,5 +1,7 @@
 # Recipe: dynamic list from worker data
 
+For cached reads, unavailable offline states, safe reconnect actions, and failed-refresh retention, follow [Offline reading and recovery](../offline-reading.md) (also available as himi docs offline-reading). A refresh failure must preserve useful content; an empty result requires a successful read.
+
 Render a **live array from your Tier-5 worker** as a scrolling list — the single most
 common Himi screen shape (products, bookings, events, posts, contacts…). This recipe
 stitches together three pieces that are each documented separately but easy to miss as

package/guides/recipe-four-state.md

@@ -1,5 +1,6 @@
 # Recipe: four screen states (loading / empty / error / ready)
 
+For cached reads, unavailable offline states, safe reconnect actions, and failed-refresh retention, follow [Offline reading and recovery](../offline-reading.md) (also available as himi docs offline-reading). A refresh failure must preserve useful content; an empty result requires a successful read.
 **The rule every recipe follows:** a screen that loads or writes data shows a
 **loading state**, a **classified error state**, and a **recovery action where the
 user can fix the failure** — retry for an offline or a server failure, and for a failed