# Email composer (shared template)

One composer for every hub that emails people. It lives in `packages/ui/src/components/templates/email-*.tsx`; apps import it from `@/components/templates/email-composer`.

> **Rule:** `.cursor/rules/exxat-email-composer.mdc` · **Skill:** `exxat-email-composer` · **Agent:** `email-builder` · **Router:** `node scripts/agent-context-router.mjs email-compose`

## Parts

| Piece | What it is |
|---|---|
| `EmailComposerProvider` | Mount once (`AppShellContextProviders`). Owns the composer and history rails. |
| `useEmailComposer()` | `openComposer(context, handlers)`, `openHistory(context)`. |
| `useEmailHubAction()` (app hook) | A hub's **Email** header action plus the inline confirmation. |
| `EmailComposerSheet` / `EmailHistorySheet` | Floating `Sheet` rails (`FloatingSheetPanel`); the hub behind stays live. |
| `EmailRecipientsReview` | First page: Select Role, Options, Recipients. Multi-audience only. |
| `EmailMessagePreview` | The shared email layout (header, subject, sender line, body, attachments, footer). Preview and History both use it. |
| `EmailChipField` | To / Cc / Bcc / From / Reply to as badges; collapses to one row. |
| `EmailHeaderFooterPicker` | Email header and footer inside the message area. |
| `EmailAttachmentPreviewDialog` | Whole attachment tile opens a preview. |
| `RichTextEditor mergeFields` · `MergeTagInput` · `MergeFieldMenu` | Merge fields as chips, `@` typeahead, searchable menu. |

## Layout

Toolbar (title, Preview ⇄ Edit, history, size, close) · From / Reply to · To + Cc / Bcc · Subject + **Template** menu · Email header · body (full width, no box) · Email footer · attachments · footer (Send test email, Send ▾ Schedule). "Edit recipients" or Back returns to the Recipients page.

## The contract

A hub never builds UI. It maps its rows to an `EmailComposerContext`: `audiences`, `recipients` (merge `fields`, optional `records`, `lastEmailed`, `blockedReason`), `templates` per audience, `mergeFields`, `sender`, `brand`, optional `history`. Reference adapter: `apps/web/lib/email/people-email-context.ts`. Brand: `lib/email/use-email-brand.tsx` (school avatar + product lock-up from the shell).

## Rules in short

- Merge fields are `{{key}}` text, drawn as chips; every field has a description.
- One `isDefault` template per audience (a **Default** tag, no "Mark as default"); every template brings a header and footer unless blank.
- The Recipients page opens first only when there is more than one audience.
- Send is confirmed; outcomes are inline (`LocalBanner`), never a toast.
- Rail is `z-[80]`: menus `z-properties-sheet-portal`, dialogs `z-[90]`.

**Not built yet:** Leo write, per-person edits, expanded mode with a template library, a full history page.
