@startsimpli/integrations 0.2.45 → 0.2.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "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",

package/src/comms/__tests__/api.test.ts

@@ -235,6 +235,23 @@ describe('product updates', () => {
     expect(r.html).toBe('<p>Hi Quinn</p>');
   });
 
+  it('per-send audience: GET/PUT drafts/{id}/audience/, POST .../preview/, GET audience/segments/', async () => {
+    const result = { audience: { base: 'all' }, is_default: true, preview: { count: 3, eligible: 3, excluded: {}, excluded_total: 0, sample: [], excluded_sample: [] } };
+    reply = () => HttpResponse.json(result);
+    await api().getDraftAudience('d-1');
+    expect([last().method, last().path]).toEqual(['GET', pathOf(`${P}/drafts/d-1/audience/`)]);
+    await api().saveDraftAudience('d-1', { base: 'inactive', days: 30 });
+    expect([last().method, last().path]).toEqual(['PUT', pathOf(`${P}/drafts/d-1/audience/`)]);
+    expect(last().body).toEqual({ audience: { base: 'inactive', days: 30 } });
+    await api().previewDraftAudience('d-1', { segment: { key: 'paying' } });
+    expect([last().method, last().path]).toEqual(['POST', pathOf(`${P}/drafts/d-1/audience/preview/`)]);
+    expect(last().body).toEqual({ audience: { segment: { key: 'paying' } } });
+    reply = () => HttpResponse.json({ available: false, segments: [] });
+    const segs = await api().listAudienceSegments();
+    expect(last().path).toBe(pathOf(`${P}/audience/segments/`));
+    expect(segs.available).toBe(false);
+  });
+
   // Shipped contract (updates lane): 202 with a placeholder draft still generating.
   it('POST programs/product_update/send-now/ with notes', async () => {
     reply = () => HttpResponse.json({ draft: draft({ generating: true, subject: '' }), reason: null }, { status: 202 });

package/src/comms/__tests__/audience-panel.test.tsx

@@ -0,0 +1,155 @@
+/**
+ * Per-send audience on a pending draft (bd startsim-xkcnk): an "Audience"
+ * disclosure under each draft that shows who will receive it, lets the admin
+ * narrow it (activity, signup dates, a segment the foundry's backend defines,
+ * explicit exclusions), previews the count with an "excluded and why"
+ * breakdown, and saves it on the draft. Nothing is requested until it is opened.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { 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 { DraftReview } from '../components/DraftReview';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { AudiencePreview, AudienceSpec, DraftAudience } from '../types/index';
+import { BASE, P, SLUG, draft } from './fixtures';
+
+interface Hit { method: string; path: string; body: any }
+let hits: Hit[] = [];
+let audience: DraftAudience;
+let segmentsReply: () => Response;
+let previewReply: (spec: AudienceSpec) => Response;
+
+const rel = (p: string) => p.replace(new URL(P).pathname, '');
+const preview = (over: Partial<AudiencePreview> = {}): AudiencePreview => ({
+  count: 42, eligible: 50, excluded: { opted_out: 5, suppressed: 3 }, excluded_total: 8,
+  sample: ['a@x.com', 'b@x.com'], excluded_sample: [{ email: 'gone@x.com', reason: 'opted_out' }], ...over,
+});
+
+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);
+    if (hit.path === '/drafts/') {
+      return HttpResponse.json({ count: 1, next: null, previous: null, results: [draft()] });
+    }
+    if (hit.path === '/audience/segments/') return segmentsReply();
+    if (hit.path === '/drafts/d-1/audience/' && hit.method === 'GET') return HttpResponse.json(audience);
+    if (hit.path === '/drafts/d-1/audience/' && hit.method === 'PUT') {
+      return HttpResponse.json({ audience: hit.body.audience, is_default: false, preview: preview() });
+    }
+    if (hit.path === '/drafts/d-1/audience/preview/') return previewReply(hit.body.audience);
+    return HttpResponse.json({});
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterAll(() => server.close());
+beforeEach(() => {
+  hits = [];
+  audience = { audience: { base: 'all' }, is_default: true, preview: preview() };
+  segmentsReply = () => HttpResponse.json({
+    available: true,
+    segments: [{ key: 'never_designed', label: 'Signed up, never made a design', description: '' },
+      { key: 'paying', label: 'Paying users', description: '' }],
+  });
+  previewReply = (spec) => HttpResponse.json({ audience: spec, is_default: false, preview: preview({ count: 7, excluded: {}, excluded_total: 0, excluded_sample: [] }) });
+});
+afterEach(() => server.resetHandlers());
+
+async function openAudience() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const user = userEvent.setup();
+  render(
+    <QueryClientProvider client={qc}>
+      <DraftReview api={createCommsApi(SLUG)} pollIntervalMs={20} />
+    </QueryClientProvider>,
+  );
+  const trigger = await screen.findByRole('button', { name: 'Audience' });
+  return { user, trigger };
+}
+
+const previews = () => hits.filter((h) => h.path === '/drafts/d-1/audience/preview/');
+
+describe('Audience panel', () => {
+  it('asks for nothing until it is opened, then shows who receives it and why others are excluded', async () => {
+    const { user, trigger } = await openAudience();
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(hits.some((h) => h.path.includes('audience'))).toBe(false);
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    expect(await within(region).findByText(/42 people will receive this/)).toBeInTheDocument();
+    expect(within(region).getByText(/8 excluded/)).toBeInTheDocument();
+    expect(within(region).getByText(/5 unsubscribed/)).toBeInTheDocument();
+    expect(within(region).getByText(/3 suppressed/)).toBeInTheDocument();
+    expect(within(region).getByText('a@x.com')).toBeInTheDocument();
+    expect(within(region).getByText(/Using the program default/)).toBeInTheDocument();
+  });
+
+  it('previews a narrower activity audience without saving', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'inactive');
+    await waitFor(() => expect(previews().at(-1)?.body.audience).toMatchObject({ base: 'inactive', days: 14 }));
+    expect(await within(region).findByText(/7 people will receive this/)).toBeInTheDocument();
+    expect(hits.some((h) => h.method === 'PUT')).toBe(false);
+  });
+
+  it('lists the foundry\'s segments and previews the chosen one', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Only people in segment'), 'never_designed');
+    await waitFor(() => expect(previews().at(-1)?.body.audience.segment).toEqual({ key: 'never_designed' }));
+  });
+
+  it('says segments are unavailable when the foundry has no backend', async () => {
+    segmentsReply = () => HttpResponse.json({ available: false, segments: [] });
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    expect(await within(region).findByText(/Segments need the foundry's own backend/)).toBeInTheDocument();
+    expect(within(region).queryByLabelText('Only people in segment')).toBeNull();
+  });
+
+  it('takes signup dates and an exclusion list, one address per line', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.type(await within(region).findByLabelText('Signed up after'), '2026-10-01');
+    await user.type(within(region).getByLabelText('Never send to'), 'A@x.com{enter}b@x.com');
+    await waitFor(() => expect(previews().at(-1)?.body.audience).toMatchObject({
+      joined_after: '2026-10-01', exclude: { emails: ['a@x.com', 'b@x.com'] },
+    }));
+  });
+
+  it('saves the audience on the draft', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'active');
+    await user.click(within(region).getByRole('button', { name: 'Save audience' }));
+    await waitFor(() => expect(hits.find((h) => h.method === 'PUT')?.body).toEqual({
+      audience: { base: 'active', days: 14 },
+    }));
+  });
+
+  it('shows the server\'s reason when the audience cannot be resolved', async () => {
+    previewReply = () => HttpResponse.json({ detail: 'the foundry\'s backend refused the segment request (500)' }, { status: 400 });
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'inactive');
+    expect(await within(region).findByRole('alert')).toHaveTextContent(/refused the segment request/);
+  });
+});

package/src/comms/__tests__/image-library.test.tsx

@@ -0,0 +1,230 @@
+/**
+ * Image library inside the Announcements fold (bd startsim-ktuhz, picker lane).
+ *
+ * "Images" is a small section of the composer: upload a picture with its alt
+ * text (alt is required), see the foundry's library as thumbnails, insert one
+ * into the message, delete one. Uploads are multipart POSTs to comms/assets/.
+ *
+ * Inserting writes `![alt](url)` on its own paragraph; saving the draft turns
+ * that into an <img> (escaped, max-width 100%) in the html and `[Image: alt]` in
+ * the plain-text part. The server sanitiser has the last word on which hosts
+ * survive.
+ *
+ * TEST ENVIRONMENT NOTE: jsdom's FormData is not recognised by Node's fetch (it is
+ * sent as "[object FormData]"), so the tests wrap fetch: a FormData body is read
+ * field by field and forwarded as JSON with an X-Test-Form header. That keeps
+ * "the request carries file and alt" under test; the multipart encoding itself
+ * is the browser's. The helper test below checks the real fetch call directly.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { 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 { CustomerEmailsPage } from '../components/pages/CustomerEmailsPage';
+import { textToHtml, textToPlain } from '../components/AnnouncementComposer';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { CommsAsset } from '../types/index';
+import { BASE, P, SLUG, comeback, draft, productUpdate, settings } from './fixtures';
+
+const asset = (over: Partial<CommsAsset> = {}): CommsAsset => ({
+  id: 'img-1',
+  key: 'crochets/img-1.png',
+  url: 'https://cdn.test/crochets/img-1.png',
+  filename: 'cat.png',
+  content_type: 'image/png',
+  bytes: 1234,
+  width: 60,
+  height: 40,
+  alt: 'A cat',
+  created_at: '2026-10-31T10:00:00Z',
+  ...over,
+});
+
+interface Hit { method: string; path: string; body: any; form?: Record<string, string> }
+let hits: Hit[] = [];
+let library: CommsAsset[] = [];
+let uploadReply: () => Response;
+
+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 isForm = request.headers.get('X-Test-Form') === '1';
+    let body: any;
+    let form: Hit['form'];
+    if (request.method !== 'GET') {
+      const t = await request.text();
+      const parsed = t ? JSON.parse(t) : undefined;
+      if (isForm) form = parsed;
+      else body = parsed;
+    }
+    const hit: Hit = { method: request.method, path: rel(url.pathname), body, form };
+    hits.push(hit);
+    if (hit.path === '/settings/') return HttpResponse.json(settings());
+    if (hit.path === '/programs/') return HttpResponse.json([comeback(), productUpdate()]);
+    if (hit.path === '/drafts/' && hit.method === 'POST') return HttpResponse.json(draft({ id: 'a-1' }), { status: 201 });
+    if (hit.path === '/drafts/') return HttpResponse.json({ count: 0, next: null, previous: null, results: [] });
+    if (hit.path === '/assets/' && hit.method === 'POST') return uploadReply();
+    if (hit.path === '/assets/') return HttpResponse.json({ count: library.length, next: null, previous: null, results: library });
+    const m = hit.path.match(/^\/assets\/([^/]+)\/$/);
+    if (m && hit.method === 'DELETE') {
+      library = library.filter((a) => a.id !== m[1]);
+      return new HttpResponse(null, { status: 204 });
+    }
+    return HttpResponse.json({});
+  }),
+);
+
+let realFetch: typeof fetch;
+let lastInit: RequestInit | undefined;
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  realFetch = globalThis.fetch; // msw's patched fetch, captured after listen()
+  vi.stubGlobal('fetch', (input: RequestInfo | URL, init?: RequestInit) => {
+    if (init?.body instanceof FormData) {
+      lastInit = init; // the upload call itself (later refetches must not overwrite it)
+      const entries = Object.fromEntries(init.body.entries());
+      const headers = { ...(init.headers as Record<string, string>), 'X-Test-Form': '1', 'Content-Type': 'application/json' };
+      return realFetch.call(globalThis, input, {
+        ...init,
+        headers,
+        body: JSON.stringify({ file: (entries.file as File).name, alt: String(entries.alt) }),
+      });
+    }
+    return realFetch.call(globalThis, input, init);
+  });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterAll(() => {
+  server.close();
+  vi.unstubAllGlobals();
+});
+beforeEach(() => {
+  hits = [];
+  library = [];
+  uploadReply = () => HttpResponse.json({}, { status: 500 });
+});
+afterEach(() => server.resetHandlers());
+
+async function openImages() {
+  const user = userEvent.setup();
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  render(
+    <QueryClientProvider client={qc}>
+      <CustomerEmailsPage api={createCommsApi(SLUG)} foundrySlug={SLUG} pollIntervalMs={20} />
+    </QueryClientProvider>,
+  );
+  await user.click(await screen.findByRole('button', { name: 'Announcements' }));
+  const region = await screen.findByRole('region', { name: 'Announcements' });
+  return { user, region };
+}
+
+const png = () => new File([new Uint8Array([137, 80, 78, 71])], 'cat.png', { type: 'image/png' });
+const uploads = () => hits.filter((h) => h.method === 'POST' && h.path === '/assets/');
+
+describe('textToHtml / textToPlain with images', () => {
+  it('turns a paragraph that is only an image into an escaped, responsive <img>', () => {
+    expect(textToHtml('Hello\n\n![A "cat"](https://cdn.test/a.png)')).toBe(
+      '<p>Hello</p><p><img src="https://cdn.test/a.png" alt="A &quot;cat&quot;" style="max-width:100%;height:auto;border:0"></p>',
+    );
+  });
+  it('handles an image inline and escapes markup around it', () => {
+    expect(textToHtml('See ![x](https://cdn.test/a.png) <b>now</b>')).toBe(
+      '<p>See <img src="https://cdn.test/a.png" alt="x" style="max-width:100%;height:auto;border:0"> &lt;b&gt;now&lt;/b&gt;</p>',
+    );
+  });
+  it('never turns a non-http(s) target into an image', () => {
+    expect(textToHtml('![x](javascript:alert(1))')).toBe('<p>![x](javascript:alert(1))</p>');
+  });
+  it('writes [Image: alt] in the plain-text part', () => {
+    expect(textToPlain('Hi\n\n![A cat](https://cdn.test/a.png)')).toBe('Hi\n\n[Image: A cat]');
+  });
+});
+
+describe('Images section', () => {
+  it('lists the foundry library as thumbnails with their alt text', async () => {
+    library = [asset(), asset({ id: 'img-2', alt: 'A dog', url: 'https://cdn.test/crochets/img-2.png' })];
+    const { region } = await openImages();
+    const imgs = await within(region).findAllByRole('img', { name: 'A cat' });
+    expect(imgs[0]).toHaveAttribute('src', 'https://cdn.test/crochets/img-1.png');
+    expect(within(region).getByRole('img', { name: 'A dog' })).toBeInTheDocument();
+  });
+
+  it('needs a file AND alt text before it will upload', async () => {
+    const { user, region } = await openImages();
+    const button = await within(region).findByRole('button', { name: 'Upload image' });
+    expect(button).toBeDisabled();
+    await user.upload(within(region).getByLabelText('Image file'), png());
+    expect(button).toBeDisabled();
+    await user.type(within(region).getByLabelText('Describe the image'), 'A cat');
+    expect(button).toBeEnabled();
+  });
+
+  it('uploads multipart with the file and alt, then shows it in the library', async () => {
+    uploadReply = () => {
+      library = [asset()];
+      return HttpResponse.json(asset(), { status: 201 });
+    };
+    const { user, region } = await openImages();
+    await user.upload(await within(region).findByLabelText('Image file'), png());
+    await user.type(within(region).getByLabelText('Describe the image'), 'A cat');
+    await user.click(within(region).getByRole('button', { name: 'Upload image' }));
+    await waitFor(() => expect(uploads()).toHaveLength(1));
+    const form = uploads()[0].form!;
+    expect(form.file).toBe('cat.png');
+    expect(form.alt).toBe('A cat');
+    // what the helper really sent: a FormData body and NO forced JSON content type
+    expect(lastInit?.body).toBeInstanceOf(FormData);
+    expect((lastInit?.headers as Record<string, string>)['Content-Type']).toBeUndefined();
+    expect(await within(region).findByRole('img', { name: 'A cat' })).toBeInTheDocument();
+    expect(within(region).getByLabelText('Describe the image')).toHaveValue('');
+  });
+
+  it("shows the server's reason when an upload is refused", async () => {
+    uploadReply = () => HttpResponse.json({ detail: 'that is not a PNG, JPEG, GIF or WebP image' }, { status: 400 });
+    const { user, region } = await openImages();
+    await user.upload(await within(region).findByLabelText('Image file'), png());
+    await user.type(within(region).getByLabelText('Describe the image'), 'x');
+    await user.click(within(region).getByRole('button', { name: 'Upload image' }));
+    expect(await within(region).findByRole('alert')).toHaveTextContent('not a PNG, JPEG, GIF or WebP');
+  });
+
+  it('inserts an image into the message as its own paragraph', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.type(within(region).getByLabelText('Message'), 'Hello there');
+    await user.click(await within(region).findByRole('button', { name: 'Insert A cat' }));
+    expect(within(region).getByLabelText('Message')).toHaveValue(
+      'Hello there\n\n![A cat](https://cdn.test/crochets/img-1.png)',
+    );
+  });
+
+  it('saves a draft whose html has the <img> and whose text part says [Image: alt]', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.type(within(region).getByLabelText('Subject'), 'Pics');
+    await user.type(within(region).getByLabelText('Message'), 'Look');
+    await user.click(await within(region).findByRole('button', { name: 'Insert A cat' }));
+    await user.click(within(region).getByRole('button', { name: 'Save as draft' }));
+    await waitFor(() => expect(hits.some((h) => h.method === 'POST' && h.path === '/drafts/')).toBe(true));
+    const body = hits.find((h) => h.method === 'POST' && h.path === '/drafts/')!.body;
+    expect(body.html).toBe(
+      '<p>Look</p><p><img src="https://cdn.test/crochets/img-1.png" alt="A cat" style="max-width:100%;height:auto;border:0"></p>',
+    );
+    expect(body.text).toBe('Look\n\n[Image: A cat]');
+  });
+
+  it('deletes an image from the library', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.click(await within(region).findByRole('button', { name: 'Delete A cat' }));
+    await waitFor(() => expect(hits.some((h) => h.method === 'DELETE' && h.path === '/assets/img-1/')).toBe(true));
+    await waitFor(() => expect(within(region).queryByRole('img', { name: 'A cat' })).not.toBeInTheDocument());
+  });
+});

package/src/comms/api/_fetch.ts

@@ -28,7 +28,7 @@ export function setAuthTokenProvider(
 }
 
 export interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   body?: unknown;
   query?: Record<string, string | number | boolean | undefined | null>;
 }
@@ -47,7 +47,9 @@ export async function request<T>(path: string, opts: RequestOptions = {}): Promi
   }
 
   const headers: Record<string, string> = { Accept: 'application/json' };
-  if (body !== undefined) headers['Content-Type'] = 'application/json';
+  const isForm = typeof FormData !== 'undefined' && body instanceof FormData;
+  // A FormData body carries its own multipart boundary: the browser sets the header.
+  if (body !== undefined && !isForm) headers['Content-Type'] = 'application/json';
   if (_tokenProvider) {
     try {
       const token = await _tokenProvider();
@@ -61,7 +63,7 @@ export async function request<T>(path: string, opts: RequestOptions = {}): Promi
     method,
     headers,
     credentials: 'include',
-    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    ...(body !== undefined ? { body: isForm ? (body as FormData) : JSON.stringify(body) } : {}),
   });
 
   const contentType = resp.headers.get('Content-Type') || '';

package/src/comms/api/comms.ts

@@ -17,9 +17,14 @@ import type {
   ChangesResponse,
   CommsMetrics,
   CommsProgram,
+  AssetsQuery,
+  CommsAsset,
   CommsSettings,
   CommsSettingsPatch,
+  AudienceSegments,
+  AudienceSpec,
   Draft,
+  DraftAudience,
   DraftCreate,
   DraftPatch,
   DraftsQuery,
@@ -65,10 +70,20 @@ export interface CommsApi {
   listDrafts(query?: DraftsQuery): Promise<Paginated<Draft>>;
   getDraft(id: string): Promise<Draft>;
   createDraft(input: DraftCreate): Promise<Draft>;
+
+  // image library
+  listAssets(query?: AssetsQuery): Promise<Paginated<CommsAsset>>;
+  uploadAsset(file: File, alt: string): Promise<CommsAsset>;
+  deleteAsset(id: string): Promise<void>;
   updateDraft(id: string, patch: DraftPatch): Promise<Draft>;
   approveDraft(id: string): Promise<Draft>;
   discardDraft(id: string): Promise<Draft>;
   previewDraft(id: string): Promise<RenderedEmail>;
+  // per-send audience: the draft's own spec (or the program default) + who it reaches
+  getDraftAudience(id: string): Promise<DraftAudience>;
+  saveDraftAudience(id: string, audience: AudienceSpec): Promise<DraftAudience>;
+  previewDraftAudience(id: string, audience: AudienceSpec): Promise<DraftAudience>;
+  listAudienceSegments(): Promise<AudienceSegments>;
   sendUpdateNow(input?: { notes?: string }): Promise<SendNowResult>;
 
   // results
@@ -110,10 +125,24 @@ export function createCommsApi(slug: string): CommsApi {
     listDrafts: (query = {}) => request(`${P}/drafts/`, { query: { ...query } }),
     getDraft: (id) => request(draftPath(id)),
     createDraft: (input) => request(`${P}/drafts/`, { method: 'POST', body: input }),
+    listAssets: (query = {}) => request(`${P}/assets/`, { query: { ...query } }),
+    uploadAsset: (file, alt) => {
+      const form = new FormData();
+      form.append('file', file);
+      form.append('alt', alt);
+      return request(`${P}/assets/`, { method: 'POST', body: form });
+    },
+    deleteAsset: (id) => request(`${P}/assets/${seg(id)}/`, { method: 'DELETE' }),
     updateDraft: (id, patch) => request(draftPath(id), { method: 'PATCH', body: patch }),
     approveDraft: (id) => request(draftPath(id, 'approve'), { method: 'POST' }),
     discardDraft: (id) => request(draftPath(id, 'discard'), { method: 'POST' }),
     previewDraft: (id) => request(draftPath(id, 'preview')),
+    getDraftAudience: (id) => request(draftPath(id, 'audience')),
+    saveDraftAudience: (id, audience) =>
+      request(draftPath(id, 'audience'), { method: 'PUT', body: { audience } }),
+    previewDraftAudience: (id, audience) =>
+      request(draftPath(id, 'audience/preview'), { method: 'POST', body: { audience } }),
+    listAudienceSegments: () => request(`${P}/audience/segments/`),
     sendUpdateNow: (input = {}) =>
       request(`${P}/programs/product_update/send-now/`, { method: 'POST', body: input }),
 

package/src/comms/components/AnnouncementComposer.tsx

@@ -12,7 +12,9 @@ import { Button, Input, Label, Textarea } from '@startsimpli/ui';
 
 import type { CommsApi } from '../api/comms';
 import { DEFAULT_POLL_MS, useCreateDraft, useDraft } from '../hooks/index';
+import type { CommsAsset } from '../types/index';
 import { DraftReview } from './DraftReview';
+import { ImageLibrary } from './ImageLibrary';
 import { ErrorNotice, Note, humanize, useFieldId } from './_shared';
 
 export interface AnnouncementComposerProps {
@@ -24,15 +26,35 @@ type Mode = 'write' | 'notes';
 
 const escapeHtml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
-/** Blank-line-separated paragraphs; a single newline is a line break. */
+const IMAGE = /!\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+const escapeAttr = (v: string) => escapeHtml(v).replace(/"/g, '&quot;');
+
+/** One paragraph's text, with `![alt](https://url)` turned into an <img> and everything else escaped. */
+function inlineHtml(text: string): string {
+  let out = '';
+  let last = 0;
+  for (const m of text.matchAll(IMAGE)) {
+    out += escapeHtml(text.slice(last, m.index)).replace(/\n/g, '<br>');
+    out += `<img src="${escapeAttr(m[2])}" alt="${escapeAttr(m[1])}" style="max-width:100%;height:auto;border:0">`;
+    last = (m.index ?? 0) + m[0].length;
+  }
+  return out + escapeHtml(text.slice(last)).replace(/\n/g, '<br>');
+}
+
+/** Blank-line-separated paragraphs; a single newline is a line break; an image is `![alt](https://url)`. */
 export function textToHtml(text: string): string {
   return text
     .trim()
     .split(/\n{2,}/)
-    .map((p) => `<p>${escapeHtml(p.trim()).replace(/\n/g, '<br>')}</p>`)
+    .map((p) => `<p>${inlineHtml(p.trim())}</p>`)
     .join('');
 }
 
+/** The plain-text part: each image reads `[Image: alt]`. */
+export function textToPlain(text: string): string {
+  return text.trim().replace(IMAGE, (_m, alt: string) => `[Image: ${alt}]`);
+}
+
 /** Follows one notes draft until the worker has finished writing it. */
 function NotesProgress({
   api,
@@ -72,6 +94,9 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
     else setStatus('Your draft is ready. Review it below.');
   }, []);
 
+  const insertImage = (a: CommsAsset) =>
+    setMessage((m) => `${m.trimEnd()}${m.trim() ? '\n\n' : ''}![${a.alt}](${a.url})`);
+
   const canSave = mode === 'write' ? !!subject.trim() && !!message.trim() : !!notes.trim();
 
   const submit = () => {
@@ -83,7 +108,7 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
             subject: subject.trim(),
             ...(preheader.trim() ? { preheader: preheader.trim() } : {}),
             html: textToHtml(message),
-            text: message.trim(),
+            text: textToPlain(message),
           }
         : { notes: notes.trim() };
     create.mutate(input, {
@@ -140,6 +165,7 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
               <Textarea id={`${ids}-msg`} rows={8} value={message} onChange={(e) => setMessage(e.target.value)} />
               <Note>Plain text: leave a blank line between paragraphs, and anything in angle brackets is shown as typed. {'{{first_name}}'} and {'{{app_url}}'} are filled in for each customer.</Note>
             </div>
+            <ImageLibrary api={api} onInsert={insertImage} />
           </>
         ) : (
           <div className="space-y-1">

package/src/comms/components/AudiencePanel.tsx

@@ -0,0 +1,221 @@
+/**
+ * Per-send audience for one pending draft (bd startsim-xkcnk): who receives it,
+ * narrowed by activity, signup dates and a segment the foundry's own backend
+ * defines, minus explicit exclusions. Shows the recipient count, a sample and an
+ * "excluded and why" breakdown before anyone approves; "Save audience" stores it
+ * on the draft. A segment can only narrow the foundry's customers.
+ */
+import { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
+import { Button, Input, Label, Textarea } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useAudienceSegments, useDraftAudience, usePreviewAudience, useSaveAudience } from '../hooks/index';
+import type { AudiencePreview, AudienceSegment, AudienceSpec, ExcludedReason } from '../types/index';
+import { ErrorNotice, NativeSelect, Note, useFieldId } from './_shared';
+
+const DEFAULT_DAYS = 14;
+const DEBOUNCE_MS = 250;
+
+const REASON_LABEL: Record<ExcludedReason, string> = {
+  no_email: 'with no email address',
+  excluded: 'excluded by you',
+  excluded_segment: 'in the excluded segment',
+  undeliverable: 'with an undeliverable address',
+  unverified: 'with an unverified email',
+  opted_out: 'unsubscribed',
+  suppressed: 'suppressed (bounce or complaint)',
+};
+
+interface Form {
+  base: 'all' | 'active' | 'inactive';
+  days: string;
+  after: string;
+  before: string;
+  segment: string;
+  excludeSegment: string;
+  exclude: string;
+}
+
+function toForm(spec: AudienceSpec): Form {
+  return {
+    base: spec.base ?? 'all',
+    days: String(spec.days ?? DEFAULT_DAYS),
+    after: (spec.joined_after ?? '').slice(0, 10),
+    before: (spec.joined_before ?? '').slice(0, 10),
+    segment: spec.segment?.key ?? '',
+    excludeSegment: spec.exclude?.segment?.key ?? '',
+    exclude: (spec.exclude?.emails ?? []).join('\n'),
+  };
+}
+
+export function parseEmails(text: string): string[] {
+  return [...new Set(text.split(/[\s,;]+/).map((e) => e.trim().toLowerCase()).filter(Boolean))];
+}
+
+export function toSpec(f: Form): AudienceSpec {
+  const spec: AudienceSpec = { base: f.base };
+  if (f.base !== 'all') spec.days = Math.max(1, Math.floor(Number(f.days)) || DEFAULT_DAYS);
+  if (f.after) spec.joined_after = f.after;
+  if (f.before) spec.joined_before = f.before;
+  if (f.segment) spec.segment = { key: f.segment };
+  const emails = parseEmails(f.exclude);
+  if (emails.length || f.excludeSegment) {
+    spec.exclude = {};
+    if (emails.length) spec.exclude.emails = emails;
+    if (f.excludeSegment) spec.exclude.segment = { key: f.excludeSegment };
+  }
+  return spec;
+}
+
+function Summary({ preview }: { preview: AudiencePreview }) {
+  const reasons = Object.entries(preview.excluded).filter(([, n]) => n) as [ExcludedReason, number][];
+  return (
+    <div className="space-y-2 rounded-md bg-muted/40 p-3 text-sm" aria-live="polite">
+      <p className="font-medium">
+        {preview.count} {preview.count === 1 ? 'person' : 'people'} will receive this
+      </p>
+      {preview.sample.length ? (
+        <ul className="flex flex-wrap gap-x-3 text-xs text-muted-foreground">
+          {preview.sample.map((e) => (
+            <li key={e}>{e}</li>
+          ))}
+        </ul>
+      ) : null}
+      {preview.excluded_total ? (
+        <div>
+          <p>{preview.excluded_total} excluded</p>
+          <ul className="list-disc pl-5 text-muted-foreground">
+            {reasons.map(([reason, n]) => (
+              <li key={reason}>
+                {n} {REASON_LABEL[reason] ?? reason}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function SegmentSelect({ id, label, value, onChange, segments, none }: {
+  id: string; label: string; value: string; onChange: (v: string) => void; segments: AudienceSegment[]; none: string;
+}) {
+  return (
+    <div className="space-y-1">
+      <Label htmlFor={id}>{label}</Label>
+      <NativeSelect id={id} value={value} onChange={(e) => onChange(e.target.value)}>
+        <option value="">{none}</option>
+        {segments.map((s) => (
+          <option key={s.key} value={s.key}>{s.label}</option>
+        ))}
+      </NativeSelect>
+    </div>
+  );
+}
+
+function AudienceForm({ api, draftId }: { api: CommsApi; draftId: string }) {
+  const prefix = useFieldId(`comms-audience-${draftId}`);
+  const loaded = useDraftAudience(api, draftId, true);
+  const segments = useAudienceSegments(api, true);
+  const previewMut = usePreviewAudience(api, draftId);
+  const save = useSaveAudience(api, draftId);
+  const [form, setForm] = useState<Form | null>(null);
+  const [shown, setShown] = useState<AudiencePreview | null>(null);
+  const initial = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (loaded.data && form === null) {
+      setForm(toForm(loaded.data.audience));
+      setShown(loaded.data.preview);
+      initial.current = JSON.stringify(toSpec(toForm(loaded.data.audience)));
+    }
+  }, [loaded.data, form]);
+
+  const spec = useMemo(() => (form ? toSpec(form) : null), [form]);
+  const specKey = spec ? JSON.stringify(spec) : null;
+  const { mutate } = previewMut;
+  useEffect(() => {
+    if (!spec || specKey === initial.current) return;
+    const t = setTimeout(() => {
+      mutate(spec, {
+        onSuccess: (d) => { setShown(d.preview); },
+        onError: () => setShown(null),
+      });
+    }, DEBOUNCE_MS);
+    return () => clearTimeout(t);
+    // spec is derived from specKey
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [specKey, mutate]);
+
+  if (loaded.error) return <ErrorNotice error={loaded.error} />;
+  if (!form || !spec) return <Note>Loading the audience…</Note>;
+  const set = (patch: Partial<Form>) => setForm({ ...form, ...patch });
+  const dirty = specKey !== initial.current;
+  const available = segments.data?.available ?? false;
+  const list = segments.data?.segments ?? [];
+
+  return (
+    <div className="space-y-3">
+      {loaded.data?.is_default && !dirty ? <Note>Using the program default. Change anything below to set this send's own audience.</Note> : null}
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-who`}>Who</Label>
+          <NativeSelect id={`${prefix}-who`} value={form.base} onChange={(e) => set({ base: e.target.value as Form['base'] })}>
+            <option value="all">Everyone</option>
+            <option value="active">Seen recently</option>
+            <option value="inactive">Not seen for a while</option>
+          </NativeSelect>
+        </div>
+        {form.base !== 'all' ? (
+          <div className="space-y-1">
+            <Label htmlFor={`${prefix}-days`}>Within days</Label>
+            <Input id={`${prefix}-days`} type="number" min={1} className="w-24" value={form.days} onChange={(e) => set({ days: e.target.value })} />
+          </div>
+        ) : null}
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-after`}>Signed up after</Label>
+          <Input id={`${prefix}-after`} type="date" value={form.after} onChange={(e) => set({ after: e.target.value })} />
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-before`}>Signed up before</Label>
+          <Input id={`${prefix}-before`} type="date" value={form.before} onChange={(e) => set({ before: e.target.value })} />
+        </div>
+      </div>
+      {available ? (
+        <div className="flex flex-wrap gap-3">
+          <SegmentSelect id={`${prefix}-seg`} label="Only people in segment" value={form.segment}
+            onChange={(v) => set({ segment: v })} segments={list} none="Everyone (no segment)" />
+          <SegmentSelect id={`${prefix}-xseg`} label="Never send to segment" value={form.excludeSegment}
+            onChange={(v) => set({ excludeSegment: v })} segments={list} none="None" />
+        </div>
+      ) : segments.data ? (
+        <Note>Segments need the foundry's own backend, which is not deployed yet. Activity and signup date still work.</Note>
+      ) : null}
+      <ErrorNotice error={segments.error} />
+      <div className="space-y-1">
+        <Label htmlFor={`${prefix}-exclude`}>Never send to</Label>
+        <Textarea id={`${prefix}-exclude`} rows={3} placeholder="One email address per line"
+          value={form.exclude} onChange={(e) => set({ exclude: e.target.value })} />
+      </div>
+      {shown ? <Summary preview={shown} /> : null}
+      {previewMut.isPending ? <Note>Counting…</Note> : null}
+      <ErrorNotice error={previewMut.error ?? save.error} />
+      <div className="flex items-center gap-2">
+        <Button type="button" size="sm" disabled={save.isPending || !dirty}
+          onClick={() => save.mutate(spec, { onSuccess: () => { initial.current = specKey; setForm({ ...form }); } })}>
+          Save audience
+        </Button>
+        {save.isSuccess && !dirty ? <span className="text-sm text-muted-foreground">Saved.</span> : null}
+      </div>
+    </div>
+  );
+}
+
+/** The open panel; the draft row owns the "Audience" button that shows it. */
+export function AudiencePanel({ api, draftId, id }: { api: CommsApi; draftId: string; id?: string }): ReactElement {
+  return (
+    <div id={id} role="region" aria-label="Audience" className="mt-2 space-y-3 rounded-md border p-3">
+      <AudienceForm api={api} draftId={draftId} />
+    </div>
+  );
+}

package/src/comms/components/DraftReview.tsx

@@ -20,6 +20,7 @@ import {
   useUpdateDraft,
 } from '../hooks/index';
 import type { Draft, DraftPatch } from '../types/index';
+import { AudiencePanel } from './AudiencePanel';
 import { EmailPreview } from './EmailPreview';
 import { ErrorNotice, Note, formatDate, humanize, useFieldId } from './_shared';
 
@@ -81,6 +82,7 @@ function DraftEditor({ api, draft, onDone }: { api: CommsApi; draft: Draft; onDo
 function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
   const [editing, setEditing] = useState(false);
   const [previewing, setPreviewing] = useState(false);
+  const [auditing, setAuditing] = useState(false);
   const ready = !draft.generating && !draft.error;
   const preview = useDraftPreview(api, draft.id, previewing && ready);
   const sendTest = useSendTest(api);
@@ -99,6 +101,15 @@ function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
             <>
               <Button type="button" size="sm" variant="outline" onClick={() => setPreviewing((v) => !v)}>Preview</Button>
               <Button type="button" size="sm" variant="outline" onClick={() => setEditing((v) => !v)}>Edit</Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                aria-expanded={auditing}
+                onClick={() => setAuditing((v) => !v)}
+              >
+                Audience
+              </Button>
               <Button
                 type="button"
                 size="sm"
@@ -127,6 +138,7 @@ function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
       ) : null}
       <ErrorNotice error={sendTest.error ?? approve.error ?? discard.error ?? preview.error} />
       {editing && ready ? <DraftEditor api={api} draft={draft} onDone={() => setEditing(false)} /> : null}
+      {auditing && ready ? <AudiencePanel api={api} draftId={draft.id} /> : null}
       {previewing && preview.data ? <EmailPreview email={preview.data} /> : null}
     </li>
   );

package/src/comms/components/ImageLibrary.tsx

@@ -0,0 +1,115 @@
+/**
+ * The foundry's email image library, inside the announcement composer (bd
+ * startsim-ktuhz): upload a picture with its alt text (required), browse the
+ * library as thumbnails (server-paged), insert one into the message, delete one.
+ * The server decides what an image is (type sniffed, EXIF dropped) and which hosts
+ * survive the email sanitiser; this only collects, lists and hands back a url.
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Input, Label } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useAssets, useDeleteAsset, useUploadAsset } from '../hooks/index';
+import type { CommsAsset } from '../types/index';
+import { ErrorNotice, Note, useFieldId } from './_shared';
+
+export interface ImageLibraryProps {
+  api: CommsApi;
+  /** Called with the chosen image; the composer puts it in the message. */
+  onInsert: (asset: CommsAsset) => void;
+  pageSize?: number;
+}
+
+export function ImageLibrary({ api, onInsert, pageSize = 12 }: ImageLibraryProps): ReactElement {
+  const ids = useFieldId('comms-images');
+  const [page, setPage] = useState(1);
+  const assets = useAssets(api, { page, page_size: pageSize });
+  const upload = useUploadAsset(api);
+  const remove = useDeleteAsset(api);
+  const [file, setFile] = useState<File | null>(null);
+  const [alt, setAlt] = useState('');
+  const [inputKey, setInputKey] = useState(0);
+
+  const results = assets.data?.results ?? [];
+
+  const submit = () => {
+    if (!file || !alt.trim()) return;
+    upload.mutate(
+      { file, alt: alt.trim() },
+      {
+        onSuccess: () => {
+          setFile(null);
+          setAlt('');
+          setInputKey((k) => k + 1);
+          setPage(1);
+        },
+      },
+    );
+  };
+
+  return (
+    <div className="space-y-3 rounded-md border p-3">
+      <p className="text-sm font-medium">Images</p>
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="space-y-1">
+          <Label htmlFor={`${ids}-file`}>Image file</Label>
+          <input
+            key={inputKey}
+            id={`${ids}-file`}
+            type="file"
+            accept="image/png,image/jpeg,image/gif,image/webp"
+            onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+            className="block text-sm"
+          />
+        </div>
+        <div className="min-w-48 flex-1 space-y-1">
+          <Label htmlFor={`${ids}-alt`}>Describe the image</Label>
+          <Input id={`${ids}-alt`} value={alt} onChange={(e) => setAlt(e.target.value)} />
+        </div>
+        <Button type="button" disabled={!file || !alt.trim() || upload.isPending} onClick={submit}>
+          Upload image
+        </Button>
+      </div>
+      <Note>PNG, JPEG, GIF or WebP. The description is read aloud by screen readers and shown when images are blocked.</Note>
+      <ErrorNotice error={upload.error ?? remove.error ?? assets.error} />
+
+      {results.length ? (
+        <ul className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+          {results.map((a) => (
+            <li key={a.id} className="space-y-1">
+              <img src={a.url} alt={a.alt} className="h-20 w-full rounded border object-cover" />
+              <div className="flex gap-1">
+                <Button type="button" size="sm" variant="outline" aria-label={`Insert ${a.alt}`} onClick={() => onInsert(a)}>
+                  Insert
+                </Button>
+                <Button
+                  type="button"
+                  size="sm"
+                  variant="ghost"
+                  aria-label={`Delete ${a.alt}`}
+                  disabled={remove.isPending}
+                  onClick={() => remove.mutate(a.id)}
+                >
+                  Delete
+                </Button>
+              </div>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <Note>{assets.isLoading ? 'Loading images…' : 'No images yet.'}</Note>
+      )}
+
+      {assets.data && (assets.data.previous || assets.data.next) ? (
+        <div className="flex items-center gap-2">
+          <Button type="button" size="sm" variant="outline" disabled={!assets.data.previous} onClick={() => setPage((p) => p - 1)}>
+            Previous
+          </Button>
+          <Button type="button" size="sm" variant="outline" disabled={!assets.data.next} onClick={() => setPage((p) => p + 1)}>
+            Next
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/comms/components/index.ts

@@ -9,3 +9,4 @@ export * from './ProductUpdates';
 export * from './DraftReview';
 export * from './ResultsPanel';
 export * from './SendLog';
+export * from './AudiencePanel';

package/src/comms/hooks/index.ts

@@ -19,11 +19,16 @@ import {
 
 import type { CommsApi } from '../api/comms';
 import type {
+  AssetsQuery,
+  AudienceSegments,
+  AudienceSpec,
+  CommsAsset,
   CommsMetrics,
   CommsProgram,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
+  DraftAudience,
   DraftCreate,
   DraftPatch,
   DraftsQuery,
@@ -48,9 +53,13 @@ export const commsKeys = {
     ['startsimpli', 'comms', slug, 'generation', key, step] as const,
   preview: (slug: string, key: string, step: number) =>
     ['startsimpli', 'comms', slug, 'preview', key, step] as const,
+  assetsAll: (slug: string) => ['startsimpli', 'comms', slug, 'assets'] as const,
+  assets: (slug: string, q: AssetsQuery = {}) => ['startsimpli', 'comms', slug, 'assets', q] as const,
   draftsAll: (slug: string) => ['startsimpli', 'comms', slug, 'drafts'] as const,
   drafts: (slug: string, q: DraftsQuery = {}) => ['startsimpli', 'comms', slug, 'drafts', q] as const,
   draft: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'drafts', 'one', id] as const,
+  audience: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'audience', id] as const,
+  audienceSegments: (slug: string) => ['startsimpli', 'comms', slug, 'audience-segments'] as const,
   draftPreview: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'draft-preview', id] as const,
   sends: (slug: string, q: SendsQuery = {}) => ['startsimpli', 'comms', slug, 'sends', q] as const,
   metrics: (slug: string, q: MetricsQuery = {}) => ['startsimpli', 'comms', slug, 'metrics', q] as const,
@@ -206,6 +215,41 @@ export function useDraftPreview(api: CommsApi, id: string, enabled: boolean): Us
   });
 }
 
+// per-send audience -----------------------------------------------------------
+
+export function useDraftAudience(api: CommsApi, id: string, enabled: boolean): UseQueryResult<DraftAudience> {
+  return useQuery({
+    queryKey: commsKeys.audience(api.slug, id),
+    queryFn: () => api.getDraftAudience(id),
+    enabled,
+    staleTime: 0,
+  });
+}
+
+export function useAudienceSegments(api: CommsApi, enabled: boolean): UseQueryResult<AudienceSegments> {
+  return useQuery({
+    queryKey: commsKeys.audienceSegments(api.slug),
+    queryFn: () => api.listAudienceSegments(),
+    enabled,
+  });
+}
+
+/** Who a candidate audience would reach; nothing is saved. */
+export function usePreviewAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  return useMutation({ mutationFn: (spec: AudienceSpec) => api.previewDraftAudience(id, spec) });
+}
+
+export function useSaveAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (spec: AudienceSpec) => api.saveDraftAudience(id, spec),
+    onSuccess: (data) => {
+      qc.setQueryData(commsKeys.audience(api.slug, id), data);
+      return qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) });
+    },
+  });
+}
+
 function useDraftsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
   const qc = useQueryClient();
   return useMutation<R, Error, V>({
@@ -243,6 +287,28 @@ export function useSendUpdateNow(api: CommsApi): UseMutationResult<SendNowResult
   return useDraftsWrite(api, (input: { notes?: string }) => api.sendUpdateNow(input));
 }
 
+// image library ---------------------------------------------------------------
+
+export function useAssets(api: CommsApi, q: AssetsQuery): UseQueryResult<Paginated<CommsAsset>> {
+  return useQuery({ queryKey: commsKeys.assets(api.slug, q), queryFn: () => api.listAssets(q) });
+}
+
+function useAssetsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
+  const qc = useQueryClient();
+  return useMutation<R, Error, V>({
+    mutationFn: fn,
+    onSuccess: () => qc.invalidateQueries({ queryKey: commsKeys.assetsAll(api.slug) }),
+  });
+}
+
+export function useUploadAsset(api: CommsApi): UseMutationResult<CommsAsset, Error, { file: File; alt: string }> {
+  return useAssetsWrite(api, ({ file, alt }: { file: File; alt: string }) => api.uploadAsset(file, alt));
+}
+
+export function useDeleteAsset(api: CommsApi): UseMutationResult<void, Error, string> {
+  return useAssetsWrite(api, (id: string) => api.deleteAsset(id));
+}
+
 // results ------------------------------------------------------------------
 
 /** Server-side pagination: page/page_size go to the server, never sliced here. */

package/src/comms/types/index.ts

@@ -211,6 +211,64 @@ export interface Draft {
   error: string | null;
   /** True while a worker is still writing the content: poll getDraft(id). */
   generating: boolean;
+  /** This send's own audience; null/absent = the program default. */
+  audience?: AudienceSpec | null;
+  audience_is_default?: boolean;
+  /** Recipients queued, set at approve. */
+  recipient_count?: number | null;
+}
+
+/** A tenant-evaluated segment: the key (and params) the foundry's backend understands. */
+export interface SegmentRef {
+  key: string;
+  params?: Record<string, unknown>;
+}
+
+/** Who one send goes to. Always narrows the foundry's customers; never widens. */
+export interface AudienceSpec {
+  base?: 'all' | 'active' | 'inactive';
+  days?: number;
+  joined_after?: string;
+  joined_before?: string;
+  segment?: SegmentRef;
+  exclude?: { emails?: string[]; segment?: SegmentRef };
+}
+
+export type ExcludedReason =
+  | 'no_email'
+  | 'excluded'
+  | 'excluded_segment'
+  | 'undeliverable'
+  | 'unverified'
+  | 'opted_out'
+  | 'suppressed';
+
+export interface AudiencePreview {
+  /** Who will receive it. */
+  count: number;
+  /** Matched the audience before mailability and exclusions. */
+  eligible: number;
+  excluded: Partial<Record<ExcludedReason, number>>;
+  excluded_total: number;
+  sample: string[];
+  excluded_sample: { email: string; reason: ExcludedReason }[];
+}
+
+export interface DraftAudience {
+  audience: AudienceSpec;
+  is_default: boolean;
+  preview: AudiencePreview;
+}
+
+export interface AudienceSegment {
+  key: string;
+  label: string;
+  description: string;
+}
+
+export interface AudienceSegments {
+  available: boolean;
+  segments: AudienceSegment[];
 }
 
 /** POST drafts/: either the email as written (201) or notes to write it from (202, generating). */
@@ -218,6 +276,23 @@ export type DraftCreate =
   | { subject: string; html: string; preheader?: string; text?: string }
   | { notes: string };
 
+/** One image in the foundry's email image library (comms/assets/). */
+export interface CommsAsset {
+  id: string;
+  key: string;
+  /** Public CDN url; the only host the server's email sanitiser keeps. */
+  url: string;
+  filename: string;
+  content_type: string;
+  bytes: number;
+  width: number;
+  height: number;
+  alt: string;
+  created_at: string;
+}
+
+export type AssetsQuery = PageParams;
+
 export type DraftPatch = Partial<Pick<Draft, 'subject' | 'preheader' | 'html' | 'text'>>;
 
 export const NOTHING_CUSTOMER_FACING = 'nothing_customer_facing';