@wix/himalaya-cli 0.1465.0 → 0.1467.0

package/guides/form-submit.service.ts

@@ -7,6 +7,7 @@
 // The worker validates there, lands the write, and reports the outcome as state
 // (error / savedMessage strings + a hideSavedLink boolean), so the descriptor
 // renders every outcome with plain collapseWhenEmpty Texts + one gated button.
+// A failed write keeps the typed values and shows a classified, user-facing line.
 //
 // The write rides the Wix transport → the descriptor's logicBundle MUST declare
 // "wix_api" (RFC 0043 D4).
@@ -24,6 +25,7 @@ interface PostFormState {
   savedMessage: string;  // "" unless saved           → collapseWhenEmpty
   hideSavedLink: boolean; // gates the "Open post" button via hiddenPath
   savedScreenId: string;  // deep-link target for the created entity
+  cannotSave: boolean;    // true after a permission failure → the submit's disabledPath
 }
 
 function shape(s: Partial<PostFormState>): PostFormState {
@@ -37,25 +39,69 @@ function shape(s: Partial<PostFormState>): PostFormState {
     savedMessage: s.savedMessage ?? "",
     savedScreenId,
     hideSavedLink: status !== "saved" || !savedScreenId,
+    cannotSave: s.cannotSave ?? false,
   };
 }
 
