@wix/himalaya-cli 0.1544.0 → 0.1546.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/himi-json-output.md

@@ -493,3 +493,32 @@ Apple provisioning commands (`draft`, `plan`, `apply`, `status`, `screenshots`)
 legacy `--profile` combined with Catalog registration/route selectors as `invalid_usage`,
 before reading inputs or credentials. `connect` retains its intentional legacy profile plus
 Catalog mapping route and registration check.
+
+## Apple-key onboarding (`himi store apple-keys`)
+
+`setup` and `status` emit JSON with `ok`, `app`, `site`, `bundleId`, `asc`, `iap`,
+`ready`, `purchasesAppId`, and `completed`. `asc` carries `present` and available
+`keyId`/`issuerId`; `iap` carries `present`. A group omitted during setup has
+`present: null`, `state: "not_checked"`. A failed status read has `present: null`,
+`state: "unavailable"`; the other service is still read and reported, and the
+command exits 1 with `apple_keys_failed`. Setup also attempts both selected uploads
+independently and reports the successful writes if either service fails. No private
+key is returned. A successful
+read exits 0 even when `ready` is false. Dry runs add `dryRun: true` and `planned`.
+`completed` names writes confirmed during this invocation (`asc`, `purchases_app`,
+`iap`); it is not a transaction or a guarantee that a timed-out write did not land.
+
+| Code | Meaning |
+|---|---|
+| `invalid_usage` | Invalid identity, incomplete key flags, invalid/unreadable key or a key inside the repository, or missing `--yes`. Exit 2; no key writes. |
+| `owner_session_unavailable` | Himi/Wix owner credentials or target configuration could not be resolved. `error` retains the session diagnostic. |
+| `apple_keys_failed` | A service call, authorization check or read-back failed. Exit 1; earlier writes listed in `completed` remain stored. Read status before retrying. |
+
+The ASC endpoint (`GET`/`POST /v1/admin/store/asc-key`) also returns stable `code`
+values on failures: `unauthorized`, `token_revoked`, `revocation_check_unavailable`,
+`method_not_allowed`, `invalid_input`, `invalid_app_id`, `invalid_site_id`,
+`forbidden_cross_tenant`, `forbidden_site`, `invalid_asc_key`,
+`apple_keys_unconfigured`, `apple_keys_not_saved`, `build_secrets_busy`, or
+`apple_keys_unavailable`. `build_secrets_busy` is HTTP 409: another ASC upload or
+push setup holds the site; retry after it finishes. Responses have `Cache-Control:
+no-store`; both methods require app authority and current Wix site ownership.

package/guides/iap-products.md

@@ -33,6 +33,51 @@ catalogs. Subscriptions are refused before anything reaches Apple.
 
 These key and profile prerequisites apply to direct Apple mode. There is **no ambient fallback**: direct mode requires `--profile`, and exported `ASC_*` variables never select the account. Managed mode below uses no local `.p8`.
 
+## Set up the owner's Apple keys
+
+Use `himi store apple-keys setup` to upload either key independently of push setup
+and local signing profiles. The **App Store Connect API key** is stored in Branded
+BuildSecrets for Catalog. The separate **In-App Purchase key** is stored on the
+purchases app using the purchases service's `SetAppleCredentials` operation.
+Create the latter under App Store Connect → Users and Access → Integrations →
+In-App Purchase; an ASC API key cannot replace it.
+
+Sign into the owner's Wix account (`wix login`) and Himi (`himi login --browser
+--target wix`), and use an app slug that account already owns. Keep both `.p8`
+files outside the repository, including after resolving symlinks.
+
+```sh
+himi store apple-keys setup --app <slug> --site <metaSiteId> --bundle-id <bundle> \
+  --asc-key-file /private/keys/asc.p8 --asc-key-id <id> --asc-issuer-id <issuer> \
+  --iap-key /private/keys/iap.p8 --iap-key-id <id> --iap-issuer-id <issuer> --yes
+himi store apple-keys status --app <slug> --site <metaSiteId> --bundle-id <bundle> --json
+```
+
+Each key's three flags must be supplied together; omit the other group to upload
+only one key. Setup contacts only the services for the supplied key groups; an
+unselected group reports `present: null`, `state: "not_checked"`. Each group supplies
+its own issuer ID. `setup --dry-run` validates
+local inputs and reads stored status without registering an app or uploading keys.
+Without `--dry-run`, setup requires `--yes`; supplied keys replace the corresponding
+stored key. An IAP upload registers the bundle's purchases app if it does not exist,
+and reuses an existing registration. It does not connect the payment provider or
+create product mappings: run `himi store iap connect` afterward.
+
+Status returns presence for each key, ASC identifiers when available, and the
+`purchasesAppId` to use with Catalog commands. `ready` means both keys are stored;
+it does not prove Apple permissions, product readiness or payment-provider setup.
+Private keys are never returned or saved locally. Both commands emit JSON; a
+successful status read exits 0 even when a key is missing. Status reads both services
+independently; if one fails, it exits 1 but retains the other result and marks the
+failed group `present: null`, `state: "unavailable"`. Setup reports completed
+writes if a later step fails. When both keys are selected, a failure in one service
+does not prevent the other upload; read status before retrying. The ASC upload preserves
+existing signing, Google Play and live Ping credentials, and refuses when it cannot
+read the credentials needed for preservation. Concurrent ASC uploads and push setup
+exclude each other through the same site lease; a busy site returns HTTP 409.
+It never provisions certificates,
+profiles, APNs or Firebase. Containers Builder is not used.
+
 ## Managed provisioning through Catalog
 
 Provisioning commands use managed mode when `--profile` is absent; `--managed`
@@ -139,10 +184,10 @@ with Catalog's current revision, preserving the SKU, item identity, and metadata
 Managed `connect` never opens an Apple key on the Mac. It reuses an In-App Purchase key
 already stored by purchases. If there is none, it reports `apple_key_missing`; an App Store
 Connect API key is a different credential and cannot replace it. The purchases contract
-supports encrypted key writes but not reading a key back, and Branded does not currently
-provide a dedicated In-App Purchase key bridge. Provisioning that missing server key remains
-a backend prerequisite. Explicit legacy `--profile` plus `--iap-key` remains available for
-owner-driven onboarding. Supplying local key flags in managed mode is refused.
+supports encrypted key writes but not reading a key back. Upload the missing key with
+`himi store apple-keys setup` and its IAP key flags, then rerun managed connect.
+Explicit legacy `--profile` plus `--iap-key` also remains available. Supplying local
+key flags directly to managed connect is refused.
 
 For a managed draft, pass the Catalog registration and route:
 

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/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