@wix/himalaya-cli 0.1465.0 → 0.1467.0

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.
 

package/guides/recipe-search.md

@@ -64,9 +64,9 @@ not say why there are no rows.
 | Initial, no query | Search prompt plus useful recent queries, categories, or suggestions. Avoid presenting this as a failed search. |
 | Loading | First load: a skeleton or progress state. Refresh: keep current results visible and show a compact progress indicator when possible. |
 | Results | Matching rows, result count, and the available sort/filter controls. |
-| No matches | Explain that the current query or filters found nothing; offer Clear or a way to adjust them. |
+| No matches | An `EmptyState` explaining that the current query or filters found nothing; offer a way to adjust them, and Clear only where the field is controlled (the native slot) — the inline `SearchField` is uncontrolled, so Clear there empties the query but not the field. |
 | Empty catalog | Explain that the catalog itself has no items yet, independent of the query; provide a useful browse/back action. |
-| Error | Show an error with Retry, retain the query and controls, and keep it distinct from no matches. |
+| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, Sign in for sign-in, no action for permission. Retain the query and controls, and keep it distinct from no matches. |
 
 ### Native slot and old-client fallback
 
@@ -170,7 +170,12 @@ interface PostsState {
   all: PostRow[];        // the full fetched set — NOT bound by the descriptor
   items: PostRow[];      // ← itemsPath binds here; always derived from all + query
   query: string;
-  loadingText: string; emptyText: string; error: string; notErrored: boolean;
+  hideNoPosts: boolean;  // the EmptyState for "loaded, and there is nothing at all"
+  hideNoMatches: boolean; // the EmptyState for "there are posts, none match the query"
+  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e)
+  hideLoading: boolean; hideOfflineError: boolean; hideServerError: boolean;
+  hideSignInError: boolean; hidePermissionError: boolean;
+  hideRefreshError: boolean;                    // hiddenPath flags, as in recipe-four-state
 }
 
 function visible(all: PostRow[], query: string): PostRow[] {
@@ -186,31 +191,103 @@ function queryFrom(arg: unknown): string {
   return String(a?.value ?? a?.text ?? a?.query ?? "");
 }
 
+// Actions are not serialized: the user can type while load() is in flight, and the
+// action that finishes last writes the whole state. So the latest query lives outside
+// the state, and every fetch applies it when it returns.
+let currentQuery = "";
+
+// The SearchField is uncontrolled: it opens empty, so the query must start over too.
+// `load` (opening the screen) resets it; a query typed while that fetch is in flight
+// still wins. `retry` keeps it.
+load: async (s) => { currentQuery = ""; return loadList(s); },
+
+// After defineService: a cold boot restores the persisted `query` AND the `items` and
+// empty flags derived from it. Re-derive them for an empty query before anything paints.
+const booted = (svc as unknown as { getState?: () => Record<string, unknown> | undefined }).getState?.();
+if (booted && typeof booted === "object") {
+  Object.assign(booted, shape({ ...(booted as Partial<PostsState>), query: "", items: undefined }));
+}
+
 // actions:
 search: (s, arg) => {
   const query = queryFrom(arg);
+  currentQuery = query;
   const items = visible(s.all, query);
-  return shape({ ...s, query, items });   // shape() recomputes emptyText from items+query
+  return shape({ ...s, query, items });   // shape() recomputes the empty flags from all+items+query
 },
-clear: (s) => shape({ ...s, query: "", items: s.all }),
+clear: (s) => { currentQuery = ""; return shape({ ...s, query: "", items: s.all }); },
 ```
 
-- `load()` fetches once, fills `all`, and sets `items = visible(all, query)`.
+- `load()` fetches once, fills `all`, and sets `items = visible(all, currentQuery)`.
+  On a `signIn` or `permission` failure it clears **`all` as well as `items`** —
+  `search`, `clear` and `retry` rebuild rows from `all`, so rows left there come
+  back on the next keystroke.
 - The shipped Blog v3 `WixPost` type includes `categoryIds` and both Wix-image and
   embed-thumbnail media projections. Normalize them without a local cast:
   `coverUrl: post.media?.wixMedia?.image?.url ?? post.media?.embedMedia?.thumbnail?.url ?? ""`
   and `categoryIds: post.categoryIds ?? []`.
-- **`emptyText` should distinguish** "no data at all" from "no matches":
-  `query ? `No matches for “${query}”.` : "No posts yet."` — recompute it in
-  `shape()` wherever items change.
+- **Two empty states, both `EmptyState`**: "no data at all" and "no matches" are
+  different screens. Search's `shape()` takes four-state's flags with one change:
+  `blank` is `all.length === 0`, not `items.length === 0` — `items` is the filtered
+  view, so a query with no matches over rows kept after a failed refresh must not
+  read as "nothing loaded" and show the full-screen error. In `shape()`, wherever
+  items change, recompute
+  `hideNoPosts = !(status === "ready" && all.length === 0)` and
+  `hideNoMatches = !(all.length > 0 && items.length === 0)` — no `status` check,
+  because the user can still search the rows kept after a failed refresh. Their
+  copy is static — an `EmptyState` cannot bind its text on native — and the
+  no-matches one has no action: the `SearchField` is uncontrolled, so a "Clear
+  search" button would empty the worker's query while the field still shows it:
+
+```jsonc
+{ "id": "empty.noPosts",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "inbox", "title": "No posts yet",
+               "subtitle": "New posts will show up here." } },
+  "modifiers": { "hiddenPath": "$service:posts.hideNoPosts" } },
+{ "id": "empty.noMatches",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "search", "title": "No posts match your search",
+               "subtitle": "Try a different word." } },
+  "modifiers": { "hiddenPath": "$service:posts.hideNoMatches" } }
+```
+
+## 3. Loading, error and retry
+
+A searchable list loads data, so it carries the four states of
+`himi docs recipe-four-state`:
+
+- **Loading** — a `Skeleton` shaped like the result rows, gated by `hideLoading`,
+  while the first `load()` runs. The search field is usable at once.
+- **Error, nothing loaded** — one `EmptyState` per class `classifyError` can
+  return, **no icon**, user-facing copy; offline and server get **Try again** →
+  `tier5.posts.retry`, sign-in gets **Sign in**, permission gets no action. The
+  `catch` sets `errorKind` from `classifyError(e)`; it never shows `e.message`.
+- **Retry keeps the query.** `retry` re-runs `load()` and then re-applies
+  `currentQuery` — not `s.query`, which is the query from when the retry
+  STARTED — so what the user typed during the fetch is not lost.
+- **No matches is not an error.** A successful search with zero results shows the
+  no-matches `EmptyState` ("No posts match your search"), with no action and no retry.
+
+```ts
+retry: async (s) => {
+  const next = await load(s);                            // classified on failure
+  // Lost access clears the rows; any other failure keeps them for the Banner.
+  const lostAccess = next.errorKind === "signIn" || next.errorKind === "permission";
+  const all = lostAccess ? [] : next.all;
+  return shape({ ...next, all, query: currentQuery, items: visible(all, currentQuery) });
+},
+```
 
-## 3. Server-side search (large datasets)
+## 4. Server-side search (large datasets)
 
 In-worker filtering is right up to a few hundred rows. Past that, make `search`
 re-query the API with the term (most Wix domain query endpoints take a filter,
 e.g. blog `queryPosts` — check `himi sdk wix-<domain>`), keep `status: "loading"`
 during the round-trip, and debounce higher (300–400ms). The descriptor does not
-change — only the action's body.
+change — only the action's body. A failed server-side search **keeps the query and
+the results already on screen** and shows the refresh `Banner` with **Try again**,
+which runs the same query again.
 
 ## Gotchas
 
@@ -231,6 +308,6 @@ change — only the action's body.
 ## See also
 
 - `himi docs recipe-dynamic-list` — the list this recipe filters.
-- `himi docs recipe-four-state` — the emptyText/error/loading strings.
+- `himi docs recipe-four-state` — the loading, classified error and retry idiom.
 - `himi components SearchField` / `FilterChips` / `Tabs`.
 - `.agents/skills/himalaya/examples/search-list.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.