+// A failed save is an ACTION error: one user-facing sentence per class, shown next to
+// the submit button, which is the retry (`himi docs recipe-four-state`). Never e.message.
+type ErrorKind = "offline" | "server" | "signIn" | "permission";
+const SAVE_FAILED: Record<ErrorKind, string> = {
+  offline: "You're offline, so nothing was saved. Try again when you reconnect.",
+  server: "Couldn't save your changes. Try again.",
+  signIn: "Your session has ended. Sign in, then save again.",
+  permission: "You don't have permission to save this.",
+};
+
+// The HTTP status rides in the message: `HTTP 503: …` on a device, `Wix 503 for …`
+// under `himi test` / `himi render`. Only a transport failure is "offline".
+const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
+// No answer at all — what a dropped connection says on every platform.
+const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|Failed to connect|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+// Android reports an unknown host as the bare hostname (`users.wix.com`) — hence the last form.
+// No session on the device: the native bridge refuses before any request leaves.
+// A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
+// Android `site account is not the bound site …`; the web host `HTTP 501: {"error":"webwix_owner_no_session"}`.
+const SIGNED_OUT = /wixApi not enabled|session unavailable|PRINCIPAL_CHANGED|not signed in|siteNotPermitted\(requested: "account"|site account is not the bound site|webwix_owner_no_session/i;
+
+// The same classifier as `himi docs recipe-four-state`.
+function classifyError(e: unknown): ErrorKind {
+  const msg = String((e as Error)?.message ?? e ?? "");
+  const code = String((e as { code?: unknown })?.code ?? "");
+  const status = Number(STATUS.exec(msg)?.[1] ?? 0);
+  if (status === 401) return "signIn";
+  if (status === 403) return "permission";
+  if (SIGNED_OUT.test(msg)) return "signIn";
+  if (code === "offline_write_blocked") return "offline"; // a write refused before it left
+  // A web call that never reached Wix arrives as
+  // `HTTP 502: {"error":"webwix_direct_failed","detail":"Failed to fetch"}` — judge its detail.
+  if (status && !msg.includes("webwix_direct_failed")) return "server";
+  if (TRANSPORT.test(msg)) return "offline";
+  return "server"; // a bug or a malformed row is not the user's connection
+}
+
 // Blog draft bodies are rich content — wrap the plain text minimally.
 function toRichContent(text: string): WixRichContent {
   return { nodes: [{ type: "PARAGRAPH", nodes: [{ type: "TEXT", textData: { text, decorations: [] } }] }] };
 }
 
+// Every key that describes the LAST attempt, not this run: a cold boot starts from the declared values.
+const OUTCOME_KEYS = ["status", "error", "savedMessage", "savedScreenId", "hideSavedLink", "cannotSave"] as const;
+
 const svc = defineService<PostFormState, {
   submit: (s: PostFormState, values?: Record<string, unknown>) => Promise<PostFormState>;
 }>("postForm", {
   state: shape({}),
+  // Outcome keys are per-attempt: a cold boot must not restore a stale error, or a submit
+  // disabled by a 403 the user has since been granted past.
+  notHydrated: OUTCOME_KEYS,
   actions: {
     // `values` is the ONLY channel for what the user typed — keyed by FormField id.
     // Coerce defensively: everything but toggles arrives as a string-ish unknown.
     submit: async (s, values) => {
       const title = String(values?.title ?? "").trim();
       const body = String(values?.body ?? "").trim();
-      if (!title) return shape({ ...s, status: "error", error: "Title is required" });
+      if (!title) return shape({ ...s, status: "error", error: "Title is required", savedMessage: "" });
       try {
         const r = await createDraftPost({
           title,
@@ -69,10 +115,22 @@ const svc = defineService<PostFormState, {
           savedScreenId: id ? `my_post_${id}` : "", // wire a templated detail route per the tier-5 guide
         });
       } catch (e) {
-        return shape({ ...s, title, body, status: "error", error: String((e as Error)?.message ?? e) });
+        const kind = classifyError(e);
+        // Echo what the user typed back into the prefill, so a failed save loses nothing.
+        // Clear the last success line: a failed attempt must not also read "Draft created.".
+        return shape({ ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "", cannotSave: kind === "permission" });
       }
     },
   },
 });
 
+// An older runtime ignores `notHydrated` (it does not set `himalaya.hydrationOptOut`) and restores the
+// whole snapshot: reset the outcome keys in place before any action runs, or a 403's disabled submit
+// would come back on every launch with no way to clear it.
+if ((globalThis as { himalaya?: { hydrationOptOut?: unknown } }).himalaya?.hydrationOptOut !== true) {
+  const booted = (svc as unknown as { getState?: () => Record<string, unknown> | undefined }).getState?.();
+  const fresh = shape({}) as unknown as Record<string, unknown>;
+  if (booted && typeof booted === "object") for (const k of OUTCOME_KEYS) booted[k] = fresh[k];
+}
+
 export { svc };

package/guides/getting-started.md

@@ -323,7 +323,8 @@ pull-to-refresh + load-more), a create/edit form `examples/form-submit.*`
 (`himi docs recipe-form-submit`), a searchable list `examples/search-list.*`
 (`himi docs recipe-search`), a first-run onboarding card `examples/onboarding.*`
 (`himi docs recipe-onboarding`), and the loading/empty/error/ready idiom they all share
-(`himi docs recipe-four-state`). Then — **before you
+(`himi docs recipe-four-state` — every recipe that loads or writes data shows a loading state,
+a classified error state and a recovery action where the user can fix the failure). Then — **before you
 design** — read the UX guide (`himi docs designing-himi-screens`) and, for a multi-screen app,
 the mobile contract guide (`himi docs mobile-ux`), then follow
 *Author a Tier-5 screen*.

package/guides/himi-skill.md

@@ -346,7 +346,8 @@ pull-to-refresh + load-more), a create/edit form `examples/form-submit.*`
 (`himi docs recipe-form-submit`), a searchable list `examples/search-list.*`
 (`himi docs recipe-search`), a first-run onboarding card `examples/onboarding.*`
 (`himi docs recipe-onboarding`), and the loading/empty/error/ready idiom they all share
-(`himi docs recipe-four-state`). Then — **before you
+(`himi docs recipe-four-state` — every recipe that loads or writes data shows a loading state,
+a classified error state and a recovery action where the user can fix the failure). Then — **before you
 design** — read the UX guide (`himi docs designing-himi-screens`) and, for a multi-screen app,
 the mobile contract guide (`himi docs mobile-ux`), then follow
 *Author a Tier-5 screen*.

package/guides/index.json

