@wix/himalaya-cli 0.1474.0 → 0.1476.0

package/guides/component-reference.json

@@ -14,10 +14,6 @@
     "SelectionControl",
     "ActivityIndicator",
     "Menu",
-    "Tooltip",
-    "Popover",
-    "ChipsInput",
-    "OtpInput",
     "Video",
     "PdfView",
     "MediaPlayer",
@@ -805,21 +801,7 @@
       "category": "Overlays & menus",
       "propsType": "TooltipProps",
       "bindings": [],
-      "notImplemented": {
-        "props": [
-          "edge",
-          "trigger",
-          "onDismiss"
-        ],
-        "platforms": [
-          "ios",
-          "android",
-          "web"
-        ],
-        "severity": "category",
-        "note": "Not an overlay — renders always-expanded inline; `edge`, `trigger` and dismissal are inert."
-      },
-      "propsSource": "export interface TooltipProps {\n  anchor?: Component;\n  text?: string;\n  /** Present → rich tooltip. */\n  title?: string;\n  edge?: \"top\" | \"bottom\" | \"leading\" | \"trailing\" | \"auto\";\n  trigger?: \"tap\" | \"long_press\" | \"auto\";\n  onDismiss?: Action;\n}"
+      "propsSource": "export interface TooltipProps {\n  anchor?: Component;\n  text?: string;\n  /** Present → rich tooltip. */\n  title?: string;\n  /** The side of the anchor the bubble floats on; `auto` / absent → `top`. Flips to the opposite\n   *  side when there is no room, as every renderer does. */\n  edge?: \"top\" | \"bottom\" | \"leading\" | \"trailing\" | \"auto\";\n  /** What opens the (otherwise hidden) bubble. `auto` / absent → a long-press on touch, hover and\n   *  keyboard focus on the web. */\n  trigger?: \"tap\" | \"long_press\" | \"auto\";\n  /** Fired once each time an open tooltip closes (outside tap, Escape, timeout). */\n  onDismiss?: Action;\n}"
     },
     {
       "name": "Popover",
@@ -828,16 +810,6 @@
       "bindings": [
         "presentedPath"
       ],
-      "notImplemented": {
-        "props": [
-          "edge"
-        ],
-        "platforms": [
-          "ios"
-        ],
-        "severity": "category",
-        "note": "The bubble is drawn in flow under its anchor; `edge` placement is not implemented."
-      },
       "propsSource": "export interface PopoverProps {\n  anchor?: Component;\n  content?: Component;\n  edge?: \"top\" | \"bottom\" | \"leading\" | \"trailing\" | \"auto\";\n  presented?: boolean;\n  presentedPath?: string;\n  onDismiss?: Action;\n  /** The overlay traps focus and hides the rest of the tree from AT while\n   *  presented (iOS `accessibilityViewIsModal`, Android `isTraversalGroup`, ARIA\n   *  `aria-modal`). TRI-STATE: absent takes the Popover's default — MODAL,\n   *  from the one shared overlay default table — and an explicit `false` opts out. Applies to a\n   *  popover presented through `presented` / `presentedPath`; one with neither is an\n   *  inline callout, and never modal. */\n  modal?: boolean;\n}"
     },
     {
@@ -862,10 +834,7 @@
           "callback": "onAdd",
           "key": "value",
           "encoding": "string",
-          "platforms": [
-            "web"
-          ],
-          "note": "On web, Enter dispatches the trimmed new chip value. Native onAdd remains listed as not implemented in the component reference."
+          "note": "The new token, trimmed and non-empty, committed by Return or a comma (each segment before a comma is one token; the text after the last stays in the field). The field clears; the chips themselves stay the worker's, so a worker that wants the token shown appends it to `valuesPath`."
         },
         {
           "callback": "onRemove",
@@ -884,17 +853,6 @@
           ]
         }
       ],
