@wix/himalaya-cli 0.995.0 → 0.997.0

package/guides/cms-collections.md

@@ -316,7 +316,8 @@ every **foreign** collection — one this app neither owns nor declares:
       { "id": "QaRecipes", "displayName": "Recipes", "readRole": "ANYONE", "itemCount": null,
         "fields": [ { "key": "title", "type": "TEXT" }, { "key": "cookMinutes", "type": "NUMBER" } ] }
     ],
-    "truncated": 6
+    "truncated": 6,
+    "others": [ { "id": "Orders", "displayName": "Orders" } ]
   }
 }
 ```
@@ -333,16 +334,23 @@ before declaring it, rather than guessing; the scan will not invent one for you.
 - **Foreign collections are never item-counted** (`itemCount: null`). A row count is one
   query each, and fanning that across a whole site is the cost this scan must not pay.
   Declare or adopt the collection and the count arrives with the next `himi cms query`.
-- **Only the first 25 are described.** `foreign.count` is how many the scan listed and
-  `foreign.truncated` says how many of those went undescribed, so a short list is never
-  mistaken for a short site. For the full per-collection picture — field types,
-  read/write roles and sample rows — use
-  [`himi site analyze --site <msid>`](wix-business-context.md).
-- **`foreign.count` is not a site census.** `GET /data/v2/collections` is paged and this
-  scan reads one page. When Wix reports a total larger than that page,
-  `unlistedCollections` says how many the listing left out; when Wix reports no total,
-  neither field can tell you, so treat `foreign.count` as "foreign collections in what we
-  listed" and use `site analyze` if you need certainty about a very large site.
+- **Only the first 25 are described; every one is named.** `foreign.count` is how many the
+  scan listed and `foreign.truncated` says how many of those went undescribed — and
+  `foreign.others` still lists each of them as `{ id, displayName }`, so "does this site
+  already have an orders collection?" is answerable from this one call. To see one of them
+  in full, declare it (`wixId`) and run `himi cms query` again, or use
+  [`himi site analyze --site <msid>`](wix-business-context.md) for the per-collection
+  picture — field types, read/write roles and sample rows.
+- **The listing is followed page by page.** `GET /data/v2/collections` is offset-paged, and
+  the scan reads until Wix's `pagingMetadata.total` is reached — or, when Wix flags
+  `tooManyToCount` and sends no total, until a page comes back empty. If the walk stops
+  before that — Wix stopped honoring the offset, or the page backstop was hit — the report
+  carries `listingIncomplete: true`, and `foreign` covers only what was listed.
+  `unlistedCollections` adds how many were left out when Wix gave a total; with
+  `tooManyToCount` nobody knows, so only the flag is set. A declared collection the partial
+  listing did not reach is read by its id, so it is never reported as `missing` just
+  because the scan stopped short. When Wix reports no total and does not flag
+  `tooManyToCount`, one page is taken as the whole listing.
 
 **The scan is owner-scoped, and there is no tokenless alternative.** It needs
 `--site <msid>` (or `WIX_SITE_ID`) and owner auth via `wix token`, because enumerating

package/guides/component-reference.json

@@ -128,7 +128,7 @@
       "bindings": [
         "title"
       ],
-      "propsSource": "export interface ButtonProps {\n  /** Button label — binding-aware (\"$item.\"/\"$service:\") on web, iOS and Android. */\n  title: string;\n  action: Action;\n  style?: string;\n  disabled?: boolean;\n  /** Capability enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  loading?: boolean;\n  size?: \"sm\" | \"md\" | \"lg\";\n  fullWidth?: boolean;\n  iconOnly?: boolean;\n  /** #1049 — corner radius; reshapes the button (overrides the forced pill). */\n  cornerRadius?: number;\n  /** #1049 — minimum height (pt/dp/px). */\n  minHeight?: number;\n}"
+      "propsSource": "export interface ButtonProps {\n  /** Button label — binding-aware (\"$item.\"/\"$service:\") on web, iOS and Android. */\n  title: string;\n  action: Action;\n  style?: string;\n  /** Literal only, NOT bindable: a `\"$service:…\"` string here fails `validate`, and there is no\n   *  `disabledPath`. To disable from worker state, author two buttons — the live one and a\n   *  `disabled: true` copy — and swap them with complementary `modifiers.hiddenPath` flags\n   *  (e.g. `canSubmit` / `cannotSubmit`); also guard the action so a stray tap is a no-op. */\n  disabled?: boolean;\n  /** Capability enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  loading?: boolean;\n  size?: \"sm\" | \"md\" | \"lg\";\n  fullWidth?: boolean;\n  iconOnly?: boolean;\n  /** #1049 — corner radius; reshapes the button (overrides the forced pill). */\n  cornerRadius?: number;\n  /** #1049 — minimum height (pt/dp/px). */\n  minHeight?: number;\n}"
     },
     {
       "name": "TextField",
@@ -475,7 +475,7 @@
           ]
         }
       ],
