@wix/himalaya-cli 0.1475.0 → 0.1477.0

package/guides/recipe-four-state.md

@@ -3,8 +3,9 @@
 **The rule every recipe follows:** a screen that loads or writes data shows a
 **loading state**, a **classified error state**, and a **recovery action where the
 user can fix the failure** — retry for an offline or a server failure, and for a failed
-write; Sign in when the user is signed out; nothing for a permission failure, an empty result
-or a field error, where the same request gives the same answer. This recipe is the shared
+write; Sign in when the user is signed out; the site's join flow for a non-member when
+available; nothing for a permission failure, an empty result or a field error, where the same
+request gives the same answer. This recipe is the shared
 idiom; the other recipes link here for it. Design guidance for the states:
 `himi docs designing-himi-screens` §5 ("Loading states", "Error states").
 
@@ -22,7 +23,7 @@ more than half model error, and the reference apps (`apps/himi-owner-lite`,
 ## 1. One status field, a classified error, derived flags
 
 ```ts
-type ErrorKind = "" | "offline" | "server" | "signIn" | "permission";
+type ErrorKind = "" | "offline" | "server" | "signIn" | "membership" | "permission";
 
 interface State {
   status: "loading" | "ready" | "error";
@@ -34,6 +35,7 @@ interface State {
   hideOfflineError: boolean; // one EmptyState per error class …
   hideServerError: boolean;
   hideSignInError: boolean;
+  hideMembershipError: boolean;
   hidePermissionError: boolean;
   hideRefreshError: boolean; // … and a Banner when a refresh fails over rows we kept
 }
@@ -50,6 +52,7 @@ function shape(s: Partial<State>): State {
     hideOfflineError: !(blank && errorKind === "offline"),
     hideServerError: !(blank && errorKind === "server"),
     hideSignInError: !(blank && errorKind === "signIn"),
+    hideMembershipError: !(blank && errorKind === "membership"),
     hidePermissionError: !(blank && errorKind === "permission"),
     // Only a failure a retry can fix gets the banner over kept rows.
     hideRefreshError: !(!blank && (errorKind === "offline" || errorKind === "server")),
@@ -66,31 +69,49 @@ const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRoute
 // A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
 // Android `site account is not the bound site …`.
 const SIGNED_OUT = /wixApi not enabled|session unavailable|PRINCIPAL_CHANGED|not signed in|siteNotPermitted\(requested: "account"|site account is not the bound site/i;
+// The account is not a member of this site: iOS `NotSiteMember(metaSiteId: …)`,
+// Android `not a member of site …`. NOT `WDE0027` — that is Wix Data's generic
+// permission refusal, which a signed-in member and a visitor both get.
+const NOT_MEMBER = /\bNotSiteMember\b|\bnot a member of site\b/i;
 
-function classifyError(e: unknown): ErrorKind {
+function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknown" = "unknown"): ErrorKind {
   const msg = String((e as Error)?.message ?? e ?? "");
-  const code = String((e as { code?: unknown })?.code ?? "");
+  // Some bridges put the Wix code in the response body rather than Error.code.
+  const code = String((e as { code?: unknown })?.code ?? /"(?:code|error)"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? "");
   const status = Number(STATUS.exec(msg)?.[1] ?? 0);
-  if (status === 401) return "signIn";        // signed out (or the session expired)
-  if (status === 403) return "permission";    // signed in, without access
-  if (SIGNED_OUT.test(msg)) return "signIn";
+  if (code === "AccountSessionExpired" || code === "webwix_account_signed_out" || SIGNED_OUT.test(msg)) return "signIn";
+  if (code === "NotSiteMember" || NOT_MEMBER.test(msg)) return "membership";
+  // A 401 is a missing or expired session — unless the host knows the user is signed
+  // in, when it is a policy refusal. Never "server": a retry sends the same 401 back.
+  if (status === 401) return authState === "signedIn" ? "permission" : "signIn";
+  // A 403 is a missing permission — but a visitor the host knows is signed out gets
+  // `403 WDE0027` on member-only data too, and signing in is what fixes that.
+  if (status === 403) return authState === "signedOut" ? "signIn" : "permission";
   if (code === "offline_write_blocked") return "offline";   // a write refused before it left
   // A web call that never reached Wix arrives as
   // `HTTP 502: {"error":"webwix_direct_failed","detail":"Failed to fetch"}` — judge its detail.
-  if (status && !msg.includes("webwix_direct_failed")) return "server";
-  if (TRANSPORT.test(msg)) return "offline";
+  // The top-level 502 is the bridge wrapper, not the underlying transport result.
+  const detail = msg.includes("webwix_direct_failed")
+    ? /"detail"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? msg
+    : msg;
+  if (status && detail === msg) return "server";
+  if (TRANSPORT.test(detail)) return "offline";
   return "server";   // anything else — a bug, a malformed row — is not the user's connection
 }
 
+// App-specific host integration. If the host does not expose auth state here,
+// keep "unknown": a 401 then shows Sign in, which is what a session that ended needs.
+function currentAuthState(): "signedIn" | "signedOut" | "unknown" { return "unknown"; }
+
 async function load(s: State): Promise<State> {
   try {
     const items = (await fetchRows()).map(normalize);
     return shape({ status: "ready", items });
   } catch (e) {
-    const errorKind = classifyError(e);
+    const errorKind = classifyError(e, currentAuthState()); // use host/session state when available
     // Keep the rows: a refresh that fails must not blank a screen that had content —
     // unless access is gone, when the rows must not stay on screen either.
-    const lostAccess = errorKind === "signIn" || errorKind === "permission";
+    const lostAccess = errorKind === "signIn" || errorKind === "membership" || errorKind === "permission";
     return shape({ ...s, items: lostAccess ? [] : s.items, status: "error", errorKind });
   }
 }
@@ -140,9 +161,16 @@ only when the screen shows the user something different for it.
   "body": { "package": "himalaya", "type": "EmptyState",
     "props": { "title": "Sign in to view products",
                "subtitle": "Your session has ended.",
-               "action": { "actionId": "tier5.products.signIn" },   // a worker action that dispatches himi.wix.signInDirect
+               "action": { "actionId": "tier5.products.openSignIn" },
                "actionLabel": "Sign in" } },
   "modifiers": { "hiddenPath": "$service:products.hideSignInError" } },
+{ "id": "error.membership",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Join this site to view products",
+               "subtitle": "Use this site's join flow, or ask the owner for access.",
+               "action": { "actionId": "tier5.products.openJoin" },
+               "actionLabel": "Join this site" } },
+  "modifiers": { "hiddenPath": "$service:products.hideMembershipError" } },
 { "id": "error.permission",           // no action: retrying gives the same answer
   "body": { "package": "himalaya", "type": "EmptyState",
     "props": { "title": "You need permission to view this screen",
@@ -164,10 +192,21 @@ only when the screen shows the user something different for it.
   the binding reads without negation.
 - Ready state is simply the data itself (the list rows, the detail fields) — it
   needs no dedicated marker.
-- **Sign in is a worker action.** A renderer cannot dispatch `himi.wix.*`, so the
-  sign-in `EmptyState` calls `tier5.products.signIn`, which the worker defines:
-  it dispatches `himi.wix.signInDirect` and then reloads
-  (`himi docs wix-login-integration`).
+- **Sign in uses a real auth flow.** A renderer cannot dispatch `himi.wix.*`, so
+  the sign-in `EmptyState` calls an app action that opens its configured auth gate
+  or sign-in screen, then reloads after authentication. Do not dispatch
+  `himi.wix.signInDirect` from this button: it requires the email and password
+  collected by a credential form (`himi docs wix-login-integration`).
+- **Membership is not sign-in.** `NotSiteMember` (Android: `not a member of
+  site`) means the account must join this site. Route it to the membership state;
+  wire its action to the app's join/registration UI, or omit the action when no
+  such flow exists. A `403 WDE0027` is NOT membership: Wix Data returns it to a
+  signed-in member without access too, so it stays a permission error.
+- **A 403 is a permission error** — the user lacks access and signing in again
+  changes nothing — unless the host's auth state says the user is signed out: a
+  visitor gets `403 WDE0027` on member-only data, and signing in fixes it. A 401 is
+  the session that ended — unless the host says the user is signed in, when it is a
+  permission refusal.
 - **Loading is a `Skeleton` shaped like the loaded content** when you know the
   layout — the same rows at about the same size. `StatefulSection` or
   `ActivityIndicator` are fine where they fit better. A plain `"Loading…"` `Text`
@@ -194,7 +233,7 @@ only when the screen shows the user something different for it.
 | loading | initial state (`status: "loading"`) | content-shaped skeleton; NO retry |
 | error, nothing on screen | `catch` in the first load | the class's `EmptyState`: user-facing copy + a recovery action where one exists |
 | error, rows on screen | `catch` in a refresh (offline or server) | rows stay; a `Banner` with **Try again** above them |
-| sign-in or permission | `catch` in any load | rows go; the class's `EmptyState` (Sign in, or no action) |
+| sign-in, membership or permission | `catch` in any load | rows go; the class's `EmptyState` (auth flow, join flow, or no action) |
 | empty | derived: ready + 0 rows | say what *would* fill it, and how |
 | ready | successful fetch | the content |
 
@@ -227,9 +266,10 @@ only when the screen shows the user something different for it.
   (`dev/net-mocks.json`, CMS seed rows). `himi render <screenId> --no-mocks` shows
   the initial frame — the loading state — and
   `--state '{"products":{"status":"error","errorKind":"offline","hideOfflineError":false,…}}'`
-  forces an error class without the network. A `dev/net-mocks.json` rule that
-  answers 401, 403 or 500 previews the sign-in, permission and server classes
-  through the real `classifyError`.
+  forces an error class without the network. A `dev/net-mocks.json` rule reaches
+  the worker only as `Wix <status> for …` — the hermetic crawl drops the response
+  body — so a 401, 403 or 500 rule previews the sign-in, permission and server
+  classes. Preview the membership class with `--state`.
 
 ## See also
 

package/guides/recipe-search.md

@@ -66,7 +66,7 @@ not say why there are no rows.
 | Results | Matching rows, result count, and the available sort/filter controls. |
 | No matches | An `EmptyState` explaining that the current query or filters found nothing; offer a way to adjust them, and Clear only where the field is controlled (the native slot) — the inline `SearchField` is uncontrolled, so Clear there empties the query but not the field. |
 | Empty catalog | Explain that the catalog itself has no items yet, independent of the query; provide a useful browse/back action. |
-| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, Sign in for sign-in, no action for permission. Retain the query and controls, and keep it distinct from no matches. |
+| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, the app's auth flow for sign-in, the site's join flow for `NotSiteMember`, and no action for permission. Retain the query and controls, and keep it distinct from no matches. |
 
 ### Native slot and old-client fallback
 
@@ -172,9 +172,9 @@ interface PostsState {
   query: string;
   hideNoPosts: boolean;  // the EmptyState for "loaded, and there is nothing at all"
   hideNoMatches: boolean; // the EmptyState for "there are posts, none match the query"
-  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e)
+  errorKind: "" | "offline" | "server" | "signIn" | "membership" | "permission";  // classifyError(e, currentAuthState())
   hideLoading: boolean; hideOfflineError: boolean; hideServerError: boolean;
-  hideSignInError: boolean; hidePermissionError: boolean;
+  hideSignInError: boolean; hideMembershipError: boolean; hidePermissionError: boolean;
   hideRefreshError: boolean;                    // hiddenPath flags, as in recipe-four-state
 }
 
@@ -219,7 +219,7 @@ clear: (s) => { currentQuery = ""; return shape({ ...s, query: "", items: s.all
 ```
 
 - `load()` fetches once, fills `all`, and sets `items = visible(all, currentQuery)`.
-  On a `signIn` or `permission` failure it clears **`all` as well as `items`** —
+  On a `signIn`, `membership` or `permission` failure it clears **`all` as well as `items`** —
   `search`, `clear` and `retry` rebuild rows from `all`, so rows left there come
   back on the next keystroke.
 - The shipped Blog v3 `WixPost` type includes `categoryIds` and both Wix-image and
@@ -261,8 +261,11 @@ A searchable list loads data, so it carries the four states of
   while the first `load()` runs. The search field is usable at once.
 - **Error, nothing loaded** — one `EmptyState` per class `classifyError` can
   return, **no icon**, user-facing copy; offline and server get **Try again** →
-  `tier5.posts.retry`, sign-in gets **Sign in**, permission gets no action. The
-  `catch` sets `errorKind` from `classifyError(e)`; it never shows `e.message`.
+  `tier5.posts.retry`, sign-in opens the app's configured auth flow, `NotSiteMember`
+  opens the site's join flow when the app provides one, and permission gets no
+  action. The `catch` sets `errorKind` from `classifyError(e, currentAuthState())`
+  (both from `himi docs recipe-four-state`); it never
+  shows `e.message`.
 - **Retry keeps the query.** `retry` re-runs `load()` and then re-applies
   `currentQuery` — not `s.query`, which is the query from when the retry
   STARTED — so what the user typed during the fetch is not lost.
@@ -273,7 +276,8 @@ A searchable list loads data, so it carries the four states of
 retry: async (s) => {
   const next = await load(s);                            // classified on failure
   // Lost access clears the rows; any other failure keeps them for the Banner.
-  const lostAccess = next.errorKind === "signIn" || next.errorKind === "permission";
+  const lostAccess = next.errorKind === "signIn" || next.errorKind === "membership"
+    || next.errorKind === "permission";
   const all = lostAccess ? [] : next.all;
   return shape({ ...next, all, query: currentQuery, items: visible(all, currentQuery) });
 },

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

@@ -112,10 +112,16 @@ The first arg after `state` is the action's payload object: the descriptor's `Ac
 | `Rating` | `onChange` | `{ value }` — the 1-based star index |
 | `ColorPicker` | `onChange` | `{ value }` — the hex string |
 | `DatePicker` | `onChange` | `{ value }` — unix **seconds**, string-encoded |
-| `OtpInput` | `onChange`, `onComplete` | `{ value }` — the assembled code (dispatched on React Native today; the other renderers show the boxes read-only) |
-| `ChipsInput` | `onRemove` | `{ value }` — the removed chip |
+| `OtpInput` | `onChange`, `onComplete` | `{ value }` — the assembled code: `onChange` on every edit, `onComplete` once, on the edit that fills the last box |
+| `ChipsInput` | `onAdd`, `onRemove` | `{ value }` — the new token (trimmed; committed by Return or a comma, and the field clears) / the removed chip. Append the token to `valuesPath` to show it |
 | `Button` / `ListItem` | `action` / `onTap` | exactly the descriptor's `params` (no injected value) |
 
+For a controlled `OtpInput`, bind `valuePath` and have `onChange` store `payload.value` in that
+bound field. An `onComplete` reducer can then clear it to empty the boxes. Service subscriptions
+report **changes**: returning an already-empty bound field without first storing the user's edit
+is a no-op and does not reset the local input. A completion-only input can omit `valuePath` and
+submit the assembled code directly from `payload.value`.
+
 The payload rides in **`args`**. Some arms also mirror it into `params`; that is permitted only
 for string-encoded values, because `Action.params` is `map<string,string>` in the proto. Every
 host merges `{...params, ...args}` (args winning) before invoking the reducer, so a worker sees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1475.0",
+  "version": "0.1477.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "224e56d2071ce0050cf65a861313895b2147862685f52d1f6b8abd95"
+  "falconPackageHash": "c8bc671d48c378f2cea33ccdf2dd61f759b3920ebb50a7c0a1c87a1d"
 }

package/templates/beauty-salon/tier5-src/_shared/engine-intl.ts

@@ -444,3 +444,24 @@ export function calendarDay(date: Date, timeZone?: string): string {
   }
   return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
 }
+
+/**
+ * [timeZone]'s offset from UTC in ms at instant [at] (Asia/Jerusalem in winter: 7_200_000), or NaN
+ * where it cannot be known — no ECMA-402 (the wrist engines) or a zone this engine does not know.
+ * Callers fall back to the device zone on NaN, as the formatters above do.
+ */
+export function zoneOffsetAt(at: number, timeZone: string): number {
+  if (hasIntl() && Number.isFinite(at)) {
+    try {
+      const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", second: "2-digit",
+      }).formatToParts(new Date(at));
+      const n = (type: string) => Number(parts.find((p) => p.type === type)?.value);
+      return Date.UTC(n("year"), n("month") - 1, n("day"), n("hour") % 24, n("minute"), n("second")) - at;
+    } catch {
+      /* a zone this engine does not know: NaN below */
+    }
+  }
+  return NaN;
+}

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

@@ -16,3 +16,38 @@ export function categoryName(value: unknown): string {
   const name = (value as { name?: unknown }).name;
   return typeof name === "string" ? name.trim() : "";
 }
+
+import { zoneOffsetAt } from "./engine-intl.js";
+
+const HAS_OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+const LOCAL_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?/;
+
+/** The instant (ms) a slot starts. Wix may list a slot's `startDate` as a LOCAL wall time with its
+ *  `timezone` beside it ("2026-11-02T18:30:00" in America/New_York is 23:30Z); a bare `Date.parse`
+ *  would read that in the device's zone. So a local time is placed in the slot's own zone when this
+ *  engine has Intl and knows the zone, and read in the device's zone only when it cannot be. */
+export function slotStartInstant(slot: { startDate?: string; timezone?: unknown }): number {
+  const start = slot.startDate ?? "";
+  if (!start) return NaN;
+  const local = LOCAL_TIME.exec(start);
+  if (HAS_OFFSET.test(start) || !local || typeof slot.timezone !== "string" || !slot.timezone) return Date.parse(start);
+  const wall = Date.UTC(+local[1], +local[2] - 1, +local[3], +local[4], +local[5], +(local[6] ?? 0));
+  const offset = zoneOffsetAt(wall, slot.timezone);
+  if (!Number.isFinite(offset)) return Date.parse(start);
+  // Once more at the corrected instant, so a wall time beside a DST change lands on the right side.
+  const again = zoneOffsetAt(wall - offset, slot.timezone);
+  return wall - (Number.isFinite(again) ? again : offset);
+}
+
+/** The slot a host asked to open at (`himi_time` input `start`, an ISO 8601 instant): the id of the
+ *  slot that starts at that same instant, or "" when none does (taken since, or out of the window).
+ *  Compared as instants, so `…T16:30:00Z` finds a slot listed as `…T18:30:00+02:00`, or as a local
+ *  `…T18:30:00` beside `timezone: "Asia/Jerusalem"`. */
+export function slotIdAt(slots: Iterable<[string, { startDate?: string; timezone?: unknown }]>, start: string): string {
+  const at = start ? Date.parse(start) : NaN;
+  if (!Number.isFinite(at)) return "";
+  for (const [id, slot] of slots) {
+    if (slotStartInstant(slot) === at) return id;
+  }
+  return "";
+}

package/templates/beauty-salon/tier5-src/_shared/host-events.ts

@@ -1,26 +1,65 @@
 // Host events — what a member screen tells the app hosting it about something the member did
-// (a booking confirmed), so a host such as Symphony can say so in its chat and refresh what it shows.
+// (a booking confirmed or cancelled), so a host such as Symphony can say so in its chat and refresh
+// what it shows.
 //
 // A worker dispatches `host.event` with `{ type, ...fields }` (string values only: a dispatch carries
 // one string params map). An embed (`HimalayaEmbed`) hands it to the host's `onAction` as an action
 // with that id; anywhere else nothing handles it and it is dropped. It is a notice, never a request:
 // the host owns what happens next, and the worker never waits on it or depends on its answer.
+//
+// The contract (hosts parse exactly this — Symphony's `PlaceHostEvent`):
+//   type         booking.created | booking.cancelled | plan.used
+//   serviceName  the class / service title (bookings)      planName   the plan's name (plan.used)
+//   start, end   ISO 8601 instants WITH an offset (`Z` or `+02:00`); a local time is left out
+//   remaining    sessions left on the plan, when known (a whole number)
+//   bookingId, serviceId, planId   when known
 
 import { dispatch } from "@himalaya/dispatch";
 
 export const HOST_EVENT_ACTION_ID = "host.event";
 
 /** The events a member screen reports. */
-export type HostEventType = "booking.created";
+export type HostEventType = "booking.created" | "booking.cancelled" | "plan.used";
 
-/** Tell the host about [type]. Never throws: a host that does not listen must not break the screen. */
-export async function emitHostEvent(type: HostEventType, fields: Record<string, string | undefined> = {}): Promise<void> {
+export interface HostEventFields {
+  bookingId?: string;
+  serviceId?: string;
+  serviceName?: string;
+  planId?: string;
+  planName?: string;
+  start?: string;
+  end?: string;
+  remaining?: number | string;
+}
+
+const WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i;
+
+/** [value] when it is an ISO 8601 instant that names its offset, else "". A slot's LOCAL wall time
+ *  ("2026-11-02T18:30:00") would be read in the host's zone, i.e. a wrong hour, so it is left out. */
+export function hostEventInstant(value: unknown): string {
+  return typeof value === "string" && WITH_OFFSET.test(value) && Number.isFinite(Date.parse(value)) ? value : "";
+}
+
+/** The `host.event` params for [type] and [fields]: unset and empty fields are left out, times
+ *  without an offset are left out, and `remaining` is a whole number ≥ 0 or nothing. */
+export function hostEventParams(type: HostEventType, fields: HostEventFields = {}): Record<string, string> {
   const params: Record<string, string> = { type };
   for (const [key, value] of Object.entries(fields)) {
-    if (typeof value === "string" && value !== "") params[key] = value;
+    let out = "";
+    if (key === "start" || key === "end") out = hostEventInstant(value);
+    else if (key === "remaining") {
+      const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+      out = Number.isInteger(n) && n >= 0 ? String(n) : "";
+    } else if (typeof value === "string") out = value.trim();
+    if (out) params[key] = out;
   }
+  return params;
+}
+
+/** Tell the host about [type]. Never throws: a host that does not listen must not break the screen. */
+export async function emitHostEvent(type: HostEventType, fields: HostEventFields = {}): Promise<void> {
   try {
-    await dispatch(HOST_EVENT_ACTION_ID, params);
+    await dispatch(HOST_EVENT_ACTION_ID, hostEventParams(type, fields));
   } catch {
     // Not embedded, or the host has no handler: nothing to tell.
   }

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

@@ -4,6 +4,7 @@ import { navigate } from "@himalaya/state";
 import { copyParam } from "../_shared/himi-copy.js";
 import { memberAccess, assertMemberAccess, memberAccessChanged, memberAccessDenied, type MemberAccess } from "../_shared/member-access.js";
 import { fetchMemberBookings, type MemberBookingRow } from "../_shared/member-bookings.js";
+import { emitHostEvent } from "../_shared/host-events.js";
 import { dayKey, dayLabel } from "@himalaya/time";
 import { localPreferences } from "../_shared/local-preferences.js";
 import { parseWeeklyGoal, weeklyGoalProgress, weeklySessionsFromPages } from "../_shared/weekly-goal.js";
@@ -136,6 +137,9 @@ const svc = defineBackendCollection<S, MemberBookingRow>("himiBookingBookings",
         await cancelBookingAsMember(target.row.id, target.row.revision);
         await assertMemberAccess(target.member);
         cancelTarget = undefined;
+        // Told to the app hosting this screen (an embed's `onAction`); dropped where nothing hosts it.
+        await emitHostEvent("booking.cancelled", { bookingId: target.row.id, serviceId: target.row.serviceId,
+          serviceName: target.row.title, start: target.row.start, end: target.row.end });
         await svc.refresh();
         return derive({ ...(svc.getState() as unknown as S), actionMessage: copyParam("bookings.cancelDone", "Booking cancelled.") });
       } catch (error) {

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

@@ -16,7 +16,8 @@ import { formatServicePrice, serviceIsChargeable } from "../_shared/wix-service-
 import { stashCopy, copyParam } from "../_shared/himi-copy.js";
 import { upsert as dbUpsert, remove as dbRemove, enqueue as dbEnqueue, type DbEntity } from "@himalaya/local-db";
 import { isBridgeUnavailable } from "../_shared/owner-load-error.js";
-import { emitHostEvent } from "../_shared/host-events.js";
+import { emitHostEvent, hostEventInstant } from "../_shared/host-events.js";
+import { slotIdAt } from "../_shared/himi-bookings.js";
 import { wixMediaUrl, WIX_DETAIL_IMAGE } from "@himalaya/wix-media";
 
 // Offline-first (data-offline): booking a slot is WRITE-BEHIND against the
@@ -147,12 +148,23 @@ function inputId(): string {
   // `id` nav param (himi.open { screenId: "himi_time", id }) into worker input.
   // The screenId-slice below is #570 back-compat for pre-params releases with
   // baked `himi_time_<id>` screenIds — do not author against this.
-  const input = (globalThis as { himalaya?: { input?: { id?: unknown; screenId?: unknown } } }).himalaya?.input;
+  // `serviceId` is the same thing under the name a HOST uses to open this screen (the deep-entry
+  // contract: Branded Lite README, "Opening at a booking").
+  const input = (globalThis as { himalaya?: { input?: { id?: unknown; serviceId?: unknown; screenId?: unknown } } }).himalaya?.input;
   if (typeof input?.id === "string" && input.id) return input.id;
+  if (typeof input?.serviceId === "string" && input.serviceId) return input.serviceId;
   const screenId = typeof input?.screenId === "string" ? input.screenId : "";
   return screenId.startsWith("himi_time_") ? screenId.slice("himi_time_".length) : "";
 }
 
+/** The time a host opened this screen at (`himalaya.input.start`, ISO 8601), or "". Every load
+ *  preselects that slot (or opens on its day) until the member picks a day or a time themselves —
+ *  not just the first, because the boot load and the screen's own `load` can overlap. */
+let pendingStart = (() => {
+  const start = (globalThis as { himalaya?: { input?: { start?: unknown } } }).himalaya?.input?.start;
+  return typeof start === "string" && Number.isFinite(Date.parse(start)) ? start : "";
+})();
+
 function strOf(arg: unknown): string {
   if (typeof arg === "string") return arg;
   const a = arg as { value?: string; text?: string } | undefined;
@@ -534,15 +546,20 @@ const svc = defineService<S, {
         const days = daysOf(rows);
         // Keep the customer's day across a reload when it still has times;
         // otherwise open on the first day that has any.
+        // A host's `start` (deep entry): that slot preselected, or — taken since — its day.
+        const wantedStart = pendingStart;
+        const startRow = wantedStart ? rows.find((r) => r.id === slotIdAt(slotsById, wantedStart)) : undefined;
+        // The requested day even with no time left on it: "taken since" opens there, nothing selected.
+        const startDay = wantedStart ? days.find((d) => d.id === dayKey(wantedStart)) : undefined;
         const keep = days.find((d) => d.id === next.selectedDay && d.hasSlots);
-        const initialDay = keep?.id ?? days.find((d) => d.hasSlots)?.id ?? days[0]?.id ?? "";
-        const selectionAlive = slotsById.has(next.selectedSlotId);
+        const initialDay = startRow?.dayKey ?? startDay?.id ?? keep?.id ?? days.find((d) => d.hasSlots)?.id ?? days[0]?.id ?? "";
+        const selectionAlive = !!startRow || slotsById.has(next.selectedSlotId);
         const header = serviceHeaderFields(serviceRes.service);
         return derive(withDay({
           ...next,
           days,
-          selectedSlotId: selectionAlive ? next.selectedSlotId : "",
-          selectedLine: selectionAlive ? next.selectedLine : "",
+          selectedSlotId: startRow ? startRow.id : selectionAlive ? next.selectedSlotId : "",
+          selectedLine: startRow ? [startRow.day, startRow.title, startRow.subtitle].filter(Boolean).join(" · ") : selectionAlive ? next.selectedLine : "",
           status: "ready",
           errored: false,
           serviceName: serviceRes.service?.name || copyParam("time.serviceNameFallback", "Choose a time"),
@@ -567,6 +584,7 @@ const svc = defineService<S, {
     selectDay: (s, arg) => {
       const day = chosenDay(arg);
       if (!day || !s.days.some((d) => d.id === day)) return derive(s);
+      pendingStart = "";
       return derive(withDay(s, day));
     },
     refreshMember: (s, arg) => { stashCopy(arg); return probeMember(s); },
@@ -575,6 +593,7 @@ const svc = defineService<S, {
         ? arg
         : ((arg as { id?: string; slotId?: string })?.slotId ?? (arg as { id?: string })?.id ?? "");
       const selected = allRows.find((slot) => slot.id === slotId);
+      if (selected) pendingStart = "";
       return derive({
         ...s,
         selectedSlotId: selected ? slotId : s.selectedSlotId,
@@ -638,12 +657,14 @@ const svc = defineService<S, {
       if (!slot) return derive({ ...s, message: copyParam("time.bookSlotGone", "That time is no longer available. Try again.") });
       // A confirmed booking is reported to the app hosting this screen (an embed's `onAction`), so a
       // host chat can say so and refresh what it shows. Dropped where nothing hosts the screen.
-      const reportBooked = (bookingId: string | undefined) => emitHostEvent("booking.created", {
-        bookingId,
+      // The booking's own instants carry an offset; a slot's may be LOCAL to its timezone, which
+      // `emitHostEvent` leaves out rather than let the host read it in its own zone.
+      const reportBooked = (booking: { id?: string; startDate?: string; endDate?: string } | undefined) => emitHostEvent("booking.created", {
+        bookingId: booking?.id,
         serviceId: s.id,
         serviceName: s.serviceName,
-        start: slot.startDate,
-        end: slot.endDate,
+        start: hostEventInstant(booking?.startDate) || slot.startDate,
+        end: hostEventInstant(booking?.endDate) || slot.endDate,
       });
       // PAID service — FULLY NATIVE in-app payment (mirrors Wix's RN apps): NO
       // hosted-checkout WebView / browser redirect. The chain is
@@ -679,7 +700,7 @@ const svc = defineService<S, {
           const orderRes = hosted ? { paymentGatewayOrderId: "" } : await createOrder(checkoutId);
           const snapshotId = orderRes.paymentGatewayOrderId ?? "";
           if (!snapshotId && !hosted) {
-            await reportBooked(bookingId);
+            await reportBooked(created.booking);
             return derive({ ...pending, bookingInFlight: false, successMessage: copyParam("time.successMessage", "Booked. Your confirmation is ready in My Bookings."), message: "" });
           }
           // 4. Collect payment IN-APP — wallet when this app has one wired, otherwise
@@ -701,7 +722,7 @@ const svc = defineService<S, {
             },
           });
           if (pay.kind === "paid") {
-            await reportBooked(bookingId);
+            await reportBooked(created.booking);
             return derive({ ...pending, bookingInFlight: false, successMessage: copyParam("time.successMessage", "Booked. Your confirmation is ready in My Bookings."), message: "" });
           }
           if (pay.kind === "handoff") {
@@ -740,7 +761,7 @@ const svc = defineService<S, {
         // Reconcile the optimistic local id with the server-assigned booking id.
         const realId = created.booking?.id;
         if (realId && realId !== localId) { await cacheDrop(localId); await cachePut(localRow(realId)); }
-        await reportBooked(realId);
+        await reportBooked(created.booking);
         return derive({
           ...pending,
           bookingInFlight: false,

package/templates/beauty-salon-owner/tier5-src/_shared/engine-intl.ts

@@ -444,3 +444,24 @@ export function calendarDay(date: Date, timeZone?: string): string {
   }
   return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
 }
+
+/**
+ * [timeZone]'s offset from UTC in ms at instant [at] (Asia/Jerusalem in winter: 7_200_000), or NaN
+ * where it cannot be known — no ECMA-402 (the wrist engines) or a zone this engine does not know.
+ * Callers fall back to the device zone on NaN, as the formatters above do.
+ */
+export function zoneOffsetAt(at: number, timeZone: string): number {
+  if (hasIntl() && Number.isFinite(at)) {
+    try {
+      const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", second: "2-digit",
+      }).formatToParts(new Date(at));
+      const n = (type: string) => Number(parts.find((p) => p.type === type)?.value);
+      return Date.UTC(n("year"), n("month") - 1, n("day"), n("hour") % 24, n("minute"), n("second")) - at;
+    } catch {
+      /* a zone this engine does not know: NaN below */
+    }
+  }
+  return NaN;
+}

package/templates/branded-lite/tier5-src/_shared/engine-intl.ts

@@ -444,3 +444,24 @@ export function calendarDay(date: Date, timeZone?: string): string {
   }
   return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
 }
+
+/**
+ * [timeZone]'s offset from UTC in ms at instant [at] (Asia/Jerusalem in winter: 7_200_000), or NaN
+ * where it cannot be known — no ECMA-402 (the wrist engines) or a zone this engine does not know.
+ * Callers fall back to the device zone on NaN, as the formatters above do.
+ */
+export function zoneOffsetAt(at: number, timeZone: string): number {
+  if (hasIntl() && Number.isFinite(at)) {
+    try {
+      const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", second: "2-digit",
+      }).formatToParts(new Date(at));
+      const n = (type: string) => Number(parts.find((p) => p.type === type)?.value);
+      return Date.UTC(n("year"), n("month") - 1, n("day"), n("hour") % 24, n("minute"), n("second")) - at;
+    } catch {
+      /* a zone this engine does not know: NaN below */
+    }
+  }
+  return NaN;
+}

package/templates/branded-lite/tier5-src/_shared/himi-bookings.ts

@@ -16,3 +16,38 @@ export function categoryName(value: unknown): string {
   const name = (value as { name?: unknown }).name;
   return typeof name === "string" ? name.trim() : "";
 }
+
+import { zoneOffsetAt } from "./engine-intl.js";
+
+const HAS_OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+const LOCAL_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?/;
+
+/** The instant (ms) a slot starts. Wix may list a slot's `startDate` as a LOCAL wall time with its
+ *  `timezone` beside it ("2026-11-02T18:30:00" in America/New_York is 23:30Z); a bare `Date.parse`
+ *  would read that in the device's zone. So a local time is placed in the slot's own zone when this
+ *  engine has Intl and knows the zone, and read in the device's zone only when it cannot be. */
+export function slotStartInstant(slot: { startDate?: string; timezone?: unknown }): number {
+  const start = slot.startDate ?? "";
+  if (!start) return NaN;
+  const local = LOCAL_TIME.exec(start);
+  if (HAS_OFFSET.test(start) || !local || typeof slot.timezone !== "string" || !slot.timezone) return Date.parse(start);
+  const wall = Date.UTC(+local[1], +local[2] - 1, +local[3], +local[4], +local[5], +(local[6] ?? 0));
+  const offset = zoneOffsetAt(wall, slot.timezone);
+  if (!Number.isFinite(offset)) return Date.parse(start);
+  // Once more at the corrected instant, so a wall time beside a DST change lands on the right side.
+  const again = zoneOffsetAt(wall - offset, slot.timezone);
+  return wall - (Number.isFinite(again) ? again : offset);
+}
+
+/** The slot a host asked to open at (`himi_time` input `start`, an ISO 8601 instant): the id of the
+ *  slot that starts at that same instant, or "" when none does (taken since, or out of the window).
+ *  Compared as instants, so `…T16:30:00Z` finds a slot listed as `…T18:30:00+02:00`, or as a local
+ *  `…T18:30:00` beside `timezone: "Asia/Jerusalem"`. */
+export function slotIdAt(slots: Iterable<[string, { startDate?: string; timezone?: unknown }]>, start: string): string {
+  const at = start ? Date.parse(start) : NaN;
+  if (!Number.isFinite(at)) return "";
+  for (const [id, slot] of slots) {
+    if (slotStartInstant(slot) === at) return id;
+  }
+  return "";
+}