@wix/himalaya-cli 0.1465.0 → 0.1466.0

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.

package/guides/recipe-four-state.md

@@ -1,52 +1,117 @@
 # Recipe: four screen states (loading / empty / error / ready)
 
+**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
+write; Sign in when the user is signed out; nothing for a permission failure, an empty result
+or a field error, where the same request gives the same answer. This recipe is the shared
+idiom; the other recipes link here for it. Design guidance for the states:
+`himi docs designing-himi-screens` §5 ("Loading states", "Error states").
+
 Every data-backed screen has four states, and Himi's idiom renders all of them
-from **one flat layout** — no conditional trees, no separate loading screen. The
-worker computes a **display string per state** (non-empty only in its state) and
-the descriptor binds each to a `Text` with `collapseWhenEmpty: true`. Sections
-that must fully appear/disappear gate with the `hiddenWhen`/`hiddenPath` modifier
-bound to a worker boolean. The empty state is always an `EmptyState` node, gated
-the same way.
+from **one flat layout** — no conditional trees, no separate loading screen. Each
+state is its own node, gated with the `hiddenPath` modifier bound to a worker
+boolean, and the worker derives every flag from one `status` field. The empty state
+and each error class are `EmptyState` nodes, gated the same way.
 
 This is the corpus norm: of the in-repo worker bundles, ~3 in 4 model loading,
 more than half model error, and the reference apps (`apps/himi-owner-lite`,
-`apps/demo-app`, and Himi Blog) all ship this exact shape. The
+`apps/demo-app`, and Himi Blog) all ship this shape. The
 `examples/dynamic-list.*` and `examples/form-submit.*` pairs both demonstrate it.
 
-## 1. One status field, derived display strings
+## 1. One status field, a classified error, derived flags
 
 ```ts
+type ErrorKind = "" | "offline" | "server" | "signIn" | "permission";
+
 interface State {
   status: "loading" | "ready" | "error";
   items: Row[];
-  loadingText: string;   // "Loading…"        only while loading
-  error: string;         // the message        only when failed
-  notEmpty: boolean;     // gates the EmptyState (hiddenPath hides when TRUE)
-  notErrored: boolean;   // gates the Retry button (hiddenPath hides when TRUE)
+  errorKind: ErrorKind;      // why the last load failed; "" unless status is "error"
+  // hiddenPath hides a node when its flag is TRUE — name flags in the hide direction.
+  hideLoading: boolean;      // the skeleton: shown only while loading with nothing on screen
+  notEmpty: boolean;         // the EmptyState: shown only when ready with zero rows
+  hideOfflineError: boolean; // one EmptyState per error class …
+  hideServerError: boolean;
+  hideSignInError: boolean;
+  hidePermissionError: boolean;
+  hideRefreshError: boolean; // … and a Banner when a refresh fails over rows we kept
 }
 
 function shape(s: Partial<State>): State {
   const status = s.status ?? "ready";
   const items = s.items ?? [];
+  const errorKind: ErrorKind = status === "error" ? (s.errorKind || "server") : "";
+  const blank = items.length === 0;   // nothing on screen to keep
   return {
-    status, items,
-    loadingText: status === "loading" ? "Loading products…" : "",
-    error: s.error ?? "",
-    notEmpty: !(status === "ready" && items.length === 0),
-    notErrored: status !== "error",
+    status, items, errorKind,
+    hideLoading: !(status === "loading" && blank),
+    notEmpty: !(status === "ready" && blank),
+    hideOfflineError: !(blank && errorKind === "offline"),
+    hideServerError: !(blank && errorKind === "server"),
+    hideSignInError: !(blank && errorKind === "signIn"),
+    hidePermissionError: !(blank && errorKind === "permission"),
+    // Only a failure a retry can fix gets the banner over kept rows.
+    hideRefreshError: !(!blank && (errorKind === "offline" || errorKind === "server")),
   };
 }
+
+// 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/;
+// 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 …`.
+const SIGNED_OUT = /wixApi not enabled|session unavailable|PRINCIPAL_CHANGED|not signed in|siteNotPermitted\(requested: "account"|site account is not the bound site/i;
+
+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";        // signed out (or the session expired)
+  if (status === 403) return "permission";    // signed in, without access
+  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";   // anything else — a bug, a malformed row — is not the user's connection
+}
+
+async function load(s: State): Promise<State> {
+  try {
+    const items = (await fetchRows()).map(normalize);
+    return shape({ status: "ready", items });
+  } catch (e) {
+    const errorKind = classifyError(e);
+    // Keep the rows: a refresh that fails must not blank a screen that had content —
+    // unless access is gone, when the rows must not stay on screen either.
+    const lostAccess = errorKind === "signIn" || errorKind === "permission";
+    return shape({ ...s, items: lostAccess ? [] : s.items, status: "error", errorKind });
+  }
+}
 ```
 
-Route **every** state change through `shape()` — set `status` + raw data, let it
-recompute the strings and flags. Hand-maintaining them per action is how screens
-end up loading-and-errored at once.
+Route **every** state change through `shape()` — set `status`, `errorKind` and the
+raw data, and let it recompute the flags. Hand-maintaining them per action is how
+screens end up loading-and-errored at once.
+
+**Never show the raw error.** `e.message` is for your logs; the user sees the copy
+of the class it falls in. The classifier above is deliberately small: add a class
+only when the screen shows the user something different for it.
 
-## 2. The descriptor: one node per state + a gated Retry
+## 2. The descriptor: one node per state
 
 ```jsonc
