@wix/himalaya-cli 0.1210.0 → 0.1211.0

package/templates/community-club-owner/tier5-src/_shared/owner-module-data.ts

@@ -13,9 +13,11 @@ import { queryGiftCards, getGiftCard } from '@himalaya/wix-gift-cards';
 import { queryDonationCampaigns, getDonationCampaign } from '@himalaya/wix-donations';
 import { query as queryBadges, get as getBadge } from '@himalaya/wix-badges';
 import { wixMediaUrl } from '@himalaya/wix-media';
+import { getSiteTimeZone } from '@himalaya/wix-analytics';
 import { type OwnerModuleId } from './owner-modules.js';
 import { type CollectionPage } from './collection-query.js';
-import { copyParam } from './himi-copy.js';
+import { copyParam, copyTemplate } from './himi-copy.js';
+import { calendarDay, formatDateMedium, formatMonthDay, formatWeekdayDateTime } from './engine-intl.js';
 import { eligibleOwnerOperations } from './owner-operations.js';
 
 export interface OwnerRecord {
@@ -33,91 +35,144 @@ const join = (...values: string[]) => values.filter(Boolean).join(' · ');
 const name = (value: unknown, first: string, last: string) => [field(value, first), field(value, last)].filter(Boolean).join(' ');
 const yesNo = (value: unknown) => typeof value === 'boolean' ? value ? 'Yes' : 'No' : '';
 const LIMIT = 50;
+
+/** The site's IANA zone, resolved once per worker. Wix hands every date here as a UTC instant;
+ *  formatting it in the viewer's device zone (or leaving it raw) shows an owner outside UTC the
+ *  wrong hour and sometimes the wrong day. A failed or unset lookup degrades to the
+ *  device zone — a zone is garnish on a date, never a reason to fail the collection. The
+ *  answer, failure included, is kept for the worker's life: a role that cannot read site
+ *  properties would otherwise re-send the failing request for every page a search walks. */
+let zoneLookup: Promise<string | undefined> | undefined;
+function siteZone(): Promise<string | undefined> {
+  // `Promise.resolve().then` so a bridge that throws synchronously is caught here too.
+  zoneLookup ??= Promise.resolve().then(getSiteTimeZone).catch(() => undefined);
+  return zoneLookup;
+}
+
+/** A Wix date value as an instant. A calendar date with no time ("2026-11-07") is a DAY, not an
+ *  instant: it is built at local midnight and formatted with no zone, so it never shifts across
+ *  one — including on engines without Intl, where a zone could not be applied anyway. */
+function ownerInstant(value: string): { date: Date; dayOnly: boolean } | undefined {
+  if (!value) return undefined;
+  const day = /^(\d{4})-(\d\d)-(\d\d)$/.exec(value);
+  if (day) return { date: new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3])), dayOnly: true };
+  const ms = /^\d{13}$/.test(value) ? Number(value) : Date.parse(value);
+  return Number.isFinite(ms) ? { date: new Date(ms), dayOnly: false } : undefined;
+}
+/** Has the instant (or, for a calendar date, the whole day) passed? */
+function ownerPast(value: string, now = Date.now()): boolean {
+  const parsed = ownerInstant(value);
+  if (!parsed) return false;
+  const { date, dayOnly } = parsed;
+  return (dayOnly ? new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1).getTime() : date.getTime()) <= now;
+}
+
+type DateStyle = 'date' | 'dateTime' | 'short';
+/** A Wix date as owner copy, through the shared engine-intl shapes: `date` "Jan 5, 2026",
+ *  `dateTime` "Mon, Jan 5, 3:07 PM", `short` "Jan 5" (with the year when it is not this year).
+ *  A value that is not a date at all is kept as Wix sent it. */
+function ownerDate(value: string, zone: string | undefined, style: DateStyle = 'date'): string {
+  if (!value) return '';
+  const parsed = ownerInstant(value);
+  if (!parsed) return value;
+  const { date } = parsed, tz = parsed.dayOnly ? undefined : zone;
+  if (style === 'dateTime') return formatWeekdayDateTime(date, undefined, tz);
+  if (style === 'short' && calendarDay(date, tz).slice(0, 4) === calendarDay(new Date(), tz).slice(0, 4)) return formatMonthDay(date, undefined, tz);
+  return formatDateMedium(date, undefined, tz);
+}
 function offsetOf(cursor: string): number {
   if (cursor && !/^\d{1,9}$/.test(cursor)) throw new Error('Invalid collection cursor. Refresh this view.');
   return Number(cursor || 0);
 }