-      "propsSource": "export interface FilterChipsProps {\n  chips: FilterChip[];\n  /** Literal ids, or a binding-aware `$service:`/`$item.` live selection. */\n  selectedIds?: string[];\n  multiSelect?: boolean;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `chips`). */\n  optionsPath?: string;\n}"
+      "propsSource": "export interface FilterChipsProps {\n  chips: FilterChip[];\n  /** Literal ids, or binding-aware: put the `$service:` sentinel INSIDE the array as its ONE\n   *  element — `selectedIds: [\"$service:<svc>.<field>\"]`, where the field holds the selected\n   *  ids. A bare `\"$service:…\"` string is rejected by `validate` — the prop is an array. */\n  selectedIds?: string[];\n  multiSelect?: boolean;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `chips`). */\n  optionsPath?: string;\n}"
     },
     {
       "name": "Tabs",
@@ -1258,6 +1258,7 @@
     "Presentation": "export type Presentation =\n  | \"push\"\n  | \"sheet\"\n  | \"replace\"\n  | \"dismiss\"\n  | \"back\"\n  | \"full_screen\"\n  | \"alert\"\n  | \"snackbar\";",
     "FilterChip": "export interface FilterChip {\n  id: string;\n  label: string;\n  leadingIcon?: IconRef;\n  count?: number;\n}",
     "TabItem": "export interface TabItem {\n  id: string;\n  label: string;\n  badge?: string;\n}",
+    "PickerOption": "export interface PickerOption {\n  id: string;\n  label: string;\n}",
     "GaugeRing": "export interface GaugeRing {\n  /** Fraction 0..1 for this ring. */\n  value?: number;\n  /** `$service:`/`$item.` binding → a live number (overrides `value`). */\n  valuePath?: string;\n  tint?: TokenName;\n}",
     "WidgetTimeRef": "export interface WidgetTimeRef {\n  /** Epoch seconds the style counts from/to. */\n  at: number;\n  /** SwiftUI `Text.DateStyle` / Android time style (default \"timer\"). */\n  style?: \"timer\" | \"relative\" | \"date\" | \"time\" | \"offset\";\n}",
     "Border": "export interface Border {\n  width: number;\n  color: TokenRef;\n}"

package/guides/component-reference.md

@@ -481,6 +481,10 @@ export interface ButtonProps {
   title: string;
   action: Action;
   style?: string;
+  /** Literal only, NOT bindable: a `"$service:…"` string here fails `validate`, and there is no
+   *  `disabledPath`. To disable from worker state, author two buttons — the live one and a
+   *  `disabled: true` copy — and swap them with complementary `modifiers.hiddenPath` flags
+   *  (e.g. `canSubmit` / `cannotSubmit`); also guard the action so a stray tap is a no-op. */
   disabled?: boolean;
   /** Capability enrichments. */
   leadingIcon?: IconRef;
@@ -904,7 +908,9 @@ export interface SearchFieldProps {
 ```ts
 export interface FilterChipsProps {
   chips: FilterChip[];
-  /** Literal ids, or a binding-aware `$service:`/`$item.` live selection. */
+  /** Literal ids, or binding-aware: put the `$service:` sentinel INSIDE the array as its ONE
+   *  element — `selectedIds: ["$service:<svc>.<field>"]`, where the field holds the selected
+   *  ids. A bare `"$service:…"` string is rejected by `validate` — the prop is an array. */
   selectedIds?: string[];
   multiSelect?: boolean;
   onChange?: Action;
@@ -2141,7 +2147,8 @@ export interface LogicBundleRef {
 
 A few props take a typed **object** rather than nested components. Some are arrays of them:
 `FilterChips.chips` is a `FilterChip[]`, `SegmentedControl.options` / `Tabs.tabs` are a
-`TabItem[]`, and `Gauge.rings` is a `GaugeRing[]` (concentric rings, drawn outer→inner).
+`TabItem[]`, `Picker.options` / `WheelPicker.options` are a `PickerOption[]`, and
+`Gauge.rings` is a `GaugeRing[]` (concentric rings, drawn outer→inner).
 One is a single object: `Text.timeRef` is a `WidgetTimeRef`, the widget-safe live clock —
 note its `at` is REQUIRED and is in epoch SECONDS. The prop blocks above name these types;
 here are the interfaces themselves (for the arrays, each item's own fields — `id` is what an
@@ -2161,6 +2168,11 @@ export interface TabItem {
   badge?: string;
 }
 
+export interface PickerOption {
+  id: string;
+  label: string;
+}
+
 export interface GaugeRing {
   /** Fraction 0..1 for this ring. */
   value?: number;
@@ -2444,3 +2456,30 @@ export type Presentation =
   | "alert"
   | "snackbar";
 ```
+
+### What each `presentation` does
+
+The verb decides what happens to the navigation stack. Where there is a target screen it is
+`params.screenId`, and an action that carries a `screenId` but no verb is a `push`.
+
+| `presentation` | Effect |
+|---|---|
+| `push` | Open `screenId` on top of the current screen; Back returns to where you were. The default. |
+| `replace` | Open `screenId` without keeping the current screen to go Back to. The hosts differ on what Back does next: on iOS and Android the ACTIVE stack is reset to its root before `screenId` is pushed (the open sheet's or cover's own stack when one is up, otherwise the current tab's or the app's single stack), so Back returns to that root and, inside a modal, a further Back closes the modal; on web only the top screen of the current tab is swapped, so Back returns to the screen that was beneath it. |
+| `back` | Pop the current screen (nothing happens at a stack root). On iOS and Android, inside a sheet or cover it pops the modal's own stack first and closes the modal at its root; on web it pops the tab's stack, so close a modal with `dismiss`. |
+| `dismiss` | Close the presented sheet or full-screen cover (on web, an open alert too). Nothing happens when no modal is up. |
+| `sheet` | Present `screenId` as a sheet over the current screen. One at a time: presenting another replaces it. |
+| `full_screen` | Present `screenId` as a full-screen cover. |
+| `alert` | Show an alert built from `args`: `title` (required), `message`, `confirmLabel`, `cancelLabel`, `destructive`, and `confirmActionId` / `cancelActionId` — the action each button runs, with this action's `params`. No `screenId`. |
+| `snackbar` | Show a transient message from `args`: `message` (required) and `tone`. No `screenId`. |
+
+A Close or Done button is a descriptor action: `{ "actionId": "himi.open", "presentation": "dismiss" }`
+(or `"back"`). Two limits to know before you design a flow around them:
+
+- **No action switches tabs.** A `himi.open` whose target is another tab's root screen PUSHES
+  that screen onto the current tab's stack; it does not select the other tab. Only the tab bar
+  and other app chrome select a tab.
+- **A worker can only push.** A worker action that returns `_nav` (`navigate()` from
+  `@himalaya/state`, see `himi docs tier-5-add-a-screen`) opens a linkable screen as a
+  `push`. There is no `_nav` form of `back` or `dismiss`: put those verbs on a descriptor
+  action.

package/guides/designing-himi-screens.md

@@ -69,11 +69,15 @@ decision.
 
 **Kit typography.** A design kit (or an app's tokens) may set a per-style `family`. The rules:
 every typography entry must stay **complete** (`size`+`weight`+`line` — native decode is strict, a
-family-only entry blanks the whole token set; CI-gated); a `family` must be **registered in the host
-app** or it silently falls back to the system font; safe cross-platform values today are the system
-default (no family), `Wix Madefor Text`/`Wix Madefor Display` where the host registers them, and
-`Georgia` (an OS font on iOS/macOS/web;
-approximated by the `serif` generic on Android).
+family-only entry blanks the whole token set; CI-gated); a `family` must come from the **font
+catalog** — `himi fonts list` is the whole vocabulary (curated families such as Playfair Display,
+Karla, Oswald or Lora; the `Wix Madefor Text`/`Wix Madefor Display` pair every host carries; and
+`Georgia`, an OS font on iOS/macOS/web approximated by the `serif` generic on Android) — or be
+`$system` (the platform face by name — how an idiom overlay goes native over a brand base).
+Anything else silently falls back to the system font. Naming a catalog family in tokens is all it
+takes: `himi push` publishes its faces with the release and every renderer, web included, loads
+them. Run `himi fonts check` before pushing — it fails on a name outside the catalog, and on a
+family whose faces could not be fetched, which would otherwise ship as its fallback on web.
 
 ### Token discipline — every value is a `TokenRef`, never a literal
 Colors, gradients, shadows, materials, motions are named tokens (`{ token: "accentPrimary" }`), never

package/guides/getting-started.md

@@ -70,9 +70,11 @@ the UX source of truth even if that guide is absent from the installed CLI.
 `himi init my-shop --template branded-lite` (a full consumer reference over a Wix
 site — store/bookings/events/blog/cart/CMS, wired to `@himalaya/wix-*` + a visitor session)
 or `--template owner-lite` (owner CRUD/management: lists, details, forms). That reference is
-**dozens of screens** with a generated `dev/index.ts` — keep it and trim to the approved
-`SPEC.md` (`himi docs trim-a-template`); do not delete `tier5-src/` + `dev/` and start from
-blank. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
+**dozens of screens** in one megabytes-long `dev/index.ts` of raw descriptors. Keep its
+worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to the approved
+`SPEC.md` when most of its screens fit, or **mine** it when few do — keep the
+`tier5-src/_shared/` helpers and Wix worker chains and write your own screens. Do not delete
+`tier5-src/` + `dev/` and start from blank. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published
 to Wix — and `--remote` on `himi init` fetches one from there (the bundled copy is
 the offline fallback). Publish any app of your own as a template with `himi template publish` —
@@ -86,8 +88,8 @@ template's identity, fixtures and boot-time worker calls would all have to be to
 when consent is **synthetic/local-only** and you need something that cannot auto-fetch (see the
 preflight below); or when you are **learning the wiring** and want one screen and one worker with
 nothing else in the file. The recipes below are written for exactly these cases. What blank is
-NOT good for is a real customer app whose shape a published template already has — trimming that
-template (`himi docs trim-a-template`) beats rebuilding it screen by screen.
+NOT good for is a real customer app whose shape a published template already has — trimming or
+mining that template (`himi docs trim-a-template`) beats rebuilding its Wix wiring from scratch.
 
 **A template is a SHOWCASE APP, so look at it before you pick it.** Each one is a real published
 release running on the plane: `GET /v1/templates.md` gives every row a `preview/a/<id>` URL that

package/guides/headless-loop.md

@@ -210,10 +210,20 @@ JSC (iOS) and WebView (Android) worker scopes don't have them — so a bundle th
 die on a real device fails on your laptop. The most common instance:
 
 ```js
+async function loadList() { /* fetch + shape; return the next state */ }  // module level
+
 retry: async (s) => svc.actions.load(s),   // ✗ `.actions` is undefined on device
-retry: async (s) => svc.load(s),           // ✓ actions are DIRECT methods
+retry: async () => loadList(),             // ✓ call the helper, not the handle
 ```
 
+Actions are DIRECT methods on the handle (`svc.load()`), and they take the action's payload
+arguments, never the state. Even so, never call the handle from inside its own action:
+`svc`'s type is inferred from the very object you are writing, so the reference is circular and
+`validate --strict` rejects it (TS7022/TS7023), and passing `s` is
+`Expected 0 arguments, but got 1`. Put the work in a module-level function, return it from both
+`load` and `retry`, and keep `svc.load()` for the one module-eval kick at the bottom of the
+bundle — the shape `himi docs recipe-dynamic-list` ships.
+
 With no fixture the crawl runs **offline** (the Wix transport rejects), which exercises the
 failure UI your screens should have. `--net` takes the ordinary net-mocks shape
 (`{ "rules": [...] }`) — the same file the on-device `fake.net` seam reads.

package/guides/sdk-reference.json

@@ -7262,7 +7262,7 @@
         "name": "WixServiceAvailabilityOptions",
         "kind": "interface",
         "jsdoc": "/** How to bound an availability query. `bookable` is a `query.filter` member — the\n *  request's `query` has only `filter` and `sort`, so there is NO paging member and\n *  a `paging: { limit }` you add is silently dropped rather than honoured. */",
-        "decl": "export interface WixServiceAvailabilityOptions {\n  /** Bookable slots only. Defaults to `true`; pass `false` to get the unbookable\n   *  ones too (a greyed-out calendar), which is what the endpoint returns unfiltered. */\n  bookable?: boolean;\n}"
+        "decl": "export interface WixServiceAvailabilityOptions {\n  /** Bookable slots only. Defaults to `true`; pass `false` to get the unbookable\n   *  ones too (a greyed-out calendar), which is what the endpoint returns unfiltered.\n   *  `false` OMITS the filter key rather than sending `bookable: false` — the latter\n   *  is a filter for unbookable slots ONLY, i.e. an empty calendar on a live site.\n   *  Unfiltered is the large response described below, so keep the window to the\n   *  days on screen. For unbookable slots alone, filter the entries on\n   *  `entry.bookable === false`. */\n  bookable?: boolean;\n}"
       },
       {
         "name": "queryServiceAvailability",
@@ -7296,11 +7296,23 @@
         "jsdoc": "/** Convenience: staff members = resources tagged \"staff\" (filtered client-side). */",
         "decl": "export async function queryStaff(limit = 100): Promise<WixResource[]>;"
       },
+      {
+        "name": "WixSelectedPaymentOption",
+        "kind": "type",
+        "jsdoc": "/** How the customer intends to pay — the Create Booking `SelectedPaymentOption` enum.\n *  `OFFLINE` = pay in person at the venue; `ONLINE` = pay through checkout;\n *  `MEMBERSHIP` = a Wix Pricing Plan; `MEMBERSHIP_OFFLINE` = a pricing plan the\n *  business redeems by hand. It must be one the service offers. */",
+        "decl": "export type WixSelectedPaymentOption = \"OFFLINE\" | \"ONLINE\" | \"MEMBERSHIP\" | \"MEMBERSHIP_OFFLINE\";"
+      },
+      {
+        "name": "WixBookSlotOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface WixBookSlotOptions {\n  /** Sent as `booking.selectedPaymentOption`. Omitted from the request when unset,\n   *  so a call without it sends exactly the body it always did. */\n  selectedPaymentOption?: WixSelectedPaymentOption;\n}"
+      },
       {
         "name": "bookSlot",
         "kind": "function",
-        "jsdoc": "/** Book a specific availability slot — POST /bookings/v2/bookings. Pass the FULL\n *  slot from queryServiceAvailability + the booker's contact. The v1 createBooking\n *  above rejects a bare slot; the v2 route with bookedEntity.slot is the one that\n *  works. Verified live (status CREATED). */",
-        "decl": "export function bookSlot(slot: WixBookingSlotFull, firstName: string, lastName: string, email: string): Promise<WixCreateBookingResponse>;",
+        "jsdoc": "/** Book a specific availability slot — POST /bookings/v2/bookings. Pass the FULL\n *  slot from queryServiceAvailability + the booker's contact. The v1 createBooking\n *  above rejects a bare slot; the v2 route with bookedEntity.slot is the one that\n *  works. Verified live (status CREATED).\n *\n *  A visitor booking a PAID service to pay in person (no on-device payment) is a\n *  three-call chain:\n *\n *    1. `bookSlot(slot, first, last, email, { selectedPaymentOption: \"OFFLINE\" })`\n *       → the booking, status CREATED.\n *    2. `createCheckout([{ quantity: 1, catalogReference: { appId: <Wix Bookings\n *       appDefId 13d21c63-b5ec-5912-8397-c3a5ddb27a97>, catalogItemId: booking.id } }])`\n *       from `@himalaya/wix-ecom` → the checkout id.\n *    3. `createOrder(checkoutId)` from `@himalaya/wix-ecom` → the order, with the\n *       balance left for the venue to collect.\n *\n *  This chain was verified with raw Wix calls, not through these wrappers.\n *  It is not verified whether `createOrder` still returns a `paymentGatewayOrderId`\n *  for an OFFLINE booking, so do not read one as \"charge now\" and send a\n *  pay-in-person customer into the cashier.\n *\n *  Wix documents `selectedPaymentOption` as REQUIRED whenever the booking is paid\n *  through an eCommerce checkout, and it must be an option the service offers.\n *  Leave `options` out and the request is the one this function always sent. */",
+        "decl": "export function bookSlot(\n  slot: WixBookingSlotFull,\n  firstName: string,\n  lastName: string,\n  email: string,\n  options?: WixBookSlotOptions,\n): Promise<WixCreateBookingResponse>;",
         "http": "POST /bookings/v2/bookings"
       },
       {

package/guides/templates.md

@@ -83,10 +83,13 @@ back to the offline copy — so it never hard-fails. Then run the normal loop
 (`himi build` / `validate` / `render` / `push --draft`).
 
 **`branded-lite` is a full reference, not a small starter.** After `himi init --template
-branded-lite`, trim it to the screens in the approved `SPEC.md` rather than deleting
-`tier5-src/` + `dev/` and starting from blank. Which files to delete, and how
-`dev/index.ts`, `tier5-src/`, and `navigation.linkableScreens` relate:
-`himi docs trim-a-template`.
+branded-lite`, trim it or mine it rather than deleting `tier5-src/` + `dev/` and starting from
+blank. **Trim** when most of the approved `SPEC.md` is screens the template already has: delete
+the rest. **Mine** when few of its screens match: keep the `tier5-src/_shared/` helpers and the
+Wix worker chains, and write your own screens in `dev/index.ts` — the file holds every screen
+as a raw descriptor (megabytes for the full templates), so replacing it is often faster than
+editing it. Both paths, and how `dev/index.ts`, `tier5-src/`, and `navigation.linkableScreens`
+relate: `himi docs trim-a-template`.
 
 **Point a `branded-lite` (or vertical overlay) scaffold at your site.** Set
 `WIX_CLIENT_ID` (Headless OAuth client on that site) and `WIX_SITE_URL` before build /

package/guides/testing-himi-apps.md

@@ -137,12 +137,21 @@ worker scope: **no `setTimeout`/`setInterval`**. That makes a whole class of on-
 fail locally — including this one, which every other local check passes:
 
 ```js
+async function loadList() { /* fetch + shape; return the next state */ }  // module level
+
 // ✗ `.actions` does not exist on the handle — undefined on device
 retry: async (s) => svc.actions.load({ ...s, status: "loading" }),
-// ✓ actions are DIRECT methods
-retry: async (s) => svc.load({ ...s, status: "loading" }),
+// ✓ call the module-level helper, not the handle
+retry: async () => loadList(),
 ```
 
+Actions are DIRECT methods on the handle (`svc.load()`), and they take the action's payload
+arguments, never the state. Even so, never call the handle from inside its own action: `svc`'s
+type is inferred from the very object you are writing, so the reference is circular and
+`validate --strict` rejects it (TS7022/TS7023), and passing `s` is `Expected 0 arguments, but got 1`. Put the work in a module-level function, return it
+from both `load` and `retry`, and keep `svc.load()` for the one module-eval kick at the bottom
+of the bundle — the shape `himi docs recipe-dynamic-list` ships.
+
 In-repo, [`tier5-bundle-guardrails.test.ts`](../core/dev-server/tests/tier5-bundle-guardrails.test.ts)
 forbids both statically across every committed bundle; that gate does not ship off-repo, which
 is why the crawl enforces it dynamically. The clock and `Math.random` are pinned too, so two
@@ -394,8 +403,11 @@ Don't hand-write fixtures — capture the real thing once:
 3. Replay it in any tier — as a `fake.net` fixture (tests) or an OTA scenario (live dev).
 
 The transform lives in [`net-freeze.ts`](../core/dev-server/src/net-freeze.ts) (one static rule
-per distinct `method+host+path`, last capture wins). Caveat: the traffic ring truncates large
-bodies — trim/verify a frozen fixture before relying on it as a JSON mock.
+per distinct `method+host+path`, last capture wins). A request whose body names a
+`dataCollectionId` is keyed on that too and frozen with `matcher.bodyContains`, so each Wix Data
+collection's `POST /wix-data/v2/items/query` replays its own rows instead of the last one
+recorded. Caveat: the traffic ring truncates large bodies — trim/verify a frozen fixture before
+relying on it as a JSON mock.
 
 ---
 
@@ -557,6 +569,41 @@ Recorded so the next person does not re-walk them (#2231):
 
 ---
 
+## Web preview: which Wix visitor you are
+
+A web preview that nobody has signed into calls Wix as an **anonymous visitor**, and that
+visitor owns what it writes: a cart, a booking, an order. The browser holds the identity
+itself. It gets its own visitor straight from Wix, so there is **one anonymous Wix visitor per
+browser, per origin, per app `clientId`**. The visitor's refresh token is kept in
+`localStorage` under `himalaya.wixVisitor.<clientId>`; the short-lived access token stays in
+memory and is renewed from it.
+
+The visitor **survives** page reloads, draft pushes and new releases, a renewed preview link
+(`pvt`), and other tabs of the same browser, which share it.
+
+You get a **new** visitor, who cannot see the old one's records, when:
+
+- the site data is cleared, or the preview is opened in a private window or another browser;
+- the same app is opened from a different origin — the `www.wixapis.com` preview link and a
+  mount on another Wix host each keep their own store;
+- renewing the stored visitor fails, so the browser starts a fresh one;
+- the app's `clientId` changes.
+
+One path is **not** stable at all: the call goes through the preview server instead. That
+happens when the browser cannot reach Wix itself (its visitor mint or a request fails, after
+which the rest of that page load stays on the fallback); when the preview's identity check
+fails or takes longer than 4 seconds, which sends calls through the server until 5 seconds
+after that check started; when the server has switched browser-direct calls off; and for a call that carries its
+own headers or an absolute URL. A write made in one of those windows can be missing when you
+read it back as the browser's own visitor.
+That server uses one anonymous visitor per server instance, **shared** by everyone it serves and
+replaced when its token expires. A signed-in member is a separate identity (the member session)
+and is not affected by any of this.
+
+So when a visitor's own record vanishes from a preview, first check whether the browser, the
+origin or the site data changed. A record that has to outlive those belongs to a signed-in
+member, or should be read back by an id the app kept.
+
 ## Web automation: selector contract
 
 Driving the web host (the `/preview` co-host, the Himi Player, or a standalone web build)

package/guides/tier-5-add-a-screen.md

@@ -104,7 +104,7 @@ The first arg after `state` is the action's payload object: the descriptor's `Ac
 | `TextField` / `RichTextField` | `onChange`, `onSubmit` | `{ value }` — the current text (onChange fires per keystroke) |
 | `SearchField` | `onChange`, `onSubmit` | `{ value }` — the query, debounced by `debounceMs` |
 | `Picker` / `SegmentedControl` / `Tabs` / `WheelPicker` | `onChange` | `{ selectedId }` — the id of the newly selected option |
-| `FilterChips` | `onChange` | `{ selectedIds }` — the **array** of ids selected *after* the tap (honors `multiSelect`) |
+| `FilterChips` | `onChange` | `{ selectedIds }` — the **array** of ids selected *after* the tap (honors `multiSelect`). To drive the highlight from state, bind the sentinel **inside** the array: `selectedIds: ["$service:<svc>.<field>"]` |
 | `Toggle` | `onChange` | `{ value }` — the next state, as a boolean |
 | `SelectionControl` | `onChange` | `{ value }` — the next checked state, as a boolean |
 | `Stepper` | `onChange` | `{ value }` — the clamped next value, as an int |
@@ -395,13 +395,23 @@ mis-pointed `refresh` clobbers good data every tick); the module-eval `load()` i
 *once, on entry*. Reach for module-eval `load()` for initial load; use `refresh`
 only for genuinely live data.
 
-> The `modifiers.onAppear` action is a lifecycle hook that fires when a node appears.
-> It fires on **web too**, at parity with iOS/Android — the web host's screen host
-> dispatches it, with test coverage to match, shipped in #722. Reach for it for
-> **re-entry refresh** and navigation-borne params. Do **not** reach for it as your
-> *initial-load* path: module-eval `svc.load()` above is the blessed initial-load
-> primitive on every surface, and since #2282 it is honoured in the contained web
-> frame as well.
+> The `modifiers.onAppear` action fires when the screen **mounts** — on web, iOS and Android.
+> Use it to hand the worker navigation-borne or build-time params. Do **not** reach for it as
+> your *initial-load* path: module-eval `svc.load()` above is the blessed initial-load
+> primitive on every surface, and since #2282 it is honoured in the contained web frame as
+> well.
+>
+> **It is not a "the user came back" hook.** Whether returning to a screen fires it again
+> depends on whether the host kept that screen mounted, and that differs by platform. iOS
+> fires it once per mounted view, and keeps both visited tabs and the screen under a pushed
+> detail mounted, so a tab return or a Back does not re-fire it. Android fires it each time the
+> node enters composition. On web it fires when the screen host mounts the screen.
+>
+> So for state another screen may have changed — a cart, a signed-in flag, a record saved
+> elsewhere — re-read it in the action that loads the screen (`load`) or in an explicit
+> `refresh`, not in `onAppear` (and see
+> [State does not cross screens automatically](#state-does-not-cross-screens-automatically)
+> for how to hand it off).
 
 **Load with the sanctioned transport, not raw `fetch`.** A worker action calls the
 typed Wix clients (`@himalaya/wix-*`) or the raw chokepoint
@@ -558,12 +568,15 @@ accepted limitations: [RFC 0040 § Amendment — the `_poll` directive](../core/
 **1. The list opens the canonical detail screen, passing the id as a param** (only the
 `screenId` is canonical — the id rides alongside it):
 
-```ts
-// in the list worker, per row:
-await dispatch("himi.open", { screenId: "event", id: row.id, presentation: "push" });
-// descriptor onTap form: { actionId: "himi.open", params: { screenId: "event", id: "$item.id" } }
+```jsonc
+// the row's onTap — `$item.id` is substituted per row:
+{ "actionId": "himi.open", "params": { "screenId": "event", "id": "$item.id" } }
 ```
 
+When the decision to navigate is the worker's (after a save, or once a lookup resolves), return
+`navigate(...)` from the action instead — see [Navigate from the worker](#navigate-from-the-worker-navigate-and-_nav)
+below.
+
 **2. Declare the linkable route with `paramKeys` in `config.ts`** (the id key the host
 threads into `himalaya.input`):
 
@@ -575,7 +588,7 @@ linkableScreens: [
 
 **3. The detail worker reads `himalaya.input.id`** and loads in module-eval `load()`
 (the blessed initial-load primitive above), **not** an `onAppear` action — `onAppear`
-does fire on web, but it is the re-entry hook, not the initial-load path (see the
+fires on every platform, but it is a mount hook, not the initial-load path (see the
 callout above):
 
 ```ts
@@ -645,6 +658,47 @@ For a bottom-tab app, list each tab as a `NavTabItem` in the app config's `navig
 block — note the single-screen `himi init` scaffold ships **no** `navigation`, so a
 multi-tab app adds it.
 
+#### Navigate from the worker: `navigate()` and `_nav`
+
+A worker action moves the user by returning its next state with a transient `_nav` field.
+`navigate` from `@himalaya/state` writes it for you:
+
+```ts
+import { defineService, navigate } from "@himalaya/state";
+
+// in an action — after the save lands, open the record it created:
+save: async (s) => {
+  const id = await saveDraft(s.draft);   // your module-level helper; returns the new id
+  return navigate({ ...s, saving: false }, { screenId: "event", args: { id } });
+},
+```
+
+The runtime strips `_nav` before the state is stored, and the host opens `screenId` exactly as
+a tapped `himi.open` would — including the `args` arriving as `himalaya.input` on the target.
+The rules:
+
+- `screenId` must be a **linkable** screen (`navigation.linkableScreens`), or the host
+  ignores the directive.
+- `args` values are **strings only**; anything else is dropped rather than coerced.
+- It always **pushes**. There is no `_nav` form of `back`, `dismiss`, `sheet` or `replace`.
+
+`_nav` is the worker-side navigation all three hosts route. A worker's
+`dispatch("himi.open", …)` is routed by the web host's nav bridge only; on iOS and Android a
+worker `dispatch` reaches the native action registry, which has no `himi.open` handler.
+
+#### Back, dismiss, and tabs
+
+Everything that is not a push is a **descriptor** action with a `presentation` verb — a Close
+or Done button is `{ "actionId": "himi.open", "presentation": "dismiss" }` (or `"back"`). The
+component reference tabulates every verb (`himi components --json`, or the Actions section of
+`himi docs component-reference`): `back` pops the current screen, `dismiss` closes a presented
+sheet or cover.
+
+**No action switches tabs.** A `himi.open` — tapped or from `_nav` — whose target is another
+tab's root screen pushes that screen onto the *current* tab's stack; it does not select the
+other tab. Only the tab bar and other app chrome select a tab, so design a cross-tab jump as a
+push of the detail you want, not as a hop to the other tab's root.
+
 ### Enumerable variants with `FragmentSlot` (RFC 0045)
 
 Use `fragmentSlot()` when a discriminator selects among a finite set of shipped

package/guides/tokens.md

@@ -29,6 +29,9 @@ tokens.json fail to decode on iOS + Android** — and the web renderer is lenien
 the missing field), so the bug passes web review and only breaks on device. CI guards it:
 `himi validate` reports a token set that would not decode on device.
 
+`family` is optional: a font the app can ship (`himi fonts list`), or `"$system"` for each
+platform's own UI face — SF Pro on iOS/macOS, Roboto on Android, the system UI stack on the web.
+
 ## Colors
 
 A color is a hex string, OR a per-scheme object `{ light, dark?, highContrast? }`. In the

package/guides/trim-a-template.md

@@ -1,13 +1,22 @@
 # Trim a template to N screens
 
 `himi init --template branded-lite` (and the vertical overlays) scaffolds a **full
-reference app**, not a 5-screen starter: on the order of **70 `tier5-src/` workers**,
-**~90 screens**, and a **~1 MB AUTO-GENERATED `dev/index.ts`**, plus a matching
-`navigation.linkableScreens` list. That is the right starting point for a Wix-backed
-customer app — keep it, then **delete what the approved `SPEC.md` does not need**. Do
-not wipe `tier5-src/` + `dev/` and re-author from the blank `himi init` shape; that
-throws away the live Wix wiring the template exists to give you. Vertical overlays
-retheme copy/tokens; they do not shrink the screen count.
+reference app**, not a 5-screen starter: on the order of **70 `tier5-src/` workers** and
+**70 screens**, plus a matching `navigation.linkableScreens` list. Every screen is a nested
+raw descriptor in one `dev/index.ts`, and that file is big: about **4.5 MB / 80,000 lines**
+for `branded-lite`, and **0.8–1.8 MB** for the vertical templates (`retail-store` ~0.85 MB,
+`gym-fitness` ~1.8 MB / 32,000 lines). Its header says *"Edit them freely — this file is
+yours now"*, and it is: nothing regenerates it after `himi init`.
+
+Do not wipe `tier5-src/` + `dev/` and re-author from the blank `himi init` shape; that throws
+away the live Wix wiring the template exists to give you. Vertical overlays retheme
+copy/tokens; they do not shrink the screen count. There are two ways to keep that wiring:
+
+- **Trim it** when the approved `SPEC.md` is mostly screens the template already has: keep
+  those, **delete what the plan does not need** ([How to trim](#how-to-trim)).
+- **Mine it** when the app's screens are its own and few template screens match — the
+  realistic case for a multi-megabyte file of nested descriptors. Keep the worker layer,
+  replace the screens ([Or mine it](#or-mine-it-keep-the-wix-plumbing-write-your-own-screens)).
 
 For a small **non-Wix** pattern (chat, feed, habits, tip calculator), skip this guide
 and scaffold a remote starter instead: `himi init my-app --template chat-bot --remote`
@@ -20,7 +29,7 @@ A screen is not one file. After `himi init`, these three must agree:
 | Keep / delete together | What it is |
 |---|---|
 | `tier5-src/<worker-dir>/` | The worker (state + actions). Directory name is the logic-bundle id (`himi-branded-lite-home`, `himi-booking-services`, …). |
-| `dev/index.ts` `SCREENS` map | The descriptor JSON. The AUTO-GENERATED header means **the in-repo app is the generator's source of truth** — after `himi init` this copy is **yours**; edit it. |
+| `dev/index.ts` `SCREENS` map | The descriptors, as raw objects. After `himi init` the file is **yours** ("this file is yours now") — edit it, cut it down, or replace it. |
 | `config.ts` `navigation.linkableScreens` | Deep-link / tab targets. `himalaya://screen/<id>` resolves **only** if the id is listed here. Tab roots also appear under `navigation.tabBar.items`. |
 
 `himi validate --strict` fails if a tab/linkable id has no descriptor, or a descriptor
@@ -52,6 +61,52 @@ Worked example — keep Home + Shop + Account from branded-lite:
   `himi_account`, … and drops `himi_services`, `himi_events`, …
 - `linkableScreens` + `tabBar.items` match that set (Home / Shop / Profile).
 
+## Or mine it: keep the Wix plumbing, write your own screens
+
+When few of the template's screens match the app — say a class schedule with a day strip,
+spots left and a waitlist, none of which the template draws — hand-editing the descriptor file
+is not the fast path. What a template gives you that is hard to write and easy to reuse is the
+**worker layer**. Keep that, and author the screens yourself:
+
+1. **Keep the helpers.** `tier5-src/_shared/` holds the tested Wix plumbing: price and
+   currency formatting (`wix-service-price.ts`, `engine-intl.ts`), text helpers
+   (`himi-text.ts`), and the per-vertical shaping (`himi-bookings.ts`, `himi-store.ts`,
+   `himi-events.ts`, …). Import them from your own workers.
+2. **Keep the write chains you need.** A transaction that spans several Wix calls is the
+   expensive part to rediscover — the booking worker's `createBooking → createCheckout →
+   createOrder` chain in `tier5-src/himi-booking-time/`, or the cart's checkout in
+   `tier5-src/himi-branded-lite-cart/`. Keep that worker and bind your screen to it, or move
+   the chain into your own worker.
+3. **Delete the template screens.** Remove the worker dirs you are not keeping, and replace the
+   `SCREENS` map in `dev/index.ts` with your own screens (and `linkableScreens` /
+   `tabBar.items` to match).
+4. **Write each screen as small local functions** in `dev/index.ts` that return raw descriptor
+   objects. They are plain TypeScript functions in your own file, not a package (there is no
+   builder-DSL package — `himi docs designing-himi-screens`), so they compile to the same raw
+   descriptors `himi init` writes:
+
+   ```ts
+   // dev/index.ts
+   const node = (id: string, type: string, props: Record<string, unknown>) =>
+     ({ id, body: { package: "himalaya", type, props } });
+   const text = (id: string, value: string, style = "body") => node(id, "Text", { text: value, style });
+
+   function classDetail() {
+     return {
+       screenId: "class_detail",
+       // renderer, schemaVersion, cacheControl, logicBundle: exactly as `himi init` writes them
+       payload: node("root", "VStack", { spacing: 12, children: [
+         text("name", "$service:classDetail.name", "title1"),
+         text("spots", "$service:classDetail.spotsLabel", "caption"),
+         node("book", "Button", { title: "Book", style: "primary", action: { actionId: "tier5.classDetail.book" } }),
+       ] }),
+     };
+   }
+   ```
+
+5. **Prove it** the same way as a trim: `himi validate --strict`, `himi render <screen>`, then
+   `himi test`.
+
 ## What not to do
 
 - Do not hand-edit the in-repo `apps/himi-branded-lite/dev/index.ts` to "slim the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.995.0",
+  "version": "0.997.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -65,5 +65,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "5b0f23dafc9d3aeac20f9bc73a248437fbcc9e65b1a8a25e8bb80cac"
+  "falconPackageHash": "1da0e386b23642ce946cc95fbb56bb7988c6100b680fe7dbaf954a99"
 }