@startsimpli/integrations 0.2.48 → 0.2.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.48",
+  "version": "0.2.50",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps, plus foundry customer email (subpath ./comms).",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -35,7 +35,7 @@
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0",
     "@startsimpli/llm": ">=0.4.0",
-    "@startsimpli/ui": "^0.4.162"
+    "@startsimpli/ui": "^0.4.164"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -64,8 +64,8 @@
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
-    "@startsimpli/llm": "0.4.25",
-    "@startsimpli/ui": "0.4.162"
+    "@startsimpli/ui": "0.4.164",
+    "@startsimpli/llm": "0.4.25"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

package/src/comms/__tests__/customer-emails-page.test.tsx

@@ -241,7 +241,7 @@ describe('overview (A1)', () => {
     await comebackSwitch();
     for (const name of [
       /^comeback sequence settings$/i, /^product updates$/i, /^approval$/i,
-      /^voice$/i, /^sending domain$/i, /^results$/i, /^send log$/i,
+      /^voice$/i, /^time zone$/i, /^sending domain$/i, /^results$/i, /^send log$/i,
     ]) {
       expect(screen.getByRole('button', { name })).toHaveAttribute('aria-expanded', 'false');
     }

package/src/comms/__tests__/fixtures.ts

@@ -33,6 +33,7 @@ export const settings = (over: Partial<CommsSettings> = {}): CommsSettings => ({
   domain_records: [],
   domain_checked_at: null,
   paused: false,
+  default_timezone: '',
   source_repos: [],
   from_address: 'Crochets <crochets@mail.startsimpli.com>',
   ...over,

package/src/comms/__tests__/recipient-local-send.test.tsx

@@ -0,0 +1,358 @@
+/**
+ * Recipient-local-time sends in the comms UI (bd startsim-ofio9.4, epic
+ * startsim-ofio9): the schedule picker's "exact time" vs "each recipient's own
+ * time zone" choice with the no-known-zone count and the fallback that applies,
+ * the default_timezone setting, and per-zone progress in the scheduled list.
+ * A mocked Django (msw) behind the REAL createCommsApi client.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+import { DefaultTimeZoneSetting } from '../components/DefaultTimeZoneSetting';
+import { DraftReview } from '../components/DraftReview';
+import { SendLog } from '../components/SendLog';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { CommsSettings, Draft, DraftGroup, ScheduledSend } from '../types/index';
+import { BASE, P, SLUG, draft, settings } from './fixtures';
+
+interface Hit { method: string; path: string; body: any }
+let hits: Hit[] = [];
+let drafts: Draft[] = [];
+let scheduledReport: ScheduledSend[] = [];
+let commsSettings: CommsSettings = settings();
+let noTimezone: number | undefined = 3;
+
+const rel = (p: string) => p.replace(new URL(P).pathname, '');
+
+const server = setupServer(
+  http.all(`${P}/*`, async ({ request }) => {
+    const url = new URL(request.url);
+    const text = request.method === 'GET' ? '' : await request.text();
+    const hit: Hit = { method: request.method, path: rel(url.pathname), body: text ? JSON.parse(text) : undefined };
+    hits.push(hit);
+    const { method, path, body } = hit;
+    let m: RegExpMatchArray | null;
+    if (path === '/settings/') {
+      if (method === 'PATCH') commsSettings = { ...commsSettings, ...body };
+      return HttpResponse.json(commsSettings);
+    }
+    if (path === '/drafts/' && method === 'GET') {
+      const wanted = url.searchParams.get('status');
+      const results = drafts.filter((d) => !wanted || d.approval === wanted);
+      return HttpResponse.json({ count: results.length, next: null, previous: null, results });
+    }
+    if ((m = path.match(/^\/drafts\/([\w-]+)\/(approve|reschedule|cancel)\/$/)) && method === 'POST') {
+      const d = drafts.find((x) => x.id === m![1])!;
+      if (m[2] === 'approve' && body?.send_mode === 'recipient_local') {
+        Object.assign(d, { approval: 'scheduled', state: 'scheduled', send_mode: 'recipient_local', local_time: `${body.send_at}:00`, send_at: '2026-11-19T19:00:00+00:00', groups: [] });
+      } else if (m[2] === 'approve') {
+        d.approval = 'approved';
+      } else if (m[2] === 'reschedule') {
+        Object.assign(d, { local_time: `${body.send_at}:00` });
+      } else {
+        Object.assign(d, { approval: 'sent', state: 'sent', notice: { code: 'cancelled_partial', reason: 'Cancelled. 6 recipients in 5 time zones had not been sent and will not be. 1 recipient in 1 time zone was already sent or started and cannot be recalled.' } });
+      }
+      return HttpResponse.json(d);
+    }
+    if ((m = path.match(/^\/drafts\/([\w-]+)\/audience\/$/)) && method === 'GET') {
+      const preview: any = { count: 7, eligible: 7, excluded: {}, excluded_total: 0, sample: [], excluded_sample: [] };
+      if (noTimezone !== undefined) preview.no_timezone = noTimezone;
+      return HttpResponse.json({ audience: { base: 'all' }, is_default: true, preview });
+    }
+    if (path === '/sends/' && method === 'GET') {
+      return HttpResponse.json({ count: 0, next: null, previous: null, results: [], scheduled: scheduledReport });
+    }
+    return HttpResponse.json({ detail: `unhandled ${method} ${path}` }, { status: 599 });
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+beforeEach(() => {
+  hits = [];
+  drafts = [draft()];
+  scheduledReport = [];
+  commsSettings = settings();
+  noTimezone = 3;
+});
+
+function renderWith(node: (api: ReturnType<typeof createCommsApi>) => React.ReactElement) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });
+  return render(<QueryClientProvider client={qc}>{node(createCommsApi(SLUG))}</QueryClientProvider>);
+}
+
+const writes = () => hits.filter((h) => h.method !== 'GET');
+const LOCAL = 'In each recipient.s own time zone';
+const EXACT = 'At this exact time';
+
+async function openPicker() {
+  await userEvent.click(await screen.findByRole('button', { name: /schedule/i }));
+}
+
+const group = (over: Partial<DraftGroup>): DraftGroup => ({
+  zone: 'Asia/Tokyo', at: '2026-11-20T00:00:00+00:00', state: 'waiting', late: false, note: null,
+  sources: { browser: 1, foundry_default: 0, utc: 0 }, count: 1, pending: 1, sent: 0, failed: 0, suppressed: 0,
+  started_at: null, completed_at: null, failure: null, reason: null, ...over,
+});
+
+const rolling = (over: Partial<Draft> = {}): Draft => draft({
+  approval: 'rolling', state: 'rolling', next_actions: ['reschedule', 'send_now', 'cancel'],
+  send_mode: 'recipient_local', local_time: '2026-11-20T09:00:00', send_at: '2026-11-20T00:00:00+00:00',
+  recipient_count: 3,
+  groups: [
+    group({ zone: 'Pacific/Kiritimati', at: '2026-11-19T19:00:00+00:00', state: 'sent', pending: 0, sent: 1 }),
+    group({ zone: 'Asia/Tokyo', state: 'sending', count: 2, pending: 1, sent: 1 }),
+    group({ zone: 'America/New_York', at: '2026-11-20T14:00:00+00:00' }),
+  ],
+  group_summary: { total: 3, waiting: 1, sending: 1, sent: 1, failed: 0, expired: 0, cancelled: 0 },
+  ...over,
+});
+
+describe('the schedule picker offers two ways to time a send', () => {
+  it('defaults to the exact time and shows the choice', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    expect(screen.getByRole('radio', { name: EXACT })).toBeChecked();
+    expect(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') })).not.toBeChecked();
+    expect(screen.getByLabelText('Time zone')).toBeInTheDocument();
+  });
+
+  it('exact mode still posts the instant with its zone and no send_mode', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    fireEvent.change(screen.getByLabelText('Send at'), { target: { value: '2026-11-03T10:00' } });
+    await userEvent.selectOptions(screen.getByLabelText('Time zone'), 'Asia/Tokyo');
+    await userEvent.click(screen.getByRole('button', { name: /approve and schedule/i }));
+    await waitFor(() => expect(writes()[0].body).toEqual({ send_at: '2026-11-03T10:00', timezone: 'Asia/Tokyo' }));
+  });
+
+  it('local mode posts the wall-clock time with send_mode and no time zone', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    await userEvent.click(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') }));
+    expect(screen.queryByLabelText('Time zone')).toBeNull();
+    fireEvent.change(screen.getByLabelText('Send at'), { target: { value: '2026-11-20T09:00' } });
+    await userEvent.click(screen.getByRole('button', { name: /approve and schedule/i }));
+    await waitFor(() =>
+      expect(writes()[0]).toMatchObject({
+        method: 'POST', path: '/drafts/d-1/approve/', body: { send_at: '2026-11-20T09:00', send_mode: 'recipient_local' },
+      }),
+    );
+    expect(writes()[0].body.timezone).toBeUndefined();
+  });
+
+  it('says how many recipients have no known zone and that UTC applies when no default is set', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    await userEvent.click(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') }));
+    expect(await screen.findByText(/3 recipients have no known time zone/i)).toBeInTheDocument();
+    expect(await screen.findByText(/no default time zone is set.*UTC/i)).toBeInTheDocument();
+  });
+
+  it('names the default time zone as the fallback when one is set', async () => {
+    commsSettings = settings({ default_timezone: 'Europe/Paris' });
+    noTimezone = 1;
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    await userEvent.click(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') }));
+    expect(await screen.findByText(/1 recipient has no known time zone/i)).toBeInTheDocument();
+    expect(await screen.findByText(/they get Europe\/Paris, your default time zone/i)).toBeInTheDocument();
+  });
+
+  it('says so when every recipient has a known zone', async () => {
+    noTimezone = 0;
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    await userEvent.click(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') }));
+    expect(await screen.findByText(/every recipient has a known time zone/i)).toBeInTheDocument();
+  });
+
+  it('explains the span and the late-zone rule in plain words', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    await userEvent.click(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') }));
+    expect(screen.getByText(/up to 26 hours/i)).toBeInTheDocument();
+    expect(screen.getByText(/zones where that time has passed send immediately/i)).toBeInTheDocument();
+  });
+
+  it('asks the audience only once local mode is chosen', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await openPicker();
+    expect(hits.filter((h) => h.path.endsWith('/audience/') && h.path.includes('d-1'))).toHaveLength(0);
+  });
+});
+
+describe('a scheduled recipient-local draft', () => {
+  beforeEach(() => {
+    drafts = [draft({
+      approval: 'scheduled', state: 'scheduled', send_mode: 'recipient_local', local_time: '2026-11-20T09:00:00',
+      send_at: '2026-11-19T19:00:00+00:00', send_timezone: null, recipient_count: 7, groups: [],
+    })];
+  });
+
+  it('is listed as 9:00 in each recipient\'s own time zone', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    const heading = await screen.findByRole('heading', { name: /scheduled to send/i });
+    const list = within(heading.parentElement as HTMLElement);
+    expect(await list.findByText(/in each recipient.s own time zone/i)).toBeInTheDocument();
+    expect(list.getByText(/9:00/)).toBeInTheDocument();
+    expect(list.getByText(/people who join after the first zone starts are not included/i)).toBeInTheDocument();
+  });
+
+  it('reschedules with the local picker preselected', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^reschedule$/i }));
+    expect(screen.getByRole('radio', { name: new RegExp(LOCAL, 'i') })).toBeChecked();
+    fireEvent.change(screen.getByLabelText('Send at'), { target: { value: '2026-11-22T08:30' } });
+    await userEvent.click(screen.getByRole('button', { name: /move send/i }));
+    await waitFor(() =>
+      expect(writes()[0]).toMatchObject({
+        path: '/drafts/d-1/reschedule/', body: { send_at: '2026-11-22T08:30', send_mode: 'recipient_local' },
+      }),
+    );
+  });
+});
+
+describe('a rolling recipient-local draft', () => {
+  beforeEach(() => {
+    drafts = [rolling()];
+  });
+
+  it('shows per-zone progress, soonest first', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    const table = await screen.findByRole('table', { name: /progress by time zone/i });
+    const rows = within(table).getAllByRole('row').slice(1);
+    expect(rows).toHaveLength(3);
+    expect(rows[0]).toHaveTextContent('Pacific/Kiritimati');
+    expect(rows[0]).toHaveTextContent(/sent/i);
+    expect(rows[0]).toHaveTextContent('1 of 1');
+    expect(rows[1]).toHaveTextContent('Asia/Tokyo');
+    expect(rows[1]).toHaveTextContent(/sending/i);
+    expect(rows[1]).toHaveTextContent('1 of 2');
+    expect(rows[2]).toHaveTextContent('America/New_York');
+    expect(rows[2]).toHaveTextContent(/waiting/i);
+  });
+
+  it('summarises how many zones have gone out', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/2 of 3 time zones started/i)).toBeInTheDocument();
+  });
+
+  it('says what cancel does to zones already sent', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/zones already sent cannot be recalled/i)).toBeInTheDocument();
+  });
+
+  it('cancel posts cancel and shows what the server says was and was not sent', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /cancel remaining zones/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/cancel/' }));
+  });
+
+  it('shows a failed zone with its reason', async () => {
+    drafts = [rolling({
+      groups: [group({ zone: 'Asia/Tokyo', state: 'failed', pending: 2, count: 2,
+        failure: { stage: 'send', code: 'recipients_not_sent', reason: '2 recipients still unsent after 3 retries' } })],
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    const table = await screen.findByRole('table', { name: /progress by time zone/i });
+    expect(within(table).getByText(/2 recipients still unsent after 3 retries/i)).toBeInTheDocument();
+  });
+
+  it('marks a zone that went out late and one with a clock-change note', async () => {
+    drafts = [rolling({
+      groups: [
+        group({ zone: 'Asia/Tokyo', state: 'sending', late: true }),
+        group({ zone: 'America/New_York', state: 'waiting', note: 'gap' }),
+      ],
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    const table = await screen.findByRole('table', { name: /progress by time zone/i });
+    expect(within(table).getByText(/sent late/i)).toBeInTheDocument();
+    expect(within(table).getByText(/clock change skips this time/i)).toBeInTheDocument();
+    expect(within(table).getByText(/first moment after the change/i)).toBeInTheDocument();
+    expect(within(table).queryByText(/elapsed/i)).toBeNull();
+  });
+
+  it('says the plan is frozen at the first zone, before and after it starts', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/people who join after the first zone starts are not included/i)).toBeInTheDocument();
+  });
+
+  it('Send now asks first, says what it does, and posts only on confirm', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^send now$/i }));
+    expect(writes()).toEqual([]);
+    expect(screen.getByText(/send now starts every waiting time zone immediately/i)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: /yes, start every waiting zone/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/approve/' }));
+    expect(writes()[0].body).toBeUndefined();
+  });
+
+  it('Send now can be backed out of with no write', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^send now$/i }));
+    await userEvent.click(screen.getByRole('button', { name: /keep waiting/i }));
+    expect(screen.queryByText(/send now starts every waiting time zone/i)).toBeNull();
+    expect(writes()).toEqual([]);
+  });
+});
+
+describe('send log', () => {
+  it('lists a rolling draft with its progress reason', async () => {
+    scheduledReport = [{
+      id: 'r-1', program_key: 'announcement', subject: 'Global news', status: 'rolling',
+      reason: '2 of 3 time zones started; next: America/New_York at 2026-11-20T14:00:00+00:00',
+      send_at: '2026-11-20T14:00:00+00:00', send_timezone: null, cancelled_at: null,
+      send_mode: 'recipient_local', local_time: '2026-11-20T09:00:00', groups: [], group_summary: null,
+    }];
+    renderWith((api) => <SendLog api={api} />);
+    expect(await screen.findByText('Global news')).toBeInTheDocument();
+    expect(screen.getByText('rolling')).toBeInTheDocument();
+    expect(screen.getByText(/2 of 3 time zones started/i)).toBeInTheDocument();
+    expect(screen.getByText(/in each recipient.s own time zone/i)).toBeInTheDocument();
+  });
+});
+
+describe('default time zone setting', () => {
+  it('shows the current value and saves a new one', async () => {
+    commsSettings = settings({ default_timezone: 'Europe/Paris' });
+    renderWith((api) => <DefaultTimeZoneSetting api={api} />);
+    const select = await screen.findByLabelText(/default time zone/i);
+    expect(select).toHaveValue('Europe/Paris');
+    await userEvent.selectOptions(select, 'America/Denver');
+    await userEvent.click(screen.getByRole('button', { name: /save/i }));
+    await waitFor(() =>
+      expect(writes()[0]).toMatchObject({ method: 'PATCH', path: '/settings/', body: { default_timezone: 'America/Denver' } }),
+    );
+    expect(await screen.findByText(/saved/i)).toBeInTheDocument();
+  });
+
+  it('can be cleared back to UTC', async () => {
+    commsSettings = settings({ default_timezone: 'Europe/Paris' });
+    renderWith((api) => <DefaultTimeZoneSetting api={api} />);
+    await userEvent.selectOptions(await screen.findByLabelText(/default time zone/i), '');
+    await userEvent.click(screen.getByRole('button', { name: /save/i }));
+    await waitFor(() => expect(writes()[0].body).toEqual({ default_timezone: '' }));
+  });
+
+  it('explains what it is for', async () => {
+    renderWith((api) => <DefaultTimeZoneSetting api={api} />);
+    expect(await screen.findByText(/used for recipients whose own time zone is not known/i)).toBeInTheDocument();
+  });
+
+  it('makes no write until Save', async () => {
+    renderWith((api) => <DefaultTimeZoneSetting api={api} />);
+    await screen.findByLabelText(/default time zone/i);
+    expect(writes()).toEqual([]);
+  });
+});

package/src/comms/components/DefaultTimeZoneSetting.tsx

@@ -0,0 +1,67 @@
+/**
+ * The foundry's default time zone (bd startsim-ofio9.4): the zone used for
+ * recipients whose own zone is not known when a send is timed per recipient.
+ * Blank means UTC. PATCH settings.default_timezone.
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Label } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useCommsSettings, useUpdateCommsSettings } from '../hooks/index';
+import { ErrorNotice, NativeSelect, Note, timeZoneOptions, useFieldId } from './_shared';
+
+export interface DefaultTimeZoneSettingProps {
+  api: CommsApi;
+}
+
+function Form({ api, current }: { api: CommsApi; current: string }) {
+  const update = useUpdateCommsSettings(api);
+  const id = useFieldId('comms-default-zone');
+  const [zone, setZone] = useState(current);
+  const [saved, setSaved] = useState(false);
+  const options = Array.from(new Set([...(current ? [current] : []), ...timeZoneOptions()]));
+  return (
+    <form
+      className="space-y-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        setSaved(false);
+        update.mutate({ default_timezone: zone }, { onSuccess: () => setSaved(true) });
+      }}
+    >
+      <div className="space-y-1">
+        <Label htmlFor={id}>Default time zone</Label>
+        <div>
+          <NativeSelect
+            id={id}
+            value={zone}
+            onChange={(e) => {
+              setSaved(false);
+              setZone(e.target.value);
+            }}
+          >
+            <option value="">Not set (UTC)</option>
+            {options.map((z) => (
+              <option key={z} value={z}>{z}</option>
+            ))}
+          </NativeSelect>
+        </div>
+        <p className="text-sm text-muted-foreground">
+          Used for recipients whose own time zone is not known, when an email goes out at the same local time for
+          everyone. Without one, those recipients get UTC.
+        </p>
+      </div>
+      <div className="flex items-center gap-3">
+        <Button type="submit" disabled={update.isPending}>Save time zone</Button>
+        {saved ? <Note>Saved.</Note> : null}
+      </div>
+      <ErrorNotice error={update.error} />
+    </form>
+  );
+}
+
+export function DefaultTimeZoneSetting({ api }: DefaultTimeZoneSettingProps): ReactElement | null {
+  const { data: settings } = useCommsSettings(api);
+  if (!settings) return null;
+  return <Form api={api} current={settings.default_timezone ?? ''} />;
+}

package/src/comms/components/DraftReview.tsx

@@ -190,6 +190,8 @@ export function DraftItem({
       {previewing && preview.data ? <EmailPreview email={preview.data} /> : null}
       {scheduling && ready ? (
         <SchedulePicker
+          api={api}
+          draftId={draft.id}
           submitLabel="Approve and schedule"
           pending={approve.isPending}
           onCancel={() => setScheduling(false)}

package/src/comms/components/SchedulePicker.tsx

@@ -1,51 +1,123 @@
 /**
- * Pick when an approved draft goes out: a local date and time plus the time
- * zone it is meant in (default: the viewer's). The server stores the instant in
- * UTC; this form only collects the wall-clock time and the zone name.
+ * Pick when an approved draft goes out. Two ways:
+ *  - "At this exact time": a local date and time plus the time zone it is meant
+ *    in (default: the viewer's). The server stores the instant in UTC.
+ *  - "At this time in each recipient's own time zone": one wall-clock time that
+ *    every recipient gets on their own clock (9:00 for everyone, wherever they
+ *    are). Shows how many recipients have no known zone and which fallback
+ *    applies to them (the foundry's default time zone, else UTC).
  */
 import { useState, type ReactElement } from 'react';
 import { Button, Input, Label } from '@startsimpli/ui';
 
-import type { ScheduleInput } from '../types/index';
+import type { CommsApi } from '../api/comms';
+import { useCommsSettings, useDraftAudience } from '../hooks/index';
+import type { ScheduleInput, SendMode } from '../types/index';
 import { NativeSelect, localTimeZone, timeZoneOptions, useFieldId } from './_shared';
 
 export interface SchedulePickerProps {
+  api: CommsApi;
+  /** The draft being scheduled: its audience says how many recipients have no known zone. */
+  draftId: string;
   submitLabel: string;
   pending?: boolean;
+  /** Start on the per-recipient mode (rescheduling a recipient-local draft). */
+  initialMode?: SendMode;
+  /** Hide the exact-time choice: a rolling recipient-local draft can only take a local time. */
+  localOnly?: boolean;
   onSubmit: (schedule: ScheduleInput) => void;
   onCancel: () => void;
 }
 
-export function SchedulePicker({ submitLabel, pending, onSubmit, onCancel }: SchedulePickerProps): ReactElement {
+/** Who has no zone of their own, and what they get instead. */
+function ZoneNotice({ api, draftId }: { api: CommsApi; draftId: string }): ReactElement | null {
+  const audience = useDraftAudience(api, draftId, true).data?.preview;
+  const settings = useCommsSettings(api).data;
+  if (audience?.no_timezone === undefined) return null;
+  const n = audience.no_timezone;
+  if (n === 0) {
+    return <p className="basis-full text-xs text-muted-foreground">Every recipient has a known time zone.</p>;
+  }
+  const fallback = settings
+    ? settings.default_timezone
+      ? `They get ${settings.default_timezone}, your default time zone.`
+      : 'No default time zone is set, so they get UTC.'
+    : '';
+  return (
+    <p className="basis-full text-xs text-muted-foreground">
+      {`${n} ${n === 1 ? 'recipient has' : 'recipients have'} no known time zone. ${fallback}`.trim()}
+    </p>
+  );
+}
+
+export function SchedulePicker({
+  api,
+  draftId,
+  submitLabel,
+  pending,
+  initialMode = 'fixed',
+  localOnly,
+  onSubmit,
+  onCancel,
+}: SchedulePickerProps): ReactElement {
+  const [mode, setMode] = useState<SendMode>(localOnly ? 'recipient_local' : initialMode);
   const [when, setWhen] = useState('');
   const [zone, setZone] = useState(localTimeZone);
   const whenId = useFieldId('comms-send-at');
   const zoneId = useFieldId('comms-send-zone');
+  const modeName = useFieldId('comms-send-mode');
+  const local = mode === 'recipient_local';
   return (
     <form
       className="mt-2 flex flex-wrap items-end gap-3 rounded-md border p-3"
       onSubmit={(e) => {
         e.preventDefault();
-        if (when) onSubmit({ send_at: when, timezone: zone });
+        if (!when) return;
+        onSubmit(local ? { send_at: when, send_mode: 'recipient_local' } : { send_at: when, timezone: zone });
       }}
     >
+      {localOnly ? null : (
+        <fieldset className="basis-full space-y-1">
+          <legend className="sr-only">When it goes out</legend>
+          <label className="flex items-center gap-2 text-sm">
+            <input type="radio" name={modeName} checked={!local} onChange={() => setMode('fixed')} />
+            At this exact time
+          </label>
+          <label className="flex items-center gap-2 text-sm">
+            <input type="radio" name={modeName} checked={local} onChange={() => setMode('recipient_local')} />
+            At this time in each recipient&apos;s own time zone
+          </label>
+        </fieldset>
+      )}
       <div className="space-y-1">
         <Label htmlFor={whenId}>Send at</Label>
         <Input id={whenId} type="datetime-local" required value={when} onChange={(e) => setWhen(e.target.value)} />
       </div>
-      <div className="space-y-1">
-        <Label htmlFor={zoneId}>Time zone</Label>
-        <div>
-          <NativeSelect id={zoneId} value={zone} onChange={(e) => setZone(e.target.value)}>
-            {timeZoneOptions().map((z) => (
-              <option key={z} value={z}>{z}</option>
-            ))}
-          </NativeSelect>
+      {local ? null : (
+        <div className="space-y-1">
+          <Label htmlFor={zoneId}>Time zone</Label>
+          <div>
+            <NativeSelect id={zoneId} value={zone} onChange={(e) => setZone(e.target.value)}>
+              {timeZoneOptions().map((z) => (
+                <option key={z} value={z}>{z}</option>
+              ))}
+            </NativeSelect>
+          </div>
         </div>
-      </div>
-      <p className="basis-full text-xs text-muted-foreground">
-        A time that has already passed sends immediately.
-      </p>
+      )}
+      {local ? (
+        <>
+          <p className="basis-full text-xs text-muted-foreground">
+            Goes out at that time on each recipient&apos;s own clock, starting with the earliest zones. A worldwide
+            audience takes up to 26 hours to finish. Zones where that time has passed send immediately.
+          </p>
+          <ZoneNotice api={api} draftId={draftId} />
+        </>
+      ) : (
+        <p className="basis-full text-xs text-muted-foreground">
+          A time that has already passed sends immediately.
+        </p>
+      )}
       <Button type="submit" size="sm" disabled={pending || !when}>{submitLabel}</Button>
       <Button type="button" size="sm" variant="ghost" onClick={onCancel}>Close</Button>
     </form>

package/src/comms/components/ScheduledSends.tsx

@@ -2,6 +2,10 @@
  * Approved drafts waiting for their send time: when they go out, and the three
  * things you can still do before then (reschedule, send now, cancel). Once the
  * send starts the server refuses cancel and reschedule (409), shown as-is.
+ *
+ * A recipient-local draft ("9:00 in each recipient's own time zone") is listed
+ * too, and once its first zone has gone out it is "rolling": a per-zone progress
+ * table, and cancel / reschedule act on the zones that have not started only.
  */
 import { useState, type ReactElement } from 'react';
 import { Button } from '@startsimpli/ui';
@@ -15,9 +19,9 @@ import {
   useDrafts,
   useRescheduleDraft,
 } from '../hooks/index';
-import type { Draft } from '../types/index';
+import type { Draft, DraftGroup } from '../types/index';
 import { SchedulePicker } from './SchedulePicker';
-import { ErrorNotice, formatDateTime } from './_shared';
+import { ErrorNotice, Note, formatDateTime, formatLocalTime } from './_shared';
 
 export interface ScheduledSendsProps {
   api: CommsApi;
@@ -26,12 +30,58 @@ export interface ScheduledSendsProps {
   pageSize?: number;
 }
 
+function groupCell(g: DraftGroup): string {
+  if (g.state === 'waiting') return 'Waiting';
+  if (g.state === 'sending') return g.late ? 'Sending (sent late: its time had already passed)' : 'Sending';
+  if (g.state === 'sent') return g.late ? 'Sent late (its time had already passed)' : 'Sent';
+  if (g.state === 'failed') return `Failed${g.failure ? `: ${g.failure.reason}` : ''}`;
+  if (g.state === 'expired') return `Expired: ${g.reason ?? 'comms were paused at its time'}`;
+  return 'Cancelled';
+}
+
+function GroupProgress({ groups }: { groups: DraftGroup[] }) {
+  return (
+    <table className="mt-2 w-full text-left text-sm" aria-label="Progress by time zone">
+      <thead>
+        <tr className="text-muted-foreground">
+          <th className="py-1 pr-3 font-medium">Time zone</th>
+          <th className="py-1 pr-3 font-medium">Goes out</th>
+          <th className="py-1 pr-3 font-medium">State</th>
+          <th className="py-1 font-medium">Sent</th>
+        </tr>
+      </thead>
+      <tbody>
+        {groups.map((g) => (
+          <tr key={g.zone} className="border-t">
+            <td className="py-1 pr-3">{g.zone}</td>
+            <td className="py-1 pr-3">
+              {formatDateTime(g.at, g.zone)}
+              {g.note === 'gap'
+                ? ' (a clock change skips this time here, so it goes out at the first moment after the change)'
+                : g.note === 'overlap'
+                  ? ' (this time happens twice here; the first is used)'
+                  : ''}
+            </td>
+            <td className="py-1 pr-3">{groupCell(g)}</td>
+            <td className="py-1">{`${g.sent} of ${g.count}`}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
 function ScheduledItem({ api, draft }: { api: CommsApi; draft: Draft }) {
   const [moving, setMoving] = useState(false);
+  const [confirmingNow, setConfirmingNow] = useState(false);
   const reschedule = useRescheduleDraft(api);
   const cancel = useCancelDraft(api);
   const sendNow = useApproveDraft(api);
   const zone = draft.send_timezone || undefined;
+  const perZone = draft.send_mode === 'recipient_local';
+  const isRolling = draft.state === 'rolling' || draft.approval === 'rolling';
+  const groups = draft.groups ?? [];
+  const started = groups.filter((g) => g.state !== 'waiting').length;
   const live = useDraftAudience(api, draft.id, true).data?.preview.count;
   const frozen = draft.recipient_count;
   const count =
@@ -45,25 +95,60 @@ function ScheduledItem({ api, draft }: { api: CommsApi; draft: Draft }) {
       <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
         <span className="min-w-[10rem] flex-1 font-medium">{draft.subject || '(no subject)'}</span>
         <span className="text-sm text-muted-foreground">
-          {`Sends ${formatDateTime(draft.send_at, zone)}`}
-          {zone && zone !== 'UTC' ? ` (${formatDateTime(draft.send_at, 'UTC')})` : ''}
+          {perZone
+            ? `Sends ${formatLocalTime(draft.local_time)} in each recipient's own time zone`
+            : `Sends ${formatDateTime(draft.send_at, zone)}`}
+          {perZone && !isRolling ? ` (first zone ${formatDateTime(draft.send_at)})` : ''}
+          {!perZone && zone && zone !== 'UTC' ? ` (${formatDateTime(draft.send_at, 'UTC')})` : ''}
         </span>
         <div className="flex flex-wrap gap-2">
           <Button type="button" size="sm" variant="outline" onClick={() => setMoving((v) => !v)}>Reschedule</Button>
-          <Button type="button" size="sm" variant="outline" disabled={sendNow.isPending} onClick={() => sendNow.mutate(draft.id)}>
+          <Button type="button" size="sm" variant="outline" disabled={sendNow.isPending} onClick={() => (isRolling ? setConfirmingNow(true) : sendNow.mutate(draft.id))}>
             Send now
           </Button>
           <Button type="button" size="sm" variant="ghost" disabled={cancel.isPending} onClick={() => cancel.mutate(draft.id)}>
-            Cancel schedule
+            {isRolling ? 'Cancel remaining zones' : 'Cancel schedule'}
           </Button>
         </div>
       </div>
       {count ? <p className="text-sm text-muted-foreground">{count}</p> : null}
+      {perZone ? (
+        <p className="text-sm text-muted-foreground">
+          People who join after the first zone starts are not included.
+        </p>
+      ) : null}
+      {isRolling && confirmingNow ? (
+        <div className="flex flex-wrap items-center gap-2 text-sm">
+          <span>Send now starts every waiting time zone immediately.</span>
+          <Button
+            type="button"
+            size="sm"
+            disabled={sendNow.isPending}
+            onClick={() => sendNow.mutate(draft.id, { onSuccess: () => setConfirmingNow(false) })}
+          >
+            Yes, start every waiting zone
+          </Button>
+          <Button type="button" size="sm" variant="ghost" onClick={() => setConfirmingNow(false)}>Keep waiting</Button>
+        </div>
+      ) : null}
+      {isRolling ? (
+        <>
+          <p className="text-sm text-muted-foreground">
+            {`${started} of ${groups.length} time zones started. Cancel stops the zones that have not started; zones already sent cannot be recalled.`}
+          </p>
+          {groups.length ? <GroupProgress groups={groups} /> : null}
+          {draft.notice ? <Note>{draft.notice.reason}</Note> : null}
+        </>
+      ) : null}
       {draft.dispatch_error ? (
         <p className="text-sm text-muted-foreground">{`Trying again: ${draft.dispatch_error}`}</p>
       ) : null}
       {moving ? (
         <SchedulePicker
+          api={api}
+          draftId={draft.id}
+          initialMode={perZone ? 'recipient_local' : 'fixed'}
+          localOnly={isRolling}
           submitLabel="Move send"
           pending={reschedule.isPending}
           onCancel={() => setMoving(false)}
@@ -78,17 +163,20 @@ function ScheduledItem({ api, draft }: { api: CommsApi; draft: Draft }) {
 export function ScheduledSends({ api, pollIntervalMs = DEFAULT_POLL_MS, pageSize = 10 }: ScheduledSendsProps): ReactElement | null {
   const [page, setPage] = useState(1);
   const drafts = useDrafts(api, { status: 'scheduled', page, page_size: pageSize }, pollIntervalMs);
-  if (drafts.error) return <ErrorNotice error={drafts.error} />;
-  if (!drafts.data?.results.length) return null;
+  const rolling = useDrafts(api, { status: 'rolling', page: 1, page_size: 50 }, pollIntervalMs);
+  const error = drafts.error ?? rolling.error;
+  if (error) return <ErrorNotice error={error} />;
+  const rows = [...(rolling.data?.results ?? []), ...(drafts.data?.results ?? [])];
+  if (!rows.length) return null;
   return (
     <div className="space-y-1">
       <h3 className="text-sm font-medium">Scheduled to send</h3>
       <ul className="divide-y">
-        {drafts.data.results.map((d) => (
+        {rows.map((d) => (
           <ScheduledItem key={d.id} api={api} draft={d} />
         ))}
       </ul>
-      {drafts.data.count > pageSize ? (
+      {drafts.data && drafts.data.count > pageSize ? (
         <div className="flex items-center gap-2 text-sm">
           <Button type="button" size="sm" variant="outline" disabled={!drafts.data.previous} onClick={() => setPage(page - 1)}>
             Previous

package/src/comms/components/SendLog.tsx

@@ -18,7 +18,7 @@ import {
 import type { CommsApi } from '../api/comms';
 import { useSends } from '../hooks/index';
 import { COMEBACK_PROGRAM_KEY, PRODUCT_UPDATE_PROGRAM_KEY } from '../types/index';
-import { ErrorNotice, NativeSelect, formatDate, formatDateTime, useFieldId } from './_shared';
+import { ErrorNotice, NativeSelect, formatDate, formatDateTime, formatLocalTime, useFieldId } from './_shared';
 
 export interface SendLogProps {
   api: CommsApi;
@@ -93,7 +93,9 @@ export function SendLog({ api, pageSize = 25 }: SendLogProps): ReactElement {
                   <TableCell>{programLabel(s.program_key)}</TableCell>
                   <TableCell>{s.status}</TableCell>
                   <TableCell>
-                    {s.status === 'scheduled'
+                    {s.send_mode === 'recipient_local' && (s.status === 'scheduled' || s.status === 'rolling')
+                      ? `In each recipient's own time zone, from ${formatLocalTime(s.local_time)}`
+                      : s.status === 'scheduled'
                       ? formatDateTime(s.send_at, s.send_timezone)
                       : s.status === 'cancelled'
                         ? `Cancelled ${formatDateTime(s.cancelled_at)}`

package/src/comms/components/_shared.tsx

@@ -56,6 +56,14 @@ export function formatDateTime(iso: string | null | undefined, timeZone?: string
   }
 }
 
+/** A wall-clock time with no zone ("2026-11-20T09:00:00"), shown as written: "Nov 20, 2026, 9:00 AM". */
+export function formatLocalTime(local: string | null | undefined): string {
+  if (!local) return '';
+  const d = new Date(local);
+  if (Number.isNaN(d.getTime())) return '';
+  return d.toLocaleString(undefined, { year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' });
+}
+
 /** The viewer's IANA zone, or 'UTC' when the runtime cannot say. */
 export function localTimeZone(): string {
   try {

package/src/comms/components/index.ts

@@ -4,6 +4,7 @@ export * from './SequenceSettings';
 export * from './EmailPreview';
 export * from './ApprovalModeSetting';
 export * from './VoiceSettings';
+export * from './DefaultTimeZoneSetting';
 export * from './SendingDomain';
 export * from './ProductUpdates';
 export * from './DraftReview';

package/src/comms/components/pages/CustomerEmailsPage.tsx

@@ -22,6 +22,7 @@ import { DEFAULT_POLL_MS, useCommsSettings, usePrograms } from '../../hooks/inde
 import { CommsApiError } from '../../types/index';
 import { AnnouncementComposer } from '../AnnouncementComposer';
 import { ApprovalModeSetting } from '../ApprovalModeSetting';
+import { DefaultTimeZoneSetting } from '../DefaultTimeZoneSetting';
 import { ProductUpdates } from '../ProductUpdates';
 import { ProgramToggles } from '../ProgramToggles';
 import { ResultsPanel } from '../ResultsPanel';
@@ -93,6 +94,9 @@ export function CustomerEmailsPage({
           <Fold value="voice" title="Voice">
             <VoiceSettings api={api} />
           </Fold>
+          <Fold value="timezone" title="Time zone">
+            <DefaultTimeZoneSetting api={api} />
+          </Fold>
           <Fold value="domain" title="Sending domain">
             <SendingDomain api={api} />
           </Fold>

package/src/comms/hooks/index.ts

@@ -281,8 +281,8 @@ export type ApproveDraftVars = string | ({ id: string } & Partial<ScheduleInput>
 export function useApproveDraft(api: CommsApi): UseMutationResult<Draft, Error, ApproveDraftVars> {
   return useScheduleWrite(api, (v: ApproveDraftVars) => {
     if (typeof v === 'string') return api.approveDraft(v);
-    const { id, send_at, timezone } = v;
-    return api.approveDraft(id, send_at ? { send_at, timezone } : undefined);
+    const { id, send_at, ...rest } = v;
+    return api.approveDraft(id, send_at ? { send_at, ...rest } : undefined);
   });
 }
 

package/src/comms/types/index.ts

@@ -52,6 +52,11 @@ export interface CommsSettings {
   domain_records: DomainRecord[];
   domain_checked_at: string | null;
   paused: boolean;
+  /**
+   * IANA zone used for recipients with no known zone of their own when a send is
+   * timed per recipient. Blank = UTC.
+   */
+  default_timezone: string;
   source_repos: SourceRepo[];
   /**
    * The From address comms mail actually goes out with (UI gap G3): the
@@ -194,11 +199,11 @@ export interface ChangesResponse {
   unclassified: string[];
 }
 
-export type DraftApproval = 'pending' | 'scheduled' | 'expired' | 'failed' | 'approved' | 'discarded';
+export type DraftApproval = 'pending' | 'scheduled' | 'rolling' | 'expired' | 'failed' | 'approved' | 'discarded';
 
 /** The named state of a draft/send (server `state`); every one has a reason and a next action. */
 export type DraftState =
-  | 'generating' | 'writing_failed' | 'pending' | 'cancelled' | 'scheduled'
+  | 'generating' | 'writing_failed' | 'pending' | 'cancelled' | 'scheduled' | 'rolling'
   | 'expired' | 'failed' | 'sending' | 'sent' | 'discarded';
 
 export type DraftAction =
@@ -221,6 +226,42 @@ export interface DraftFailure {
   at?: string;
 }
 
+/** One time zone's slice of a recipient-local send; counts come from the recipient rows. */
+export type GroupState = 'waiting' | 'sending' | 'sent' | 'failed' | 'expired' | 'cancelled';
+
+export interface DraftGroup {
+  zone: string;
+  /** UTC instant this zone's local time arrives. */
+  at: string;
+  state: GroupState;
+  /** Started well after `at` (the time had already passed when scheduled, or it was moved earlier). */
+  late: boolean;
+  /** 'gap': the local time is skipped by a clock change (it goes out at the first moment after the change); 'overlap': it happens twice (first one used). */
+  note: 'gap' | 'overlap' | null;
+  sources: { browser: number; foundry_default: number; utc: number };
+  count: number;
+  pending: number;
+  sent: number;
+  failed: number;
+  suppressed: number;
+  started_at: string | null;
+  completed_at: string | null;
+  failure: { stage: string; code: string; reason: string } | null;
+  reason: string | null;
+}
+
+export interface GroupSummary {
+  total: number;
+  waiting: number;
+  sending: number;
+  sent: number;
+  failed: number;
+  expired: number;
+  cancelled: number;
+}
+
+export type SendMode = 'fixed' | 'recipient_local';
+
 export interface Draft {
   id: string;
   program_key: string;
@@ -259,6 +300,13 @@ export interface Draft {
   /** A scheduled send whose audience lookup failed and is being retried. */
   dispatch_attempts?: number;
   dispatch_error?: string | null;
+  /** 'recipient_local': `local_time` is a wall-clock time in each recipient's own zone. */
+  send_mode?: SendMode;
+  /** The wall-clock time (no offset) of a recipient-local send, e.g. 2026-11-20T09:00:00. */
+  local_time?: string | null;
+  /** Per-zone progress, soonest first; empty until the plan is frozen at the first zone's time. */
+  groups?: DraftGroup[];
+  group_summary?: GroupSummary | null;
 }
 
 /** A tenant-evaluated segment: the key (and params) the foundry's backend understands. */
@@ -295,6 +343,8 @@ export interface AudiencePreview {
   excluded_total: number;
   sample: string[];
   excluded_sample: { email: string; reason: ExcludedReason }[];
+  /** Recipients with no known time zone of their own (a default or UTC applies to a per-zone send). */
+  no_timezone?: number;
 }
 
 export interface DraftAudience {
@@ -322,6 +372,11 @@ export interface AudienceSegments {
 export interface ScheduleInput {
   send_at: string;
   timezone?: string;
+  /**
+   * 'recipient_local': `send_at` is a wall-clock time with no offset, sent at that
+   * time in each recipient's own zone; `timezone` must be absent.
+   */
+  send_mode?: SendMode;
 }
 
 /** POST drafts/: either the email as written (201) or notes to write it from (202, generating). */
@@ -398,12 +453,16 @@ export interface ScheduledSend {
   id: string;
   program_key: string;
   subject: string;
-  status: 'scheduled' | 'expired' | 'failed' | 'cancelled';
+  status: 'scheduled' | 'rolling' | 'expired' | 'failed' | 'cancelled';
   /** Why: the failure, the pause that expired it, or who cancelled it. */
   reason?: string;
   send_at: string | null;
   send_timezone: string | null;
   cancelled_at: string | null;
+  send_mode?: SendMode;
+  local_time?: string | null;
+  groups?: DraftGroup[];
+  group_summary?: GroupSummary | null;
 }
 
 /** GET sends/: the recipient rows (paginated) plus the not-yet-sent drafts. */