@wix/himalaya-cli 0.1464.0 → 0.1466.0

package/dist/cli.mjs

@@ -8127,6 +8127,7 @@ function resolveTranslation(value, catalog3, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`
@@ -139245,7 +139246,7 @@ function stillLoading(state) {
 function hasOwnError(state) {
   if (!state || typeof state !== "object") return false;
   for (const [k2, v2] of Object.entries(state)) {
-    if (/^not/i.test(k2)) continue;
+    if (/^not/i.test(k2) || /^(?:no|hide)[A-Z]/.test(k2)) continue;
     if (/error|failed|failure/i.test(k2) && v2 !== null && v2 !== void 0 && v2 !== false && v2 !== "") return true;
     if (/^(status|phase|state)$/i.test(k2) && typeof v2 === "string" && /error|fail/i.test(v2)) return true;
   }
@@ -153201,7 +153202,7 @@ function screenStateOf(services, html, opts = {}) {
     }
     if (status === "loading" || s2.isLoading === true || s2.noLoading === false) loading = true;
     const emptyText = str3(s2.emptyText) ?? str3(s2.emptySourceText);
-    if (!empty2 && (status === "empty" || s2.isEmpty === true || s2.noEmptySource === false || emptyText && page !== void 0 && painted(emptyText, page))) {
+    if (!empty2 && (status === "empty" || s2.isEmpty === true || s2.noEmptySource === false || s2.notEmpty === false || emptyText && page !== void 0 && painted(emptyText, page))) {
       const line = emptyText && painted(emptyText, page) ? quotableLine(emptyText) : void 0;
       empty2 = { state: "empty", ...line ? { line } : {} };
     }

package/guides/designing-himi-screens.md

@@ -257,7 +257,7 @@ scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar
 > in the *outer* column, between the pager and the bottom CTA). Its built-in indicator is faint; pair an
 > explicit `PageControl` if the dots need to read.
 
-**Feedback & overlays** — `Banner` for a persistent inline message (with a retry action on error);
+**Feedback & overlays** — `Banner` for a persistent inline message (with a retry action when a refresh fails over content you kept; a screen with nothing to show uses an error `EmptyState`, see §5);
 `Snackbar` for a transient confirmation; `AlertDialog` for a blocking decision; `BottomSheet` for
 contextual actions/detail; `Tooltip`/`Popover` for a small anchored hint. *Reach for `Snackbar`, not
 `AlertDialog`, to confirm a completed action — don't block on success.* The `Snackbar` COMPONENT draws
@@ -345,7 +345,7 @@ to drive them:
 |---|---|---|
 | **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Required on every screen that loads data asynchronously, and re-checked on every redesign. Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. See [Loading states](#loading-states-part-of-the-design) below. |
 | **Empty** | `EmptyState` (`title`, optional `icon` / `subtitle`) **plus a directive action** (`action` + `actionLabel`) | An empty screen is an invitation to act, not a dead end. Give it the next step, for example `"actionLabel": "Add your first item"`. Use `EmptyState` for **every** empty state, so all empty states in the app have the same layout and style. See [Empty states](#empty-states-one-component-one-layout) below. |
-| **Error** | `Banner` (or inline) **with a retry action** | Say what failed and offer recovery; never a blank screen or a raw error string. |
+| **Error** | Classified first. Nothing on screen: an `EmptyState` per class (`title` + `subtitle`, **no icon**, an action only for a real recovery). Rows on screen: keep them, add a `Banner` with retry. Field and action errors stay local. | Say what happened in the user's words and offer recovery only when there is one; never a blank screen or a raw error string. See [Error states](#error-states-classify-then-present) below. |
 | **Loaded** | the real content | The one everyone remembers to build. |
 
 Bind visibility to worker state with `hidden_path` (`$service:…`/`$item.` data-bound collapse in
@@ -416,6 +416,60 @@ To show the empty state only when the list is empty, bind `hiddenPath` to a work
 (see `himi docs recipe-four-state`). Write the title and the subtitle as literal copy or as
 `$t:` keys. Today, iOS and Android do not resolve a `$service:` binding in `title` or `subtitle`.
 
+### Error states: classify, then present
+
+An error state says what happened, in the user's words, and offers a way out only when there
+is one. Classify the failure first: each class has its own place on the screen, its own copy and
+its own recovery.
+
+| Class | When | Where it shows | Example copy | Recovery |
+|---|---|---|---|---|
+| **Offline** | No answer reached the device (no connection, no route, the request timed out). | The screen or section that failed to load. | "Reconnect to the internet" / "Connect to the internet, then try again." | **Try again**, which re-runs the load. |
+| **Server failure** | The service answered with a failure. | The screen or section. | "Unable to load orders" / "There was a technical issue on our end. Please wait and try again later." | **Try again**, when a retry can help. |
+| **Permission or sign-in** | The user is signed out, or signed in without access (HTTP 401 / 403). | The screen or section. | "Sign in to view orders" / "You need permission to view this screen" | The next step the app offers — **Sign in**, or a contact action. No retry: the same request fails again. |
+| **Empty results** | The request succeeded and returned nothing. | **Not an error** — the empty state (above). | "No orders yet" | The empty state's directive action. |
+| **Field validation** | A value the user typed is not valid. | Beside the field, in its own error slot (see **Inputs & forms** in §3). | "Enter a valid email." | The user corrects the field. No retry. |
+| **Action failure** | A write or a command failed (save, delete, book). | Near the action or the affected content — a line by the button, or a `danger` snackbar (`ui.snackbar({ message, tone: "danger" })`). | "Couldn't save your changes. Try again." | Keep what the user entered; the action itself is the retry. |
+
+- **A screen- or section-level error is an `EmptyState` with no icon.** Set `title` and
+  `subtitle`; leave `icon` out. Add `action` + `actionLabel` only when the user has a useful
+  recovery — retry, reload, sign in. Every error then has the same layout and style, as every
+  empty state does. Do not build one by hand from `Icon`, `Text` and `Button` nodes.
+- **One node per class.** iOS and Android do not resolve a `$service:` binding in `EmptyState`
+  `title` or `subtitle`, so the worker cannot swap the text. Give each class the screen can hit its
+  own `EmptyState` with literal copy or `$t:` keys, and gate each one with `hiddenPath` bound to a
+  worker flag. The worker classifies the failure once and sets the flags — see
+  `himi docs recipe-four-state` for the whole pattern.
+- **User-facing language, never the raw error.** Say what happened and what the user can do. Never
+  show `e.message`, a status code, a stack trace or an API error string — keep those for your logs.
+- **Recovery only when it makes sense.** Offer **Try again** for an offline or a server failure,
+  and for a failed write. Do not offer it for a permission error, an empty result or a field error:
+  the same request gives the same answer.
+- **Empty is not an error.** A successful call with zero rows shows the empty state.
+- **A failed refresh keeps the content.** When data is already on screen and a refresh fails,
+  keep the rows and show a `Banner` (`severity: "warning"`, with a **Try again** `action` and its
+  `actionLabel`) above them. A failed "load more" keeps the rows too, but its error and **Try
+  again** go in a row at the end of the list that retries the same cursor
+  (`himi docs recipe-dynamic-list`) — the user is at the bottom, and the Banner's retry reloads
+  page 1. Replace the content with an error state only when there is nothing to show, or when a
+  sign-in or permission failure means the rows are no longer the user's to see.
+- **The error replaces the loader.** When a load fails, hide the loading state and show the error —
+  never both at once.
+
+```jsonc
+{ "id": "orders.error.offline",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Reconnect to the internet",
+               "subtitle": "Connect to the internet, then try again.",
+               "action": { "actionId": "tier5.orders.retry" },
+               "actionLabel": "Try again" } },
+  "modifiers": { "hiddenPath": "$service:orders.hideOfflineError" } }
+```
+
+**When an `ErrorState` component ships.** A dedicated `ErrorState` component is planned. When it
+is available, use it in place of the icon-less `EmptyState`. Only the component changes: the
+classes, where each one shows, the copy rules and the recovery rules above stay the same.
+
 **Loading & empty states are first-class — use the `Skeleton` and `EmptyState` component types.**
 
 There is **no builder-DSL package** — the `@wix/himalaya` umbrella exposes `./core`, `./state`,
@@ -488,7 +542,8 @@ screen for free.
 Run this punch list on the screen (it's also a good reviewer checklist):
 
 - [ ] **One** primary action, on the one `accentPrimary` surface?
-- [ ] All four states designed — loading / empty / error / loaded (empty & error have an action)?
+- [ ] All four states designed — loading / empty / error / loaded (empty has a directive action; error has a recovery action when one exists)?
+- [ ] Errors classified (offline / server / permission or sign-in), each an icon-less `EmptyState` with user-facing copy — no raw error text? Empty results shown as empty, not as an error? A failed refresh keeps the content?
 - [ ] Loading state matches the loaded layout (a content-shaped `Skeleton` where the layout is known)? For a redesign, was the existing loading state reviewed against the new layout? A static screen has none?
 - [ ] Every value a token — zero literal hex / off-scale spacing / invented type sizes?
 - [ ] Is every user-facing string routed through a copy key with a sensible fallback (`copyOf(key, fallback)` backed by your own `COPY` map; worker strings via `onAppear` params) — none baked directly into the descriptor?

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

@@ -21,54 +21,100 @@
             "id": "loading",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "Skeleton",
               "props": {
-                "text": "$service:products.loadingText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "height": 64,
+                "cornerRadius": 12,
+                "count": 5
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:products.hideLoading"
             }
           },
           {
             "id": "empty",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
+              "props": {
+                "icon": "bag",
+                "title": "No products in this store yet",
+                "subtitle": "Products you add to the store show up here."
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:products.notEmpty"
+            }
+          },
+          {
+            "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": {
-                "text": "$service:products.emptyText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "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",
+            "id": "error.permission",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
               "props": {
-                "text": "$service:products.error",
-                "style": "body",
-                "color": "warning",
-                "collapseWhenEmpty": true
+                "title": "You need permission to view this screen",
+                "subtitle": "Ask the owner of this store for access."
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:products.hidePermissionError"
             }
           },
           {
-            "id": "retry",
+            "id": "error.refresh",
             "body": {
               "package": "himalaya",
-              "type": "Button",
+              "type": "Banner",
               "props": {
-                "title": "Retry",
-                "style": "secondary",
-                "size": "sm",
-                "action": { "actionId": "tier5.products.retry" }
+                "severity": "warning",
+                "title": "Couldn't refresh",
+                "message": "Showing what was loaded before.",
+                "action": {
+                  "actionId": "tier5.products.retry"
+                },
+                "actionLabel": "Try again"
               }
             },
-            "modifiers": { "hiddenPath": "$service:products.notErrored" }
+            "modifiers": {
+              "hiddenPath": "$service:products.hideRefreshError"
+            }
           },
           {
             "id": "products_list",

package/guides/dynamic-list.service.ts

@@ -4,8 +4,10 @@
 //
 // The pattern: the worker OWNS the array. It fetches on boot (`svc.load()` at the
 // bottom), normalizes raw REST rows into FLAT `$item`-friendly fields, and computes
-// a display string per screen state (loading / empty / error) so the descriptor can
-// render four states with plain `collapseWhenEmpty` Texts — no conditional layout.
+// one `hiddenPath` flag per screen state (loading / empty / each error class /
+// refresh failure) so the descriptor renders every state from one flat layout.
+// Errors are CLASSIFIED (`himi docs recipe-four-state`): the user sees the copy of
+// the class, never the raw wire message.
 //
 // Because this worker rides the Wix transport (globalThis.himalaya.wixApi), the
 // descriptor's logicBundle.declaredCapabilities MUST include "wix_api" (RFC 0043 D4).
@@ -22,13 +24,21 @@ interface ProductRow {
   initial: string; // derived presentation field (avatar letter)
 }
 
+// A public catalog has no sign-in flow, so a 401 reads as "permission" here — every
+// class this worker can return has a node in the descriptor.
+type ErrorKind = "" | "offline" | "server" | "permission";
+
 interface ProductsState {
   status: "loading" | "ready" | "error";
   items: ProductRow[]; // ← itemsPath binds here; MUST initialize as an array
-  loadingText: string; // "Loading…" while loading, "" after → collapseWhenEmpty
-  emptyText: string;   // set when ready + no rows, "" otherwise
-  error: string;       // message when failed, "" otherwise
-  notErrored: boolean; // for hiddenPath on the Retry button
+  errorKind: ErrorKind; // why the last load failed; "" unless status is "error"
+  // hiddenPath hides a node when its flag is TRUE.
+  hideLoading: boolean;         // skeleton: first load, nothing on screen
+  notEmpty: boolean;            // EmptyState: ready with zero rows
+  hideOfflineError: boolean;    // one EmptyState per error class …
+  hideServerError: boolean;
+  hidePermissionError: boolean;
+  hideRefreshError: boolean;    // … and a Banner when a refresh fails over kept rows
   selectedId: string;  // row identity from onTap params — drive a detail view from it
 }
 
@@ -52,24 +62,59 @@ function normalize(raw: StoreProduct): ProductRow {
 function shape(s: Partial<ProductsState>): ProductsState {
   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…" : "",
-    emptyText: status === "ready" && items.length === 0 ? "No products in this store yet." : "",
-    error: s.error ?? "",
-    notErrored: status !== "error",
+    errorKind,
+    hideLoading: !(status === "loading" && blank),
+    notEmpty: !(status === "ready" && blank),
+    hideOfflineError: !(blank && errorKind === "offline"),
+    hideServerError: !(blank && errorKind === "server"),
+    hidePermissionError: !(blank && errorKind === "permission"),
+    hideRefreshError: !(!blank && (errorKind === "offline" || errorKind === "server")),
     selectedId: s.selectedId ?? "",
   };
 }
 
-async function loadList(): Promise<ProductsState> {
+// 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`, except that a public screen with no sign-in flow shows the permission state for a sign-in failure.
+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 "permission";
+  if (status === 403) return "permission";
+  if (SIGNED_OUT.test(msg)) return "permission";
+  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
+}
+
+async function loadList(s: Partial<ProductsState>): Promise<ProductsState> {
   try {
     const res = await queryStoreProducts(50);
     const items = (res.products ?? []).filter((p) => p?.id).map(normalize);
-    return shape({ status: "ready", items });
+    return shape({ status: "ready", items, selectedId: s.selectedId });
   } catch (e) {
-    return shape({ status: "error", items: [], error: String((e as Error)?.message ?? e) });
+    const errorKind = classifyError(e);
+    // Keep the rows on a refresh failure; clear them when access is gone.
+    const items = errorKind === "permission" ? [] : s.items ?? [];
+    return shape({ ...s, status: "error", items, errorKind });
   }
 }
 
