@wix/himalaya-cli 0.1614.0 → 0.1616.0

package/templates/salon-spa/tier5-src/_shared/business-chat-transport.ts

@@ -0,0 +1,148 @@
+// The business chat's Wix calls: the member-role chat-web SDK for rooms and history, plus the calls the SDKs have
+// no helper for (a typed message sent through Smart Chat, a tapped button, a private attachment's download URL).
+import { getChatToken, getMessagesPage, listChatroomsPage } from "@himalaya/wix-chat-web";
+import { assertMemberAccess, memberAccess } from "./member-access.js";
+
+const MANAGE = "https://manage.wix.com";
+const MEMBER = { role: "member" } as const;
+type Raw = Record<string, unknown>;
+type Bridge = { call(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<unknown> };
+
+/** Who is signed in. `userId` is empty until the host reports it; the chat then tells the business
+ *  side apart by the room's participant id instead. */
+export interface ChatIdentity { authenticated: boolean; userId: string; email: string; scope: string }
+export async function chatIdentity(): Promise<ChatIdentity> {
+  const member = await memberAccess();
+  return { authenticated: !!member.email, userId: "", email: member.email, scope: member.scope };
+}
+export const assertChatIdentity = (identity: ChatIdentity): Promise<void> => assertMemberAccess(identity);
+
+/** Every request is fenced: the member is re-checked before it goes out and again before its response is
+ *  used, so a sign-out or account switch mid-request never leaks one member's data to the next. */
+async function fenced<T>(identity: ChatIdentity, run: () => Promise<T>): Promise<T> {
+  await assertChatIdentity(identity);
+  const result = await run();
+  await assertChatIdentity(identity);
+  return result;
+}
+
+/** Any other member-scoped call (the AI chat's) goes through the same fence. */
+export const fence = fenced;
+
+// Minting a chat token is a network round trip, and every chat call used to mint its own. One token
+// per member is reused until the member changes or a request using it is refused.
+let cachedToken: { key: string; token: string } | null = null;
+const tokenKey = (identity: ChatIdentity): string => `${identity.email}|${identity.scope}`;
+async function chatTokenFor(identity: ChatIdentity): Promise<string> {
+  const key = tokenKey(identity);
+  if (cachedToken?.key === key) return cachedToken.token;
+  const { chatToken } = await getChatToken(MEMBER);
+  // The host mints for whoever is signed in NOW: a token minted while the member switched belongs to the
+  // new member and must not be cached under the old one.
+  await assertChatIdentity(identity);
+  cachedToken = { key, token: chatToken };
+  return chatToken;
+}
+/** Runs `run` with the member's cached token; a refused request mints a fresh token and tries once more. */
+async function withToken<T>(identity: ChatIdentity, run: (chatToken: string) => Promise<T>): Promise<T> {
+  const reused = cachedToken?.key === tokenKey(identity);
+  try {
+    return await run(await chatTokenFor(identity));
+  } catch (error) {
+    cachedToken = null;
+    if (!reused || !/\b(?:401|403)\b|token/i.test(String((error as Error)?.message ?? error))) throw error;
+    return run(await chatTokenFor(identity));
+  }
+}
+
+const MAX_ROOM_PAGES = 20;
+/** Every chatroom the member can see: the cursor is followed so the business room is found on any page. */
+export const listRooms = (identity: ChatIdentity): Promise<{ items: Raw[]; more: boolean }> => fenced(identity, async () => {
+  const items: Raw[] = [];
+  let nextPointer: number | string | undefined;
+  for (let page = 0; page < MAX_ROOM_PAGES; page++) {
+    const result = await withToken(identity, (chatToken) => listChatroomsPage({ ...MEMBER, chatToken, pageSize: 50, ...(nextPointer !== undefined ? { nextPointer } : {}) }));
+    items.push(...(result.items as unknown as Raw[]));
+    nextPointer = result.nextPointer;
+    if (nextPointer === undefined) return { items, more: false };
+  }
+  return { items, more: true };
+});
+/** How many of the member's BUSINESS chatrooms have unread messages, as the server counts them (capped at 100).
+ *  Not the rooms themselves: the header badge needs only the total. A response without a valid count is
+ *  unavailable, never zero. */
+export const unreadRoomCount = (identity: ChatIdentity): Promise<number> => fenced(identity, async () => {
+  const page = await withToken(identity, (chatToken) => listChatroomsPage({ ...MEMBER, chatToken, pageSize: 1, onlyUnread: true, participantType: "business" }));
+  const count = page.unreadChatroomCount;
+  if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) throw new Error("unavailable unread chat count");
+  return count;
+});
+export const messagesPage = (identity: ChatIdentity, roomId: string): Promise<Raw[]> => fenced(identity, async () =>
+  (await withToken(identity, (chatToken) => getMessagesPage(roomId, { ...MEMBER, chatToken, pageSize: 50, ordering: "Desc" }))).items as unknown as Raw[]);
+
+function bridge(): Bridge {
+  const api = (globalThis as unknown as { himalaya?: { wixApi?: Bridge } }).himalaya?.wixApi;
+  if (!api) throw new Error("wix_api_bridge_unavailable");
+  return api;
+}
+/** A typed message goes through Smart Chat, exactly as the site's chat widget sends it. The Inbox then files it under
+ *  Wix Smart Chat and the AI can answer it; a message posted straight into the room has no channel, so the AI never
+ *  saw it and the owner's reply went out by email. Smart Chat chooses the conversation and stored message id.
+ *  The bridge resolves once the AI has finished answering, not when the message is stored. */
+export const sendMessage = (identity: ChatIdentity, text: string): Promise<string | undefined> => fenced(identity, async () => {
+  const response = await bridge().call("POST", "/wix-assistant-widget/v1/messages/stream", {
+    message: { sender: "SITE_VISITOR", messageType: "QUESTION", body: { mainText: text } },
+  });
+  // The first stream frame names the persisted question. Keep its exact id so a send
+  // that moves from an old Members transcript to Smart Chat never relies on a text match.
+  let frames: unknown = response;
+  if (typeof frames === "string") {
+    const raw = frames;
+    try { frames = JSON.parse(raw); }
+    catch {
+      frames = [];
+      // The bridge buffers SSE verbatim. Ignore event/comment lines and decode the
+      // data of each frame; some hosts instead hand over NDJSON or parsed frames.
+      for (const block of raw.split(/\r?\n\r?\n/)) {
+        const lines = block.split(/\r?\n/);
+        const event = lines.find(line => line.startsWith('event:'))?.slice(6).trim();
+        const data = lines.filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
+        try {
+          const value = JSON.parse(data || block);
+          (frames as unknown[]).push(event === 'inputMessage' && !value?.inputMessage ? { inputMessage: value } : value);
+        } catch { /* Comments and other non-JSON frames carry no stored question id. */ }
+      }
+      // A buffered NDJSON response has no SSE separators.
+      if (!(frames as unknown[]).length) {
+        try { frames = [JSON.parse(raw.split('\n', 1)[0]!)]; } catch { return undefined; }
+      }
+    }
+  }
+  for (const frame of Array.isArray(frames) ? frames : [frames]) {
+    const input = (frame as { inputMessage?: { id?: unknown; sender?: unknown; messageType?: unknown } } | null)?.inputMessage;
+    if (input?.sender === "SITE_VISITOR" && input.messageType === "QUESTION" && typeof input.id === "string" && input.id) return `smart-chat:${input.id}`;
+  }
+  return undefined;
+});
+/** A tapped button is a silent, ephemeral message carrying the button's chat action. */
+export const sendButton = (identity: ChatIdentity, roomId: string, input: { id: string; text: string; appId: string; interactionId: string }): Promise<void> => fenced(identity, async () => {
+  await withToken(identity, (chatToken) => bridge().call("POST", `${MANAGE}/_api/chat-web/v2/chatrooms/${encodeURIComponent(roomId)}/messages`, {
+    sendMessageBody: { id: input.id, messageType: "message", messageTypeVersion: 1, summary: input.text, isEphemeral: true, isSilent: true, data: [{ mimeType: "text/plain", data: { text: input.text } }] },
+    sendMessageOptions: { chatAction: { actionType: "BUTTON_INTERACTION", appId: input.appId, interactionId: input.interactionId } },
+  }, { ChatToken: chatToken }));
+});
+
+const https = (value: unknown): string => (typeof value === "string" && /^https:\/\/[^\s\\]+$/.test(value) ? value : "");
+/** A fresh, authorized URL for an attachment. A private file is always fetched by its id. */
+export const attachmentUrl = (identity: ChatIdentity, media: { mediaId?: string; mediaProvider?: string; url?: string; fileName?: string }): Promise<string> => fenced(identity, async () => {
+  if (media.mediaProvider === "WixMediaPrivate") {
+    if (!media.mediaId) throw new Error("attachment_has_no_media_id");
+    const response = await bridge().call("POST", "/communication-channels-media/v1/download-url", {
+      fileId: media.mediaId, ...(media.fileName ? { downloadFileName: media.fileName } : {}),
+    }) as Raw | null;
+    const url = https(response?.downloadUrl);
+    if (!url) throw new Error("attachment_download_url_invalid");
+    return url;
+  }
+  return https(media.url);
+});