-{ "id": "loading", "…Text": { "text": "$service:products.loadingText",
-    "color": "textSecondary", "collapseWhenEmpty": true } },
+{ "id": "loading",
+  "body": { "package": "himalaya", "type": "Skeleton",
+    "props": { "height": 72, "cornerRadius": 12, "count": 4 } },   // shaped like the rows
+  "modifiers": { "hiddenPath": "$service:products.hideLoading" } },
+
 { "id": "empty",
   "body": { "package": "himalaya", "type": "EmptyState",
     "props": { "icon": "bag", "title": "No products in this store yet",
@@ -54,62 +119,121 @@ end up loading-and-errored at once.
                "action": { "actionId": "tier5.products.create" },
                "actionLabel": "Add your first product" } },
   "modifiers": { "hiddenPath": "$service:products.notEmpty" } },
-{ "id": "error",   "…Text": { "text": "$service:products.error",
-    "color": "danger", "collapseWhenEmpty": true } },
-{ "id": "retry",
-  "body": { "package": "himalaya", "type": "Button",
-    "props": { "title": "Retry", "style": "secondary", "size": "sm",
-               "action": { "actionId": "tier5.products.retry" } } },
-  "modifiers": { "hiddenPath": "$service:products.notErrored" } }
+
+// Errors: an EmptyState per class, with NO icon, user-facing copy, and an action
+// only when the user can recover.
+{ "id": "error.offline",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Reconnect to the internet",
+               "subtitle": "Connect to the internet, then try again.",
+               "action": { "actionId": "tier5.products.retry" },
+               "actionLabel": "Try again" } },
+  "modifiers": { "hiddenPath": "$service:products.hideOfflineError" } },
+{ "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" } },
+{ "id": "error.signIn",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Sign in to view products",
+               "subtitle": "Your session has ended.",
+               "action": { "actionId": "tier5.products.signIn" },   // a worker action that dispatches himi.wix.signInDirect
+               "actionLabel": "Sign in" } },
+  "modifiers": { "hiddenPath": "$service:products.hideSignInError" } },
+{ "id": "error.permission",           // no action: retrying gives the same answer
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "You need permission to view this screen",
+               "subtitle": "Ask the owner of this business for access." } },
+  "modifiers": { "hiddenPath": "$service:products.hidePermissionError" } },
+
+// A refresh that failed over rows we kept: say so above the rows, keep the rows.
+{ "id": "error.refresh",
+  "body": { "package": "himalaya", "type": "Banner",
+    "props": { "severity": "warning", "title": "Couldn't refresh",
+               "message": "Showing what was loaded before.",
+               "action": { "actionId": "tier5.products.retry" },
+               "actionLabel": "Try again" } },
+  "modifiers": { "hiddenPath": "$service:products.hideRefreshError" } }
 ```
 
-- `collapseWhenEmpty` on a `Text` renders **nothing at all** (no blank line) when
-  the bound string is `""` — the whole state machine is "which string is non-empty".
 - `hiddenPath` / `hiddenWhen` hide a node when the bound boolean is **true** —
-  name worker booleans in the *hide* direction (`notErrored`, `hideSavedLink`) so
+  name worker booleans in the *hide* direction (`notEmpty`, `hideServerError`) so
   the binding reads without negation.
 - Ready state is simply the data itself (the list rows, the detail fields) — it
   needs no dedicated marker.
-- **Use `EmptyState` for every empty state.** It draws one standard layout on
-  every platform: icon, title, subtitle and button, with type and gaps from the
-  app's tokens. Only `title` is required. `actionLabel` is required when you set
-  `action`: there is no default label, and `himi validate` reports a missing one.
+- **Sign in is a worker action.** A renderer cannot dispatch `himi.wix.*`, so the
+  sign-in `EmptyState` calls `tier5.products.signIn`, which the worker defines:
+  it dispatches `himi.wix.signInDirect` and then reloads
+  (`himi docs wix-login-integration`).
+- **Loading is a `Skeleton` shaped like the loaded content** when you know the
+  layout — the same rows at about the same size. `StatefulSection` or
+  `ActivityIndicator` are fine where they fit better. A plain `"Loading…"` `Text`
+  bound to a worker string (`collapseWhenEmpty: true`) is the minimum, not the goal.
+- **Use `EmptyState` for every empty state and every screen-level error.** It
+  draws one standard layout on every platform with the app's tokens. Only `title`
+  is required. `actionLabel` is required when you set `action`: there is no
+  default label, and `himi validate` reports a missing one. For an error, leave
+  `icon` out.
 - Write the `EmptyState` title and subtitle as literal copy or `$t:` keys. Today,
-  iOS and Android do not resolve a `$service:` binding in those props, so gate the
-  node with `hiddenPath` instead of binding its text.
+  iOS and Android do not resolve a `$service:` binding in those props — which is
+  why each error class is its own node instead of one node with bound text.
+- **A node for every class `classifyError` can return** — otherwise that failure
+  paints a blank screen. A screen with no sign-in flow still gets a 401 when a
+  session ends; map `"signIn"` to `"permission"` in its classifier rather than drop
+  the node.
+- **When a planned `ErrorState` component ships,** swap the error `EmptyState`
+  nodes for it. The classes, the copy and the recovery rules stay as they are.
 
 ## 3. Which state when
 
-| State   | Set where                            | User affordance                    |
-|---------|--------------------------------------|------------------------------------|
-| loading | initial state + start of `load`      | skeleton/spinner text; NO retry    |
-| error   | `catch` in any fetch/write           | message + **Retry** (re-runs load) |
-| empty   | derived: ready + 0 rows              | say what *would* fill it, and how  |
-| ready   | successful fetch                     | the content                        |
+| State | Set where | User affordance |
+|---|---|---|
+| loading | initial state (`status: "loading"`) | content-shaped skeleton; NO retry |
+| error, nothing on screen | `catch` in the first load | the class's `EmptyState`: user-facing copy + a recovery action where one exists |
+| error, rows on screen | `catch` in a refresh (offline or server) | rows stay; a `Banner` with **Try again** above them |
+| sign-in or permission | `catch` in any load | rows go; the class's `EmptyState` (Sign in, or no action) |
+| empty | derived: ready + 0 rows | say what *would* fill it, and how |
+| ready | successful fetch | the content |
 
 - **Transient write feedback** (saved/deleted/published toasts) is the same idiom
   one more time: an `actionMessage`/`savedMessage` string, non-empty only right
-  after the write (see `himi docs recipe-form-submit`).
+  after the write (see `himi docs recipe-form-submit`). A **failed write** keeps
+  what the user entered and shows its error next to the submit button, which is
+  the retry.
 - **Empty ≠ error.** A 200 with zero rows is empty; only a failed call is error.
   Write empty copy that names the next step ("Add your first product") — see
   `himi docs designing-himi-screens` §5 for the design guidance.
-- **Retry re-runs `load()`**, resetting to `loading` first, so a stuck error can't
-  double-render with stale rows.
+- **Retry re-runs `load()`.** An action returns one state, so the error stays up
+  until the new result replaces it — rows, empty, or a fresh error. Do not clear
+  the rows to "show progress"; that is how a second failure blanks the screen.
 
 ## Gotchas
 
 - **Initialize `status: "loading"` and kick `svc.load()` at the bottom of the
   worker file** — a screen that boots `ready`+empty flashes the empty state before
   data arrives.
-- **Never leave a display string `undefined`** — `collapseWhenEmpty` collapses
-  `""`; an undefined binding renders the literal path. `shape()` prevents this.
-- **Keep failed-load rows.** On a *refresh* failure, prefer keeping the old rows +
-  showing the error over blanking to a dead screen (set `error`, keep `items`).
-- **`himi render` shows the initial frame** — expect the loading state, not rows;
-  all four bindings are still structurally checkable there.
+- **Keep failed-load rows.** On a *refresh* failure, keep the old rows and show
+  the `Banner` — never blank to a dead screen (set `status` and `errorKind`, keep
+  `items`). `load-more` is the same: a broken page 2 must not blank page 1 — and
+  its retry is its own (see `himi docs recipe-dynamic-list`), because the refresh
+  banner's **Try again** reloads page 1.
+- **Never leave a bound display string `undefined`** — `collapseWhenEmpty`
+  collapses `""`; an undefined binding renders the literal path. `shape()` prevents
+  this.
+- **`himi render` shows the loaded screen when the app has recorded data**
+  (`dev/net-mocks.json`, CMS seed rows). `himi render <screenId> --no-mocks` shows
+  the initial frame — the loading state — and
+  `--state '{"products":{"status":"error","errorKind":"offline","hideOfflineError":false,…}}'`
+  forces an error class without the network. A `dev/net-mocks.json` rule that
+  answers 401, 403 or 500 previews the sign-in, permission and server classes
+  through the real `classifyError`.
 
 ## See also
 
 - `himi docs recipe-dynamic-list` — the list recipe this state machine wraps.
 - `himi docs recipe-form-submit` — the write-outcome variant (saving/saved/error).
+- `himi docs recipe-search` — the same states around a query.
 - `himi docs designing-himi-screens` §5 — copywriting + design for the states.

package/guides/recipe-onboarding.md

@@ -57,7 +57,8 @@ const svc = defineService<State, {
 
 - **Best-effort by design**: wrap every storage touch in `try/catch`. A missing
   or failing store means the card shows again next launch — a mild repeat,
-  never an error state.
+  never an error state. The card reads a local flag and loads no remote data,
+  so it needs no loading state, no error state and no retry.
 - Namespace the key (`<app>.<what>`) — the store is app-scoped but shared
   across the app's workers.