@wix/himalaya-cli 0.1613.0 → 0.1615.0

package/fixtures/wix-canned.json

@@ -625,6 +625,10 @@
       "total": 2
     }
   },
+  "POST /online-programs/participants/v3/join-applications/query": {
+    "joinApplications": [],
+    "pagingMetadata": { "count": 0, "total": 0 }
+  },
   "GET /pricing-plans/v2/plans/public": {
     "plans": [
       {

package/guides/component-reference.json

@@ -565,7 +565,7 @@
       "category": "Feedback",
       "propsType": "SnackbarProps",
       "bindings": [],
-      "propsSource": "export interface SnackbarProps {\n  message: string;\n  action?: Action;\n  durationMs?: number;\n  severity?: Severity;\n  /** #1059 — action label; overridable for localized hosts. Default \"Take action\". */\n  actionLabel?: string;\n}"
+      "propsSource": "export interface SnackbarProps {\n  message: string;\n  action?: Action;\n  durationMs?: number;\n  severity?: Severity;\n  /** #1059 — action label; overridable for localized hosts. Default \"Take action\". */\n  actionLabel?: string;\n  /** #4661 — a 40 pt/dp thumbnail at the leading edge (`https:` or a local file/asset URL; any\n   *  other is ignored), drawn by the same presenter as a worker's `ui.snackbar({ imageUrl })`. */\n  imageUrl?: string;\n}"
     },
     {
       "name": "AlertDialog",

package/guides/component-reference.md

@@ -1200,6 +1200,9 @@ export interface SnackbarProps {
   severity?: Severity;
   /** #1059 — action label; overridable for localized hosts. Default "Take action". */
   actionLabel?: string;
+  /** #4661 — a 40 pt/dp thumbnail at the leading edge (`https:` or a local file/asset URL; any
+   *  other is ignored), drawn by the same presenter as a worker's `ui.snackbar({ imageUrl })`. */
+  imageUrl?: string;
 }
 ```
 

package/guides/designing-himi-screens.md

@@ -307,7 +307,10 @@ contextual actions/detail; `Tooltip`/`Popover` for a small anchored hint. *Reach
 inline where you place it; for a transient toast that floats at the bottom of the screen — an app
 error after a failed action, say — use the `snackbar` presentation verb or `ui.snackbar({ message,
 tone: "danger" })` from a worker: it floats above the tab bar, animates in and out, queues, honours
-`durationMs`, and is announced to screen readers on every platform.
+`durationMs`, and is announced to screen readers on every platform. It stays a toast: two lines of
+message, one optional 40 pt thumbnail (`imageUrl`), one action of up to 24 characters, 2–10 s on screen.
+For "Item deleted — Undo", a screen worker can `await` it and read `actionTapped` instead of wiring an
+action id; anything richer is a descriptor overlay, not a snackbar.
 
 **Status & data-viz** — `Badge`/`Tag`/`Chip` for compact labels; `Rating` for stars (`size: "sm"` in a
 dense row); `ProgressBar` for determinate progress, `ActivityIndicator` for indeterminate; `Gauge` for

package/guides/hhp.md

@@ -210,13 +210,13 @@ Declare the mockup each screen was designed from in `hhp.json`:
 A screen may also carry `params` (the navigation input a device opens it with, used by native capture, #4935) and `fidelity: { "warn": 80, "fail": 60 }`. Thresholds can also be set app-wide at the top level.
 
 ```bash
-himi fidelity --content <dir> [--screen a,b] [--variant light,dark,rtl,tablet] [--ios <udid>] [--android <serial>] [--ios-tablet <udid>] [--android-tablet <serial>] [--app-id <id>] [--release <id>] [--no-native] [--json] [--post-pr <n>]
+himi fidelity --content <dir> [--screen a,b] [--variant light,dark,rtl,tablet] [--ios <udid>] [--android <serial>] [--ios-tablet <udid>] [--android-tablet <serial>] [--app-id <id>] [--release <id>] [--serve <port>] [--no-native] [--json] [--post-pr <n>]
 ```
 
 For each screen and variant (`light`, `dark`, `rtl`, `tablet`), the command does four things:
 
 1. **Captures the mockup.** It draws the page in Chromium at the variant's width. Dark mode is drawn by emulating `prefers-color-scheme`. RTL is drawn by setting `dir=rtl` on the page.
-2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the Hebrew language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` the Player shows the app's **live** release, not your working copy. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
+2. **Captures the web render** from the app's recorded data, as `himi render` does by default. Native frames come from Himi Player on the devices you pass: `--ios <udid>` and `--android <serial>`, plus `--ios-tablet` and `--android-tablet` for the tablet variant. Only those devices are touched. For each variant the command sets dark or light appearance and, for `rtl`, the Hebrew language (iOS `AppleLanguages`, Android per-app locale, API 33+). It opens `himi://app/<app>/screen/<screen>` and captures once two frames match. Every setting it changed is restored afterwards, also on Ctrl-C. A variant with no device is reported `skipped`, never passed. Without `--release <id>` or `--serve <port>` the Player shows the app's **live** release, not your working copy. `--serve <port>` serves the working copy on `127.0.0.1:<port>` as `himi run` does, so native and web render the same release. The Player reads a local origin only from a Debug build that compiled it in (see [View your package on a device](himi-player-implementation.md#view-your-package-on-a-device)): build it with `HIMALAYA_API_BASE_URL_INFO=http://127.0.0.1:<port>` on iOS and `-PhimalayaDevServeBaseUrl=http://10.0.2.2:<port>` on Android. An iOS device whose Player reads another origin is skipped with the rebuild to run. Android's origin cannot be read back from the installed app, so check that build yourself. A screen that declares `params` is skipped natively for now, because the Player's deep link does not carry them yet. On a fresh iOS simulator, open one `himi://` link by hand first and accept iOS's "Open in Himi Player?" prompt: the command cannot answer it, and until it is accepted every iOS capture shows the prompt.
 3. **Scores mockup↔web** with ImageMagick SSIM, globally and per tile. The worst tile says where the screens differ most.
 4. **Asks a fresh model** two questions, using the repo's fidelity judge prompt. The model never ran in the session that wrote the app.
    - **Design:** does WEB look like the MOCKUP? This judges the port.

package/guides/sdk-reference.json

@@ -5332,19 +5332,43 @@
         "name": "SnackbarOptions",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface SnackbarOptions {\n  message: string;\n  /** Default \"info\". */\n  tone?: SnackbarTone;\n  /** Auto-dismiss delay in ms, on every host. Default 3000; 0 or less also means 3000. */\n  durationMs?: number;\n  /** One action button (\"Undo\", \"View\"). Tapping it runs `actionId` with `args`, then dismisses the\n   *  snackbar. The id must be a worker action:\n   *  - one of this bundle's own `tier5.<svc>.<action>` ids — run on THIS worker, never another\n   *    screen's or the app-level worker's;\n   *  - an app service's `app.<svc>.<action>` — needs `app_services` and an exported action (an app\n   *    service's own id needs neither). The web host refuses it until it hosts app services.\n   *  Any other id (`capability.*`, `himi.*`, a registered handler) is refused when the snackbar is\n   *  requested: the call rejects and nothing is shown. A host that cannot tell which worker asked\n   *  (React Native, an embedded web region) refuses every `action` the same way. */\n  action?: SnackbarAction;\n}"
+        "decl": "export interface SnackbarOptions {\n  /** At most two lines on screen; a longer message is ellipsised. */\n  message: string;\n  /** Default \"info\". */\n  tone?: SnackbarTone;\n  /** Auto-dismiss delay in ms, clamped on every host to {@link SNACKBAR_LIMITS} (2–10 s, at least\n   *  4 s with an `action` so it can be reached by VoiceOver / TalkBack before it goes). Absent, 0 or\n   *  less: the default, 3000 (4000 with an `action`). */\n  durationMs?: number;\n  /** A thumbnail of the thing the toast is about: a 40 pt square at the leading edge. `https:` on\n   *  every host; a local `file:` URL on iOS and macOS only, whose image pipeline already reads local\n   *  files. Any other URL is ignored (the toast shows without it), and an image that fails to load\n   *  just hides. */\n  imageUrl?: string;\n  /** One action button (\"Undo\", \"View\"). Tapping it dismisses the snackbar and resolves the call\n   *  `{ actionTapped: true }`. With an `actionId` the tap also runs that action with `args`. The id\n   *  must be a worker action:\n   *  - one of this bundle's own `tier5.<svc>.<action>` ids — run on THIS worker, never another\n   *    screen's or the app-level worker's;\n   *  - an app service's `app.<svc>.<action>` — needs `app_services` and an exported action (an app\n   *    service's own id needs neither). The web host refuses it until it hosts app services.\n   *  Any other id (`capability.*`, `himi.*`, a registered handler) is refused when the snackbar is\n   *  requested: the call rejects and nothing is shown. A host that cannot tell which worker asked\n   *  (React Native, an embedded web reg\n/* … */"
       },
       {
         "name": "SnackbarAction",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface SnackbarAction {\n  /** The button's text — also its VoiceOver / TalkBack / screen-reader label. */\n  label: string;\n  /** What the tap runs: one of this bundle's own `tier5.<svc>.<action>` ids, or `app.<svc>.<action>`. */\n  actionId: string;\n  /** The action's arguments, which the reducer receives as typed JSON. */\n  args?: Record<string, unknown>;\n}"
+        "decl": "export interface SnackbarAction {\n  /** The button's text — also its VoiceOver / TalkBack / screen-reader label. At most 24\n   *  characters; a longer label is ellipsised. */\n  label: string;\n  /** What the tap runs, if anything: one of this bundle's own `tier5.<svc>.<action>` ids, or\n   *  `app.<svc>.<action>`. A screen worker may leave it out and branch on `actionTapped` instead\n   *  (\"Undo\"); an app service may not. */\n  actionId?: string;\n  /** The action's arguments, which the reducer receives as typed JSON. */\n  args?: Record<string, unknown>;\n}"
+      },
+      {
+        "name": "SnackbarResult",
+        "kind": "interface",
+        "jsdoc": "/** What a snackbar call resolves with. */",
+        "decl": "export interface SnackbarResult {\n  /** The user tapped the action. Always false for a snackbar without one (resolved on\n   *  presentation); with one, false when it was dismissed any other way — timed out, swiped, closed,\n   *  or replaced by a newer snackbar. */\n  actionTapped: boolean;\n}"
+      },
+      {
+        "name": "SNACKBAR_LIMITS",
+        "kind": "const",
+        "jsdoc": "/** #4661 — the constraints that keep a snackbar a toast, enforced here and again by every host. */",
+        "decl": "export const SNACKBAR_LIMITS = {\n  messageLines: 2,\n  labelChars: 24,\n  minDurationMs: 2000,\n  /** The floor with an action: long enough to reach it with a screen reader. */\n  minActionDurationMs: 4000,\n  maxDurationMs: 10_000,\n  /** The thumbnail's side, in pt / dp / CSS px. */\n  imageSize: 40,\n} as const;"
+      },
+      {
+        "name": "snackbarDurationMs",
+        "kind": "function",
+        "jsdoc": "/** The duration a host shows a snackbar for: absent / non-finite / 0 or less → undefined (the host\n *  default applies), else clamped to {@link SNACKBAR_LIMITS}. */",
+        "decl": "export function snackbarDurationMs(durationMs: number | undefined, hasAction: boolean): number | undefined;"
+      },
+      {
+        "name": "snackbarLabel",
+        "kind": "function",
+        "jsdoc": "/** An action label as every host draws it: at most {@link SNACKBAR_LIMITS}.labelChars characters\n *  (by code point, so an emoji is never cut in half), the last one an ellipsis when it was cut. */",
+        "decl": "export function snackbarLabel(label: string): string;"
       },
       {
         "name": "snackbar",
         "kind": "function",
-        "jsdoc": "/** Show a transient snackbar toast: it floats above the tab bar, slides and fades in and out\n *  (fades only under reduced motion), queues behind one that is already showing, and is read\n *  by VoiceOver / TalkBack. Resolves once it is PRESENTED (not after it auto-dismisses).\n *  Rejects with `no_ui_host` if no presenter is attached; with an `action`, also with\n *  `invalid_action` (empty label or id), `action_not_allowed` (not one of this bundle's\n *  actions), or, for an `app.*` id, `undeclared` (no `app_services`), `not_exported`, `no_service`,\n *  `no_action`, `not_booted` or `unavailable`. */",
-        "decl": "export async function snackbar(options: SnackbarOptions): Promise<void>;"
+        "jsdoc": "/** Show a transient snackbar toast: it floats above the tab bar, slides and fades in and out\n *  (fades only under reduced motion), queues behind one that is already showing, and is announced\n *  by VoiceOver / TalkBack / the screen reader. Without an `action` it resolves\n *  `{ actionTapped: false }` once it is queued, as before; with one it resolves when the snackbar\n *  goes, `{ actionTapped: true }` only if the action was tapped (see {@link SnackbarResult}).\n *  Rejects with `no_ui_host` if no presenter is attached; with an `action`, also with\n *  `invalid_action` (empty label), `action_id_required` (an app service with no `actionId`),\n *  `action_not_allowed` (not one of this bundle's actions), or, for an `app.*` id, `undeclared` (no\n *  `app_services`), `not_exported`, `no_service`, `no_action`, `not_booted` or `unavailable`. */",
+        "decl": "export async function snackbar(options: SnackbarOptions): Promise<SnackbarResult>;"
       },
       {
         "name": "version",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1613.0",
+  "version": "0.1615.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "8d1e7814c00d18146088e2680fe43650535ec12113548c216d4fdbe0"
+  "falconPackageHash": "16f0d18dbd708953827546385ed370640a8dc38276cb7033d3cc5068"
 }

package/templates/beauty-salon/tier5-src/_shared/branded-load-state.ts

@@ -35,11 +35,14 @@ export interface LoadFlags {
   notMock: boolean;
   notMockEmpty: boolean;
   notMockUnavailable: boolean;
+  /** hiddenWhen gate for the empty state: false ONLY when the site answered with no rows
+   *  (`notMockEmpty` is true then — it gates the sample banner, not the empty state). */
+  hideEmpty: boolean;
 }
 
 export const LOADING: LoadFlags = {
   status: "loading", error: "", signInRequired: false, notErrored: true, notLoading: false, busy: true, noSignIn: true,
-  isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true,
+  isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true, hideEmpty: true,
 };
 
 const READY: LoadFlags = { ...LOADING, status: "ready", notLoading: true, busy: false };
@@ -78,7 +81,7 @@ type Rows<K extends string, T> = { [P in K]: T[] } & { emptyText: string } & Loa
 export function loaded<K extends string, T>(key: K, rows: T[], copy: LoadCopy<T>): Rows<K, T> {
   if (rows.length) return { ...READY, [key]: rows, emptyText: "" } as Rows<K, T>;
   if (samplesRequested()) return sampleRows(key, copy, "empty");
-  return { ...READY, [key]: [], emptyText: copyParam(`${copy.prefix}.emptyText`, copy.empty) } as Rows<K, T>;
+  return { ...READY, [key]: [], emptyText: copyParam(`${copy.prefix}.emptyText`, copy.empty), hideEmpty: false } as Rows<K, T>;
 }
 
 /** A query threw. Never rows the customer did not create. */

package/templates/beauty-salon/tier5-src/_shared/himi-account.ts

@@ -1,6 +1,8 @@
 import { dispatch } from "@himalaya/dispatch";
 // Relative for node resolution (see himi-store.ts note); rewritten off-repo.
 import { displayName, getMyData, initials, type WixMyData } from "@himalaya/wix-users";
+import { getMyMember } from "@himalaya/wix-members";
+import { wixMediaUrl } from "@himalaya/wix-media";
 import { formatDateMedium, formatWeekdayDateTime } from "../_shared/engine-intl.js";
 
 export interface AccountProfile {
@@ -82,6 +84,31 @@ function profileFromData(data: WixMyData, fallbackEmail = ""): AccountProfile {
   };
 }
 
+/** The signed-in site member's name and photo from their member record, or undefined when it
+ *  cannot be read or names nobody (the caller then shows the email). */
+async function siteMemberProfile(email: string): Promise<AccountProfile | undefined> {
+  try {
+    const member = (await getMyMember({ fieldsets: ["FULL"] }))?.member;
+    const name = [member?.contact?.firstName, member?.contact?.lastName].map((part) => (part ?? "").trim()).filter(Boolean).join(" ")
+      || (member?.profile?.nickname ?? "").trim();
+    if (!name) return undefined;
+    const image = wixMediaUrl(member?.profile?.photo?.url) || wixMediaUrl(member?.profile?.photo?.id) || "";
+    return {
+      isMember: true,
+      identityLine: "Signed in",
+      detailLine: email || name,
+      memberName: name,
+      memberEmail: email || member?.loginEmail || "",
+      memberImage: image,
+      memberInitials: initialsFromName(name) || "M",
+      hasMemberImage: !!image,
+      noMemberImage: !image,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 export function guestProfile(detailLine: string): AccountProfile {
   return {
     isMember: false,
@@ -118,6 +145,10 @@ export async function loadMemberProfile(guestDetailLine: string): Promise<Accoun
     const data = await getMyData();
     return profileFromData(data, storedEmail);
   } catch {
+    // The account profile is an owner endpoint: the web host refuses it, and a site member need
+    // not have one. The member's own record (the Members API) still names them.
+    const member = await siteMemberProfile(storedEmail);
+    if (member) return member;
     return {
       isMember: true,
       identityLine: "Signed in",

package/templates/beauty-salon/tier5-src/_shared/himi-booking-saved.ts

@@ -0,0 +1,88 @@
+// Saved (favorite) booking services use the host's durable, app-scoped KV, shared by every
+// screen worker — the service detail toggles a row (himi-booking-service `toggleSaved`), the
+// Favorites list reads them (himi-booking-saved). Same model as _shared/himi-store-saved.ts: a
+// failed write must never claim that a save succeeded.
+export interface SavedService {
+  id: string;
+  name: string;
+  /** The price line as the detail showed it ("$250"), kept so the list paints offline. */
+  price: string;
+  /** The duration line ("1 hr"). */
+  duration: string;
+  image: string;
+  category: string;
+  /** A course: the list's Book passes `course` to the time screen, which then refuses a course
+   *  whose record failed to load instead of offering its sessions one by one. */
+  course?: boolean;
+}
+type StorageLike = { getItem(key: string): string | null; setItem(key: string, value: string): void };
+type Host = { himalaya?: { storage?: StorageLike; input?: Record<string, unknown> }; localStorage?: StorageLike };
+const BASE = "himi-booking:saved-services:v1";
+function storage(): StorageLike {
+  const host = globalThis as Host;
+  const kv = host.himalaya?.storage ?? host.localStorage;
+  if (!kv) throw new Error("Saved-service storage is unavailable");
+  return kv;
+}
+const validPart = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(value) && value !== "default";
+/** Saves belong to whoever made them. A signed-in member's live under the host's authenticated
+ *  account + business — the partition collection preferences use, so a second member on the same
+ *  device never sees them; a visitor's live on the device. A member's partition, read for the
+ *  first time, takes the visitor's saves on this device (signing in carries them, like a cart),
+ *  once — the device list is then emptied. */
+function storeKey(kv: StorageLike): string {
+  const input = (globalThis as Host).himalaya?.input;
+  const account = input?.__himiPreferenceAccount, business = input?.__himiPreferenceBusiness;
+  if (!validPart(account) || !validPart(business)) return BASE;
+  const key = `${BASE}.${account}.${encodeURIComponent(business)}`;
+  if (kv.getItem(key) === null) {
+    const visitor = kv.getItem(BASE);
+    if (visitor !== null) {
+      kv.setItem(key, visitor);
+      // Empty the device list only once the member's copy is confirmed: a web host may swallow a
+      // failed write, and clearing then would lose the visitor's saves.
+      if (kv.getItem(key) === visitor) kv.setItem(BASE, "[]");
+    }
+  }
+  return key;
+}
+const str = (value: unknown): string => (typeof value === "string" ? value : "");
+export function readSavedServices(): SavedService[] {
+  const kv = storage();
+  const raw = kv.getItem(storeKey(kv));
+  if (!raw) return [];
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed)) throw new Error("Invalid saved-service data");
+  const rows = new Map<string, SavedService>();
+  for (const value of parsed) {
+    if (!value || typeof value !== "object") continue;
+    const row = value as Record<string, unknown>;
+    if (typeof row.id !== "string" || !row.id.trim() || typeof row.name !== "string") continue;
+    rows.set(row.id, { id: row.id, name: row.name, price: str(row.price), duration: str(row.duration), image: str(row.image), category: str(row.category), ...(row.course === true ? { course: true } : {}) });
+  }
+  return [...rows.values()];
+}
+
+export function isServiceSaved(id: string): boolean {
+  return readSavedServices().some(row => row.id === id);
+}
+export function writeSavedServices(rows: SavedService[]): void {
+  const kv = storage();
+  const key = storeKey(kv);
+  const value = JSON.stringify(rows);
+  kv.setItem(key, value);
+  // Web hosts may swallow quota/security errors. Confirm the synchronous write
+  // before displaying success; a missing/mismatched read is a failed save.
+  if (kv.getItem(key) !== value) throw new Error("Saved-service write did not persist");
+}
+/** Save or unsave; returns the new saved state. The newest save is listed first. */
+export function toggleSavedService(service: SavedService): boolean {
+  if (!service.id.trim() || !service.name.trim()) throw new Error("No service to save");
+  const rows = readSavedServices();
+  const saved = !rows.some(row => row.id === service.id);
+  writeSavedServices(saved ? [service, ...rows] : rows.filter(row => row.id !== service.id));
+  return saved;
+}
+export function removeSavedService(id: string): void {
+  writeSavedServices(readSavedServices().filter(row => row.id !== id));
+}

package/templates/beauty-salon/tier5-src/himi-booking-service/index.ts

@@ -22,6 +22,7 @@ import { wixMediaUrl, WIX_DETAIL_IMAGE, WIX_LIST_IMAGE } from "@himalaya/wix-med
 import { formatClock, formatDateMedium, formatMonthDay } from "../_shared/engine-intl.js";
 import { descriptionBody } from "../_shared/rich-body.js";
 import { openRichLink } from "../_shared/rich-content-link.js";
+import { isServiceSaved, toggleSavedService } from "../_shared/himi-booking-saved.js";
 
 // Offline-first (data-offline): the service detail is a public read-through. On a
 // fetch failure we fall back to the last-synced row for this service written by
@@ -182,6 +183,13 @@ interface S {
   sessionMessageOk: boolean;
   sessionMessageFailed: boolean;
   noSessionMessage: boolean;
+  // ---- Favorites (the heart an app adds with withServiceSaveToggle; _shared/himi-booking-saved.ts) ----
+  saved: boolean;
+  notSaved: boolean;
+  /** The heart's spoken label: what a tap does now. */
+  saveLabel: string;
+  /** "" unless the last save or unsave failed. */
+  saveMessage: string;
 }
 
 function inputId(): string {
@@ -790,6 +798,10 @@ function derive(s: S): S {
     // Change Time opens the time screen, which cannot book a service closed to online booking.
     noChangeTime: (control !== "book" && control !== "waitlist" && control !== "closed") || !s.bookableOnline,
     noSessionMessage: !s.sessionMessage,
+    notSaved: !s.saved,
+    saveLabel: s.saved
+      ? copyParam("service.unsaveLabel", "Remove from favorites")
+      : copyParam("service.saveLabel", "Save to favorites"),
     notBookableOnline: !s.bookableOnline,
     noAbout: !s.about && !s.aboutJson,
     noPolicy: s.policyLines.length === 0,
@@ -866,9 +878,16 @@ function withService(s: S, service: WixService): S {
     // WS-C — canonical param-less target; the descriptor's choose-time CTA
     // binds the separate `id` state field as a first-class nav param.
     timeScreenId: "himi_time",
+    saved: savedNow(serviceId),
   });
 }
 
+/** Whether the service is a favorite. Unreadable storage reads as not saved: the heart is a
+ *  convenience and never holds the screen back. */
+function savedNow(id: string): boolean {
+  try { return !!id && isServiceSaved(id); } catch { return false; }
+}
+
 /** The service record: with staff details when this token may read them, else without. */
 async function fetchService(id: string): Promise<WixService | undefined> {
   try {
@@ -897,9 +916,10 @@ const svc = defineService<S, {
   book: (s: S) => S;
   changeTime: (s: S) => S;
   joinWaitlist: (s: S, arg?: unknown) => Promise<S>;
+  toggleSaved: (s: S) => S;
 }>("himiBookingService", {
   // A join's outcome belongs to that visit: a cold start must not replay it from saved state.
-  notHydrated: ["sessionMessage", "sessionMessageOk", "sessionMessageFailed", "noSessionMessage"],
+  notHydrated: ["sessionMessage", "sessionMessageOk", "sessionMessageFailed", "noSessionMessage", "saveMessage"],
   state: derive({
     status: "loading",
     id,
@@ -1005,6 +1025,10 @@ const svc = defineService<S, {
     noChangeTime: true,
     ...NO_SESSION_MESSAGE,
     noSessionMessage: true,
+    saved: false,
+    notSaved: true,
+    saveLabel: "",
+    saveMessage: "",
   }),
   actions: {
     load: async (s, arg) => {
@@ -1012,14 +1036,16 @@ const svc = defineService<S, {
       rememberSignIn(arg);
       if (!s.id) return derive({ ...s, status: "ready", errored: true });
       // A new view: a join's outcome from before is not news when the screen shows again.
-      const start = { ...s, policyExpanded: false, scheduleExpanded: false, ...NO_SESSION_MESSAGE };
+      const start = { ...s, policyExpanded: false, scheduleExpanded: false, saveMessage: "", ...NO_SESSION_MESSAGE };
       try {
         const service = await fetchService(s.id);
         if (!service) return withSession(derive({ ...start, status: "ready" }), undefined);
         loadedService = service;
         // The session the Agenda row opened on, read beside the service-wide availability.
         const [shown, sel] = await Promise.all([withGroupAvailability(withService(start, service), service), readSessionBounded(service)]);
-        return withSession(shown, sel);
+        // The heart is read again after the waits (the session read takes up to 10 s): a toggle
+        // tapped meanwhile wrote storage, and the snapshot taken before would undo it.
+        return withSession({ ...shown, saved: savedNow(s.id) }, sel);
       } catch {
         // Offline: paint from the last-synced services cache (written by the list
         // worker) before falling back to the error state. The cache holds the name,
@@ -1038,6 +1064,7 @@ const svc = defineService<S, {
             category: String(cached.category ?? ""),
             images: image ? [{ url: image, alt: name }] : [],
             timeScreenId: `himi_time_${s.id}`,
+            saved: savedNow(s.id),
           }, undefined);
         }
         return withSession({ ...start, status: "ready", errored: true, name: "" }, undefined);
@@ -1056,6 +1083,26 @@ const svc = defineService<S, {
     },
     togglePolicy: (s) => derive({ ...s, policyExpanded: !s.policyExpanded }),
     toggleSchedule: (s) => derive({ ...s, scheduleExpanded: !s.scheduleExpanded }),
+    // The heart: save or unsave this service on the device (the member's own list once signed
+    // in). The row keeps what the Favorites list shows offline; a failed write says so and never
+    // shows the heart as saved.
+    toggleSaved: (s) => {
+      if (!s.id || !s.hasService || s.errored) return s;
+      try {
+        const saved = toggleSavedService({
+          id: s.id,
+          name: s.name,
+          price: s.priceIsText ? "" : s.priceText,
+          duration: s.durationText,
+          image: s.image,
+          category: s.category,
+          ...(s.isCourse ? { course: true } : {}),
+        });
+        return derive({ ...s, saved, saveMessage: "" });
+      } catch {
+        return derive({ ...s, saved: savedNow(s.id), saveMessage: copyParam("service.saveError", "Could not update your favorites. Try again.") });
+      }
+    },
     // The footer button opens the time screen for the loaded service. A worker directive,
     // not a `himi.open` with a `$service:` id param: the iOS and Android sticky footers
     // dispatch their taps without resolving `$service:` params, so the id never arrived.

package/templates/beauty-salon/tier5-src/himi-booking-services/index.ts

@@ -3,7 +3,8 @@
 // Visitors browse every Wix Bookings service of the site, grouped by category under a small
 // title, in the business's own order (the order of the site's Book Online page). The category
 // chips are anchors, not filters: a tap scrolls the list to its category's title, and the chip
-// of the category at the top of the list lights up while the member scrolls. A name search
+// of the category at the top of the list lights up while the member scrolls. Opened with a
+// `category` nav param (a category tile), the list starts at that category. A name search
 // keeps the grouping. With two or more locations a pin limits the list to the services offered
 // at one location; the choice is shared with the Agenda and Choose Time screens. Each row
 // carries what the service record has: photo, name, tagline, a Class or Course tag, and
@@ -449,10 +450,57 @@ let activeCategory = "";
 let activeChosen = false;
 let scrollTarget = "";
 let jumps = 0;
+/** This worker run's own mark on its jump values. A renderer remembers the value it last jumped
+ *  for, and a screen restored from an earlier visit can bring that memory back: a value that
+ *  repeats across runs ("cat:x|1") would then be taken as done. Not in the state, so the boot
+ *  state (which a release hashes) does not change with the clock. */
+const RUN = Date.now().toString(36);
 let quietUntil = 0;
 /** How long a jump the worker asked for takes to settle: a top-row report inside it is the jump's
  *  own (the renderers suppress those, this is the belt to their braces). */
 const JUMP_SETTLE_MS = 900;
+/** The category this list was opened on (the `category` nav param: a category's Wix id, its
+ *  `name:<name>` key, or its name), e.g. from a category tile. Its chip lights and the list jumps
+ *  to its title once that group shows, and once more when this run's live page lands. After that
+ *  — or as soon as the member scrolls or taps a chip — the member leads.
+ *
+ *  Armed by the screen's own `load` (its onAppear), never by the boot request: the iOS and
+ *  Android lists act on a jump that CHANGES while they are on screen (a chip tap), and drop one
+ *  that is already in the state when they mount. The second jump is for a screen restored from
+ *  its last visit: the host puts back that visit's scroll position after the first one. */
+let pendingCategory = "";
+let bootLoad = true;
+/** This run's own live read has landed (a restored snapshot's rows do not count). */
+let liveLanded = false;
+let jumpedFromCache = false;
+/** The `category` param the list last started at, and that visit's `categoryActivation` (a
+ *  nonce a category tap sends, so a second tap on the SAME category is a new visit too). */
+let openedFor = "";
+let openedActivation = "";
+function inputParam(key: "category" | "categoryActivation"): string {
+  const value = (globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.[key];
+  return typeof value === "string" ? value.trim().slice(0, 200) : "";
+}
+const inputCategory = (): string => inputParam("category");
+/** Read on every `load`, not once at boot: a pooled worker is handed the next screen's input just
+ *  before its `load` runs (the web host keeps one services worker for every push). The same param
+ *  again is the screen coming back (a pop, a refresh), which keeps the member's place. */
+function armCategory(): boolean {
+  const next = inputCategory();
+  const activation = inputParam("categoryActivation");
+  if (next === openedFor && activation === openedActivation) return false;
+  openedFor = next;
+  openedActivation = activation;
+  pendingCategory = next;
+  jumpedFromCache = false;
+  // A new visit is a new run for a pooled worker: the last visit's live page is not this one's,
+  // so the jump that waits for "this run's live read" waits for the read this load starts.
+  liveLanded = false;
+  // An open with no category ("See all") starts at the top: the last visit's lit chip and its
+  // jump do not carry over to it.
+  if (!next) { activeCategory = ""; activeChosen = false; scrollTarget = ""; }
+  return true;
+}
 
 // ---- Location ------------------------------------------------------------------------
 /** The member's choice (shared with Agenda and Choose Time through the on-device store). */
@@ -500,6 +548,17 @@ function display(s: S): S {
     ...section.rows.map((row) => ({ ...row, isSection: false, notSection: true, sectionTitle: "" })),
   ]);
   const chips = titled && sections.length >= 2 ? sections.map((section) => ({ id: section.id, label: section.title })) : [];
+  const live = liveLanded && !loading;
+  if (pendingCategory && chips.length && (live || !jumpedFromCache)) {
+    const opened = chips.find((chip) => chip.id === sectionIdOf(pendingCategory) || chip.label === pendingCategory);
+    if (opened) {
+      activeCategory = opened.id;
+      activeChosen = true;
+      scrollTarget = `${opened.id}|${RUN}.${++jumps}`;
+      quietUntil = Date.now() + JUMP_SETTLE_MS;
+      if (live) pendingCategory = ""; else jumpedFromCache = true;
+    }
+  }
   // No chips (a reload in flight, a single group): the lit chip waits for the list to come back.
   if (chips.length && (!activeChosen || !chips.some((chip) => chip.id === activeCategory))) activeCategory = chips[0]!.id;
   const target = scrollTarget.split("|")[0];
@@ -553,9 +612,15 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
   register: registerServices,
   restorePagesOnLoad: true,
   onLoad() {
+    let reset: { query: string } | undefined;
+    if (bootLoad) bootLoad = false;
+    // A new visit at a category drops a search the member left on this list: a saved "massage"
+    // would hide the category the tile opened, and its jump would never land.
+    else if (armCategory() && pendingCategory) reset = { query: "" };
     // Copy is stashed before this hook. Repaint restored labels immediately, even
     // when the background query holds the old page through a slow or failed read.
     (svc as unknown as { normalizeRestored?: () => unknown }).normalizeRestored?.();
+    return reset;
   },
   state: { status: "loading", query: "", all: [], results: [], listRows: [], emptyText: "", countLabel: "", errored: false,
     notErrored: true, isLoading: true, notLoading: false, hasResults: false, noEmpty: true,
@@ -639,9 +704,10 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
         ?? ((p as { args?: { selectedIds?: unknown } } | undefined)?.args?.selectedIds);
       const picked = Array.isArray(ids) && typeof ids[0] === "string" ? ids[0] : activeCategory;
       if (!(s.categoryChips ?? []).some((chip) => chip.id === picked)) return s;
+      pendingCategory = "";
       activeCategory = picked;
       activeChosen = true;
-      scrollTarget = `${picked}|${++jumps}`;
+      scrollTarget = `${picked}|${RUN}.${++jumps}`;
       quietUntil = Date.now() + JUMP_SETTLE_MS;
       return display(s);
     },
@@ -653,6 +719,7 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
       if (!rows.some((row) => !row.isSection)) return s;
       const section = sectionOfRow(rows, argOf(p, "id"));
       if (!section || !(s.categoryChips ?? []).some((chip) => chip.id === section)) return s;
+      pendingCategory = "";
       activeCategory = section;
       activeChosen = true;
       // The member has moved on from the last jump: a re-render never scrolls back to it.
@@ -688,7 +755,7 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
     // Ended label the restored row for the same course showed, until a current pack replaces it.
     const shown = new Map((restoredEndedBridge && Array.isArray(s.results) ? s.results : []).map((row) => [row.id, row.endedText]));
     const rows = page.items.map((item) => withRowDefaults(item, shown.get(item.id)));
-    if (page.metadata?.fromCache === false && !loading && !errored) restoredEndedBridge = false;
+    if (page.metadata?.fromCache === false && !loading && !errored) { restoredEndedBridge = false; liveLanded = true; }
     const filtered = page.criteria.filter.startsWith("value:");
     const hasQuery = !!page.criteria.query.trim();
     // The menu offers every location of the whole catalog: a settled live read replaces it, the