package/templates/salon-spa/tier5-src/_shared/collection-contract.ts

@@ -0,0 +1,230 @@
+import { compareText, compareIso } from "./engine-intl.js";
+/** Shared OTA collection contract. No host APIs: used by workers and builders. */
+export interface CollectionConfig {
+  rows: string;
+  /** Flat customer history rows, divided rather than boxed. */
+  rowStyle?: "flat";
+  instanceInput?: string;
+  title: string;
+  subtitle?: string;
+  image?: string;
+  filter?: string;
+  filterValues?: string[];
+  /** A state key holding `{ label }` rows (e.g. a worker's full category list) whose
+   *  labels are filter choices even when no loaded row carries them yet. */
+  filterValuesFrom?: string;
+  searchPlaceholder?: string;
+  sortLabels?: { default: string; az: string; za: string };
+  metadata?: string[];
+  /** Numeric 0–5 row field rendered as a Rating (accessible "N out of 5") instead of
+   *  folding a "★★★★☆" glyph string into the metadata line, so screen readers get a value. */
+  rating?: string;
+  /** Domain-provided calendar text and its unavailable flag, kept separate from media. */
+  dateBadge?: { text: string; hidden: string };
+  sectioned?: boolean;
+  view: 'list' | 'grid';
+  backendQuery?: boolean;
+  paged?: boolean;
+  defaultFilter?: string;
+  reviewAction?: string;
+  reviewSelectedAction?: string;
+  /** Optional comfortable grid media height for immersive visual catalogs. */
+  gridImageHeight?: number;
+  /** What the count summary counts — ["dish", "dishes"] reads "12 dishes". Default "item(s)". */
+  countNoun?: [string, string];
+  /** Phone grid columns (default 2). A card carrying a paragraph of benefits and a CTA — a
+   *  pricing plan — is unreadable at half width, so it opts into one. */
+  gridColumns?: number;
+  /** Lines of the meta caption a comfortable row may use (default 2). */
+  metaMaxLines?: number;
+  /** The card's primary verb, shown as a visible button beside the overflow.
+   * `screenId` opens that screen with the row id; without it the verb reuses the
+   * row's own tap action (the detail screen that owns the verb). */
+  primaryVerb?: { label: string; screenId?: string;
+    /** A row field holding THIS row's verb label (Register, RSVP, Buy Tickets…); `label` stays the fallback copy. */
+    labelPath?: string;
+    /** A row boolean that hides the verb on rows that offer no action (an event with no registration). */
+    hiddenPath?: string };
+  /** The worker action that shares a row (`tier5.<service>.<name>` with `{ id }`): adds Share to the card's overflow menu. */
+  shareAction?: string;
+  /** A TIME-BOUND entity (an event, a booking, a reservation): the boolean row field the
+   *  DOMAIN sets once the record has finished — computed by the same rule as the row's own
+   *  "Past" label, in the same place, so the two cannot disagree. A finished
+   *  record's `primaryVerb` (Register, Book…) is transactional and would act on something
+   *  that is over, so it is swapped for a non-transactional "View details" that opens the
+   *  row's own detail. Without a row tap action the verb is simply hidden. */
+  endedWhen?: string;
+  /** A catalog card whose one expected per-item action is "favorite".
+   *  The ellipsis overflow is replaced by an always-visible heart toggle wired to
+   *  the same `collectionSave` reducer. A dropdown `Menu` anchored inside a
+   *  list/grid row renders clipped inside the row's own bounds, so on a product
+   *  card the overflow's items were unreachable AND the wrong pattern: shoppers
+   *  expect a heart, not a 3-item menu two taps deep. */
+  favoriteToggle?: boolean;
+  /** A state field the DOMAIN narrows `rows` by (e.g. a category picker). While it is set,
+   *  zero rows is a filtered result, not an empty source. */
+  narrowedBy?: string;
+}
+/** At or below this many records, with no query/filter narrowing them and no further
+ * page, the list/grid toggle, Refine, chips, search and count are noise. */
+export const COLLECTION_CHROME_MIN_ITEMS = 4;
+/** The accessible name of a row's overflow menu: `template` with `{title}` filled, or the
+ *  generic `fallback` for a record with no title. */
+export function collectionActionsLabel(title: string, template: string, fallback: string): string {
+  const t = title.trim();
+  return t ? template.replace('{title}', () => t) : fallback;
+}
+
+export const COLLECTIONS: Record<string, CollectionConfig> = {
+  himiStoreShop: { rows: 'results', title: 'name', subtitle: 'subtitle', image: 'image', view: 'grid', backendQuery: true, countNoun: ['product', 'products'], favoriteToggle: true },
+  himiBookingServices: { rows: 'results', title: 'name', subtitle: 'subtitle', image: 'image', filter: 'category', view: 'grid', backendQuery: true, searchPlaceholder: 'Search services', countNoun: ['service', 'services'], primaryVerb: { label: 'Book', screenId: 'himi_time' } },
+  himiBookingBookings: { rows: 'rows', title: 'title', subtitle: 'subtitle', metadata: ['status'], view: 'list', backendQuery: true,
+    defaultFilter: 'value:Upcoming', searchPlaceholder: 'Search by booking ID', countNoun: ['booking', 'bookings'], filterValues: ['Upcoming', 'Past', 'Cancelled'],
+    sortLabels: { default: 'Soonest', az: 'Oldest', za: 'Latest' } },
+  himiEvents: { rows: 'results', title: 'title', subtitle: 'dateLine', image: 'image', dateBadge: { text: 'dateBadge', hidden: 'noDateBadge' }, gridColumns: 1, view: 'grid', backendQuery: true, defaultFilter: 'value:Upcoming', searchPlaceholder: 'Search events', countNoun: ['event', 'events'], filterValues: ['Upcoming', 'Past'], sortLabels: { default: 'Date', az: 'Title A–Z', za: 'Title Z–A' }, primaryVerb: { label: 'Register', labelPath: 'actionLabel', hiddenPath: 'noAction' }, shareAction: 'share', endedWhen: 'isPast' },
+  himiBlogFeed: { rows: 'posts', title: 'title', subtitle: 'excerpt', image: 'image', filter: 'category', filterValuesFrom: 'categories', view: 'grid', narrowedBy: 'selectedCategoryId' },
+  himiOwnerLiteProducts: { rows: 'products', title: 'name', subtitle: 'price', image: 'image', view: 'grid', backendQuery: true, countNoun: ['product', 'products'] },
+  himiOwnerModules: { instanceInput: 'module', rows: 'rows', title: 'title', subtitle: 'subtitle', image: 'image', filter: 'statusLabel', view: 'list', paged: true, reviewAction: 'prepareRecord', reviewSelectedAction: 'prepareSelected' },
+  himiOwnerLiteServices: { rows: 'services', title: 'name', subtitle: 'subtitle', view: 'list', backendQuery: true, searchPlaceholder: 'Service name starts with…' },
+  himiOwnerLiteEvents: { rows: 'events', title: 'title', subtitle: 'dateLine', view: 'grid', backendQuery: true, searchPlaceholder: 'Exact event title', filterValues: ['Upcoming'], sortLabels: { default: 'Date', az: 'Title A–Z', za: 'Title Z–A' } },
+  himiOwnerLitePosts: { rows: 'posts', title: 'title', subtitle: 'excerpt', image: 'image', view: 'grid' },
+  himiOwnerLiteOrders: { rows: 'orders', title: 'buyer', subtitle: 'meta', filter: 'statusLabel', view: 'list', backendQuery: true, countNoun: ['order', 'orders'],
+    searchPlaceholder: 'Customer name, email or order #', sortLabels: { default: 'Newest', az: 'Customer A–Z', za: 'Customer Z–A' },
+    filterValues: ['Recent 7 days', 'Paid', 'Unpaid', 'Partially paid', 'Pending', 'Refunded', 'Partly refunded'] },
+  himiBrandedGroups: { rows: 'rows', title: 'name', subtitle: 'description', image: 'image', view: 'grid' },
+  himiBrandedCms: { rows: 'rows', title: 'name', subtitle: 'subtitle', view: 'grid' },
+  himiBrandedCmsCollection: { instanceInput: 'collection', rows: 'rows', title: 'title', subtitle: 'subtitle', view: 'list' },
+  himiBrandedOrders: { rows: 'rows', title: 'title', subtitle: 'subtitle', image: 'image', metadata: ['status', 'meta'], rowStyle: 'flat', view: 'list', backendQuery: true,
+    searchPlaceholder: 'Search by order number', countNoun: ['order', 'orders'], filterValues: ['Not fulfilled', 'Partially fulfilled', 'Fulfilled'],
+    sortLabels: { default: 'Newest', az: 'Oldest', za: 'Order # ↓' } },
+  himiBrandedPlans: { rows: 'rows', title: 'name', subtitle: 'description', metadata: ['badge', 'priceLine', 'periodLine', 'trialBadge', 'perk1', 'perk2', 'perk3', 'joinNote'], view: 'grid', gridColumns: 1, metaMaxLines: 8, countNoun: ['plan', 'plans'] },
+  himiBrandedPrograms: { rows: 'rows', title: 'name', subtitle: 'description', image: 'image', view: 'grid' },
+  himiBrandedCoupons: { rows: 'coupons', title: 'name', subtitle: 'subtitle', view: 'list', primaryVerb: { label: 'Get code' } },
+  himiBrandedNotifications: { rows: 'items', title: 'name', subtitle: 'subtitle', image: 'photo', metadata: ['unreadDot'], view: 'list' },
+  himiBrandedLoyalty: { rows: 'rewards', title: 'name', subtitle: 'description', view: 'grid', primaryVerb: { label: 'Redeem' } },
+  himiBrandedReviews: { rows: 'reviews', title: 'title', subtitle: 'body', metadata: ['author'], rating: 'rating', view: 'list' },
+  himiBrandedPortfolio: { rows: 'projects', title: 'title', subtitle: 'subtitle', image: 'image', view: 'grid', gridImageHeight: 180 },
+  himiBrandedInvoices: { rows: 'invoices', title: 'title', subtitle: 'subtitle', view: 'list' },
+  himiBrandedBadges: { rows: 'badges', title: 'name', subtitle: 'description', view: 'grid' },
+  himiBrandedDonations: { rows: 'campaigns', title: 'name', subtitle: 'description', view: 'grid', primaryVerb: { label: 'Donate' } },
+  himiBrandedGiftCards: { rows: 'cards', title: 'name', subtitle: 'description', view: 'grid' },
+  himiBrandedVideos: { rows: 'channels', title: 'title', subtitle: 'subtitle', image: 'coverUrl', view: 'grid', searchPlaceholder: 'Search channels', countNoun: ['channel', 'channels'] },
+  himiBrandedPodcasts: { rows: 'episodes', title: 'title', subtitle: 'subtitle', image: 'image', metadata: ['progressLabel'], view: 'list' },
+  himiBrandedForms: { rows: 'forms', title: 'name', subtitle: 'description', view: 'list' },
+  himiBrandedGalleries: { rows: 'galleries', title: 'name', subtitle: 'description', image: 'image', view: 'grid' },
+  himiBrandedMenus: { rows: 'rows', title: 'name', subtitle: 'description', image: 'image', sectioned: true, filter: 'collectionCategory', metadata: ['collectionCategory', 'priceLine', 'label1', 'label2', 'label3'], view: 'grid', searchPlaceholder: 'Search the menu', countNoun: ['dish', 'dishes'] },
+};
+export interface CollectionPreferences {
+  view: 'list' | 'grid';
+  density: 'comfortable' | 'compact';
+  sort: 'default' | 'az' | 'za';
+  filter: string;
+  query: string;
+  savedIds: string[];
+  selectedIds: string[];
+  selecting: boolean;
+  savedViews: SavedCollectionView[];
+}
+export interface SavedCollectionView {
+  id: string; name: string; view: 'list' | 'grid'; density: 'comfortable' | 'compact';
+  sort: 'default' | 'az' | 'za'; query: string; filter: string;
+}
+export interface CollectionItemAction {
+  id: string;
+  label: string;
+  destructive: boolean;
+  confirmationRequired: boolean;
+}
+export type CollectionRow = Record<string, unknown>;
+export function initialCollection(config: CollectionConfig): CollectionPreferences {
+  return { view: config.view, density: 'comfortable', sort: 'default', filter: config.defaultFilter ?? 'all', query: '', savedIds: [], selectedIds: [], selecting: false, savedViews: [] };
+}
+/** Accept only small presentation preferences from local storage. Selection is
+ * transient and never restored as an armed bulk operation. */
+export function normalizeCollection(config: CollectionConfig, value: unknown): CollectionPreferences {
+  const s = value && typeof value === 'object' ? value as Partial<CollectionPreferences> : {};
+  const base = initialCollection(config);
+  return { ...base,
+    view: s.view === 'list' || s.view === 'grid' ? s.view : base.view,
+    density: s.density === 'compact' ? 'compact' : 'comfortable',
+    sort: s.sort === 'az' || s.sort === 'za' ? s.sort : 'default',
+    query: typeof s.query === 'string' ? s.query.slice(0, 256) : '',
+    // Flat collections no longer offer Saved. Migrate its persisted value before
+    // the first backend request so an invisible old filter cannot empty the list.
+    filter: config.rowStyle === 'flat' && s.filter === 'saved' ? 'all'
+      : typeof s.filter === 'string' ? s.filter.slice(0, 256) : config.defaultFilter ?? 'all',
+    savedIds: Array.isArray(s.savedIds) ? [...new Set(s.savedIds.filter((id): id is string => typeof id === 'string' && id.length > 0 && id.length <= 256))].slice(0, 500) : [],
+    savedViews: Array.isArray(s.savedViews) ? s.savedViews.filter((v): v is SavedCollectionView => !!v && typeof v === 'object' && typeof v.name === 'string' && !!v.name.trim()).slice(0, 8).map((v, i) => ({
+      id: `view-${i}`, name: v.name.trim().slice(0, 40),
+      view: v.view === 'list' || v.view === 'grid' ? v.view : config.view,
+      density: v.density === 'compact' ? 'compact' : 'comfortable',
+      sort: v.sort === 'az' || v.sort === 'za' ? v.sort : 'default',
+      query: typeof v.query === 'string' ? v.query.slice(0, 256) : '',
+      filter: config.rowStyle === 'flat' && v.filter === 'saved' ? 'all'
+        : typeof v.filter === 'string' ? v.filter.slice(0, 256) : 'all',
+    })) : [],
+  };
+}
+const scalar = (value: unknown): string => typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+export function collectionId(row: CollectionRow): string { return scalar(row.id) || scalar(row._id) || scalar(row.key); }
+export function collectionTitle(row: CollectionRow, config: CollectionConfig): string {
+  return scalar(row[config.title]) || scalar(row.title) || scalar(row.name) || scalar(row.display) || scalar(row.label);
+}
+/** Does not mutate domain rows, paging, or domain-derived state. */
+export function projectCollection(source: CollectionRow[], config: CollectionConfig, prefs: CollectionPreferences, backendQuery = false, knownFilters: string[] = []) {
+  const query = prefs.query.trim().toLocaleLowerCase();
+  const unique = new Set<string>();
+  // Menu sections describe their following items; they are not actionable
+  // records. Carry the category onto each item before sorting or filtering.
+  let category = '';
+  const records: CollectionRow[] = config.sectioned ? source.flatMap(row => {
+    if (row.isHeader === true) { category = scalar(row.title); return []; }
+    return [{ ...row, collectionCategory: category }];
+  }) : source;
+  const rows = records.filter(row => {
+    const id = collectionId(row);
+    if (!id) return true; // render anonymous records; identity actions stay disabled
+    if (unique.has(id)) return false;
+    unique.add(id); return true;
+  });
+  const filters = config.filterValues ?? [...new Set([...knownFilters, ...rows.map(row => config.filter ? scalar(row[config.filter]) : '')].filter(Boolean))].sort();
+  const visible = rows.filter(row => {
+    if (backendQuery) return true;
+    if (prefs.filter === 'saved' && !prefs.savedIds.includes(collectionId(row))) return false;
+    if (prefs.filter.startsWith('value:') && (!config.filter || scalar(row[config.filter]) !== prefs.filter.slice(6))) return false;
+    return !query || Object.values(row).some(value => scalar(value).toLocaleLowerCase().includes(query));
+  });
+  if (!backendQuery && prefs.sort !== 'default') visible.sort((a, b) => {
+    const order = compareText(collectionTitle(a, config), collectionTitle(b, config));
+    return (prefs.sort === 'az' ? order : -order) || compareIso(collectionId(a), collectionId(b));
+  });
+  return {
+    items: visible.map(row => ({ ...row, collectionId: collectionId(row), collectionTitle: collectionTitle(row, config),
+      collectionMeta: [...new Set((config.metadata ?? ['total', 'statusLabel', 'price', 'priceLine', 'dateLine', 'meta']).filter(key => key !== config.subtitle).map(key => scalar(row[key])).filter(Boolean))].join(' · '),
+      collectionSelectLabel: prefs.selectedIds.includes(collectionId(row)) ? 'Selected' : 'Select',
+      // The save toggle names the action it WILL take (the service localizes it).
+      collectionSaveLabel: prefs.savedIds.includes(collectionId(row)) ? 'Remove from saved' : 'Save',
+      // The row's overflow menu, named for its record: out of context (a rotor, a voice
+      // command) a list of identical "Item actions" cannot be told apart.
+      collectionActionsLabel: collectionActionsLabel(collectionTitle(row, config), 'Actions for {title}', 'Item actions'),
+      collectionSubtitle: scalar(row[config.subtitle ?? '']) || scalar(row.subtitle) || scalar(row.description) || scalar(row.meta),
+      collectionImage: scalar(row[config.image ?? '']), collectionNoImage: !scalar(row[config.image ?? '']), collectionHasImage: !!scalar(row[config.image ?? '']),
+      collectionSaved: prefs.savedIds.includes(collectionId(row)), collectionNotSaved: !prefs.savedIds.includes(collectionId(row)), collectionSelected: prefs.selectedIds.includes(collectionId(row)),
+      collectionNoIdentity: !collectionId(row),
+      // Older cached EventRows predate `isPast` but already stored `statusLabel: "Past"`.
+      // Keep their ended state through an offline render until the row is refreshed.
+      ...(config.endedWhen ? (() => {
+        const ended = row[config.endedWhen] === true || (config.endedWhen === 'isPast' && row.statusLabel === 'Past');
+        return { collectionEnded: ended, collectionNotEnded: !ended };
+      })() : {}),
+      // A row restored from state saved by an older build has no badge flag. An unset hidden flag
+      // fails open and would paint an empty chip, so it reads as "no badge" until a refresh.
+      ...(config.dateBadge && typeof row[config.dateBadge.hidden] !== 'boolean'
+        ? { [config.dateBadge.text]: '', [config.dateBadge.hidden]: true } : {}),
+      // Same for a per-row verb: an unset hidden flag fails open and would show a verb with an unresolved
+      // label, so a row without the flag offers no action until a refresh establishes one.
+      ...(config.primaryVerb?.hiddenPath && typeof row[config.primaryVerb.hiddenPath] !== 'boolean'
+        ? { ...(config.primaryVerb.labelPath ? { [config.primaryVerb.labelPath]: '' } : {}), [config.primaryVerb.hiddenPath]: true } : {}) })),
+    filters, loaded: rows.length,
+  };
+}

