@wix/himalaya-cli 0.1487.0 → 0.1489.0

package/templates/branded-lite/tier5-src/himi-branded-lite-agenda/index.ts

@@ -0,0 +1,769 @@
+// himi-branded-lite-agenda — the Bookings Agenda: every upcoming CLASS session of the site,
+// under a collapsible week/month calendar.
+//
+// Everyone sees the whole schedule. A signed-in member also sees their own place in it: a
+// session they booked reads "Booked", one they wait for reads "On waitlist", and each opens
+// a sheet to view the session or cancel / leave. A full session with waitlist room offers
+// "Waitlist"; a full one without, or one outside the booking window, says so instead of
+// offering a Book that would fail.
+//
+// Appointment services are left out on purpose: their availability is every free slot of
+// the day, which is a booking grid, not an agenda of things that happen. Courses are left out
+// too: a course is booked as a whole, never one session, and Wix serves its sessions through
+// the course flow rather than the class availability this screen reads.
+//
+// The calendar marks every day with a session (one dot) and today (its own ring). The list
+// starts at the selected day, so a day with nothing on it shows the next sessions instead
+// of an empty page — the agenda answers "what is on from here".
+import { defineService, navigate } from "@himalaya/state";
+import { addDays, dayKey, toDate, weekOf, type DayDecoration, type Weekday } from "@himalaya/time";
+import {
+  cancelBookingAsMember, isBookingPolicyViolation, leaveWaitlist, listWaitlists, queryBookings, queryServiceAvailability,
+  queryServices, registerToWaitlist, type WixAvailabilityEntry, type WixBooking, type WixService,
+} from "@himalaya/wix-bookings";
+import { getMyMember } from "@himalaya/wix-members";
+import { LOADING, loadFailed, type LoadFlags } from "../_shared/branded-load-state.js";
+import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
+import { slotStartInstant } from "../_shared/himi-bookings.js";
+import { compareText } from "../_shared/engine-intl.js";
+import { assertMemberAccess, memberAccess, memberAccessChanged, type MemberAccess } from "../_shared/member-access.js";
+import { atLeast } from "../_shared/member-account-routes.js";
+import { get as getAppInfo } from "@himalaya/app-info";
+
+/** How far past the selected day the list reaches. */
+export const AGENDA_DAYS = 28;
+/** Services whose sessions are fixed events, each booked on its own. */
+const SESSION_TYPES = new Set(["CLASS"]);
+/** A booking in one of these no longer holds a place. */
+const RELEASED = new Set(["CANCELED", "CANCELLED", "DECLINED"]);
+
+export type Place = "booked" | "waitlisted" | "";
+
+/** One session as the screen needs it. `key` is the row's identity: the Wix session id when the
+ *  entry has one — two sessions of a class at the same time are two rows — else service + start. */
+export interface Session {
+  key: string;
+  /** The Wix session id — what a waitlist registers against. "" when the entry has none. */
+  sessionId: string;
+  serviceId: string;
+  title: string;
+  start: string; // ISO instant with offset
+  end: string;
+  day: string; // LOCAL day key
+  staff: string;
+  location: string;
+  total: number;
+  open: number;
+  bookable: boolean;
+  /** The session's waitlist: its size (0 = it has none) and the places left on it. */
+  waitlistTotal: number;
+  /** A booking policy closes it (too early, too late, online booking off): no Book, no Waitlist. */
+  policyClosed: boolean;
+  waitlistOpen: number;
+}
+
+export interface MemberPlace { bookingId: string; revision: string; place: Place; registrationId?: string; confirmed?: boolean }
+
+const count = (v: unknown): number => {
+  const n = Number(v ?? 0);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+};
+
+/** The `Agenda` wire shape: declared fields plus a flat string `extra` map for the row. */
+export interface AgendaEvent {
+  id: string;
+  title: string;
+  start: string;
+  end: string;
+  extra: Record<string, string>;
+}
+
+interface S extends LoadFlags {
+  firstWeekday: number;
+  today: string;
+  selectedDate: string;
+  rangeStart: string;
+  rangeEnd: string;
+  decorations: DayDecoration[];
+  events: AgendaEvent[];
+  scrollTo: string;
+  emptyText: string;
+  message: string;
+  signedIn: boolean;
+  /** An older Android binary: its Agenda drops each row's fields, so the list is replaced by a
+   *  line asking to update. */
+  updateRequired: boolean;
+  /** The list is hidden while loading or failed, and when an update is required. */
+  listHidden: boolean;
+  // The session sheet (Booked / On waitlist).
+  sheetOpen: boolean;
+  sheetTitle: string;
+  sheetWhen: string;
+  sheetHideCancel: boolean;
+  sheetHideLeave: boolean;
+  sheetBusy: boolean;
+}
+
+const flag = (on: boolean): string => (on ? "true" : "");
+
+/** "14:30" in the device's 24h/12h convention-neutral form the reference uses. */
+function clock(iso: string): string {
+  const d = toDate(iso);
+  if (!d) return "";
+  return `${d.getHours()}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+/** "(1h)", "(30m)", "(1h 30m)" — the length under the time. */
+export function lengthLabel(start: string, end: string): string {
+  const mins = Math.round((Date.parse(end) - Date.parse(start)) / 60_000);
+  if (!Number.isFinite(mins) || mins <= 0) return "";
+  const h = Math.floor(mins / 60), m = mins % 60;
+  const body = h && m
+    ? copyTemplate("agenda.lengthHoursMinutes", "{h}h {m}m", { h, m })
+    : h ? copyTemplate("agenda.lengthHours", "{h}h", { h }) : copyTemplate("agenda.lengthMinutes", "{m}m", { m });
+  return `(${body})`;
+}
+
+/** A slot's instant as an ISO string WITH an offset — iOS parses wire dates strictly. */
+function instantIso(slot: { startDate?: string; timezone?: unknown }, field: "startDate" | "endDate"): string {
+  const ms = slotStartInstant({ startDate: (slot as Record<string, unknown>)[field] as string | undefined, timezone: slot.timezone });
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : "";
+}
+
+export const sessionKey = (serviceId: string, startIso: string): string => `${serviceId}|${Date.parse(startIso)}`;
+
+/** A raw availability entry → a Session, or null when it has no usable start. */
+export function sessionOf(entry: WixAvailabilityEntry, service: WixService): Session | null {
+  const slot = (entry.slot ?? {}) as Record<string, unknown> & { startDate?: string; endDate?: string; timezone?: unknown };
+  const start = instantIso(slot, "startDate");
+  if (!start) return null;
+  const end = instantIso(slot, "endDate") || start;
+  const raw = entry as unknown as {
+    totalSpots?: number; openSpots?: number; waitingList?: { totalSpots?: number; openSpots?: number };
+    bookingPolicyViolations?: { tooEarlyToBook?: boolean; tooLateToBook?: boolean; bookOnlineDisabled?: boolean };
+  };
+  const policy = raw.bookingPolicyViolations;
+  const resource = slot.resource as { name?: string } | undefined;
+  const location = slot.location as { name?: string; formattedAddress?: string } | undefined;
+  const serviceId = String(slot.serviceId ?? service.id ?? "");
+  const sessionId = typeof slot.sessionId === "string" ? slot.sessionId : "";
+  return {
+    key: sessionId || sessionKey(serviceId, start),
+    sessionId,
+    serviceId,
+    title: service.name ?? "",
+    start, end,
+    day: dayKey(start),
+    staff: resource?.name?.trim() ?? "",
+    location: (location?.name || location?.formattedAddress || "").trim(),
+    total: count(raw.totalSpots),
+    open: count(raw.openSpots),
+    bookable: entry.bookable !== false,
+    waitlistTotal: count(raw.waitingList?.totalSpots),
+    waitlistOpen: count(raw.waitingList?.openSpots),
+    policyClosed: policy?.tooEarlyToBook === true || policy?.tooLateToBook === true || policy?.bookOnlineDisabled === true,
+  };
+}
+
+/** The member's bookings in the window → their place, keyed by the booking's session id when it
+ *  names one, else by service + start. `bySession` turns that into each row's own key. */
+export function placesOf(bookings: WixBooking[], email: string): Map<string, MemberPlace> {
+  const out = new Map<string, MemberPlace>();
+  for (const b of bookings) {
+    if (!b.id || b.contactDetails?.email?.trim().toLowerCase() !== email) continue;
+    const status = (b.status || "").toUpperCase();
+    if (RELEASED.has(status)) continue;
+    const slot = b.bookedEntity?.slot;
+    const serviceId = slot?.serviceId ?? "";
+    const start = b.startDate || (slot ? instantIso(slot, "startDate") : "");
+    if (!serviceId || !start) continue;
+    // Its session when the booking names one, so a parallel session is not marked too.
+    const bookedSession = (slot as { sessionId?: unknown } | undefined)?.sessionId;
+    out.set(typeof bookedSession === "string" && bookedSession ? bookedSession : sessionKey(serviceId, start), {
+      bookingId: b.id,
+      revision: String((b as WixBooking & { revision?: string | number }).revision ?? ""),
+      place: status === "WAITING_LIST" ? "waitlisted" : "booked",
+      confirmed: status === "CONFIRMED",
+    });
+  }
+  return out;
+}
+
+/** Each session's place, under the session's own key: by its session id, else by service + start. */
+export function bySession(found: Map<string, MemberPlace>, inWindow: Session[]): Map<string, MemberPlace> {
+  const out = new Map<string, MemberPlace>();
+  for (const x of inWindow) {
+    const place = (x.sessionId ? found.get(x.sessionId) : undefined) ?? found.get(sessionKey(x.serviceId, x.start));
+    if (place) out.set(x.key, place);
+  }
+  return out;
+}
+
+/** "1/12" booked-of-capacity, or "Full". Empty when the site reports no capacity. */
+function capacityLabel(s: Session): string {
+  if (s.total <= 0) return "";
+  if (s.open <= 0) return copyParam("agenda.full", "Full");
+  return `${s.total - s.open}/${s.total}`;
+}
+
+/** One session → one Agenda row. Exactly one of the trailing states is visible. */
+export function eventOf(s: Session, place: MemberPlace | undefined): AgendaEvent {
+  const mine = place?.place ?? "";
+  const full = s.total > 0 && s.open <= 0;
+  const canBook = !mine && s.bookable && !full && !s.policyClosed;
+  // Availability is capacity AND policy: a full session the policy closes is not joinable either.
+  const canWait = !mine && full && s.waitlistOpen > 0 && !!s.sessionId && !s.policyClosed;
+  const closed = !mine && !canBook && !canWait;
+  const capacity = capacityLabel(s);
+  return {
+    id: s.key,
+    title: s.title,
+    start: s.start,
+    end: s.end,
+    extra: {
+      serviceId: s.serviceId,
+      // Choose Time opens on THIS session: two of a class can start at the same time.
+      sessionId: s.sessionId,
+      time: clock(s.start),
+      length: lengthLabel(s.start, s.end),
+      staff: s.staff ? copyTemplate("agenda.withStaff", "With {name}", { name: s.staff }) : "",
+      capacity,
+      noCapacity: flag(!capacity),
+      location: s.location,
+      noLocation: flag(!s.location),
+      hideBook: flag(!canBook),
+      hideWaitlist: flag(!canWait),
+      hideBooked: flag(mine !== "booked"),
+      hideOnWaitlist: flag(mine !== "waitlisted"),
+      hideClosed: flag(!closed),
+      closedLabel: full ? copyParam("agenda.full", "Full") : copyParam("agenda.closed", "Closed"),
+    },
+  };
+}
+
+/** The first and last cell any month grid of `day`'s month can have, padding included. */
+function monthGrid(day: string): { start: string; end: string } {
+  const d = toDate(day);
+  if (!d) return { start: day, end: day };
+  return { start: dayKey(new Date(d.getFullYear(), d.getMonth(), 1 - 6)), end: dayKey(new Date(d.getFullYear(), d.getMonth() + 1, 6)) };
+}
+
+/** One dot per day that has a session — "something is on", not how much — and the visible
+ *  days before today dimmed and unselectable: the agenda is what is still to come. */
+export function decorationsOf(sessions: Session[], today: string, rangeStart: string, rangeEnd: string): DayDecoration[] {
+  const out: DayDecoration[] = [];
+  const dimmed = new Set<string>();
+  const dim = (from: string, to: string) => {
+    for (let day = from; day && day < today && day <= to; day = dayKey(addDays(day, 1))) {
+      if (!dimmed.has(day)) { dimmed.add(day); out.push({ date: day, disabled: true }); }
+    }
+  };
+  // Bounded by the visible days: a page a year back dims its 7-42 cells, not a year.
+  dim(rangeStart, rangeEnd);
+  // And this month's grid: an older binary (no week mode) draws it on first open, while it
+  // reports nothing until the member pages.
+  dim(monthGrid(today).start, today);
+  for (const date of [...new Set(sessions.filter((s) => s.day >= today).map((s) => s.day))].sort()) out.push({ date, dotCount: 1 });
+  return out;
+}
+
+/** The days to load: the visible days (never before today) through AGENDA_DAYS past the
+ *  selected day, so the list under the calendar always has its full reach. */
+export function windowFor(today: string, rangeStart: string, rangeEnd: string, selected: string): { start: string; end: string } {
+  const start = rangeStart > today ? rangeStart : today;
+  const from = selected > today ? selected : today;
+  // Through the last cell of the selected day's month grid as well, which is what an older
+  // binary draws before it has reported any page: every dot on it is then real.
+  const end = [rangeEnd, dayKey(addDays(from, AGENDA_DAYS)), monthGrid(from).end].reduce((a, b) => (b > a ? b : a));
+  return { start, end };
+}
+
+/** Where the selection goes when the calendar pages away from it: the first day of the
+ *  page (the 1st of the titled month in month view — the grid's first cell is padding),
+ *  or today when that is on the page. A page wholly before today has no day to select (past
+ *  days are disabled), so `current` stays selected and the list keeps showing from it. */
+export function selectionForRange(today: string, rangeStart: string, rangeEnd: string, current = today): string {
+  const { first, last } = titledDays(rangeStart, rangeEnd);
+  if (today >= first && today <= last) return today;
+  return last < today ? current : first;
+}
+
+/** The days a page is about: the whole week, or a month grid's TITLED month — its padding cells
+ *  belong to the neighbouring months. */
+export function titledDays(rangeStart: string, rangeEnd: string): { first: string; last: string } {
+  let first = rangeStart;
+  let last = rangeEnd;
+  const span = Math.round((Date.parse(rangeEnd) - Date.parse(rangeStart)) / 86_400_000);
+  if (span > 7) {
+    // A month grid: its padding cells belong to the neighbouring months. Today counts only when
+    // it is in the TITLED month — a today in the trailing padding would move the selection, and
+    // with it the grid, a month forward.
+    const d = toDate(rangeStart);
+    if (d) {
+      const month = rangeStart.endsWith("-01") ? d : new Date(d.getFullYear(), d.getMonth() + 1, 1);
+      first = dayKey(month);
+      last = dayKey(new Date(month.getFullYear(), month.getMonth() + 1, 0));
+    }
+  }
+  return { first, last };
+}
+
+/** The month grid (whole weeks) of `day`'s month, as a calendar draws it. */
+function monthGridOf(day: string, firstWeekday: number): { start: string; end: string } | undefined {
+  const d = toDate(day);
+  if (!d) return undefined;
+  const fw = (((firstWeekday % 7) + 7) % 7) as Weekday;
+  const start = weekOf(new Date(d.getFullYear(), d.getMonth(), 1), fw)[0];
+  const end = weekOf(new Date(d.getFullYear(), d.getMonth() + 1, 0), fw)[6];
+  return start && end ? { start, end } : undefined;
+}
+
+/** Does the selection survive a page change? Inside the page's TITLED days, yes — a selection in a
+ *  month grid's padding belongs to the neighbouring month. Today stays selected on any page that
+ *  shows it: opening a week that straddles two months into the month holding most of it must not
+ *  move the agenda off today. */
+export function keepsSelection(cur: { today: string; selectedDate: string }, start: string, end: string): boolean {
+  const page = titledDays(start, end);
+  if (cur.selectedDate >= page.first && cur.selectedDate <= page.last) return true;
+  return !!cur.today && cur.selectedDate === cur.today && cur.today >= start && cur.today <= end;
+}
+
+// ── loading ──────────────────────────────────────────────────────────────────
+
+let services: WixService[] | null = null;
+let sessions: Session[] = [];
+let places = new Map<string, MemberPlace>();
+let loadedWindow = { start: "", end: "" };
+let member: MemberAccess | undefined;
+let sheetKey = "";
+let busy = false;
+
+async function sessionServices(): Promise<WixService[]> {
+  if (services) return services;
+  // Every page, not the first 100: a class past the first page would silently be missing. Bounded,
+  // so a misbehaving paging answer cannot loop forever.
+  const all: WixService[] = [];
+  for (let page = 0; page < 10; page++) {
+    const res = await queryServices({ query: { paging: { limit: 100, offset: page * 100 } } } as never);
+    const batch = res.services ?? [];
+    all.push(...batch);
+    if (batch.length < 100) break;
+  }
+  services = all.filter((svc) => {
+    const raw = svc as WixService & { type?: string; hidden?: boolean };
+    return !!svc.id && SESSION_TYPES.has((raw.type ?? "").toUpperCase()) && raw.hidden !== true;
+  });
+  return services;
+}
+
+/** Every session of every class service in [start, end]. Each service is its own
+ *  call — the proven single-service availability query — so one service failing (a draft,
+ *  a removed schedule) costs its own rows, never the whole agenda. */
+async function sessionsIn(start: string, end: string): Promise<Session[]> {
+  const list = await sessionServices();
+  const from = new Date(`${start}T00:00:00`).toISOString();
+  const to = new Date(`${dayKey(addDays(end, 1))}T00:00:00`).toISOString();
+  const settled = await Promise.allSettled(list.map((svc) => queryServiceAvailability(svc.id, from, to, { bookable: false })));
+  const failures = settled.filter((r) => r.status === "rejected").length;
+  if (list.length && failures === list.length) throw (settled[0] as PromiseRejectedResult).reason;
+  const out: Session[] = [];
+  settled.forEach((r, i) => {
+    if (r.status !== "fulfilled") return;
+    for (const entry of r.value.availabilityEntries ?? []) {
+      const session = sessionOf(entry, list[i]);
+      if (session) out.push(session);
+    }
+  });
+  const seen = new Set<string>();
+  return out
+    .filter((s) => (seen.has(s.key) ? false : (seen.add(s.key), true)))
+    .sort((a, b) => Date.parse(a.start) - Date.parse(b.start) || compareText(a.title, b.title));
+}
+
+/** Mark the places that are WAITLIST registrations, with the registration id leaving needs.
+ *  A registration's booking is an ordinary pending booking, so the booking alone cannot say
+ *  "on the waitlist" — only the session's waitlist can, and only sessions with one are asked. */
+export function markWaitlisted(found: Map<string, MemberPlace>, sessionsByKey: Map<string, Session>, lists: { waitingResource?: string; registrations?: { id?: string; bookingId?: string }[] }[]): void {
+  const byBooking = new Map<string, string>();
+  for (const list of lists) for (const r of list.registrations ?? []) if (r.bookingId && r.id) byBooking.set(r.bookingId, r.id);
+  for (const [key, place] of found) {
+    const registrationId = byBooking.get(place.bookingId);
+    if (registrationId && sessionsByKey.has(key)) found.set(key, { ...place, place: "waitlisted", registrationId });
+  }
+}
+
+/** The signed-in member's bookings in the window, with the member they were read for: the two
+ *  are committed together, so a write checks against the member its place belongs to. A visitor
+ *  has none; a read that fails fails the load. */
+async function placesIn(start: string, end: string, inWindow: Session[], attempt = 0): Promise<{ who: MemberAccess | undefined; found: Map<string, MemberPlace> }> {
+  const who = await memberAccess().catch(() => undefined);
+  if (!who?.email) return { who, found: new Map() };
+  try {
+    const from = new Date(`${start}T00:00:00`).toISOString();
+    const to = new Date(`${dayKey(addDays(end, 1))}T00:00:00`).toISOString();
+    // Every page, not the first 100: a booking past it would read Book again. Bounded.
+    const bookings: WixBooking[] = [];
+    for (let page = 0; page < 5; page++) {
+      const res = await queryBookings({ query: { filter: { "contactDetails.email": { $eq: who.email }, startDate: { $gte: from, $lt: to } }, paging: { limit: 100, offset: page * 100 } } } as never);
+      const batch = res.bookings ?? [];
+      bookings.push(...batch);
+      if (batch.length < 100) break;
+    }
+    // The same member still? A sign-out or a switch during the read must not paint one member's
+    // bookings for another (the shared member-bookings read checks the same way).
+    await assertMemberAccess(who);
+    const found = bySession(placesOf(bookings, who.email), inWindow);
+    const byKey = new Map(inWindow.map((x) => [x.key, x] as const));
+    const waitlisted = [...found.keys()].map((k) => byKey.get(k)).filter((x): x is Session => !!x && x.waitlistTotal > 0 && !!x.sessionId);
+    if (waitlisted.length) {
+      // Only the session's waitlist can tell a waitlist place from a pending booking. If it cannot
+      // be read, that place is neither Booked nor free: the load fails (error state, Retry) rather
+      // than offer Book or Waitlist on a session the member already holds.
+      markWaitlisted(found, byKey, (await listWaitlists(waitlisted.map((x) => x.sessionId))).list ?? []);
+      // The lookup awaited too: still the same member?
+      await assertMemberAccess(who);
+    }
+    return { who, found };
+  } catch (err) {
+    // A failed read is not "no bookings": showing Book on a session the member holds invites a
+    // duplicate. It fails the load (the error state, with Retry), as My Bookings does.
+    if ((err as { name?: string } | null)?.name !== "MemberAccessChanged") throw err;
+    // A sign-out or a switch during the read: read again, for whoever is signed in now — never
+    // commit them with places nobody read for them. A second switch fails the load.
+    if (attempt < 1) return placesIn(start, end, inWindow, attempt + 1);
+    throw err;
+  }
+}
+
+/** Is `owner` — the member a place was loaded for — still the one signed in, to the same account
+ *  and business? Asked right before a write, so a sign-out or a switch since the load never
+ *  writes for the wrong person. */
+async function sameMember(owner: MemberAccess | undefined): Promise<boolean> {
+  if (!owner?.email) return false;
+  return assertMemberAccess(owner).then(() => true, () => false);
+}
+
+/** The member's name for a waitlist registration, when their member record has one. The
+ *  email alone registers; the name is what the business sees on its waitlist. */
+async function memberName(): Promise<{ firstName?: string; lastName?: string }> {
+  // A failed profile read registers by email alone rather than failing the join.
+  const res = await getMyMember({ fieldsets: ["FULL"] }).catch(() => undefined);
+  const contact = res?.member?.contact as { firstName?: string; lastName?: string } | undefined;
+  return { firstName: contact?.firstName || undefined, lastName: contact?.lastName || undefined };
+}
+
+/** Rebuild everything the screen reads from the module state. */
+function derive(s: S): S {
+  const events = rowsOk === false ? [] : sessions.filter((x) => x.day >= s.selectedDate).map((x) => eventOf(x, places.get(x.key)));
+  const sheet = sessions.find((x) => x.key === sheetKey);
+  const sheetPlace = sheet ? places.get(sheet.key)?.place ?? "" : "";
+  return {
+    ...s,
+    decorations: decorationsOf(sessions, s.today, s.rangeStart, s.rangeEnd),
+    events,
+    scrollTo: events[0] ? dayKey(events[0].start) : "",
+    emptyText: copyParam("agenda.emptyText", "No classes from this day on."),
+    // The only thing an update-required screen says: no tap or page clears it.
+    ...(rowsOk === false ? { message: copyParam("agenda.updateRequired", "Update the app to see the class schedule.") } : {}),
+    signedIn: !!member?.email,
+    updateRequired: rowsOk === false,
+    listHidden: s.busy === true || rowsOk === false,
+    sheetOpen: !!sheet && !!sheetPlace,
+    sheetTitle: sheet?.title ?? "",
+    sheetWhen: sheet ? `${clock(sheet.start)} ${lengthLabel(sheet.start, sheet.end)}`.trim() : "",
+    sheetHideCancel: sheetPlace !== "booked",
+    sheetHideLeave: sheetPlace !== "waitlisted",
+    sheetBusy: busy,
+  };
+}
+
+/** Leave a waitlist. The registration id comes from the load; a place known only by its
+ *  WAITING_LIST status asks the session's waitlist for it, and a registration Wix no longer lists
+ *  is released through the member cancel of its booking. */
+async function leave(place: MemberPlace, session: Session, owner: MemberAccess | undefined): Promise<void> {
+  let registrationId = place.registrationId ?? "";
+  if (!registrationId && session.sessionId) {
+    const lists = await listWaitlists([session.sessionId]);
+    for (const list of lists.list ?? []) {
+      for (const r of list.registrations ?? []) if (r.bookingId === place.bookingId && r.id) registrationId = r.id;
+    }
+    // The lookup awaited: still the member the place belongs to?
+    if (!(await sameMember(owner))) throw memberAccessChanged();
+  }
+  if (registrationId && session.sessionId) await leaveWaitlist(registrationId, session.sessionId);
+  else await cancelBookingAsMember(place.bookingId, place.revision);
+}
+
+/** The first runtime whose Android Agenda keeps a worker-bound event's `extra` — every field a row
+ *  shows, and every flag that hides its other actions. An older Android binary would draw each
+ *  row blank with all its actions at once, so it is asked to update instead. Checked at run time,
+ *  not as a descriptor floor: a release takes its highest screen floor as its own. */
+export const AGENDA_MIN_ANDROID_BINARY = "1.6.0";
+let rowsOk: boolean | undefined;
+async function rowsSupported(): Promise<boolean> {
+  const info = await getAppInfo().catch(() => undefined);
+  if (!info || info.platform !== "android") return true;
+  return atLeast(info.binaryVersion, AGENDA_MIN_ANDROID_BINARY);
+}
+
+const READY = { status: "ready" as const, error: "", signInRequired: false, notErrored: true, notLoading: true, busy: false, noSignIn: true };
+
+type View = Pick<S, "today" | "rangeStart" | "rangeEnd" | "selectedDate" | "firstWeekday">;
+/** The page and day the member asked for LAST. Every action records it before its first await,
+ *  so a read that lands after a newer page or day tap shows that view, not the one it started
+ *  from — paging back before the forward read lands must end on the user's last page. */
+let wanted: View | undefined;
+
+/** Record what the member asked for and return the state that shows it. */
+function ask(s: S, view: Partial<View>): S {
+  wanted = { ...(wanted ?? { today: s.today, rangeStart: s.rangeStart, rangeEnd: s.rangeEnd, selectedDate: s.selectedDate, firstWeekday: s.firstWeekday }), ...view };
+  // The initial state carries no date; an action that lands before `load` still needs today.
+  if (!wanted.today) wanted = { ...wanted, today: dayKey(new Date()) };
+  return { ...s, ...wanted };
+}
+
+const covers = (win: { start: string; end: string }, need: { start: string; end: string }): boolean =>
+  !!win.start && win.start <= need.start && win.end >= need.end;
+const needOf = (s: S) => windowFor(s.today, s.rangeStart, s.rangeEnd, s.selectedDate);
+
+/** Bumped by every READ: a read that a newer read overtook stands down (returns `undefined`), and
+ *  the newer one commits. An action the loaded days already cover reads nothing and bumps nothing,
+ *  so a day tap never discards a reload in flight. */
+let loadSeq = 0;
+
+/** Load the window the state needs, unless it is already loaded. `force` reloads it (the
+ *  screen re-appeared: the member may have just booked on the Choose Time screen). Resolves to
+ *  `undefined` when a newer read started while this one awaited. */
+async function ensureLoaded(base: S, force = false): Promise<S | undefined> {
+  const s = { ...base, ...wanted };
+  if (rowsOk === false) return derive(s);
+  const need = needOf(s);
+  // Days already loaded mean the last read succeeded (a failure clears them), so the screen is
+  // ready — whatever the state this action was dispatched with still said: a calendar's first
+  // page report can finish its read while `load`, dispatched with "loading", still waits.
+  if (covers(loadedWindow, need) && !force) return derive({ ...s, ...READY });
+  const seq = ++loadSeq;
+  const win = covers(loadedWindow, need) ? loadedWindow : need;
+  try {
+    const nextSessions = await sessionsIn(win.start, win.end);
+    const { who, found: nextPlaces } = await placesIn(win.start, win.end, nextSessions);
+    if (seq !== loadSeq) return undefined;
+    const now = { ...s, ...wanted };
+    if (!covers(win, needOf(now))) {
+      // The member paged past what this read covers while it ran. The days already loaded may
+      // cover where they are now (they paged back); otherwise read those.
+      return covers(loadedWindow, needOf(now)) ? derive({ ...now, ...READY }) : ensureLoaded(now);
+    }
+    sessions = nextSessions;
+    places = nextPlaces;
+    member = who;
+    loadedWindow = win;
+    return derive({ ...now, ...READY, message: "" });
+  } catch (err) {
+    if (seq !== loadSeq) return undefined;
+    const now = { ...s, ...wanted };
+    // The member paged back to days already loaded while this read failed: those still stand.
+    if (!covers(win, needOf(now)) && covers(loadedWindow, needOf(now))) return derive({ ...now, ...READY });
+    // Only the flags: the schedule is not a row collection, and a failed load keeps no rows.
+    const { sessions: _rows, emptyText: _empty, ...flags } = loadFailed("sessions", err, {
+      prefix: "agenda",
+      empty: "No classes from this day on.",
+      error: "The schedule couldn't be loaded.",
+      signIn: "Sign in to see the schedule.",
+      sample: () => [] as Session[],
+    });
+    sessions = [];
+    places = new Map();
+    loadedWindow = { start: "", end: "" };
+    return derive({ ...now, ...flags });
+  }
+}
+
+function argOf(p: unknown, key: string): string {
+  const a = p as Record<string, unknown> | undefined;
+  const v = a?.[key] ?? (a?.args as Record<string, unknown> | undefined)?.[key] ?? (a?.params as Record<string, unknown> | undefined)?.[key];
+  // Numbers too: every renderer sends onMonthChange's year/month as numbers.
+  return typeof v === "string" ? v.trim() : typeof v === "number" && Number.isFinite(v) ? String(v) : "";
+}
+
+const eventIdOf = (p: unknown): string => argOf(p, "eventId") || argOf(p, "id");
+
+/** Clock-free, so a template builds to the same release every time: `load` — or the
+ *  first `ask` before it — fills in today and this week. */
+function initial(): S {
+  return {
+    ...LOADING, firstWeekday: 0, today: "", selectedDate: "", rangeStart: "", rangeEnd: "",
+    decorations: [], events: [], scrollTo: "", emptyText: "", message: "", signedIn: false, updateRequired: false, listHidden: true,
+    sheetOpen: false, sheetTitle: "", sheetWhen: "", sheetHideCancel: true, sheetHideLeave: true, sheetBusy: false,
+  };
+}
+
+const svc = defineService<S, {
+  load: (s: S, p?: unknown) => Promise<S | undefined>;
+  retry: (s: S) => Promise<S | undefined>;
+  selectDate: (s: S, p?: unknown) => Promise<S | undefined>;
+  rangeChanged: (s: S, p?: unknown) => Promise<S | undefined>;
+  monthChanged: (s: S, p?: unknown) => Promise<S | undefined>;
+  openSheet: (s: S, p?: unknown) => S;
+  closeSheet: (s: S) => S;
+  viewSession: (s: S) => S;
+  cancelBooking: (s: S) => Promise<S | undefined>;
+  joinWaitlist: (s: S, p?: unknown) => Promise<S | undefined>;
+}>("himiBrandedAgenda", {
+  state: initial(),
+  actions: {
+    load: async (s, p) => {
+      stashCopy(p);
+      const fw = Number(argOf(p, "firstWeekday") || s.firstWeekday);
+      const today = dayKey(new Date());
+      // First appearance: open on this week. A re-appearance keeps the member's place and
+      // reloads, so a session booked on Choose Time comes back marked "Booked".
+      // This worker has read nothing yet: open on this week. Not the state's own status — a cold
+      // boot restores the last run's snapshot ("ready", last week's page) into a fresh worker.
+      const first = !loadedWindow.start;
+      const week = weekOf(today, (((fw % 7) + 7) % 7) as Weekday);
+      // Re-read the catalog when the screen shows again: classes are added, renamed and removed.
+      if (!first) services = null;
+      const asked = first
+        ? ask(s, { firstWeekday: fw, today, selectedDate: today, rangeStart: week[0], rangeEnd: week[6] })
+        : ask(s, { firstWeekday: fw, today });
+      rowsOk ??= await rowsSupported();
+      if (!rowsOk) return derive({ ...asked, ...READY, message: copyParam("agenda.updateRequired", "Update the app to see the class schedule.") });
+      return ensureLoaded(asked, !first);
+    },
+    retry: async (s) => { services = null; return ensureLoaded({ ...s, ...LOADING }, true); },
+    // Each compares with the member's LAST ask, not `s`: a read still in flight has not put the
+    // previous page into `s` yet, and paging back to that page is still a change.
+    selectDate: async (s, p) => {
+      const date = argOf(p, "date");
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || date === (wanted ?? s).selectedDate) return s;
+      // Past days are not selectable — also before the load has dimmed them on the calendar.
+      if (date < ((wanted ?? s).today || dayKey(new Date()))) return s;
+      // A month grid's padding day (iOS draws them) belongs to the next month, and the grid moves
+      // there without reporting a page: move this page with it, so paging back is still a change.
+      const cur = wanted ?? s;
+      const span = Math.round((Date.parse(cur.rangeEnd) - Date.parse(cur.rangeStart)) / 86_400_000);
+      const page = titledDays(cur.rangeStart, cur.rangeEnd);
+      if (span > 7 && (date < page.first || date > page.last)) {
+        const grid = monthGridOf(date, s.firstWeekday);
+        if (grid) return ensureLoaded(ask({ ...s, message: "" }, { selectedDate: date, rangeStart: grid.start, rangeEnd: grid.end }));
+      }
+      return ensureLoaded(ask({ ...s, message: "" }, { selectedDate: date }));
+    },
+    rangeChanged: async (s, p) => {
+      const start = argOf(p, "startDate"), end = argOf(p, "endDate");
+      const cur = wanted ?? s;
+      if (!start || !end || (start === cur.rangeStart && end === cur.rangeEnd)) return s;
+      // The selection follows the page, so the list under the calendar describes the days
+      // on screen rather than a week the user has paged away from.
+      const keep = keepsSelection(cur, start, end);
+      const selectedDate = keep ? cur.selectedDate : selectionForRange(cur.today || dayKey(new Date()), start, end, cur.selectedDate);
+      return ensureLoaded(ask({ ...s, message: "" }, { rangeStart: start, rangeEnd: end, selectedDate }));
+    },
+    // An older binary has no week mode and reports only the month. Its grid then spans the
+    // month's whole weeks; load those, so dots still show on every visible day.
+    monthChanged: async (s, p) => {
+      const year = Number(argOf(p, "year")), month = Number(argOf(p, "month"));
+      if (!year || !month) return s;
+      const first = new Date(year, month - 1, 1);
+      const start = weekOf(first, (s.firstWeekday % 7) as Weekday)[0];
+      const last = weekOf(new Date(year, month, 0), (s.firstWeekday % 7) as Weekday)[6];
+      const cur = wanted ?? s;
+      if (!start || !last || (start === cur.rangeStart && last === cur.rangeEnd)) return s;
+      const keep = keepsSelection(cur, start, last);
+      const selectedDate = keep ? cur.selectedDate : selectionForRange(cur.today || dayKey(new Date()), start, last, cur.selectedDate);
+      return ensureLoaded(ask(s, { rangeStart: start, rangeEnd: last, selectedDate }));
+    },
+    openSheet: (s, p) => {
+      const key = eventIdOf(p);
+      if (!places.get(key)) return s;
+      sheetKey = key;
+      return derive({ ...s, message: "" });
+    },
+    closeSheet: (s) => {
+      if (busy) return s;
+      sheetKey = "";
+      return derive(s);
+    },
+    viewSession: (s) => {
+      const session = sessions.find((x) => x.key === sheetKey);
+      sheetKey = "";
+      return session ? navigate(derive(s), { screenId: "himi_service", args: { id: session.serviceId } }) : derive(s);
+    },
+    // Cancel a booking (the MEMBER cancel, so Wix enforces the business's cancellation
+    // policy), or leave a waitlist (which also releases the pending booking it created).
+    cancelBooking: async (s): Promise<S | undefined> => {
+      const place = places.get(sheetKey);
+      // Read with `place`: a reload that lands meanwhile replaces both together.
+      const owner = member;
+      const session = sessions.find((x) => x.key === sheetKey);
+      const leaving = place?.place === "waitlisted";
+      if (!place || !session || busy || (!leaving && !place.revision)) return s;
+      busy = true;
+      try {
+        if (!(await sameMember(owner))) throw memberAccessChanged();
+        if (leaving) await leave(place, session, owner);
+        else await cancelBookingAsMember(place.bookingId, place.revision);
+        places.delete(sheetKey);
+        sheetKey = "";
+        const message = leaving ? copyParam("agenda.leftWaitlist", "You left the waitlist.") : copyParam("agenda.cancelDone", "Booking cancelled.");
+        // Reload against the state as it is NOW: the member may have paged while the write ran.
+        const next = await ensureLoaded(svc.getState() as S, true);
+        busy = false;
+        return derive({ ...(next ?? { ...(svc.getState() as S), ...wanted }), message });
+      } catch (err) {
+        sheetKey = "";
+        if ((err as { name?: string } | null)?.name === "MemberAccessChanged") {
+          // Someone else (or nobody) since the load: show their schedule; nothing is cancelled.
+          const next = await ensureLoaded(svc.getState() as S, true);
+          busy = false;
+          return next ? derive(next) : undefined;
+        }
+        busy = false;
+        const message = isBookingPolicyViolation(err)
+          ? copyParam("agenda.cancelPolicy", "It's too late to cancel in the app. Contact the business.")
+          : copyParam("agenda.cancelFailed", "That didn't go through. Try again.");
+        return derive({ ...(svc.getState() as S), message });
+      }
+    },
+    joinWaitlist: async (s, p): Promise<S | undefined> => {
+      const key = eventIdOf(p);
+      const session = sessions.find((x) => x.key === key);
+      // A place already held (just joined, or booked) is never joined again.
+      if (!session || busy || places.get(key)) return s;
+      const owner = member;
+      busy = true;
+      try {
+        // One person's email and name: the member is read before AND after the name, and the
+        // registration goes out only when both reads, and the member the places were loaded for, agree.
+        const before = await memberAccess().catch(() => undefined);
+        if (!before?.email) {
+          busy = false;
+          return navigate(s, { screenId: "himi_sign_in", args: { mode: "signin", returnScreenId: "himi_agenda" } });
+        }
+        const name = await memberName();
+        const current = await memberAccess().catch(() => undefined);
+        const same = (a: MemberAccess | undefined, b: MemberAccess | undefined) => !!a?.email && a.email === b?.email && a.scope === b?.scope;
+        if (!same(before, current) || !same(owner, current)) {
+          // Another member since the load — or the load was a visitor's, so their places were never
+          // read: show their schedule first; nothing is registered.
+          const next = await ensureLoaded(svc.getState() as S, true);
+          busy = false;
+          return next ? derive(next) : undefined;
+        }
+        const res = await registerToWaitlist(session.sessionId, { email: current!.email, ...name });
+        // Marked at once, so until a reload lands the row reads On waitlist and offers no second
+        // join — whether this reload commits or a newer page overtakes it.
+        places.set(key, { bookingId: res?.booking?.id ?? "", revision: "", place: "waitlisted", registrationId: res?.registrationId, confirmed: false });
+        const message = copyParam("agenda.joinedWaitlist", "You're on the waitlist.");
+        const next = await ensureLoaded(svc.getState() as S, true);
+        busy = false;
+        return derive({ ...(next ?? { ...(svc.getState() as S), ...wanted }), message });
+      } catch {
+        busy = false;
+        return derive({ ...(svc.getState() as S), message: copyParam("agenda.waitlistFailed", "Couldn't join the waitlist. Try again.") });
+      }
+    },
+  },
+});
+export { svc };