@@ -80,8 +125,8 @@ const svc = defineService<ProductsState, {
 }>("products", {
   state: shape({ status: "loading" }),
   actions: {
-    load: async () => loadList(),
-    retry: async () => loadList(),
+    load: async (s) => loadList(s),
+    retry: async (s) => loadList(s),
     // Row tap — receives the template's params ({ id: "$item.id" }, substituted per row).
     // Stash the identity; wire real navigation per the tier-5 guide (detail screens).
     open: (s, arg) => ({ ...s, selectedId: String((arg as { id?: string })?.id ?? "") }),

package/guides/form-submit-t5.descriptor.json

@@ -25,32 +25,6 @@
               "props": { "text": "New post", "style": "title1" }
             }
           },
-          {
-            "id": "error",
-            "body": {
-              "package": "himalaya",
-              "type": "Text",
-              "props": {
-                "text": "$service:postForm.error",
-                "style": "footnote",
-                "color": "danger",
-                "collapseWhenEmpty": true
-              }
-            }
-          },
-          {
-            "id": "saved",
-            "body": {
-              "package": "himalaya",
-              "type": "Text",
-              "props": {
-                "text": "$service:postForm.savedMessage",
-                "style": "footnote",
-                "color": "accentPrimary",
-                "collapseWhenEmpty": true
-              }
-            }
-          },
           {
             "id": "post_form",
             "body": {
@@ -104,13 +78,40 @@
                       "title": "Create post",
                       "style": "primary",
                       "fullWidth": true,
-                      "action": { "actionId": "tier5.postForm.submit" }
+                      "action": { "actionId": "tier5.postForm.submit" },
+                      "disabledPath": "$service:postForm.cannotSave"
                     }
                   }
                 }
               }
             }
           },
+          {
+            "id": "error",
+            "body": {
+              "package": "himalaya",
+              "type": "Text",
+              "props": {
+                "text": "$service:postForm.error",
+                "style": "footnote",
+                "color": "danger",
+                "collapseWhenEmpty": true
+              }
+            }
+          },
+          {
+            "id": "saved",
+            "body": {
+              "package": "himalaya",
+              "type": "Text",
+              "props": {
+                "text": "$service:postForm.savedMessage",
+                "style": "footnote",
+                "color": "accentPrimary",
+                "collapseWhenEmpty": true
+              }
+            }
+          },
           {
             "id": "open_saved",
             "body": {

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.)",