@@ -25,6 +25,7 @@
     "Keep structure descriptor-authored: use FragmentSlot for enumerable variants and bound list/grid templates for repetition. Use WorkerSubtree only for runtime-unknowable structure, with an explicit screen allowlist, policy budgets, and shipped fallback.",
     "Bindings ($service:<svc>.<path>, $item.<field>, $flag:<key>) are plain strings in ANY prop — INCLUDING Modifiers token refs (background, color, tint), so a worker can drive per-item theming, not just text. They CANNOT target strict-enum fields (style, size, alignment, severity, presentation, …) — those fail at render, not validation.",
     "A screen that loads data asynchronously ships a designed LOADING state with it — a `Skeleton` shaped like the loaded layout when that layout is known (`StatefulSection` or `ActivityIndicator` when they fit the behavior better) — and a REDESIGN of a data screen reviews and updates that loading state in the same change, so it never shows the old layout. Loading is its own state, never the empty or the error state; a static screen gets no loading state (`himi docs designing-himi-screens` §5).",
+    "CLASSIFY every error before you show it: offline, server failure and permission/sign-in each get their own `EmptyState` with `title` + `subtitle` and NO `icon` (one node per class, gated by `hiddenPath`, because iOS/Android do not bind `$service:` in its text), user-facing copy — never `e.message`, a status code or an API error string — and an `action` + `actionLabel` ONLY for a real recovery (Try again for offline, server and failed writes; Sign in for sign-in; none for permission, empty results or field errors). Empty results are the empty state, not an error. A refresh that fails KEEPS the rows and adds a `Banner` with retry; a load-more that fails keeps the rows and ends the list with a \"Couldn't load more\" row that retries the SAME cursor (`himi docs recipe-dynamic-list`), never the Banner, which reloads page 1. A sign-in or permission failure CLEARS the rows instead — they are no longer the user's to see. Field errors stay in the field's slot; a failed action shows next to the action. When an `ErrorState` component ships, only the component changes — these rules stay (`himi docs designing-himi-screens` §5, `himi docs recipe-four-state`).",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",
     "Declare every capability a worker uses in TWO places: the calling screen's logicBundle.declaredCapabilities (wix_platform, stream, camera, location, …) — undeclared calls are blocked — AND config.ts `capabilities`, the app-level list a binary is built with. The `capabilities` guide shows each id's import, what the binary needs and which shells serve it; validate flags an unknown id, an undeclared call, and (with `shell` in himalaya.content.json) an id that shell's binary does not serve. A capability with a native footprint (camera, location, push, …) only arrives with a new binary — an over-the-air push cannot add it. EXCEPTION: the Wix REST bridge (wix_api — the @himalaya/wix-* clients / wixApi.call) is ungated today (installed unconditionally), so it works WITHOUT a declaration; declaring wix_api is still recommended — it is where the platform is heading, and it documents what your worker touches.",
     "`validate`/`render` prove a screen is WELL-FORMED and, by default, paint its INITIAL state — NOT that the app's LOGIC is correct. A wrong reducer (a game that never ends, a bad total) passes both with ok:true. Run `himi test`: it needs NO test files — it boots each screen's real worker and dispatches every action your descriptor already declares, then reports anything that threw, stayed stuck on `loading`, or leaked a NaN/undefined/`$service:` token into visible text. It crawls on HERMETIC DATA by default (zero network): your `dev/net-mocks.json` first, then your config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI — so the fetch-SUCCESS mapping path runs too, where data-shape bugs actually live (canned data exercises code paths, not API-contract truth). Two boot-only HOSTILE passes (every list empty; every request 500) then check the empty/outage day — their findings are errors, not warnings. It also runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView), so a bundle that would only die on the device fails locally instead — e.g. `svc.actions.load(…)` (actions are DIRECT methods; `.actions` is undefined on device). (You are NOT limited to the crawled states either: rendering with `--live` runs the worker's REAL fetches against live Wix — a minted anonymous visitor token from the app's clientId — so a render CAN prove real-data binding locally with no VPN/push; and injecting `state` (`{\"<svc>\":{…}}`) renders a specific mid-flow state without the network.)",