package/templates/salon-spa/tier5-src/_shared/collection-query.ts

@@ -0,0 +1,193 @@
+/** Backend collection lifecycle shared by domain workers. The domain supplies
+ * the query and row mapper; this layer never calls a domain API or mutates it. */
+export interface CollectionQuery {
+  query: string;
+  filter: string;
+  sort: 'default' | 'az' | 'za';
+  savedIds: string[];
+}
+export interface CollectionPage<Row> {
+  items: Row[];
+  nextCursor: string;
+  total?: number;
+  metadata?: Record<string, unknown>;
+  complete?: boolean;
+}
+export interface CollectionQueryState<Row> extends CollectionPage<Row> {
+  criteria: CollectionQuery;
+  status: 'idle' | 'loading' | 'ready' | 'error';
+  loadingMore: boolean;
+  pageError: boolean;
+  complete: boolean;
+  error: string;
+  /** The rows are the source's `cached` page, shown while the live read is still out. */
+  provisional?: boolean;
+}
+/** What a collection showed, as `shownPage` hands it out and `seed` takes it back on a restored boot. */
+export interface CollectionShownPage<Row> {
+  state: CollectionQueryState<Row>;
+  loadedPages: number;
+}
+export interface CollectionQuerySource<Row> {
+  fetch(criteria: CollectionQuery, cursor: string): Promise<CollectionPage<Row>>;
+  /** Optional public cache for immediate paint; always incomplete, never a paging authority. */
+  cached?(criteria: CollectionQuery): Promise<CollectionPage<Row> | undefined>;
+  id(row: Row): string;
+  errorMessage?(error: unknown): string;
+  /** Private collections must discard prior rows when access or identity changes. A revalidation keeps the
+   *  rows it shows through any other failure: safe because one worker never serves two identities (its pool
+   *  key carries the account, and a purge tears parked workers down). */
+  clearOnError?(error: unknown): boolean;
+}
+const normalize = (q: Partial<CollectionQuery>): CollectionQuery => ({
+  query: typeof q.query === 'string' ? q.query.trim().slice(0, 256) : '',
+  filter: typeof q.filter === 'string' ? q.filter.slice(0, 256) : 'all',
+  sort: q.sort === 'az' || q.sort === 'za' ? q.sort : 'default',
+  savedIds: Array.isArray(q.savedIds) ? [...new Set(q.savedIds.filter(id => typeof id === 'string' && id.length > 0 && id.length <= 256))].slice(0, 500) : [],
+});
+const copyQuery = (q: CollectionQuery): CollectionQuery => ({ ...q, savedIds: [...q.savedIds] });
+
+/** New criteria cancel the old result logically, including an in-flight next
+ * page. Failures preserve the cursor and rows for an explicit retry. Callers
+ * publish each snapshot through their ordinary service reducer, so loading and
+ * filtered-empty never masquerade as a successfully completed query. */
+export function createCollectionQuery<Row>(source: CollectionQuerySource<Row>, publish: (state: CollectionQueryState<Row>) => void) {
+  let generation = 0, disposed = false;
+  let loadedPages = 0, restoringPages = 0;
+  let state: CollectionQueryState<Row> = { criteria: normalize({}), items: [], nextCursor: '', status: 'idle', loadingMore: false, pageError: false, complete: false, error: '' };
+  /** The query a revalidation is running under: its snapshots are held back until it is done. */
+  let revalidating = -1;
+  /** The last page the screen showed whole (rows ready, nothing paging, failing or standing in): what a revalidation
+   *  keeps on screen and restores when it fails, and what a restored boot shows. A next page loading or failing after
+   *  it leaves those rows on screen, so it is still this. */
+  let lastShown: { state: CollectionQueryState<Row>; loadedPages: number } | undefined;
+  const sameCriteria = (a: CollectionQuery, b: CollectionQuery) => JSON.stringify(a) === JSON.stringify(b);
+  let clearedByError = false;
+  const snapshot = (): CollectionQueryState<Row> => ({ ...state, criteria: copyQuery(state.criteria), items: [...state.items] });
+  const emit = () => {
+    if (disposed || revalidating === generation) return;
+    // A settled answer replaces it, an empty one included: rows the live query proved gone are never kept, and a list
+    // with nothing in it comes back as its empty state, never its loading look.
+    if (state.status === 'ready' && !state.pageError && !state.loadingMore && !state.provisional) {
+      lastShown = { state: snapshot(), loadedPages };
+    }
+    publish(snapshot());
+  };
+  const merge = (old: Row[], page: Row[]): Row[] => {
+    const positions = new Map<string, number>(), result: Row[] = [];
+    for (const item of [...old, ...page]) {
+      const id = source.id(item);
+      if (!id) throw new Error('A backend collection row requires an identity');
+      const index = positions.get(id);
+      if (index === undefined) { positions.set(id, result.length); result.push(item); }
+      else result[index] = item;
+    }
+    return result;
+  };
+  /** [keepRows]: a search typed over the rows on screen leaves them there until its answer arrives (status stays
+   *  `loading`, and nothing pages under the old answer), so the list is not blanked on each keystroke. */
+  const fetch = async (append: boolean, keepRows = false): Promise<void> => {
+    if (disposed || (append && (state.loadingMore || state.status === 'loading' || !state.nextCursor))) return;
+    const revision = append ? generation : ++generation;
+    const cursor = append ? state.nextCursor : '';
+    const criteria = copyQuery(state.criteria);
+    if (!append) loadedPages = 0;
+    state = { ...state, status: append ? 'ready' : 'loading', loadingMore: append, pageError: false, error: '',
+      ...(append ? {} : keepRows ? { nextCursor: '', complete: false, provisional: false }
+        : { items: [], nextCursor: '', total: undefined, metadata: undefined, complete: false, provisional: false }) };
+    emit();
+    try {
+      if (!append && source.cached) {
+        const cached = await source.cached(criteria).catch(() => undefined);
+        if (disposed || generation !== revision) return;
+        if (cached?.items.length) {
+          state = { ...state, items: merge([], cached.items), metadata: cached.metadata, status: 'ready', complete: false, provisional: true };
+          emit();
+        }
+      }
+      const page = await source.fetch(criteria, cursor);
+      if (disposed || generation !== revision) return;
+      if (!Array.isArray(page.items) || typeof page.nextCursor !== 'string' || (cursor && page.nextCursor === cursor)) throw new Error('Invalid collection page');
+      state = { ...state, items: merge(append ? state.items : [], page.items), nextCursor: page.nextCursor,
+        total: typeof page.total === 'number' && Number.isFinite(page.total) && page.total >= 0 ? page.total : (append ? state.total : undefined),
+        metadata: page.metadata ?? (append ? state.metadata : undefined),
+        status: 'ready', loadingMore: false, pageError: false, complete: page.complete ?? !page.nextCursor, provisional: false };
+      loadedPages++;
+    } catch (error) {
+      if (disposed || generation !== revision) return;
+      const clear = source.clearOnError?.(error) === true;
+      // Revoked access always ends what a revalidation showed, whether or not the source clears its rows.
+      clearedByError = clear || /HTTP 40[13]\b/.test(String(error));
+      if (clearedByError) lastShown = undefined;
+      if (clear) loadedPages = 0;
+      // The rows a typed search kept on screen while it ran were never its answer: a failed one shows none of them.
+      const drop = clear || keepRows;
+      state = { ...state, ...(drop ? { items: [], nextCursor: '', total: undefined, metadata: undefined } : {}),
+        status: append && !clear ? 'ready' : 'error', loadingMore: false, pageError: append && !clear, complete: false,
+        provisional: false, error: source.errorMessage?.(error) ?? '' };
+    }
+    emit();
+  };
+  return {
+    getState: snapshot,
+    /** [revalidate]: a screen coming back re-queries the rows it shows. They stay on screen until every
+     *  page is in, and a failure keeps them; revoked access still clears them, and other criteria reset. */
+    async query(criteria: Partial<CollectionQuery>, restorePages = false, revalidate = false): Promise<void> {
+      if (disposed) return Promise.resolve();
+      const next = normalize(criteria);
+      const same = JSON.stringify(next) === JSON.stringify(state.criteria);
+      const count = restorePages && same ? Math.max(loadedPages, restoringPages, 1) : 1;
+      const showing = lastShown && sameCriteria(lastShown.state.criteria, next) ? lastShown : undefined;
+      restoringPages = count;
+      // Only the search text changed: the user is typing over the rows on screen, also while the last keystroke's
+      // search is still out.
+      const typing = !same && (state.status === 'ready' || state.status === 'loading')
+        && sameCriteria({ ...state.criteria, query: '' }, { ...next, query: '' });
+      state = { ...state, criteria: next };
+      if (revalidate && showing) { revalidating = generation + 1; clearedByError = false; }
+      const pending = fetch(false, typing);
+      const revision = generation;
+      await pending;
+      // Re-appearance revalidates every previously opened page using fresh
+      // cursors. A changed query, error or revoked access stops the restoration.
+      while (!disposed && generation === revision && loadedPages < count && state.status === 'ready'
+        && !state.pageError && !state.loadingMore && state.nextCursor) await fetch(true);
+      if (generation === revision) restoringPages = 0;
+      if (revalidating === revision) {
+        revalidating = -1;
+        if (generation !== revision) return;
+        if ((state.status !== 'ready' || state.pageError) && showing && !clearedByError) {
+          state = { ...showing.state, criteria: next };
+          loadedPages = showing.loadedPages;
+        }
+        emit();
+      }
+    },
+    /** The page the screen shows (rows ready, nothing failing or still paging), for the service to keep with its
+     *  state; undefined when it shows none. */
+    shownPage(): CollectionShownPage<Row> | undefined {
+      if (!lastShown || !sameCriteria(lastShown.state.criteria, state.criteria)) return undefined;
+      const page = lastShown.state;
+      return { state: { ...page, criteria: copyQuery(page.criteria), items: [...page.items] }, loadedPages: lastShown.loadedPages };
+    },
+    /** A cold boot restored from disk: what the last run showed becomes what this one shows, so its first `load`
+     *  revalidates behind it instead of starting empty. Only before the first query, and only a well-formed page; an
+     *  empty one is the list's empty state. */
+    seed(page: unknown): boolean {
+      const candidate = page && typeof page === 'object' ? page as Partial<CollectionShownPage<Row>> : undefined;
+      const restored = candidate?.state;
+      if (generation !== 0 || state.status !== 'idle' || !restored || restored.status !== 'ready'
+        || !Array.isArray(restored.items) || typeof restored.nextCursor !== 'string') return false;
+      try { restored.items.forEach(item => { if (!source.id(item)) throw new Error('A backend collection row requires an identity'); }); } catch { return false; }
+      state = { ...state, ...restored, criteria: normalize(restored.criteria ?? {}), items: [...restored.items], status: 'ready',
+        loadingMore: false, pageError: false, provisional: false, error: '' };
+      loadedPages = Math.max(1, Math.floor(Number(candidate?.loadedPages) || 1));
+      lastShown = { state: snapshot(), loadedPages };
+      return true;
+    },
+    refresh: () => { restoringPages = 0; return fetch(false); },
+    loadMore: () => fetch(true),
+    retry: () => fetch(state.pageError),
+    dispose() { disposed = true; generation++; },
+  };
+}