-      "notImplemented": {
-        "props": [
-          "onAdd"
-        ],
-        "platforms": [
-          "ios",
-          "android"
-        ],
-        "severity": "category",
-        "note": "`onAdd` never dispatches."
-      },
       "propsSource": "export interface ChipsInputProps {\n  values?: string[];\n  /** \"$service:\" binding → string[]. */\n  valuesPath?: string;\n  placeholder?: string;\n  onAdd?: Action;\n  onRemove?: Action;\n  disabled?: boolean;\n}"
     },
     {
@@ -1193,52 +1151,15 @@
           "callback": "onChange",
           "key": "value",
           "encoding": "string",
-          "note": "The assembled code. Only RN dispatches today; web, iOS and Android render the boxes read-only.",
-          "divergences": [
-            {
-              "arms": [
-                "web",
-                "ios",
-                "android"
-              ],
-              "kind": "no-payload",
-              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
-              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
-            }
-          ]
+          "note": "The assembled code, on every edit (whitespace dropped, capped at `length`). Every arm dispatches it; an edit that leaves the code unchanged dispatches nothing."
         },
         {
           "callback": "onComplete",
           "key": "value",
           "encoding": "string",
-          "note": "Fires once the last box is filled, carrying the same assembled code as onChange. Declared separately because it is a second public callback — leaving it out left one outside the contract.",
-          "divergences": [
-            {
-              "arms": [
-                "web",
-                "ios",
-                "android"
-              ],
-              "kind": "no-payload",
-              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
-              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
-            }
-          ]
+          "note": "Fires once, on the edit that fills the last box (the transition into `value.length == length`), carrying the same assembled code as onChange — never again while the code stays full. Declared separately because it is a second public callback — leaving it out left one outside the contract."
         }
       ],