-function page(module: OwnerModuleId, rows: unknown[], nextCursor: string, total?: number, complete?: boolean): CollectionPage<OwnerRecord> {
-  return { items: rows.map(row => ownerRecord(module, row)), nextCursor, total, ...(complete === undefined ? {} : { complete }) };
+function page(rows: unknown[], nextCursor: string, total?: number, complete?: boolean): CollectionPage<unknown> {
+  return { items: rows, nextCursor, total, ...(complete === undefined ? {} : { complete }) };
 }
-function offsetPage(module: OwnerModuleId, rows: unknown[], offset: number, metadata: unknown) {
+function offsetPage(rows: unknown[], offset: number, metadata: unknown) {
   const total = at(metadata, 'total');
   const more = rows.length > 0 && (typeof total === 'number' ? offset + rows.length < total : rows.length === LIMIT);
-  return page(module, rows, more ? String(offset + rows.length) : '', typeof total === 'number' ? total : undefined);
+  return page(rows, more ? String(offset + rows.length) : '', typeof total === 'number' ? total : undefined);
 }
 
 /** Domain query shapes stay here, shared by list and detail workers. Unsupported
  * server name queries remain explicitly labelled searches of loaded records. */
 export async function queryOwnerModule(module: OwnerModuleId, cursor = ''): Promise<CollectionPage<OwnerRecord>> {
+  // The zone lookup runs beside the query, not after it: the two are independent, and serial
+  // they would double the time to a first paint.
+  const [raw, zone] = await Promise.all([queryRawOwnerModule(module, cursor), siteZone()]);
+  return { ...raw, items: raw.items.map(row => ownerRecord(module, row, zone)) };
+}
+
+async function queryRawOwnerModule(module: OwnerModuleId, cursor: string): Promise<CollectionPage<unknown>> {
   const cursorPaging = { limit: LIMIT, ...(cursor ? { cursor } : {}) };
   switch (module) {
     case 'invoices': {
       const offset = offsetOf(cursor), r = await queryInvoices({ query: { paging: { limit: LIMIT, offset } } });
-      return offsetPage(module, r.invoices ?? [], offset, r.pagingMetadata);
+      return offsetPage(r.invoices ?? [], offset, r.pagingMetadata);
     }
     case 'coupons': {
       const offset = offsetOf(cursor), r = await queryCoupons({ paging: { limit: LIMIT, offset } });
-      return offsetPage(module, r.coupons ?? [], offset, r.metadata);
+      return offsetPage(r.coupons ?? [], offset, r.metadata);
     }
     case 'giftCards': {
       const r = await queryGiftCards({ query: { cursorPaging, sort: [{ fieldName: 'createdDate', order: 'DESC' }] } });
-      return page(module, r.giftCards ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.giftCards ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'contacts': {
       const offset = offsetOf(cursor), r = await queryContacts({ query: { paging: { limit: LIMIT, offset } } });
-      return offsetPage(module, r.contacts ?? [], offset, r.pagingMetadata);
+      return offsetPage(r.contacts ?? [], offset, r.pagingMetadata);
     }
     case 'members': {
       const offset = offsetOf(cursor), r = await queryMembers({ query: { paging: { limit: LIMIT, offset } } });
-      return offsetPage(module, r.members ?? [], offset, r.metadata);
+      return offsetPage(r.members ?? [], offset, r.metadata);
     }
     case 'groups': {
       const offset = offsetOf(cursor), r = await queryGroups({ paging: { limit: LIMIT, offset } });
-      return offsetPage(module, r.groups ?? [], offset, r.metaData);
+      return offsetPage(r.groups ?? [], offset, r.metaData);
     }
     case 'reviews': {
       const r = await queryReviews({ cursorPaging, sort: [{ fieldName: 'createdDate', order: 'DESC' }] }, true);
-      return page(module, r.reviews ?? r.results ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.reviews ?? r.results ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'programs': {
       const r = await queryPrograms({ cursorPaging });
-      return page(module, r.programs ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.programs ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'badges': {
       const r = await queryBadges({ query: { cursorPaging } });
-      return page(module, r.badges ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.badges ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'reservations': {
       const r = await queryReservations({ cursorPaging, sort: [{ fieldName: 'details.startDate', order: 'ASC' }] });
-      return page(module, r.reservations ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.reservations ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'portfolio': {
       const r = await listProjects(LIMIT, cursor || undefined);
-      return page(module, r.projects ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.projects ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'donationCampaigns': {
       const r = await queryDonationCampaigns({ query: { cursorPaging, sort: [{ fieldName: 'updatedDate', order: 'DESC' }] } });
-      return page(module, r.donationCampaigns ?? [], r.pagingMetadata?.cursors?.next ?? '');
+      return page(r.donationCampaigns ?? [], r.pagingMetadata?.cursors?.next ?? '');
     }
     case 'forms': {
       // This collection is Wix Forms. Booking/event registration forms belong
       // to their respective operational records, rather than a mixed union
       // that silently drops namespaces when one permission check fails.
       const offset = offsetOf(cursor), r = await queryForms({ filter: { namespace: 'wix.form_app.form' }, paging: { limit: LIMIT, offset } });
-      return offsetPage(module, r.forms ?? [], offset, r.metaData);
+      return offsetPage(r.forms ?? [], offset, r.metaData);
     }
     case 'plans': {
       const r = await listPlans();
-      return page(module, r.plans ?? [], '', r.pagingMetadata?.total, false);
+      return page(r.plans ?? [], '', r.pagingMetadata?.total, false);
     }
     case 'subscriptions': {
       const r = await listPlanOrders();
-      return page(module, r.orders ?? [], '', r.pagingMetadata?.total, false);
+      return page(r.orders ?? [], '', r.pagingMetadata?.total, false);
     }
   }
 }
 
-export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
+export function ownerRecord(module: OwnerModuleId, raw: unknown, zone?: string): OwnerRecord {
+  const when = (path: string, style?: DateStyle) => ownerDate(field(raw, path), zone, style);
   const id = field(raw, 'id');
   if (!id) throw new Error('Wix returned a record without an identity. Refresh this view.');
   let title = '', subtitle = '', image = '', statusLabel = '';
@@ -127,7 +182,7 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
       title = field(raw, 'specification.name') || field(raw, 'displayData.name');
       subtitle = field(raw, 'specification.code');
       statusLabel = at(raw, 'expired') === true ? 'Expired' : at(raw, 'specification.active') === true ? 'Active' : 'Inactive';
-      details = [['Code', subtitle], ['Uses', field(raw, 'numberOfUsages')], ['Offer', words(field(raw, 'specification.type'))], ['Expires', field(raw, 'specification.expirationTime')]];
+      details = [['Code', subtitle], ['Uses', field(raw, 'numberOfUsages')], ['Offer', words(field(raw, 'specification.type'))], ['Expires', when('specification.expirationTime')]];
       break;
     case 'giftCards': {
       const suffix = field(raw, 'codeSuffix');
@@ -147,7 +202,7 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
         ['Initial value', field(raw, 'initialValue.formattedAmount') || join(field(raw, 'initialValue.amount'), field(raw, 'currency'))],
         ['Recipient', recipient],
         ['Order number', field(raw, 'orderInfo.orderNumber')],
-        ['Expires', expires],
+        ['Expires', when('expirationDate')],
         ['Source', words(field(raw, 'source'))],
       ];
       break;
@@ -156,7 +211,7 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
       title = field(raw, 'number') ? `#${field(raw, 'number')}` : field(raw, 'title');
       subtitle = field(raw, 'customerInfo.contactDetails.fullName') || name(raw, 'customerInfo.contactDetails.firstName', 'customerInfo.contactDetails.lastName') || field(raw, 'customerInfo.contactDetails.email');
       statusLabel = words(field(raw, 'status'));
-      details = [['Customer', subtitle], ['Total', join(field(raw, 'totals.total'), field(raw, 'currency'))], ['Due', field(raw, 'dueDate')]];
+      details = [['Customer', subtitle], ['Total', join(field(raw, 'totals.total'), field(raw, 'currency'))], ['Due', when('dueDate')]];
       break;
     case 'contacts':
       title = name(raw, 'info.name.first', 'info.name.last') || field(raw, 'primaryInfo.email');
@@ -167,12 +222,12 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
     case 'members':
       title = field(raw, 'profile.nickname') || name(raw, 'contact.firstName', 'contact.lastName') || field(raw, 'loginEmail');
       subtitle = field(raw, 'loginEmail'); image = field(raw, 'profile.photo.url'); statusLabel = words(field(raw, 'status'));
-      details = [['Email', subtitle], ['Last login', field(raw, 'lastLoginDate')]];
+      details = [['Email', subtitle], ['Last login', when('lastLoginDate')]];
       break;
     case 'groups':
       title = field(raw, 'name'); subtitle = field(raw, 'description') || field(raw, 'teaser');
       image = field(raw, 'coverImage.imageInfo.url'); statusLabel = words(field(raw, 'privacyStatus'));
-      details = [['Members', field(raw, 'memberCount') || field(raw, 'membersCount')], ['Last activity', field(raw, 'lastActivityDate')]];
+      details = [['Members', field(raw, 'memberCount') || field(raw, 'membersCount')], ['Last activity', when('lastActivityDate')]];
       break;
     case 'reviews':
       title = field(raw, 'content.title'); subtitle = field(raw, 'content.body'); statusLabel = words(field(raw, 'moderation.moderationStatus'));
@@ -184,8 +239,14 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
       details = [['Price', join(field(raw, 'pricing.price.value'), field(raw, 'pricing.price.currency'))], ['Free trial days', field(raw, 'pricing.freeTrialDays')]];
       break;
     case 'subscriptions':
-      title = field(raw, 'planName'); subtitle = field(raw, 'buyer.memberId'); statusLabel = words(field(raw, 'status'));
-      details = [['Member ID', subtitle], ['Started', field(raw, 'startDate')], ['Ends', field(raw, 'endDate')], ['Payment', words(field(raw, 'lastPaymentStatus'))]];
+      // The buyer is only a member UUID here — not something an owner can read — so the
+      // row says when the plan started instead of echoing an internal id.
+      title = field(raw, 'planName'); statusLabel = words(field(raw, 'status'));
+      {
+        const started = when('startDate', 'short');
+        subtitle = started ? copyTemplate('ownerModules.startedOn', 'Started {date}', { date: started }) : '';
+      }
+      details = [['Started', when('startDate')], ['Ends', when('endDate')], ['Payment', words(field(raw, 'lastPaymentStatus'))]];
       break;
     case 'programs':
       title = field(raw, 'description.title') || field(raw, 'details.title') || field(raw, 'name');
@@ -203,13 +264,14 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
       break;
     }
     case 'reservations':
-      title = name(raw, 'reservee.firstName', 'reservee.lastName'); subtitle = field(raw, 'details.startDate'); statusLabel = words(field(raw, 'status'));
+      title = name(raw, 'reservee.firstName', 'reservee.lastName'); subtitle = when('details.startDate', 'dateTime'); statusLabel = words(field(raw, 'status'));
       details = [['Arrival', subtitle], ['Party size', field(raw, 'details.partySize')], ['Email', field(raw, 'reservee.email')], ['Phone', field(raw, 'reservee.phone')]];
       break;
     case 'forms':
-      title = field(raw, 'name'); subtitle = field(raw, 'namespace');
+      // The list is filtered to one namespace (`wix.form_app.form`), so the namespace is an
+      // internal constant, not information — it never reaches copy.
+      title = field(raw, 'name') || copyParam('ownerModules.untitledForm', 'Untitled form');
       statusLabel = typeof at(raw, 'enabled') === 'boolean' ? at(raw, 'enabled') ? 'Enabled' : 'Disabled' : '';
-      details = [['Namespace', subtitle]];
       break;
     case 'portfolio':
       title = field(raw, 'title'); subtitle = field(raw, 'description'); image = portfolioCoverRef(at(raw, 'coverImage') as WixMediaImage | string | undefined);
@@ -217,20 +279,25 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
       break;
     case 'donationCampaigns':
       title = field(raw, 'name');
-      subtitle = join(field(raw, 'campaignGoal.targetAmount.formattedAmount'), field(raw, 'campaignGoal.endDate'));
+      {
+        const end = when('campaignGoal.endDate', 'short');
+        subtitle = join(field(raw, 'campaignGoal.targetAmount.formattedAmount'), !end ? ''
+          : ownerPast(field(raw, 'campaignGoal.endDate')) ? copyTemplate('ownerModules.endedOn', 'ended {date}', { date: end })
+          : copyTemplate('ownerModules.endsOn', 'ends {date}', { date: end }));
+      }
       image = field(raw, 'coverImage');
       statusLabel = at(raw, 'archived') === true ? 'Archived' : words(field(raw, 'status'));
       details = [
         ['Goal', field(raw, 'campaignGoal.targetAmount.formattedAmount') || field(raw, 'campaignGoal.targetAmount.amount')],
-        ['End date', field(raw, 'campaignGoal.endDate')],
+        ['End date', when('campaignGoal.endDate')],
         ['Frequencies', Array.isArray(at(raw, 'donationFrequencies')) ? (at(raw, 'donationFrequencies') as unknown[]).map(String).join(', ') : ''],
         ['Custom amount', yesNo(at(raw, 'customAmountEnabled'))],
       ];
       break;
   }
   details.push(
-    ['Created', field(raw, 'createdDate') || field(raw, 'dateCreated') || field(raw, 'createDate')],
-    ['Updated', field(raw, 'updatedDate') || field(raw, 'updateDate')],
+    ['Created', when('createdDate') || when('dateCreated') || when('createDate')],
+    ['Updated', when('updatedDate') || when('updateDate')],
   );
   return { id, moduleId: module, title: title || copyParam('ownerModules.untitled', 'Untitled record'), subtitle, image: wixMediaUrl(image), statusLabel,
     detailScreenId: `himi_owner_lite_record_${module}`,
@@ -240,6 +307,7 @@ export function ownerRecord(module: OwnerModuleId, raw: unknown): OwnerRecord {
 
 export async function getOwnerRecord(module: OwnerModuleId, id: string): Promise<OwnerRecord> {
   if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(id)) throw new Error('This record link is invalid. Return to the collection.');
+  const zone = siteZone(); // started now, beside the record fetch; it never rejects
   let raw: unknown;
   switch (module) {
     case 'coupons': raw = (await getCoupon(id)).coupon; break;
@@ -270,13 +338,13 @@ export async function getOwnerRecord(module: OwnerModuleId, id: string): Promise
         seen.add(next); cursor = next;
       }
       if (!raw) throw new Error('This project could not be located. Open the portfolio in Wix to check its availability.');
-      const record = ownerRecord(module, raw);
+      const record = ownerRecord(module, raw, await zone);
       const media = await listProjectItems(id, 100);
       return { ...record, fields: [...record.fields, { id: 'media', label: 'Loaded media items', value: String(media.items?.length ?? 0) }] };
     }
     case 'donationCampaigns': raw = (await getDonationCampaign(id)).donationCampaign; break;
   }
-  const record = ownerRecord(module, raw);
+  const record = ownerRecord(module, raw, await zone);
   if (record.id !== id) throw new Error('The returned record does not match this link. Refresh the collection.');
   return record;
 }

package/templates/community-club-owner/tier5-src/himi-owner-lite-aria-history/index.ts

@@ -26,6 +26,7 @@ const core = createAriaHistory({
     last7: () => copyParam("ownerAriaHistory.last7", "Last 7 days"),
     last30: () => copyParam("ownerAriaHistory.last30", "Last 30 days"),
     older: () => copyParam("ownerAriaHistory.older", "Older"),
+    today: () => copyParam("ownerAriaHistory.today", "Today"),
   },
 });
 

package/templates/community-club-owner/tier5-src/himi-owner-lite-home/index.ts

@@ -84,6 +84,10 @@ interface HomeState {
   notLoading: boolean;
   notErrored: boolean;
   hideContent: boolean;
+  /** The retry cards' list is hidden unless the dashboard is ready AND a source failed.
+   *  An empty list still costs its parent stack a gap, which on iOS read as a blank
+   *  band under the header; gating on `hideContent` alone left it mounted. */
+  hideSourceFailures: boolean;
   demoNote: string;
   notDemo: boolean;
 }
@@ -145,6 +149,7 @@ function shape(s: Partial<HomeState>): HomeState {
     notLoading: !isLoading,
     notErrored: status !== "error",
     hideContent: status !== "ready",
+    hideSourceFailures: status !== "ready" || !(s.sourceFailures?.length),
     demoNote: s.demoNote ?? "",
     notDemo: !s.demoNote,
   };

package/templates/community-club-owner/tier5-src/himi-owner-lite-manage/index.ts

@@ -39,6 +39,8 @@ interface State {
   noEmpty: boolean;
   hasRecents: boolean;
   noRecents: boolean;
+  /** True while `sections` is empty — gates the list so an empty one costs no gap. */
+  noSections: boolean;
   isLoading: boolean;
   notLoading: boolean;
   summaryNote: string;
@@ -200,7 +202,7 @@ function derive(state: State, areas = state.areas): State {
   // areas arrive — or when this app provisions none at all — there is nothing a
   // filter could have excluded, so "Clear filters" would be a lie.
   const noEmpty = next.noEmpty || state.status !== 'ready' || areas.length === 0;
-  return { ...state, ...next, noEmpty, recents, hasRecents: recents.length > 0, noRecents: recents.length === 0, businessName: currentBusinessName };
+  return { ...state, ...next, noEmpty, recents, hasRecents: recents.length > 0, noRecents: recents.length === 0, noSections: next.sections.length === 0, businessName: currentBusinessName };
 }
 
 // Loads are not serialized: on a warm reappearance the host's bare refresh and
@@ -276,7 +278,7 @@ const svc = defineService<State, {
     // 'All' is always a valid filter, so the chip row paints from the first frame
     // instead of appearing (and shifting the layout) when the areas arrive.
     groups: [{ id: 'all', label: allLabel() }], summary: '', noEmpty: true,
-    hasRecents: false, noRecents: true, isLoading: true, notLoading: false, summaryNote: '', handoffError: '',
+    hasRecents: false, noRecents: true, noSections: true, isLoading: true, notLoading: false, summaryNote: '', handoffError: '',
   },
   actions: {
     load: async (state, arg) => {

package/templates/events-meetups/tier5-src/_shared/engine-intl.ts

@@ -48,6 +48,36 @@ const MONTHS_LONG = [
   "July", "August", "September", "October", "November", "December",
 ] as const;
 
+/**
+ * A DateTimeFormat for `timeZone` when one is given and this engine knows it. An unknown or
+ * malformed IANA id is a RangeError in ECMA-402; these helpers never throw, so it degrades to
+ * the device zone rather than killing the screen. Without Intl there is no zone database at all,
+ * and the fallbacks below render in the device zone for the same reason.
+ *
+ * Formatters are memoised per (locale, zone, options): a management page formats several dates
+ * per row, and building a DateTimeFormat (or throwing on a bad zone) each time is not free on
+ * JSC or QuickJS. Only call it where `hasIntl()` holds — every caller does.
+ */
+const FORMATTERS = new Map<string, Intl.DateTimeFormat>();
+function dateFormat(locale: string, options: Intl.DateTimeFormatOptions, timeZone?: string): Intl.DateTimeFormat {
+  const key = `${locale}|${timeZone ?? ""}|${JSON.stringify(options)}`;
+  let formatter = FORMATTERS.get(key);
+  if (!formatter) {
+    if (hasIntl()) {
+      if (timeZone) {
+        try {
+          formatter = new Intl.DateTimeFormat(locale, { ...options, timeZone });
+        } catch {
+          /* unknown zone: device zone below, remembered under this key */
+        }
+      }
+      formatter ??= new Intl.DateTimeFormat(locale, options);
+      FORMATTERS.set(key, formatter);
+    }
+  }
+  return formatter as Intl.DateTimeFormat;
+}
+
 // The four shapes below are not invented — they are the option bags this corpus actually uses,
 // counted across every bundle: "Jan 5, 2026" (33 sites), "Jan 5" (11), "Mon, Jan 5, 3:07 PM" (8)
 // and "Jan 5, 3:07 PM" (4). Naming them means a conversion is a one-line swap rather than a
@@ -55,46 +85,46 @@ const MONTHS_LONG = [
 // ECMA-402 in engine-intl-fallback.test.ts.
 
 /** `{ month: "short", day: "numeric", year: "numeric" }` — "Jan 5, 2026". */
-export function formatDateMedium(date: Date, locale = "en-US"): string {
+export function formatDateMedium(date: Date, locale = "en-US", timeZone?: string): string {
   if (hasIntl()) {
-    return new Intl.DateTimeFormat(locale, { month: "short", day: "numeric", year: "numeric" }).format(date);
+    return dateFormat(locale, { month: "short", day: "numeric", year: "numeric" }, timeZone).format(date);
   }
   return `${MONTHS_SHORT[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
 }
 
 /** `{ month: "short", day: "numeric" }` — "Jan 5". */
-export function formatMonthDay(date: Date, locale = "en-US"): string {
+export function formatMonthDay(date: Date, locale = "en-US", timeZone?: string): string {
   if (hasIntl()) {
-    return new Intl.DateTimeFormat(locale, { month: "short", day: "numeric" }).format(date);
+    return dateFormat(locale, { month: "short", day: "numeric" }, timeZone).format(date);
   }
   return `${MONTHS_SHORT[date.getMonth()]} ${date.getDate()}`;
 }
 
 /** `{ month: "long", day: "numeric" }` — "January 5". */
-export function formatMonthDayLong(date: Date, locale = "en-US"): string {
+export function formatMonthDayLong(date: Date, locale = "en-US", timeZone?: string): string {
   if (hasIntl()) {
-    return new Intl.DateTimeFormat(locale, { month: "long", day: "numeric" }).format(date);
+    return dateFormat(locale, { month: "long", day: "numeric" }, timeZone).format(date);
   }
   return `${MONTHS_LONG[date.getMonth()]} ${date.getDate()}`;
 }
 
 /** `{ weekday: "short", month: "short", day: "numeric", hour: "numeric", minute: "2-digit" }`
  *  — "Mon, Jan 5, 3:07 PM". */
-export function formatWeekdayDateTime(date: Date, locale = "en-US"): string {
+export function formatWeekdayDateTime(date: Date, locale = "en-US", timeZone?: string): string {
   if (hasIntl()) {
-    return new Intl.DateTimeFormat(locale, {
+    return dateFormat(locale, {
       weekday: "short", month: "short", day: "numeric", hour: "numeric", minute: "2-digit",
-    }).format(date);
+    }, timeZone).format(date);
   }
   return `${WEEKDAYS_SHORT[date.getDay()]}, ${MONTHS_SHORT[date.getMonth()]} ${date.getDate()}, ${clock12(date)}`;
 }
 
 /** `{ month: "short", day: "numeric", hour: "numeric", minute: "2-digit" }` — "Jan 5, 3:07 PM". */
-export function formatMonthDayTime(date: Date, locale = "en-US"): string {
+export function formatMonthDayTime(date: Date, locale = "en-US", timeZone?: string): string {
   if (hasIntl()) {
-    return new Intl.DateTimeFormat(locale, {
+    return dateFormat(locale, {
       month: "short", day: "numeric", hour: "numeric", minute: "2-digit",
-    }).format(date);
+    }, timeZone).format(date);
   }
   return `${MONTHS_SHORT[date.getMonth()]} ${date.getDate()}, ${clock12(date)}`;
 }
@@ -380,9 +410,9 @@ export function normalizeFormattedPrice(formatted: string): string {
   return `${m[1]}${m[3]}${m[2]}`;
 }
 
-function clockParts(d: Date, locale: string): { time: string; meridiem: string } {
+function clockParts(d: Date, locale: string, timeZone?: string): { time: string; meridiem: string } {
   const full = hasIntl()
-    ? new Intl.DateTimeFormat(locale, { hour: "numeric", minute: "2-digit", hour12: true }).format(d)
+    ? dateFormat(locale, { hour: "numeric", minute: "2-digit", hour12: true }, timeZone).format(d)
     : clock12(d);
   // ICU puts a narrow no-break space before the meridiem; normalize so callers can split on it.
   const clean = full.replace(/[  ]/g, " ");
@@ -391,8 +421,8 @@ function clockParts(d: Date, locale: string): { time: string; meridiem: string }
 }
 
 /** "8:00 PM" — the one clock every customer screen uses (12-hour, en-US shape). */
-export function formatClock(date: Date, locale = "en-US"): string {
-  const { time, meridiem } = clockParts(date, locale);
+export function formatClock(date: Date, locale = "en-US", timeZone?: string): string {
+  const { time, meridiem } = clockParts(date, locale, timeZone);
   return meridiem ? `${time} ${meridiem}` : time;
 }
 
@@ -403,3 +433,14 @@ export function isPastDate(iso: string | undefined | null, now: number = Date.no
   const t = Date.parse(iso);
   return !Number.isNaN(t) && t < now;
 }
+
+/** The calendar day `date` falls on in `timeZone` (device zone when absent, unknown, or when
+ *  the engine has no Intl), as `YYYY-MM-DD`. For "is this today / this year" comparisons. */
+export function calendarDay(date: Date, timeZone?: string): string {
+  if (hasIntl()) {
+    const parts = dateFormat("en-CA", { year: "numeric", month: "2-digit", day: "2-digit" }, timeZone).formatToParts(date);
+    const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+    return `${get("year")}-${get("month")}-${get("day")}`;
+  }
+  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+}