@wix/himalaya-cli 0.1465.0 → 0.1467.0

package/dist/cli.mjs

@@ -139246,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;
   }
@@ -153202,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 } : {} };
     }
@@ -185850,7 +185850,8 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "from-base44-cli",
   "no-browser",
   "refresh-wix",
-  "empty-app-ok"
+  "empty-app-ok",
+  "aab"
 ]);
 var SHELL_ENUM = SHELL_NAMES2.join("|");
 var SWITCH_FLAGS = new Set([...BOOLEAN_FLAGS].filter((name) => name !== "deep"));
@@ -186355,7 +186356,7 @@ var USAGE2 = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                              minBinaryVersion \u2014 all named in the output.
   himi dist [--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>]
             [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo]
-            [--android-signing qa-keystore|wix-keystore|debug]
+            [--android-signing qa-keystore|wix-keystore|debug] [--aab]
             [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan]
                                            build an INSTALLABLE QA binary (signed IPA / APK) on
                                            the Wix Job Service Mac pool and hand back an install
@@ -186390,6 +186391,13 @@ var USAGE2 = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            wix-keystore (the pool's own Wix key, when the machine
                                            carries one \u2014 fails loudly if not), or debug (the old
                                            per-machine key; QA must uninstall first).
+                                           --aab builds an Android App Bundle (.aab) instead of
+                                           an APK, to upload to Google Play yourself: you get a
+                                           download link and its sha256, and no install link or
+                                           QR (a bundle does not install on a device). Android
+                                           only. Signed with the Wix production key (wix-keystore,
+                                           the upload key Branded apps use); any other
+                                           --android-signing is refused. The default stays an APK.
                                            --borrow-ios-id is an
                                            iOS-only interim: sign under an internal enterprise id the
                                            pool already has a profile for (e.g. ent.wix.time.dev); the