package/guides/recipe-voice-journal.md

@@ -36,6 +36,21 @@ export async function finishVoiceJournal(sessionId: string) {
 }
 ```
 
+**States.** Recording reads no remote data, so the journal screen needs no network
+loading or error states — but it does have states the user must see:
+
+- **Unavailable** (`status: "unavailable"` — no microphone, permission denied, or a
+  host without capture): an icon-less `EmptyState` that says recording is not
+  available and gives the next step the platform offers (for example, how to allow
+  the microphone). No **Try again**: the same call fails the same way until the
+  user changes something.
+- **Processing** (transcription, diarization): a progress or a placeholder line on
+  the entry, never a blocking spinner; a processing failure keeps the audio and
+  shows the entry without a transcript.
+- **Saved entries list**: reading `local-db` is local and quick, so it needs no
+  skeleton; an empty journal is an `EmptyState` with a "Record your first entry"
+  action.
+
 The SDUI layer can use the existing list, text, button, progress, audio/media, and state-binding
 components for recording, transcript detail, search, deferred processing, summaries, categories,
 delete, and export. Generate summaries and structured categories with `@himalaya/on-device-ai`

package/guides/search-list-t5.descriptor.json

@@ -33,54 +33,115 @@
             "id": "loading",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "Skeleton",
               "props": {
-                "text": "$service:posts.loadingText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "height": 56,
+                "cornerRadius": 12,
+                "count": 5
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideLoading"
+            }
+          },
+          {
+            "id": "empty.no_posts",
+            "body": {
+              "package": "himalaya",
+              "type": "EmptyState",
+              "props": {
+                "icon": "doc",
+                "title": "No posts yet",
+                "subtitle": "Posts you publish show up here."
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideNoPosts"
+            }
+          },
+          {
+            "id": "empty.no_matches",
+            "body": {
+              "package": "himalaya",
+              "type": "EmptyState",
+              "props": {
+                "icon": "search",
+                "title": "No posts match your search",
+                "subtitle": "Try a different word."
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideNoMatches"
+            }
+          },
+          {
+            "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.posts.retry"
+                },
+                "actionLabel": "Try again"
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideOfflineError"
             }
           },
           {
-            "id": "empty",
+            "id": "error.server",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
               "props": {
-                "text": "$service:posts.emptyText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "title": "Unable to load posts",
+                "subtitle": "There was a technical issue on our end. Please wait and try again later.",
+                "action": {
+                  "actionId": "tier5.posts.retry"
+                },
+                "actionLabel": "Try again"
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideServerError"
             }
           },
           {
-            "id": "error",
+            "id": "error.permission",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
               "props": {
-                "text": "$service:posts.error",
-                "style": "body",
-                "color": "danger",
-                "collapseWhenEmpty": true
+                "title": "You need permission to view this screen",
+                "subtitle": "Ask the owner of this blog for access."
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hidePermissionError"
             }
           },
           {
-            "id": "retry",
+            "id": "error.refresh",
             "body": {
               "package": "himalaya",
-              "type": "Button",
+              "type": "Banner",
               "props": {
-                "title": "Retry",
-                "style": "secondary",
-                "size": "sm",
-                "action": { "actionId": "tier5.posts.retry" }
+                "severity": "warning",
+                "title": "Couldn't refresh",
+                "message": "Showing what was loaded before.",
+                "action": {
+                  "actionId": "tier5.posts.retry"
+                },
+                "actionLabel": "Try again"
               }
             },
-            "modifiers": { "hiddenPath": "$service:posts.notErrored" }
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideRefreshError"
+            }
           },
           {
             "id": "posts_list",