package/guides/qa-builds.md

@@ -1026,6 +1026,81 @@ that block off the first Android `himi dist` run to settle the question with a m
 than an assumption, the way the iOS identities were settled on 2026-07-27 after two wrong
 diagnoses.
 
+### An Android App Bundle for Google Play — `--aab`
+
+An APK installs on a device. Google Play wants an **Android App Bundle** (`.aab`) for a new app,
+and a bundle installs on nothing. `--aab` builds the bundle instead, for an owner who downloads the
+Wix-built binary and uploads it to Play Console themselves:
+
+```sh
+himi login --dpx --target bo        # an INTERNAL caller: self-serve callers get 403 (see below)
+himi dist --app <app> --platform android --aab --wait --target bo
+```
+
+- **What you get:** `artifact.downloadUrl` (presigned, 7 days) and `artifact.sha256`. No
+  `installLink`, no `installPageUrl`, no QR, and `GET /v1/dist/<jobId>/install` answers 404 for it —
+  a link that hands a phone a file it cannot open is worse than none. The record carries
+  `androidFormat: "aab"`.
+- **Android only.** The default stays an APK, and iOS is untouched. It travels as
+  `androidFormat: "aab"` on `POST /v1/admin/dist` (every `/v1/owner/dist` caller is self-serve, so
+  that route always answers `403 android_format_not_allowed`), and reaches the pool as
+  `DIST_ANDROID_FORMAT=aab` in the `command` blob (see
+  [why](#why-the-jobs-parameters-ride-in-command-not-envvars)). Refusals, all typed 400s before
+  any pool time is spent: `invalid_android_format` (anything but `apk` / `aab`),
+  `android_format_requires_link` (any destination but `link`), `android_format_requires_android`
+  (an iOS-only build, where the flag would be dropped in silence), and
+  `android_format_requires_wix_keystore` (any `--android-signing` other than `wix-keystore`), and
+  `android_format_shell_unsupported` (the `owner-lite` shell, whose gradle build refuses a store
+  bundle without a real Firebase config and customer identity). A mixed `--platform ios,android`
+  applies it to the Android leg only.
+- **How the pool builds it.** `run-dist` runs store-release's `bundleRelease` task
+  (`bundleReleaseArgs` / `bundleReleaseEnv`, the same task the Play lane runs) with **AGP injected
+  signing**, with the **Wix production key** (`wix-keystore`: `~/.signing/oneapp-production.keystore`,
+  alias `WixOne`), resolved by `resolveAndroidSigner` and verified there. The pool refuses any
+  other signer for a bundle — a pool-side `DIST_ANDROID_KEYSTORE` included. The keystore path and alias are `-P` flags; the passwords ride in the environment as
+  `ORG_GRADLE_PROJECT_android.injected.signing.{store,key}.password`, never in argv. `jarsigner
+  -verify` must say `jar verified.` before anything is uploaded. The seed gate and the binary-size
+  budget run on the `.aab` as they do on an APK. `DIST_ANDROID_BUNDLE_TASK` overrides the task
+  (`DIST_ANDROID_TASK` stays the APK one), and `DIST_ANDROID_FLAVOR` picks among flavored bundles.
+  Only the task's own gradle module is searched, so a sibling module's stale bundle is never taken.
+  An **ambiguous** choice fails the build instead of guessing: the bundle's applicationId becomes
+  the app's permanent Play package.
+- **What it skips, and why.** `apksigner` and the re-sign step (a bundle is JAR-signed at build
+  time, and the injected config overrides any `signingConfig`); the 16 KB check (its ZIP half is about an installed APK,
+  which Play generates; its ELF half reads the APK `lib/` layout — Play checks alignment on
+  upload); and `--reuse-artifact` (that is an APK).
+- **Version skew.** The pool runs the release's own `run-dist`, and one older than `--aab` ignores
+  `DIST_ANDROID_FORMAT` and builds an APK. So the pool reports what it built (`androidFormat` on
+  the result callback, the `androidSigningUsed` pattern), and serve-control turns a `SUCCESS` that
+  does not say `aab` into **`FAILURE`** with `android_format_not_built: …`, recording
+  `androidFormat: "apk"`, and drops the artifact link. The verdict is read from that error on every
+  read, so a status refresh that races the callback cannot bring back `SUCCESS`. **An old runner
+  never signs with the Wix key:** for a bundle the plane dispatches `DIST_ANDROID_SIGNING=qa-keystore`,
+  and the new run-dist overrides it with `wix-keystore`, derived from `DIST_ANDROID_FORMAT=aab`. A
+  run-dist older than `--aab` therefore signs an ordinary QA APK, never an installable APK carrying
+  the Wix production certificate. The QA key is named rather than left out, because a named key
+  outranks a pool machine's `DIST_ANDROID_USE_WIX_KEYSTORE=1`. A bundle must also report `androidSigningUsed: "wix-keystore"`; one signed
+  with any other key, or that reports none, fails as `android_format_wrong_signer` with its link
+  dropped. Rebuild from a release published on a newer commit. The other direction fails too: an
+  APK job whose pool reports a bundle is `android_format_not_requested`, with its link dropped. A
+  brokered job reads the format from its OWN parameters only, so a machine with
+  `DIST_ANDROID_FORMAT=aab` in its environment no longer turns an APK job into a bundle; the check
+  stays for a runner older than that rule. A later delivery that passes every check (a retry on a
+  clean machine) clears the verdict.
+
+**Why the Wix production key, and only for a bundle.** There are two Android keys: the committed
+QA keystore and the Wix production key (WixOne). WixOne is the Play **upload** key every Branded
+app's bundle carries (`mobile-apps-engine` refuses any other certificate for a Play build), with
+Play App Signing on, so Google re-signs what users install. An `.aab` therefore signs with it —
+only its `WixOne` entry of `oneapp-production.keystore`: the alias is pinned for a bundle, whatever
+alias the pool's signing files name. Because the first upload binds a Play listing to that key for good, a **self-serve** caller
+gets no bundle at all (`403 android_format_not_allowed`): `--aab` is for internal callers until a
+Containers store build checks the app, its owner and its package name. A self-serve **APK** with
+`wix-keystore` keeps `403 android_signing_not_allowed`, unchanged. For the owner, the Play listing is bound to the WixOne upload certificate, so later
+updates come from Wix builds too; leaving Wix needs an upload-key reset through Play Console
+support. A pool machine without the key fails the build, naming the paths it searched, rather than
+signing with another key.
+
 ### The iOS lane lives in one shared place
 
 `fastlane dist` runs with `cwd = <app>/ios`, so it needs `<app>/ios/fastlane/Fastfile`. That file is
@@ -1118,6 +1193,9 @@ baking the live asset.
   or `DIST_ANDROID_USE_WIX_KEYSTORE=1` names one, and a named key wins — `apksigner` replaces the
   signature block — because the job record is written at dispatch and would otherwise name a key
   that is not on the binary.
+- **Android, `--aab`** → a **presigned `.aab` download URL** and its sha256, and **no install
+  link**: a bundle is uploaded to Google Play, it does not install on a device. See
+  [the App Bundle section](#an-android-app-bundle-for-google-play----aab).
 - **How Android picks up the branding.** `prepare:customer` writes an **xcconfig** for iOS (bundle
   id + display name) but on Android only tokens, the icon drawable and a colour XML. Android's
   `applicationId` and app label come from the **contract JSON itself**, read at gradle-configure

package/guides/recipe-dynamic-list.md

@@ -60,9 +60,12 @@ interface Row {              // FLAT strings/booleans only — see "Normalize" b
 interface State {
   status: "loading" | "ready" | "error";
   items: Row[];
-  loadingText: string;       // "Loading…" while loading, "" after  → collapseWhenEmpty
-  emptyText: string;         // "No products yet." when ready+empty, "" otherwise
-  error: string;             // message when failed, "" otherwise
+  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e), never the raw message
+  // hide* flags for hiddenPath, derived in shape() — see `himi docs recipe-four-state`
+  hideLoading: boolean; notEmpty: boolean;
+  hideOfflineError: boolean; hideServerError: boolean;
+  hideSignInError: boolean; hidePermissionError: boolean; hideRefreshError: boolean;
+  nextCursor: string; failedCursor: string; hideLoadMoreError: boolean;  // §5 load-more
 }
 ```
 
@@ -143,25 +146,46 @@ nesting to one level: a carousel of carousels is legal and unreadable.
 - A binding substitutes only when it is the **entire prop value** — never mid-string
   (`"Total: $item.price"` renders the raw token). Pre-compose strings in the worker.
 
-## 4. Four-state, the corpus way
-
-Loading / empty / error live in **worker-computed display strings** bound to `Text`s
-with `collapseWhenEmpty: true` — each renders only in its state, no conditional
-layout needed:
+## 4. Loading, error and retry
+
+A list loads data, so it ships all four states — the full idiom is
+`himi docs recipe-four-state`. For a list it comes down to this:
+
+- **Loading** — a `Skeleton` shaped like the rows (`height` of one row, `count`
+  about one screen of them), gated by `hiddenPath: "$service:products.hideLoading"`.
+  It shows only while the first load runs with nothing on screen; a pull-to-refresh
+  keeps the rows and uses the list's own spinner.
+- **Empty** — an `EmptyState` with a directive action, gated by `notEmpty`.
+- **Error, nothing on screen** — one `EmptyState` per class `classifyError` can
+  return (offline, server, sign-in, permission), **no icon**, user-facing copy.
+  Offline and server get **Try again** → `tier5.products.retry`; sign-in gets
+  **Sign in**; permission gets no action. A list with no sign-in flow maps
+  `"signIn"` to `"permission"` — a visitor still gets a 401 or 403 (Bookings
+  `searchServices`, above) and a missing node paints a blank screen. The worker's
+  `catch` sets `errorKind` from `classifyError(e)` — never `String(e.message)`,
+  which shows the user a wire error.
+- **Error, rows on screen** — a pull-to-refresh that fails offline or on the
+  server keeps the rows (`shape({ ...s, status: "error", errorKind })`, `items`
+  untouched) and shows a `Banner` with **Try again** above them, gated by
+  `hideRefreshError`. A sign-in or permission failure clears the rows instead.
+  A failed **load-more** has its own retry (§5).
 
 ```jsonc
-{ "id": "loading", "body": { "package": "himalaya", "type": "Text",
-    "props": { "text": "$service:products.loadingText", "style": "body",
-               "color": "textSecondary", "collapseWhenEmpty": true } } },
-{ "id": "empty",   "body": { "…text": "$service:products.emptyText",  "…": "collapseWhenEmpty" } },
-{ "id": "error",   "body": { "…text": "$service:products.error",     "…": "collapseWhenEmpty" } }
+{ "id": "loading",
+  "body": { "package": "himalaya", "type": "Skeleton",
+    "props": { "height": 72, "cornerRadius": 12, "count": 6 } },
+  "modifiers": { "hiddenPath": "$service:products.hideLoading" } },
+{ "id": "error.server",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Unable to load products",
+               "subtitle": "There was a technical issue on our end. Please wait and try again later.",
+               "action": { "actionId": "tier5.products.retry" }, "actionLabel": "Try again" } },
+  "modifiers": { "hiddenPath": "$service:products.hideServerError" } }
 ```
 
-Pair the error text with a `Button` → `tier5.products.retry`. (Richer screens gate
-whole sections with the `hiddenWhen` modifier bound to worker booleans — see
-`apps/himi-owner-lite`; start with `collapseWhenEmpty`, it covers most lists.)
-Design guidance for these states: `himi docs designing-himi-screens` §5, and the
-full state-machine idiom: `himi docs recipe-four-state`.
+(Richer screens gate whole sections with the same `hiddenPath`/`hiddenWhen`
+modifiers — see `apps/himi-owner-lite`.) Design guidance for these states:
+`himi docs designing-himi-screens` §5 ("Loading states", "Error states").
 
 ## 5. Refresh + load-more gestures (RFC 0008)
 
@@ -193,6 +217,16 @@ native decoders drop anything else without a word:
   stashed cursor, **append de-duplicated** rows (`seen` by id), roll `nextCursor`
   from the response (`pagingMetadata.cursors.next ?? ""`), and on failure set
   `nextCursor: ""` but **keep the rows** — a broken page-2 must not blank page-1.
+  Stash the cursor that failed (`failedCursor`) and show a small "Couldn't load
+  more" row with **Try again** at the end of the list (gated by
+  `hideLoadMoreError`), whose action restores `nextCursor = failedCursor` and runs
+  `loadMore` again. Do not route it through the refresh `Banner`: that **Try
+  again** reloads page 1 and throws away the pages already shown.
+- **Except when page 2 loses access.** A `signIn` or `permission` failure on
+  `loadMore` is not retryable and the rows already shown are no longer the
+  user's to see: clear them and go to the same sign-in / permission
+  `EmptyState` a refresh uses (`load()` in `himi docs recipe-four-state`). Keep
+  page 1 and offer the cursor retry only for `offline` and `server`.
 - APIs that don't page (or v1 fallbacks without cursors) simply never set
   `nextCursor` — the gesture props are safe to leave in place.
 
@@ -245,10 +279,11 @@ Mechanics and the prod caveat in full: `himi docs tier-5-add-a-screen`.
   no longer needed; prefer the component, which stays accessible and themable.
 - **Declare `wix_api`** in `logicBundle.declaredCapabilities` if the worker touches
   the Wix transport — validate warns (errors pre-push), and the native gate enforces it.
-- **`himi render` shows initial state; `himi render --live` shows REAL data.** Plain
-  `himi render` boots the worker so `$service:` bindings resolve — but to the *initial*
-  state (your loading frame), because it does not await `load()`: expect `loadingText`,
-  not rows. To prove real-data binding **locally, with no VPN and no push**, add `--live`:
+- **`himi render --no-mocks` shows the loading frame; `himi render --live` shows REAL
+  data.** `himi render` boots the worker so `$service:` bindings resolve. When the app
+  has recorded data (`dev/net-mocks.json`, CMS seed rows) it runs `load()` against that
+  data by default and shows rows; with none, or with `--no-mocks`, it shows the
+  *initial* state — your loading skeleton, not rows. To prove real-data binding **locally, with no VPN and no push**, add `--live`:
   it mints an anonymous visitor token from the app's `clientId` and **awaits the worker's
   real fetches** against live Wix, so the render shows actual rows and catches live-only
   binding bugs (a mistyped `$item.<field>` an empty initial array can't disprove). Use

package/guides/recipe-form-submit.md

@@ -35,6 +35,7 @@ the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi
       ],
       "submitButton": { "id": "save", "body": { "package": "himalaya", "type": "Button",
         "props": { "title": "Create post", "style": "primary", "fullWidth": true,
+                   "disabledPath": "$service:postForm.cannotSave",
                    "action": { "actionId": "tier5.postForm.submit" } } } }
     }
   }
@@ -91,12 +92,16 @@ interface FormState {
   status: "idle" | "saving" | "saved" | "error";
   error: string;                            // "" unless failed → collapseWhenEmpty
   savedMessage: string;                     // "" unless saved  → collapseWhenEmpty
+  cannotSave: boolean;                      // true after a permission failure → disabledPath
 }
 
 const svc = defineService<FormState, {
   submit: (s: FormState, values?: Record<string, unknown>) => Promise<FormState>;
 }>("postForm", {
-  state: { title: "", body: "", status: "idle", error: "", savedMessage: "" },
+  state: { title: "", body: "", status: "idle", error: "", savedMessage: "", cannotSave: false },
+  // Outcome keys are per-attempt: a cold boot must not restore a stale error, or a submit
+  // disabled by a 403 the user has since been granted past.
+  notHydrated: ["status", "error", "savedMessage", "cannotSave"],
   actions: {
     submit: async (s, values) => {
       const title = String(values?.title ?? "").trim();
@@ -106,17 +111,38 @@ const svc = defineService<FormState, {
         await createDraftPost({ title, richContent: /* … */ } as WixDraftPostWrite);
         return { ...s, title, body, status: "saved", error: "", savedMessage: "Draft created." };
       } catch (e) {
-        return { ...s, status: "error", error: String((e as Error)?.message ?? e), savedMessage: "" };
+        // Keep what the user typed (echo it back into the prefill), and say what
+        // happened in their words — never e.message.
+        const kind = classifyError(e);           // from himi docs recipe-four-state
+        return { ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "",
+                 cannotSave: kind === "permission" };  // bound to the submit's disabledPath
       }
     },
   },
 });
 export { svc };
+
+// One sentence per class of `classifyError` (himi docs recipe-four-state).
+const SAVE_FAILED: Record<string, string> = {
+  offline: "You're offline, so nothing was saved. Try again when you reconnect.",
+  server: "Couldn't save your changes. Try again.",
+  signIn: "Your session has ended. Sign in, then save again.",
+  permission: "You don't have permission to save this.",
+};
 ```
 
-- **Validate in the worker**, not the descriptor: required/format checks run in
-  `submit`, and a failure is just `status: "error"` + a message — same rendering
-  path as a network failure.
+- **Field rules stay on the fields.** Required and format checks belong in the
+  `validation` block above: the renderer holds the submit and shows each message
+  beside its field. The worker's `if (!title)` is only a guard; a cross-field or
+  server answer about ONE field goes to that field through `text.errorPath`.
+- **A failed save is an action error.** It shows near the submit button (the
+  `err` line below), in user-facing words picked by class, and it **keeps what the
+  user typed** — the catch returns `title`/`body` into the prefill so nothing is
+  lost. The submit button is the retry: there is no separate **Try again**.
+  A **sign-in** failure says to sign in and save again (the submit works once the
+  user is signed in). A **permission** failure says so and sets `cannotSave`,
+  which the submit button binds through `disabledPath`, so it offers no retry
+  that would fail the same way.
 - The write goes through a `@himalaya/wix-<domain>` client (declare `wix_api`!).
   **Wrap the entity envelope the API expects** (`{ draftPost: {...} }` handled by
   the SDK; raw `wixApi.call` writes must wrap it themselves) — an unwrapped body
@@ -125,7 +151,9 @@ export { svc };
 
 ## 3. Feedback: outcome strings + a gated follow-up action
 
-Above (or below) the form, the standard state row — each renders only in its state:
+Directly below the `Form` — its submit button is the form's last element — the
+standard outcome row, each line rendering only in its state, next to the action it
+reports on. Bind the submit's `disabledPath` to `cannotSave`:
 
 ```jsonc
 { "id": "err",   "…Text": { "text": "$service:postForm.error", "color": "danger",
@@ -163,12 +191,16 @@ shape (heading swap, `savedScreenId`, back-navigation).
   "$service:<svc>.busy"` — `disabledPath` wants a bool, not the `status` string.
   It only ever ADDS a reason to be disabled: a bound `false` never re-enables a
   submit the form's own validation is holding.
+- **An edit form loads data first.** Its `load` is a read like any other: a
+  `Skeleton` shaped like the fields while it runs, and a classified error state
+  with **Try again** if it fails (`himi docs recipe-four-state`). A create form
+  with nothing to prefill renders at once and needs no loading state.
 - **`himi render` shows the initial (empty) form** — prefill bindings resolve to
   initial state; a real submit needs the pushed preview or a device drive.
 
 ## See also
 
-- `himi docs recipe-four-state` — the state-machine idiom this recipe leans on.
+- `himi docs recipe-four-state` — the loading, classified error and retry idiom this recipe leans on.
 - `himi docs recipe-dynamic-list` — the list the created entity lands in.
 - `himi components Form` / `FormField` / `TextField` / `Toggle` / `Picker`.
 - `.agents/skills/himalaya/examples/form-submit.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.