@@ -186836,7 +186844,7 @@ var COMMANDS2 = [
   { name: "patch", summary: 'change ONE item of a published app \u2014 a screen descriptor, a Tier-5 bundle, tokens, or the app-config baseline \u2014 from a RAW FILE, with no content package and no build. The low-level door: it does not lint your package, because there is no package here; `himi push --only <selector>` is the same edit with the full build + lint gate and is what to reach for when the package is in hand. Derives a new release from the app\'s current LIVE release, or from `--from-release <id>`. An explicit `--draft` or `--live` is REQUIRED \u2014 a patch has no default blast radius \u2014 and `--notes` is required with `--live` on a screen or app-config patch, because off-repo `gitSha` is "dev" and the ledger notes are then the only durable record of bytes that correspond to no commit. A branch does not merge: activating one derived from an older release reverts every item the patch does not move, so that case is refused until `--accept-regressions`. A bundle patch must repoint a screen (`--for-screen`) or the bytes land under a manifest key nothing reads. It cannot ADD a screen (screens are git-only, RFC 0012), never claims a slug \u2014 the app must already be published \u2014 and carries no attestation, source archive, assets, icon or minBinaryVersion, each named in the output.', required: "screen <id> --file <descriptor.json> [--bundle <sha256|none>] | bundle --file <bundle.js> (--for-screen <id>[,<id>] | --no-rebind) | tokens --file <tokens.json> | app-config --file <app-config.json> ; (--draft|--live) --app <a> [--from-release <id>] [--accept-regressions] [--label <n>] [--notes <t>] [--force] [--allow-binary-gap] [--target <t>] (--control-token)" },
   { name: "flags", summary: "read and change the app's OPERATIONAL flags (RFC 0013) \u2014 `list` prints what the DEVICE door serves, `set <key> --definition` creates or replaces one, `ramp <key>` moves its rollout share or kills it, `rm <key>` deletes it and echoes the definition back so the removal is reversible. Every write is followed by a read of the same door the device uses, and the answer is reported as `servedNow`: flags are stored in the app's git-committed flags.json, so a control plane with no checkout accepts a write it will never serve.", required: "list|set|ramp|rm [<key>] [--definition <json|@file>] [--percent 0-100] [--enabled true|false] [--app <a>] (--control-token)" },
   { name: "visibility", summary: "read (no value) or set whether the public registry (/v1/apps + the Himi Player picker) LISTS the app. `public` lists it for everyone; `unlisted` hides it from listings while direct reads by app id \u2014 deep links, previews \u2014 keep working. App from --app or the content dir. Setting it needs no republish.", required: "[public|unlisted] [--app <a>] [--content <dir>] (--control-token)" },
-  { name: "dist", summary: "build an INSTALLABLE QA binary (signed IPA / APK) on the Wix Job Service Mac pool and return an install link \u2014 the serve plane brokers the job, the pool builds it. WAITS for the build by default (~4 min) and prints the install link; `--no-wait` returns a jobId immediately instead. Omitting `--release` builds whatever is LIVE for the app. A named draft is refused unless `--allow-draft` makes that exceptional build explicit. `status <jobId>` / `watch <jobId>` / `list --app <a>` / `cancel <jobId>` inspect and stop builds (`watch` reports up front whether the job mints its own signing identity or borrows one, so a doomed iOS build is cancellable in seconds rather than after the archive). Off-repo, name a target \u2014 `--target wix` for a self-serve Wix login or `--target bo` for the internal employee path (the in-repo default is a local dev plane that isn't reachable off-repo); self-serve callers may build their OWN apps under a tighter budget (2 in flight / 5 per 24h), while a manage-only owner-role credential is refused. `--shell` picks the native host to sign into (branded-lite | owner-lite | brandy | base44 | player | demo-app) and defaults to the content package's himalaya.content.json `shell` (templates carry the one they were written for), else branded-lite. The per-app shells ADD the release's declared capabilities to the binary, while Himi Player and demo-app refuse a release declaring one they lack; `--plan` previews it without building; `brandy` is the site shell \u2014 the customer's own website as native-framed tabs. `--signing` defaults to `wix-managed` \u2014 the Wix Apple account mints a per-app signing identity for the build, so the caller provisions no Apple credentials of their own; `--signing byo --site <id>` reuses an existing customer ad-hoc profile and certificate for iOS; requires an owned site and a completed personal signing binding. `--android-signing` is the Android counterpart and a SEPARATE axis (a keystore, not an Apple account): `qa-keystore` (default \u2014 the repo's committed QA key, identical on every pool machine, so a build installs over the previous one), `wix-keystore` (the Wix key the pool machine carries; the build FAILS naming the paths searched if it carries none, rather than quietly signing with something else), or `debug` (the old per-machine key \u2014 QA must uninstall any previous build first). NOT the normal way to ship: screens, Tier-5 bundles, tokens and app-config all go over the air with `himi push` in seconds \u2014 a binary trip is only needed for a NATIVE delta (a new SDUI component, a new declared capability/entitlement, a new bundle id, or a minBinaryVersion floor bump). Refuses to build an app whose launcher icon is missing, a placeholder, or one a store would reject \u2014 the one thing a binary carries that no later OTA push can fix; `--force` builds anyway", required: "[--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>] [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo] [--site <id>] [--android-signing qa-keystore|wix-keystore|debug] [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan] | status <jobId> [--target <t>] | watch <jobId> [--target <t>] [--interval <ms>] | list --app <a> [--target <t>] | cancel <jobId> [--target <t>]" },
+  { name: "dist", summary: "build an INSTALLABLE QA binary (signed IPA / APK) on the Wix Job Service Mac pool and return an install link \u2014 the serve plane brokers the job, the pool builds it. WAITS for the build by default (~4 min) and prints the install link; `--no-wait` returns a jobId immediately instead. Omitting `--release` builds whatever is LIVE for the app. A named draft is refused unless `--allow-draft` makes that exceptional build explicit. `status <jobId>` / `watch <jobId>` / `list --app <a>` / `cancel <jobId>` inspect and stop builds (`watch` reports up front whether the job mints its own signing identity or borrows one, so a doomed iOS build is cancellable in seconds rather than after the archive). Off-repo, name a target \u2014 `--target wix` for a self-serve Wix login or `--target bo` for the internal employee path (the in-repo default is a local dev plane that isn't reachable off-repo); self-serve callers may build their OWN apps under a tighter budget (2 in flight / 5 per 24h), while a manage-only owner-role credential is refused. `--shell` picks the native host to sign into (branded-lite | owner-lite | brandy | base44 | player | demo-app) and defaults to the content package's himalaya.content.json `shell` (templates carry the one they were written for), else branded-lite. The per-app shells ADD the release's declared capabilities to the binary, while Himi Player and demo-app refuse a release declaring one they lack; `--plan` previews it without building; `brandy` is the site shell \u2014 the customer's own website as native-framed tabs. `--signing` defaults to `wix-managed` \u2014 the Wix Apple account mints a per-app signing identity for the build, so the caller provisions no Apple credentials of their own; `--signing byo --site <id>` reuses an existing customer ad-hoc profile and certificate for iOS; requires an owned site and a completed personal signing binding. `--android-signing` is the Android counterpart and a SEPARATE axis (a keystore, not an Apple account): `qa-keystore` (default \u2014 the repo's committed QA key, identical on every pool machine, so a build installs over the previous one), `wix-keystore` (the Wix key the pool machine carries; the build FAILS naming the paths searched if it carries none, rather than quietly signing with something else), or `debug` (the old per-machine key \u2014 QA must uninstall any previous build first). `--aab` builds an Android App Bundle (.aab) for the owner to upload to Google Play instead of an APK \u2014 a download link and sha256, no install link (a bundle does not install on a device); Android only, signed with the Wix production key (`wix-keystore`, the upload key Branded apps use) \u2014 any other `--android-signing` is refused, and it is limited to internal callers (a self-serve caller gets 403 android_format_not_allowed). NOT the normal way to ship: screens, Tier-5 bundles, tokens and app-config all go over the air with `himi push` in seconds \u2014 a binary trip is only needed for a NATIVE delta (a new SDUI component, a new declared capability/entitlement, a new bundle id, or a minBinaryVersion floor bump). Refuses to build an app whose launcher icon is missing, a placeholder, or one a store would reject \u2014 the one thing a binary carries that no later OTA push can fix; `--force` builds anyway", required: "[--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>] [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo] [--site <id>] [--android-signing qa-keystore|wix-keystore|debug] [--aab] [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan] | status <jobId> [--target <t>] | watch <jobId> [--target <t>] [--interval <ms>] | list --app <a> [--target <t>] | cancel <jobId> [--target <t>]" },
   { name: "testflight", summary: 'build, sign and upload an app to TestFlight (internal testers \u2014 no Beta App Review), then WAIT until App Store Connect finishes processing it. Sugar for `store upload --track testflight`. Prompts first: a build number is consumed permanently on a real Apple account and cannot be reused \u2014 `--yes` for CI, `--dry-run` to see the plan without touching anything. The wait is the real check, not a nicety: fastlane prints "Successfully uploaded" for a binary App Store Connect then rejects in processing, and a rejected binary leaves NO build record at all (the reason is emailed). Public App Store review is deliberately NOT automatable here \u2014 `--track appstore` is refused; use /submit-ios-app when you mean to go public', required: "<app> [--track testflight|internal] [--profile <name>] [--yes] [--dry-run] [--skip-build] [--no-wait] [--json]" },
   { name: "store", summary: "the App Store Connect group behind `testflight`. `preflight <app>` checks readiness offline (icon, entitlements, encryption flag, version, store.config ids, listing + review record); `upload <app>` is what `testflight` runs; `status <app>` reads live build + processing state. `--profile` selects WHICH App Store Connect account: an app built for a Wix customer ships under the CUSTOMER's Apple team (Apple guideline 4.2.6 forbids an app-generation service submitting on a client's behalf), declared per-app as ios.credentialProfile in store.config.yaml and resolved from ~/.himalaya/store-credentials/<name>.json \u2014 the .p8 itself never enters the repo. `iap draft|plan|apply|status|connect|screenshots` registers an app owner's digital products as in-app purchases (non-consumables, or consumable price tiers): draft reads the Wix catalog and writes the manifest, plan and status only read, apply is the one App Store mutation boundary, connect readies the Wix site to sell them (purchases app, In-App Purchase key, appleIAP provider, product mappings; --preview-tag routes only its Serve calls to a deploy preview), screenshots renders each product's purchase screen from the app (--content) as a bound iPhone shows it to a signed-in member and names the 1290\xD72796 PNG as the item's App Review screenshot, and none of them builds, signs or needs a checkout (`himi docs iap-products`)", required: "preflight <app> [--profile <n>] | upload <app> [--track <t>] [--profile <n>] [--yes] [--dry-run] | status <app> [--profile <n>] | iap draft --site <msid> --profile <n> --apple-app <id> --bundle <id> --base-territory <t> --out <f> [--territories <a,b>] [--locale <l>] [--mode per-item|tiers] [--merge <f>] [--report <f>] [--json] | iap plan --manifest <f> --profile <n> --out <f> [--json] | iap apply --plan <f> --profile <n> --out <f> [--yes] [--limit <n>] [--json] | iap status --manifest <f> --profile <n> [--out <f>] [--json] | iap connect --manifest <f> --profile <n> [--iap-key <AuthKey.p8> --iap-key-id <id>] [--content <dir>] [--preview-tag dp-<tag>] [--dry-run] [--yes] [--out <f>] [--json] | iap screenshots --manifest <f> --content <dir> [--profile <n>] [--out-dir <d>] [--only <id,\u2026>] [--force] [--dry-run] [--json]" },
   { name: "guide", summary: "print the Himalaya overview + headless dev loop + available topics (offline)", required: "[--json]" },
@@ -193474,6 +193482,11 @@ ${label3}`);
           };
           render("  Himi Player", player);
           if (job.status !== "SUCCESS") return;
+          if (job.platform === "android" && job.androidFormat === "aab") {
+            io2.log("  android bundle");
+            io2.log("  QR omitted (an .aab is uploaded to Google Play; it does not install on a device)");
+            return;
+          }
           const shortUrl = `${origin.replace(/\/+$/, "")}/v1/dist/${encodeURIComponent(jobId)}/install`;
           const artifact = links[String(job.platform)];
           const installUrl = typeof artifact?.url === "string" ? artifact.url : void 0;
@@ -193753,7 +193766,10 @@ ${label3}`);
             // keystore on Android" — the normal combination — with one command.
             // flags["android-signing"], NOT flags.androidSigning: parseFlags does no kebab→camel
             // conversion, so the camel form reads undefined and the flag is a silent no-op.