-      "notImplemented": {
-        "props": [
-          "onComplete",
-          "onChange"
-        ],
-        "platforms": [
-          "ios",
-          "android",
-          "web"
-        ],
-        "severity": "category",
-        "note": "Neither `onChange` nor `onComplete` dispatches."
-      },
       "propsSource": "export interface OtpInputProps {\n  length?: number;\n  /** LITERAL code. A `$service:` sentinel here paints the raw token into the\n   *  boxes — bind `valuePath` instead. */\n  value?: string;\n  /** `$service:`/`$item.` binding → the live code (overrides `value`), so a\n   *  worker that clears it after submit empties the boxes. */\n  valuePath?: string;\n  onChange?: Action;\n  onComplete?: Action;\n  secure?: boolean;\n}"
     },
     {

package/guides/component-reference.md

@@ -119,9 +119,9 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 
 These props are accepted by the schema and pass validation, but the named platform's renderer never reads them — they silently do nothing (no warning, no log). Prefer a prop NOT listed here, or drive the behaviour from a worker.
 
-**Scope: 18 of 87 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
+**Scope: 14 of 87 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
 
-- **`category` (7: `Menu`, `Tooltip`, `Popover`, `ChipsInput`, `OtpInput`, `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
+- **`category` (3: `Menu`, `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
 - **`styling` (11: `Text`, `Icon`, `Carousel`, `Pager`, `Snackbar`, `WebView`, `Slider`, `SelectionControl`, `ActivityIndicator`, `Video`, `PdfView`)** — the component itself **works**; only the listed prop is inert. `Slider` on iOS is a working slider whose `debounceMs` does not throttle — not a broken `Slider`. Use the component; just do not depend on that one prop.
 
 | Component | Unread props | Platform | Kind | Note |
@@ -137,10 +137,6 @@ These props are accepted by the schema and pass validation, but the named platfo
 | `ActivityIndicator` | `ring` | ios, android, web | styling | The `ring` style is never selected (determinate vs indeterminate follows `value`). |
 | `Menu` | `itemsPath` | ios | category | `itemsPath` does not bind items. |
 | `Menu` | `style`, `itemsPath` | android, web | category | `style: "action_sheet"` renders as a dropdown. (`style: "context"` is honoured: it opens on a long-press, or right-click on web, with its `preview`.) `itemsPath` does not bind items. |
-| `Tooltip` | `edge`, `trigger`, `onDismiss` | ios, android, web | category | Not an overlay — renders always-expanded inline; `edge`, `trigger` and dismissal are inert. |
-| `Popover` | `edge` | ios | category | The bubble is drawn in flow under its anchor; `edge` placement is not implemented. |
-| `ChipsInput` | `onAdd` | ios, android | category | `onAdd` never dispatches. |
-| `OtpInput` | `onComplete`, `onChange` | ios, android, web | category | Neither `onChange` nor `onComplete` dispatches. |
 | `Video` | `poster` | ios | styling | `poster` is not shown. |
 | `PdfView` | `showPageControls`, `zoomable`, `allowShare` | web | styling | Interactive PDF.js canvas rendering honours the reader’s page, zoom and export controls. Static previews and PDF.js loading/rendering failures use a native browser-viewer fallback. In that fallback, hiding page or zoom controls is only a viewer hint and cannot reliably hide browser chrome; allowShare hides the reader’s export controls but cannot prevent browser save/print. These props are UI controls, not document access restrictions. |
 | `MediaPlayer` | `autoplayVisibilityThreshold`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` | ios | category | `autoplayVisibilityThreshold` is ignored (whenVisible = once on appear). `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render. |
@@ -1409,14 +1405,17 @@ export interface TooltipProps {
   text?: string;
   /** Present → rich tooltip. */
   title?: string;
+  /** The side of the anchor the bubble floats on; `auto` / absent → `top`. Flips to the opposite
+   *  side when there is no room, as every renderer does. */
   edge?: "top" | "bottom" | "leading" | "trailing" | "auto";
+  /** What opens the (otherwise hidden) bubble. `auto` / absent → a long-press on touch, hover and
+   *  keyboard focus on the web. */
   trigger?: "tap" | "long_press" | "auto";
+  /** Fired once each time an open tooltip closes (outside tap, Escape, timeout). */
   onDismiss?: Action;
 }
 ```
 
-> ⚠️ **Not implemented on ios, android, web:** `edge`, `trigger`, `onDismiss` — Not an overlay — renders always-expanded inline; `edge`, `trigger` and dismissal are inert.
-
 #### Popover
 
 ```ts
@@ -1437,8 +1436,6 @@ export interface PopoverProps {
 }
 ```
 
-> ⚠️ **Not implemented on ios:** `edge` — The bubble is drawn in flow under its anchor; `edge` placement is not implemented.
-
 ### Chips & selection
 
 #### Chip
@@ -1477,8 +1474,6 @@ export interface ChipsInputProps {
 }
 ```
 
-> ⚠️ **Not implemented on ios, android:** `onAdd` — `onAdd` never dispatches.
-
 **Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
 
 | callback | key | type |
@@ -1486,7 +1481,7 @@ export interface ChipsInputProps {
 | `onAdd` | `value` | string |
 | `onRemove` | `value` | string |
 
-> `onAdd` — On web, Enter dispatches the trimmed new chip value. Native onAdd remains listed as not implemented in the component reference.
+> `onAdd` — The new token, trimmed and non-empty, committed by Return or a comma (each segment before a comma is one token; the text after the last stays in the field). The field clears; the chips themselves stay the worker's, so a worker that wants the token shown appends it to `valuesPath`.
 
 > `onRemove` — The removed chip's value.
 
@@ -1936,8 +1931,6 @@ export interface OtpInputProps {
 }
 ```
 
-> ⚠️ **Not implemented on ios, android, web:** `onComplete`, `onChange` — Neither `onChange` nor `onComplete` dispatches.
-
 **Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
 
 | callback | key | type |
@@ -1945,13 +1938,9 @@ export interface OtpInputProps {
 | `onChange` | `value` | string |
 | `onComplete` | `value` | string |
 
-> `onChange` — The assembled code. Only RN dispatches today; web, iOS and Android render the boxes read-only.
-
-> ⚠️ **`onChange` on web + ios + android — DIVERGES:** renders the digit boxes without wiring onChange — the control dispatches nothing. Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it.
-
-> `onComplete` — Fires once the last box is filled, carrying the same assembled code as onChange. Declared separately because it is a second public callback — leaving it out left one outside the contract.
+> `onChange` — The assembled code, on every edit (whitespace dropped, capped at `length`). Every arm dispatches it; an edit that leaves the code unchanged dispatches nothing.
 
-> ⚠️ **`onComplete` on web + ios + android — DIVERGES:** renders the digit boxes without wiring onChange — the control dispatches nothing. Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it.
+> `onComplete` — Fires once, on the edit that fills the last box (the transition into `value.length == length`), carrying the same assembled code as onChange — never again while the code stays full. Declared separately because it is a second public callback — leaving it out left one outside the contract.
 
 ### Cross-cutting & media
 

package/guides/designing-himi-screens.md

@@ -426,14 +426,16 @@ its own 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. |
+| **Sign-in** | The session is missing or has ended: an HTTP 401, a session-expired code, a bridge that has no session, or a 403 for a visitor the host knows is signed out. When the host knows the user is signed in, a 401 is a permission refusal instead. | The screen or section. | "Sign in to view orders" / "Your session has ended." | Open the app's configured auth flow. No retry until authentication succeeds. |
+| **Site membership** | The account is not a member of this site (`NotSiteMember`). A `403 WDE0027` is not this class: Wix Data returns it to signed-in members without access too. | The screen or section. | "Join this site to view orders" / "Use this site's join flow, or ask the owner for access." | Open the site's join flow when the app provides one; otherwise show contact guidance. |
+| **Permission** | The user lacks access (HTTP 403, `WDE0027` included), or the endpoint reports a policy refusal. Signing in again does not help. A 403 for a visitor the host knows is signed out is **Sign-in** instead: member-only data refuses visitors with `403 WDE0027`. | The screen or section. | "You need permission to view this screen" | No retry; show the next useful step, such as contacting the owner. |
 | **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
+  recovery — retry, reload, the app's auth flow, or the site's join flow when available. 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
@@ -443,8 +445,9 @@ its own recovery.
 - **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.
+  and for a failed write. Use the app's auth flow for a sign-in failure, and the
+  site's join flow for `NotSiteMember` when the app provides one. Do not offer retry 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
@@ -452,7 +455,7 @@ its own recovery.
   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.
+  sign-in, membership 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.
 
@@ -543,7 +546,7 @@ 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 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?
+- [ ] Errors classified (offline / server / sign-in / site membership / permission), 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/index.json

@@ -25,7 +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`).",
+    "CLASSIFY every error before you show it: offline, server failure, sign-in, site membership and permission 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; the app's auth flow for sign-in; the site's join flow for `NotSiteMember` when available; 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, membership or permission failure CLEARS the rows instead — they are no longer the user's to see. Field errors stay in the field's slot; a failed action shows next to the action. When an `ErrorState` component ships, only the component changes — these rules stay (`himi docs designing-himi-screens` §5, `himi docs recipe-four-state`).",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",
     "Declare every capability a worker uses in TWO places: the calling screen's logicBundle.declaredCapabilities (wix_platform, stream, camera, location, …) — undeclared calls are blocked — AND config.ts `capabilities`, the app-level list a binary is built with. The `capabilities` guide shows each id's import, what the binary needs and which shells serve it; validate flags an unknown id, an undeclared call, and (with `shell` in himalaya.content.json) an id that shell's binary does not serve. A capability with a native footprint (camera, location, push, …) only arrives with a new binary — an over-the-air push cannot add it. EXCEPTION: the Wix REST bridge (wix_api — the @himalaya/wix-* clients / wixApi.call) is ungated today (installed unconditionally), so it works WITHOUT a declaration; declaring wix_api is still recommended — it is where the platform is heading, and it documents what your worker touches.",
     "`validate`/`render` prove a screen is WELL-FORMED and, by default, paint its INITIAL state — NOT that the app's LOGIC is correct. A wrong reducer (a game that never ends, a bad total) passes both with ok:true. Run `himi test`: it needs NO test files — it boots each screen's real worker and dispatches every action your descriptor already declares, then reports anything that threw, stayed stuck on `loading`, or leaked a NaN/undefined/`$service:` token into visible text. It crawls on HERMETIC DATA by default (zero network): your `dev/net-mocks.json` first, then your config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI — so the fetch-SUCCESS mapping path runs too, where data-shape bugs actually live (canned data exercises code paths, not API-contract truth). Two boot-only HOSTILE passes (every list empty; every request 500) then check the empty/outage day — their findings are errors, not warnings. It also runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView), so a bundle that would only die on the device fails locally instead — e.g. `svc.actions.load(…)` (actions are DIRECT methods; `.actions` is undefined on device). (You are NOT limited to the crawled states either: rendering with `--live` runs the worker's REAL fetches against live Wix — a minted anonymous visitor token from the app's clientId — so a render CAN prove real-data binding locally with no VPN/push; and injecting `state` (`{\"<svc>\":{…}}`) renders a specific mid-flow state without the network.)",

package/guides/qa-builds.md

@@ -1029,18 +1029,22 @@ diagnoses.
 ### An Android App Bundle for Google Play — `--aab`
 
 An APK installs on a device. Google Play wants an **Android App Bundle** (`.aab`) for a new app,
-and a bundle installs on nothing. `--aab` builds the bundle instead, for an owner who downloads the
-Wix-built binary and uploads it to Play Console themselves:
+and a bundle installs on nothing. `--aab` builds the bundle **and an APK from the same build**, for
+an owner who uploads the bundle to Play Console themselves and installs the APK on a phone:
 
 ```sh
 himi login --dpx --target bo        # an INTERNAL caller: self-serve callers get 403 (see below)
 himi dist --app <app> --platform android --aab --wait --target bo
 ```
 
-- **What you get:** `artifact.downloadUrl` (presigned, 7 days) and `artifact.sha256`. No
-  `installLink`, no `installPageUrl`, no QR, and `GET /v1/dist/<jobId>/install` answers 404 for it —
-  a link that hands a phone a file it cannot open is worse than none. The record carries
-  `androidFormat: "aab"`.
+- **What you get:** the bundle as `artifact.downloadUrl` (presigned, 7 days) and `artifact.sha256`,
+  as before, so a Google Play caller reads the same fields. The APK as `artifact.apk`
+  (`downloadUrl`, `sha256`, and its `bucket`/`key`). The QR, the links surface and
+  `GET /v1/dist/<jobId>/install` all point at that APK, never at the `.aab` — a link that hands a
+  phone a file it cannot open is worse than none. A bundle job with no `artifact.apk` gets no QR and
+  a 404 from the redirect. The APK is kept only when the pool reports it QA-signed
+  (`apk.androidSigningUsed: "qa-keystore"`) and it sits in the bundle's own S3 bucket; otherwise the
+  bundle still succeeds and the record says `companion_apk_dropped: …`. The record carries `androidFormat: "aab"`.
 - **Android only.** The default stays an APK, and iOS is untouched. It travels as
   `androidFormat: "aab"` on `POST /v1/admin/dist` (every `/v1/owner/dist` caller is self-serve, so
   that route always answers `403 android_format_not_allowed`), and reaches the pool as
@@ -1054,21 +1058,25 @@ himi dist --app <app> --platform android --aab --wait --target bo
   bundle without a real Firebase config and customer identity). A mixed `--platform ios,android`
   applies it to the Android leg only.
 - **How the pool builds it.** `run-dist` runs store-release's `bundleRelease` task
-  (`bundleReleaseArgs` / `bundleReleaseEnv`, the same task the Play lane runs) with **AGP injected
-  signing**, with the **Wix production key** (`wix-keystore`: `~/.signing/oneapp-production.keystore`,
+  (`bundleReleaseArgs` / `bundleReleaseEnv`, the same task the Play lane runs) and, in the **same
+  gradle run**, the module's matching `assemble<Variant>` task (`companionApkTask`: same module, same
+  flavor), with **AGP injected signing**, with the **Wix production key** (`wix-keystore`: `~/.signing/oneapp-production.keystore`,
   alias `WixOne`), resolved by `resolveAndroidSigner` and verified there. The pool refuses any
   other signer for a bundle — a pool-side `DIST_ANDROID_KEYSTORE` included. The keystore path and alias are `-P` flags; the passwords ride in the environment as
   `ORG_GRADLE_PROJECT_android.injected.signing.{store,key}.password`, never in argv. `jarsigner
-  -verify` must say `jar verified.` before anything is uploaded. The seed gate and the binary-size
-  budget run on the `.aab` as they do on an APK. `DIST_ANDROID_BUNDLE_TASK` overrides the task
+  -verify` must say `jar verified.` before anything is uploaded. The APK gets every APK check:
+  it is **re-signed with the committed QA key** (never left with WixOne) and `apksigner`-verified,
+  gets the 16 KB check, and must report `qa-keystore`, or the build fails. Only release outputs are
+  considered, so a stale debug APK in a warm tree is never picked. The seed gate and the binary-size budget run on both
+  files. Compile, resources and R8 are shared, so the APK adds only its packaging and one upload. `DIST_ANDROID_BUNDLE_TASK` overrides the task
   (`DIST_ANDROID_TASK` stays the APK one), and `DIST_ANDROID_FLAVOR` picks among flavored bundles.
   Only the task's own gradle module is searched, so a sibling module's stale bundle is never taken.
-  An **ambiguous** choice fails the build instead of guessing: the bundle's applicationId becomes
-  the app's permanent Play package.
-- **What it skips, and why.** `apksigner` and the re-sign step (a bundle is JAR-signed at build
+  An **ambiguous** choice fails the build instead of guessing, for the bundle and for the APK beside
+  it: the bundle's applicationId becomes the app's permanent Play package.
+- **What the bundle skips, and why.** `apksigner` and the re-sign step (a bundle is JAR-signed at build
   time, and the injected config overrides any `signingConfig`); the 16 KB check (its ZIP half is about an installed APK,
   which Play generates; its ELF half reads the APK `lib/` layout — Play checks alignment on
-  upload); and `--reuse-artifact` (that is an APK).
+  upload); and `--reuse-artifact` (that is an APK). The APK beside it gets the APK checks above.
 - **Version skew.** The pool runs the release's own `run-dist`, and one older than `--aab` ignores
   `DIST_ANDROID_FORMAT` and builds an APK. So the pool reports what it built (`androidFormat` on
   the result callback, the `androidSigningUsed` pattern), and serve-control turns a `SUCCESS` that
@@ -1088,7 +1096,7 @@ himi dist --app <app> --platform android --aab --wait --target bo
   stays for a runner older than that rule. A later delivery that passes every check (a retry on a
   clean machine) clears the verdict.
 
-**Why the Wix production key, and only for a bundle.** There are two Android keys: the committed
+**Why the Wix production key, and only for the bundle.** There are two Android keys: the committed
 QA keystore and the Wix production key (WixOne). WixOne is the Play **upload** key every Branded
 app's bundle carries (`mobile-apps-engine` refuses any other certificate for a Play build), with
 Play App Signing on, so Google re-signs what users install. An `.aab` therefore signs with it —
@@ -1096,7 +1104,10 @@ only its `WixOne` entry of `oneapp-production.keystore`: the alias is pinned for
 alias the pool's signing files name. Because the first upload binds a Play listing to that key for good, a **self-serve** caller
 gets no bundle at all (`403 android_format_not_allowed`): `--aab` is for internal callers until a
 Containers store build checks the app, its owner and its package name. A self-serve **APK** with
-`wix-keystore` keeps `403 android_signing_not_allowed`, unchanged. For the owner, the Play listing is bound to the WixOne upload certificate, so later
+`wix-keystore` keeps `403 android_signing_not_allowed`, unchanged. The APK built beside a bundle is
+QA-signed, so no installable APK carrying the WixOne signature is ever handed out; WixOne would not
+help it anyway, because the APKs Google Play delivers carry Google's app-signing key, so a phone with
+the QA APK uninstalls it before installing the app from Google Play. For the owner, the Play listing is bound to the WixOne upload certificate, so later
 updates come from Wix builds too; leaving Wix needs an upload-key reset through Play Console
 support. A pool machine without the key fails the build, naming the paths it searched, rather than
 signing with another key.
@@ -1193,8 +1204,10 @@ baking the live asset.
   or `DIST_ANDROID_USE_WIX_KEYSTORE=1` names one, and a named key wins — `apksigner` replaces the
   signature block — because the job record is written at dispatch and would otherwise name a key
   that is not on the binary.
-- **Android, `--aab`** → a **presigned `.aab` download URL** and its sha256, and **no install
-  link**: a bundle is uploaded to Google Play, it does not install on a device. See
+- **Android, `--aab`** → a **presigned `.aab` download URL** and its sha256 (`artifact.downloadUrl`;
+  a bundle is uploaded to Google Play, it does not install on a device), plus the QA-signed APK
+  from the same build as `artifact.apk`, which the QR, the links surface and
+  `GET /v1/dist/<jobId>/install` point at. See
   [the App Bundle section](#an-android-app-bundle-for-google-play----aab).
 - **How Android picks up the branding.** `prepare:customer` writes an **xcconfig** for iOS (bundle
   id + display name) but on Android only tokens, the icon drawable and a colour XML. Android's
@@ -1325,6 +1338,22 @@ apksigner verify --verbose qa.apk                   # must say "Verifies"; DOES
 aapt2 dump badging qa.apk | head -2                 # package + application-label = the branding actually baked
 ```
 
+For an **`--aab`** job, `downloadUrl` is the bundle (it installs on nothing) and the phone's file
+is `artifact.apk`, so check both:
+
+```sh
+curl -sS -o play.aab "<artifact.downloadUrl>"
+shasum -a 256 play.aab                              # must equal artifact.sha256
+jarsigner -verify play.aab                          # must say "jar verified." (signed with WixOne)
+curl -sS -o qa.apk "<artifact.apk.downloadUrl>"
+shasum -a 256 qa.apk                                # must equal artifact.apk.sha256
+apksigner verify --print-certs qa.apk               # must verify, with the committed QA key's certificate
+```
+
+The APK is signed with the committed QA key (identical on every pool machine), not a per-machine
+debug key, so it installs over an earlier QA build of the same app. It does not install over the app
+from Google Play, whose APKs carry Google's app-signing key: uninstall one before installing the other.
+
 **5. Install and drive it.**
 
 ```sh

package/guides/recipe-dynamic-list.md

@@ -60,11 +60,11 @@ interface Row {              // FLAT strings/booleans only — see "Normalize" b
 interface State {
   status: "loading" | "ready" | "error";
   items: Row[];
-  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e), never the raw message
+  errorKind: "" | "offline" | "server" | "signIn" | "membership" | "permission";  // classifyError(e, currentAuthState()), never the raw message
   // hide* flags for hiddenPath, derived in shape() — see `himi docs recipe-four-state`
   hideLoading: boolean; notEmpty: boolean;
   hideOfflineError: boolean; hideServerError: boolean;
-  hideSignInError: boolean; hidePermissionError: boolean; hideRefreshError: boolean;
+  hideSignInError: boolean; hideMembershipError: boolean; hidePermissionError: boolean; hideRefreshError: boolean;
   nextCursor: string; failedCursor: string; hideLoadMoreError: boolean;  // §5 load-more
 }
 ```
@@ -157,17 +157,18 @@ A list loads data, so it ships all four states — the full idiom is
   keeps the rows and uses the list's own spinner.
 - **Empty** — an `EmptyState` with a directive action, gated by `notEmpty`.
 - **Error, nothing on screen** — one `EmptyState` per class `classifyError` can
-  return (offline, server, sign-in, permission), **no icon**, user-facing copy.
+  return (offline, server, sign-in, site membership, permission), **no icon**, user-facing copy.
   Offline and server get **Try again** → `tier5.products.retry`; sign-in gets
-  **Sign in**; permission gets no action. A list with no sign-in flow maps
+  **Sign in**; membership opens the site's join flow when available; permission gets no action. A list with no sign-in flow maps
   `"signIn"` to `"permission"` — a visitor still gets a 401 or 403 (Bookings
   `searchServices`, above) and a missing node paints a blank screen. The worker's
-  `catch` sets `errorKind` from `classifyError(e)` — never `String(e.message)`,
+  `catch` sets `errorKind` from `classifyError(e, currentAuthState())` (both from
+  `himi docs recipe-four-state`) — never `String(e.message)`,
   which shows the user a wire error.
 - **Error, rows on screen** — a pull-to-refresh that fails offline or on the
   server keeps the rows (`shape({ ...s, status: "error", errorKind })`, `items`
   untouched) and shows a `Banner` with **Try again** above them, gated by
-  `hideRefreshError`. A sign-in or permission failure clears the rows instead.
+  `hideRefreshError`. A sign-in, membership or permission failure clears the rows instead.
   A failed **load-more** has its own retry (§5).
 
 ```jsonc
@@ -222,10 +223,10 @@ native decoders drop anything else without a word:
   `hideLoadMoreError`), whose action restores `nextCursor = failedCursor` and runs
   `loadMore` again. Do not route it through the refresh `Banner`: that **Try
   again** reloads page 1 and throws away the pages already shown.
-- **Except when page 2 loses access.** A `signIn` or `permission` failure on
+- **Except when page 2 loses access.** A `signIn`, `membership` or `permission` failure on
   `loadMore` is not retryable and the rows already shown are no longer the
-  user's to see: clear them and go to the same sign-in / permission
-  `EmptyState` a refresh uses (`load()` in `himi docs recipe-four-state`). Keep
+  user's to see: clear them and go to the same sign-in, membership or
+  permission `EmptyState` a refresh uses — membership with its join action (`load()` in `himi docs recipe-four-state`). Keep
   page 1 and offer the cursor retry only for `offline` and `server`.
 - APIs that don't page (or v1 fallbacks without cursors) simply never set
   `nextCursor` — the gesture props are safe to leave in place.

package/guides/recipe-form-submit.md

@@ -35,7 +35,6 @@ the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi
       ],
       "submitButton": { "id": "save", "body": { "package": "himalaya", "type": "Button",
         "props": { "title": "Create post", "style": "primary", "fullWidth": true,
-                   "disabledPath": "$service:postForm.cannotSave",
                    "action": { "actionId": "tier5.postForm.submit" } } } }
     }
   }
@@ -92,16 +91,15 @@ interface FormState {
   status: "idle" | "saving" | "saved" | "error";
   error: string;                            // "" unless failed → collapseWhenEmpty
   savedMessage: string;                     // "" unless saved  → collapseWhenEmpty
-  cannotSave: boolean;                      // true after a permission failure → disabledPath
 }
 
 const svc = defineService<FormState, {
   submit: (s: FormState, values?: Record<string, unknown>) => Promise<FormState>;
 }>("postForm", {
-  state: { title: "", body: "", status: "idle", error: "", savedMessage: "", cannotSave: false },
-  // Outcome keys are per-attempt: a cold boot must not restore a stale error, or a submit
-  // disabled by a 403 the user has since been granted past.
-  notHydrated: ["status", "error", "savedMessage", "cannotSave"],
+  state: { title: "", body: "", status: "idle", error: "", savedMessage: "" },
+  // Outcome keys are per-attempt: a cold boot must not restore a stale error or a
+  // "Draft created." line from an earlier run.
+  notHydrated: ["status", "error", "savedMessage"],
   actions: {
     submit: async (s, values) => {
       const title = String(values?.title ?? "").trim();
@@ -113,9 +111,8 @@ const svc = defineService<FormState, {
       } catch (e) {
         // Keep what the user typed (echo it back into the prefill), and say what
         // happened in their words — never e.message.
-        const kind = classifyError(e);           // from himi docs recipe-four-state
-        return { ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "",
-                 cannotSave: kind === "permission" };  // bound to the submit's disabledPath
+        const kind = classifyError(e, currentAuthState()); // from himi docs recipe-four-state
+        return { ...s, title, body, status: "error", error: SAVE_FAILED[kind], savedMessage: "" };
       }
     },
   },
@@ -127,6 +124,7 @@ const SAVE_FAILED: Record<string, string> = {
   offline: "You're offline, so nothing was saved. Try again when you reconnect.",
   server: "Couldn't save your changes. Try again.",
   signIn: "Your session has ended. Sign in, then save again.",
+  membership: "Join this site before saving.",
   permission: "You don't have permission to save this.",
 };
 ```
@@ -140,9 +138,10 @@ const SAVE_FAILED: Record<string, string> = {
   user typed** — the catch returns `title`/`body` into the prefill so nothing is
   lost. The submit button is the retry: there is no separate **Try again**.
   A **sign-in** failure says to sign in and save again (the submit works once the
-  user is signed in). A **permission** failure says so and sets `cannotSave`,
-  which the submit button binds through `disabledPath`, so it offers no retry
-  that would fail the same way.
+  user is signed in). A **membership** failure asks the user to join this site;
+  keep submit available so they can save after joining. A **permission** failure
+  says so and keeps submit available too, so the user can retry after access is
+  granted without restarting the form.
 - The write goes through a `@himalaya/wix-<domain>` client (declare `wix_api`!).
   **Wrap the entity envelope the API expects** (`{ draftPost: {...} }` handled by
   the SDK; raw `wixApi.call` writes must wrap it themselves) — an unwrapped body
@@ -153,7 +152,7 @@ const SAVE_FAILED: Record<string, string> = {
 
 Directly below the `Form` — its submit button is the form's last element — the
 standard outcome row, each line rendering only in its state, next to the action it
-reports on. Bind the submit's `disabledPath` to `cannotSave`:
+reports on:
 
 ```jsonc
 { "id": "err",   "…Text": { "text": "$service:postForm.error", "color": "danger",