-            ...str10(flags["android-signing"]) ? { androidSigning: str10(flags["android-signing"]) } : {}
+            ...str10(flags["android-signing"]) ? { androidSigning: str10(flags["android-signing"]) } : {},
+            // A Play bundle instead of an APK. The plane validates it (Android only, link destination,
+            // a stable key) so every caller of the route gets the same refusal.
+            ...flags.aab === true ? { androidFormat: "aab" } : {}
           }, { wixAuthorization });
         } catch (e2) {
           return distUnreachable(e2);
@@ -193830,10 +193846,11 @@ ${label3}`);
             done.push(rec);
             if (!flags.json) {
               const artifact = rec.artifact;
+              const isAab = rec.platform === "android" && rec.androidFormat === "aab";
               const installUrl = rec.platform === "ios" ? artifact?.installPageUrl : artifact?.downloadUrl ?? artifact?.installLink;
               const handoff = rec.customerAppStore;
               const handoffText = typeof handoff?.status === "string" ? `  testflight ${handoff.status}${handoff.error ? ` (${handoff.error})` : ""}` : "";
-              io2.log(`  ${rec.platform}  ${rec.status}${handoffText}${installUrl ? `  install \u2192 ${installUrl}` : ""}`);
+              io2.log(`  ${rec.platform}  ${rec.status}${handoffText}${installUrl ? isAab ? `  .aab for Google Play (not installable) \u2192 ${installUrl}` : `  install \u2192 ${installUrl}` : ""}`);
               if (artifact?.caveat) io2.log(`  \u26A0 ${artifact.caveat}`);
             }
           }

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": {