@12-apps/notifications 4.7.1 → 4.9.0

package/src/email/template.ts

@@ -0,0 +1,365 @@
+import { renderEmailText } from './text';
+import {
+  EMAIL_CONTENT_WIDTH,
+  EMAIL_FONT_STACK,
+  NEUTRAL_EMAIL_THEME,
+  type EmailTheme,
+} from './theme';
+
+/**
+ * THE transactional-mail layout: one document model, one HTML renderer, one
+ * plain-text twin.
+ *
+ * ## The problem it exists for
+ *
+ * A host that sends mail from more than one place ends up rendering it in more
+ * than one way — the notification pipeline emits a bold paragraph and a bare
+ * anchor, the sign-in flow emits a `div` with a max-width, the receipt builds
+ * its own list — and each grows its own `escapeHtml` and its own text twin. The
+ * three look like three different products, because a paragraph with no
+ * document around it inherits whatever the client decides: 13px Arial in Gmail,
+ * Times New Roman in Outlook, no centring anywhere.
+ *
+ * That is a LAYOUT problem rather than a wording one, which is what makes it a
+ * package's to solve. The words stay the host's; the document does not.
+ *
+ * ## Why the document is a MODEL and not a string
+ *
+ * Every caller hands over structure — a heading, some paragraphs, an optional
+ * facts table, at most one call to action — and never markup. Three things fall
+ * out of that, and each is a real defect in the hand-rolled renderers this
+ * replaces:
+ *
+ * 1. **Escaping cannot be forgotten.** Every field is escaped here, once. Of
+ *    the three renderers this was extracted from, two escaped the body and
+ *    interpolated the LINK raw.
+ * 2. **The plain-text twin cannot drift.** Both halves render from the same
+ *    object, so a line added to one is in the other. A `text/html` part with no
+ *    `text/plain` twin is scored by every major spam filter, and it is what a
+ *    watch, a terminal client and a screen reader in plain-text mode show.
+ * 3. **A preview is honest.** `./server`'s catalogue renders exactly this, from
+ *    exactly these inputs, so a preview cannot be right about a mail nobody
+ *    gets.
+ *
+ * ## The client constraints this encodes
+ *
+ * Stated once here, so no caller has to know them:
+ *
+ * - **Tables, not divs.** Outlook 2016+ on Windows lays HTML out with Word,
+ *   which supports no `flex`, no `grid` and no reliable `max-width` on a block.
+ *   A centred 600px table is the one construction every client agrees on.
+ * - **Inline styles.** Gmail strips `<style>` from the document it renders in
+ *   several contexts, and always in the Gmail app for a non-Gmail account. The
+ *   `<style>` block below therefore carries only the mobile media query —
+ *   progressive enhancement, never anything the layout depends on.
+ * - **No web fonts, no `color-mix()`, no CSS variables.** See `./theme`.
+ * - **A preheader.** The inbox list shows the first text in the body after the
+ *   subject; without one it shows the footer's legal line.
+ * - **`role="presentation"`** on every layout table, so a screen reader reads
+ *   the message rather than announcing a five-column grid.
+ */
+
+/** The words the LAYOUT itself needs — never the message's own sentences. */
+export interface EmailChromeCopy {
+  /** "If the button does not work, paste this address into your browser:" */
+  readonly fallbackHint: string;
+  /** "This is an automated message — please do not reply." */
+  readonly automated: string;
+  /** The footer's one line about the product, given the brand name. */
+  readonly tagline: (brand: string) => string;
+}
+
+/** The one call to action a message may carry. More than one dilutes both. */
+export interface EmailAction {
+  readonly label: string;
+  readonly href: string;
+}
+
+/** One row of the facts panel — a receipt's total, an order's reference. */
+export interface EmailFact {
+  readonly label: string;
+  readonly value: string;
+  /** Renders bolder and larger — the one number the reader came for. */
+  readonly emphasis?: boolean;
+}
+
+/** Everything a message says, with no opinion about how it looks. */
+export interface EmailDocument {
+  /** The subject line. Also the document `<title>`. */
+  readonly subject: string;
+  /**
+   * The inbox-list preview, ~90 chars. Falls back to the first paragraph,
+   * which is right far more often than it is wrong.
+   */
+  readonly preheader?: string;
+  /** The `<h1>`. Usually a restatement of the subject in the reader's terms. */
+  readonly heading: string;
+  /** The body, one entry per paragraph. Plain sentences — never markup. */
+  readonly paragraphs?: readonly string[];
+  /** An optional label/value panel under the body. */
+  readonly facts?: readonly EmailFact[];
+  /** At most one CTA. */
+  readonly action?: EmailAction;
+  /** Small print under the CTA — a deadline, a "you can ignore this". */
+  readonly notes?: readonly string[];
+  /**
+   * The layout's own words, in the recipient's language.
+   *
+   * REQUIRED, with no default in any language — the copy-portability doctrine.
+   * `@12-apps/notifications/email/locales` ships a pack per language and a host
+   * passes one BY
+   * NAME, which is a decision rather than a silence.
+   */
+  readonly chrome: EmailChromeCopy;
+  /**
+   * The product name in the header and the footer. REQUIRED: a package that
+   * defaulted this would sign another company's mail.
+   */
+  readonly brand: string;
+  /** The recipient's language, for the document's `lang` attribute. */
+  readonly locale: string;
+  /** Defaults to {@link NEUTRAL_EMAIL_THEME} — see `./theme` for why this one may. */
+  readonly theme?: EmailTheme;
+}
+
+/**
+ * Escape everything that reaches the HTML body.
+ *
+ * A store name, a buyer's display name and a product title are all user input
+ * that reaches a mail, and the ONE thing a shared layout must guarantee is that
+ * none of them can close a tag. Single quotes are escaped too: attribute values
+ * below are double-quoted, but a caller reading this should not have to check.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/**
+ * The schemes a link in a mail may use.
+ *
+ * `javascript:` is inert in every mail client, so this is not the XSS guard it
+ * would be on a page — it is the guard for the PREVIEW, which renders the same
+ * HTML in a browser, and for the day some part of this markup is reused on a
+ * screen. A rejected href drops to `#`, which fails visibly rather than
+ * silently linking somewhere unexpected.
+ */
+const SAFE_LINK_SCHEMES = new Set(["http:", "https:", "mailto:"]);
+
+/** A URL as an attribute value, or `#` when it is not one this layout will emit. */
+export function safeHref(href: string): string {
+  const trimmed = href.trim();
+  // A relative link is fine and common — every caller that has an origin
+  // resolves it before it gets here, and one that does not is better off with
+  // a path than with nothing.
+  if (trimmed.startsWith("/")) return escapeHtml(trimmed);
+  try {
+    const url = new URL(trimmed);
+    return SAFE_LINK_SCHEMES.has(url.protocol) ? escapeHtml(url.toString()) : "#";
+  } catch {
+    return "#";
+  }
+}
+
+/** The message's own first sentence, when the caller named no preheader. */
+function preheaderOf(document: EmailDocument): string {
+  return document.preheader ?? document.paragraphs?.[0] ?? document.heading;
+}
+
+/** A `<td>` of body copy. One paragraph, at the layout's own rhythm. */
+function paragraph(text: string, theme: EmailTheme): string {
+  return `<p style="margin:0 0 16px;font-size:16px;line-height:1.6;color:${theme.ink}">${escapeHtml(text)}</p>`;
+}
+
+/**
+ * The facts panel — a receipt's four lines, an order's reference.
+ *
+ * Two cells per row rather than a definition list: `<dl>` is styled
+ * inconsistently across clients and collapses to a single column in Outlook,
+ * which is the one place these are read side by side.
+ */
+function facts(rows: readonly EmailFact[], theme: EmailTheme): string {
+  if (rows.length === 0) return "";
+  const cells = rows
+    .map((row, index) => {
+      const divider =
+        index === 0 ? "" : `border-top:1px solid ${theme.border};`;
+      const value = row.emphasis
+        ? `font-size:20px;font-weight:700;color:${theme.ink}`
+        : `font-size:15px;color:${theme.ink}`;
+      return [
+        `<tr>`,
+        `<td style="${divider}padding:12px 0 12px 16px;font-size:13px;line-height:1.4;color:${theme.muted};text-transform:uppercase;letter-spacing:.4px;white-space:nowrap">${escapeHtml(row.label)}</td>`,
+        `<td align="right" style="${divider}padding:12px 16px 12px 0;line-height:1.4;${value}">${escapeHtml(row.value)}</td>`,
+        `</tr>`,
+      ].join("");
+    })
+    .join("");
+  return [
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="border-collapse:separate;background:${theme.page};border:1px solid ${theme.border};border-radius:10px;margin:0 0 24px">`,
+    cells,
+    `</table>`,
+  ].join("");
+}
+
+/**
+ * The CTA.
+ *
+ * A single-cell table with `bgcolor` AND a background style: Outlook reads the
+ * attribute and ignores the property, every other client does the reverse, and
+ * a button that loses its fill is invisible ink on white. `border-radius` is
+ * simply dropped by Word — a square button is the accepted degradation, and the
+ * alternative (a VML rounded rectangle) is forty lines of conditional comment
+ * that then has to be kept in step with the colour.
+ */
+function action(cta: EmailAction, theme: EmailTheme): string {
+  return [
+    `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:8px 0 24px">`,
+    `<tr>`,
+    `<td align="center" bgcolor="${theme.accent}" style="border-radius:8px;background:${theme.accent}">`,
+    `<a href="${safeHref(cta.href)}" style="display:inline-block;padding:14px 32px;font-family:${EMAIL_FONT_STACK};font-size:16px;font-weight:600;line-height:1;color:${theme.onAccent};text-decoration:none;border-radius:8px">${escapeHtml(cta.label)}</a>`,
+    `</td>`,
+    `</tr>`,
+    `</table>`,
+  ].join("");
+}
+
+/**
+ * The "paste this address" fallback, printed whenever there is a CTA.
+ *
+ * Not optional, and the reason is measured elsewhere in this repo: corporate
+ * mail gateways rewrite link targets, and a reader whose gateway mangles the
+ * button has no other way to reach a verification or reset link. `word-break`
+ * because a signed URL is longer than the card.
+ */
+function fallback(cta: EmailAction, chrome: EmailChromeCopy, theme: EmailTheme): string {
+  return [
+    `<p style="margin:0 0 8px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.fallbackHint)}</p>`,
+    `<p style="margin:0 0 24px;font-size:13px;line-height:1.5;word-break:break-all"><a href="${safeHref(cta.href)}" style="color:${theme.accent};text-decoration:underline">${escapeHtml(cta.href)}</a></p>`,
+  ].join("");
+}
+
+/** The brand header: wordmark over the ramp's rule. */
+function header(document: EmailDocument, theme: EmailTheme): string {
+  return [
+    `<tr>`,
+    `<td style="padding:32px 40px 0">`,
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">`,
+    `<tr><td style="font-size:20px;font-weight:700;letter-spacing:-.2px;color:${theme.ink}">${escapeHtml(document.brand)}</td></tr>`,
+    `<tr><td style="padding-top:12px"><div style="height:3px;width:44px;background:${theme.rule};border-radius:2px;font-size:0;line-height:0">&nbsp;</div></td></tr>`,
+    `</table>`,
+    `</td>`,
+    `</tr>`,
+  ].join("");
+}
+
+/** The footer: the tagline, the "do not reply" line, and nothing else. */
+function footer(document: EmailDocument, theme: EmailTheme): string {
+  const { chrome, brand } = document;
+  return [
+    `<tr>`,
+    `<td style="padding:0 40px 40px">`,
+    `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">`,
+    `<tr><td style="border-top:1px solid ${theme.border};padding-top:20px">`,
+    `<p style="margin:0 0 6px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.tagline(brand))}</p>`,
+    `<p style="margin:0;font-size:12px;line-height:1.5;color:${theme.muted}">${escapeHtml(chrome.automated)}</p>`,
+    `</td></tr>`,
+    `</table>`,
+    `</td>`,
+    `</tr>`,
+  ].join("");
+}
+
+/**
+ * The mobile media query — the one thing in a `<style>` block.
+ *
+ * Everything it does is also correct without it: the card is already
+ * `width:100%` up to 600px, so a client that strips this renders a slightly
+ * roomier mail rather than a broken one. That is the test for whether a rule
+ * belongs here at all.
+ */
+function styleBlock(): string {
+  return [
+    `<style>`,
+    `@media only screen and (max-width:620px){`,
+    `.fp-card{width:100%!important;border-radius:0!important;border-left:0!important;border-right:0!important}`,
+    `.fp-pad{padding-left:24px!important;padding-right:24px!important}`,
+    `.fp-h1{font-size:22px!important}`,
+    `}`,
+    `</style>`,
+  ].join("");
+}
+
+/**
+ * Render the document as the HTML half of the message.
+ *
+ * A complete document rather than a fragment: a `<!DOCTYPE>` is what puts
+ * Outlook into standards mode, and `x-apple-disable-message-reformatting` is
+ * what stops iOS Mail re-flowing the card to the screen width and shrinking the
+ * type with it.
+ */
+export function renderEmailHtml(document: EmailDocument): string {
+  const theme = document.theme ?? NEUTRAL_EMAIL_THEME;
+  const body = [
+    `<h1 class="fp-h1" style="margin:0 0 16px;font-size:26px;line-height:1.25;font-weight:700;letter-spacing:-.3px;color:${theme.ink}">${escapeHtml(document.heading)}</h1>`,
+    ...(document.paragraphs ?? []).map((text) => paragraph(text, theme)),
+    facts(document.facts ?? [], theme),
+    ...(document.action ? [action(document.action, theme)] : []),
+    ...(document.action ? [fallback(document.action, document.chrome, theme)] : []),
+    ...(document.notes ?? []).map(
+      (note) =>
+        `<p style="margin:0 0 8px;font-size:13px;line-height:1.5;color:${theme.muted}">${escapeHtml(note)}</p>`,
+    ),
+  ].join("\n      ");
+
+  return `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="${escapeHtml(document.locale)}">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="x-apple-disable-message-reformatting" />
+<meta name="color-scheme" content="light" />
+<meta name="supported-color-schemes" content="light" />
+<title>${escapeHtml(document.subject)}</title>
+${styleBlock()}
+</head>
+<body style="margin:0;padding:0;background:${theme.page};font-family:${EMAIL_FONT_STACK};-webkit-font-smoothing:antialiased">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;mso-hide:all">${escapeHtml(preheaderOf(document))}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:${theme.page}">
+<tr>
+<td align="center" style="padding:32px 12px">
+<table role="presentation" class="fp-card" width="${EMAIL_CONTENT_WIDTH}" cellpadding="0" cellspacing="0" border="0" style="width:${EMAIL_CONTENT_WIDTH}px;max-width:100%;background:${theme.surface};border:1px solid ${theme.border};border-radius:14px">
+${header(document, theme)}
+<tr>
+<td class="fp-pad" style="padding:24px 40px 8px">
+      ${body}
+</td>
+</tr>
+${footer(document, theme)}
+</table>
+</td>
+</tr>
+</table>
+</body>
+</html>`;
+}
+
+/** Both halves plus the subject — what every driver in this repo is handed. */
+export interface RenderedEmail {
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+}
+
+/** Render one document into the message shape `EmailDriver.send` takes. */
+export function renderEmail(document: EmailDocument): RenderedEmail {
+  return {
+    subject: document.subject,
+    html: renderEmailHtml(document),
+    text: renderEmailText(document),
+  };
+}

package/src/email/text.ts

@@ -0,0 +1,59 @@
+import type { EmailDocument } from './template';
+
+/**
+ * The plain-text half.
+ *
+ * Not a courtesy. Every major spam filter scores a `text/html` part with no
+ * `text/plain` twin, and a watch, a terminal client and a screen reader in
+ * plain-text mode show this and nothing else.
+ *
+ * It renders from the SAME `EmailDocument` the HTML half does, which is the
+ * property that matters: a line added to one is in the other, so the two cannot
+ * drift. Its own module only because the HTML renderer is already a file's
+ * worth of client workarounds — the seam is the output format, not the content.
+ */
+
+/**
+ * Render the document as the plain-text half.
+ *
+ * Not a courtesy. Every major spam filter scores a `text/html` part with no
+ * `text/plain` twin, and a watch, a terminal client and a screen reader in
+ * plain-text mode show this and nothing else. It is rendered from the SAME
+ * object, so it cannot say less than the HTML does.
+ */
+export function renderEmailText(document: EmailDocument): string {
+  const blocks = [
+    document.heading,
+    "",
+    ...textParagraphs(document),
+    ...textFacts(document),
+    ...textAction(document),
+    ...textNotes(document),
+    "--",
+    document.chrome.tagline(document.brand),
+    document.chrome.automated,
+  ];
+  return `${blocks.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+
+/** One blank line after each paragraph, as prose reads. */
+function textParagraphs(document: EmailDocument): string[] {
+  return (document.paragraphs ?? []).flatMap((text) => [text, ""]);
+}
+
+/** `Label: value` per row, as a receipt is quoted back over the phone. */
+function textFacts(document: EmailDocument): string[] {
+  const rows = document.facts ?? [];
+  return rows.length === 0 ? [] : [...rows.map((f) => `${f.label}: ${f.value}`), ""];
+}
+
+/** The CTA as label + URL: a plain-text reader has no button to press. */
+function textAction(document: EmailDocument): string[] {
+  return document.action ? [`${document.action.label}: ${document.action.href}`, ""] : [];
+}
+
+function textNotes(document: EmailDocument): string[] {
+  const notes = document.notes ?? [];
+  return notes.length === 0 ? [] : [...notes, ""];
+}
+

package/src/email/theme.ts

@@ -0,0 +1,77 @@
+/**
+ * The layout's design tokens — the nine colours a mail is drawn from.
+ *
+ * ## Why a theme is a VALUE here and copy is required config
+ *
+ * The copy-portability doctrine is that a package ships no user-facing
+ * sentences: a default in the origin host's language reads as finished to the
+ * next host right up until somebody's customer gets mail in a language they do
+ * not speak. Colour is not that. {@link NEUTRAL_EMAIL_THEME} is not anybody's
+ * brand — it is grey on white, which reads as *unstyled but tidy* rather than
+ * as *somebody else's product*. A host that passes nothing gets a mail that
+ * looks plain, not a mail that looks like a different company.
+ *
+ * So this one has a default and the copy does not, and the difference is
+ * exactly whether getting it wrong is invisible. A missing theme is visible in
+ * the first preview; a wrong-language default is invisible until a customer
+ * complains.
+ *
+ * ## What a host should know before overriding it
+ *
+ * Two rungs of most brand palettes cannot carry light text, and a mail has no
+ * theme to fall back on when a client ignores a colour. {@link accent} is the
+ * one that MUST clear 4.5:1 against white — it is the CTA fill and every link.
+ * A warm mid-tone that looks fine on a screen at 2.6:1 is unreadable in an
+ * inbox, and nothing in the pipeline will say so.
+ */
+export interface EmailTheme {
+  /** The page behind the card. Never pure white: a white card needs a ground. */
+  readonly page: string;
+  /** The card itself. */
+  readonly surface: string;
+  /** A quieter panel inside the card — the facts table. */
+  readonly panel: string;
+  /** Every hairline. */
+  readonly border: string;
+  /** Body text. */
+  readonly ink: string;
+  /** Secondary text: the footer, the fallback link, a fact's label. */
+  readonly muted: string;
+  /** The action colour — the CTA fill and every link. Must clear 4.5:1 on white. */
+  readonly accent: string;
+  /** Ink ON {@link accent}. */
+  readonly onAccent: string;
+  /** The rule under the wordmark. Decorative — nothing is written on it. */
+  readonly rule: string;
+}
+
+/**
+ * A brand-free default: greys, one blue, nothing anybody would mistake for a
+ * product. Every value clears its contrast requirement against its own ground.
+ */
+export const NEUTRAL_EMAIL_THEME: EmailTheme = {
+  page: '#F5F6F8',
+  surface: '#FFFFFF',
+  panel: '#F5F6F8',
+  border: '#E1E4E9',
+  ink: '#1A1D23',
+  muted: '#5C6470',
+  accent: '#1F5EDB',
+  onAccent: '#FFFFFF',
+  rule: '#1F5EDB',
+};
+
+/**
+ * The font stack, as one string.
+ *
+ * System fonts only, and no web font: a `@font-face` is stripped by Gmail and
+ * by Outlook, so a mail that depends on one renders in whatever the client
+ * substitutes — never the fallback the designer chose. The stack ends in the
+ * emoji faces so a status glyph in a subject line does not drop to a tofu box
+ * on Windows.
+ */
+export const EMAIL_FONT_STACK =
+  "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'";
+
+/** The card's width. 600px is the width every client lays out without scroll. */
+export const EMAIL_CONTENT_WIDTH = 600;

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   type NotificationChannel,
   type NotificationContent,
   type NotificationEvent,
+  type NotificationGenerateContext,
   type NotificationGenerator,
   type NotificationLogger,
   type NotificationRecipient,

package/src/manifest/index.ts

@@ -61,3 +61,40 @@ export const notificationsManifest = {
   server: ['http', 'jobs'],
   web: ['surface'],
 } as const satisfies PackageManifest;
+
+/**
+ * The e-mail PREVIEW console — a second manifest, from the same package.
+ *
+ * ## Why a second manifest and not two more keys on the first
+ *
+ * `notificationsManifest` has already spent both slots this surface needs:
+ * `http` is the account inbox at `/api/account`, `surface` is the bell and the
+ * preference matrix. A capability is singular by the contract's shape, so a
+ * package with two genuinely different surfaces declares two manifests — which
+ * is exactly what `@12-apps/auth` does with `@12-apps/auth-platform`, and for
+ * the same reason it gives: those two switches turn a sign-in method off for
+ * EVERYBODY, so they do not belong behind the same gate as "reset my password".
+ *
+ * The split here is the same one. The inbox ships to every signed-in user; this
+ * console publishes the product's whole transactional-mail inventory and the
+ * exact wording and link shape of its verification and reset mails, which is
+ * the reference someone writing a convincing phishing mail would want. Two
+ * manifests keep that expressible: a host mounts the inbox and DECLINES the
+ * console, in writing, rather than silently getting both behind one gate.
+ *
+ * ## What it deliberately does not declare
+ *
+ * No `db` — a catalogue is DERIVED from what a host already sends, so an
+ * adopter mounts it without touching its schema. No `notifications`, because
+ * this surface authors no alert. And no `email`: that capability is a DELIVERY
+ * port, and this manifest renders and never sends. The delivery port is the
+ * OTHER half of this package, and it stays where it is.
+ */
+export const notificationEmailPreviewsManifest = {
+  name: '@12-apps/notifications-email-previews',
+  contract: 1,
+  /** A refusal to render a preview files under its own namespace, not nowhere. */
+  observability: { namespace: 'email-previews' },
+  server: ['http'],
+  web: ['surface'],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -25,6 +25,8 @@
 
 import type { AnyServerManifest, WireRequest } from '@12-apps/wiring';
 
+import { emailPreviewRoutes } from '../email/previews/routes';
+import type { EmailPreviewsConfig } from '../email/previews/catalog';
 import {
   createApiNotifications,
   NOTIFICATIONS_JOBS,
@@ -84,3 +86,24 @@ export const notificationsServerManifest = {
    */
   jobs: NOTIFICATIONS_JOBS,
 } as const satisfies AnyServerManifest;
+
+/**
+ * The preview console's server half — the two endpoints over the catalogue.
+ *
+ * A CONSTANT, not a factory. `http.create(config)` receives whatever the host
+ * bound at adoption, and "which messages exist" is precisely a host's binding:
+ * a package cannot know that a product sends a "your quota is exhausted"
+ * notice, let alone what data it renders from. Writing `EmailPreviewsConfig`
+ * as a factory argument instead would move that decision out of
+ * `bindings.http`, where `assemble()` can report on it, into a call the report
+ * never sees.
+ *
+ * The routes carry `kind: 'authenticated'` — see `../email/previews/routes`
+ * for why the descriptor states a posture it cannot itself enforce.
+ */
+export const notificationEmailPreviewsServerManifest = {
+  name: '@12-apps/notifications-email-previews',
+  http: {
+    create: (config: EmailPreviewsConfig) => ({ routes: emailPreviewRoutes(config) }),
+  },
+} as const satisfies AnyServerManifest;

package/src/manifest/web.ts

@@ -38,9 +38,22 @@
 
 import type { AnyWebManifest } from '@12-apps/wiring';
 
+import { createEmailPreviewScreen } from '../email/previews/react/preview-screen';
 import { createWebNotifications } from '../react/create-web-notifications';
 
 export const notificationsWebManifest = {
   name: '@12-apps/notifications',
   surface: { create: createWebNotifications },
 } as const satisfies AnyWebManifest;
+
+/**
+ * The preview console's web half.
+ *
+ * One screen, named `page`, because a screen's NAME is what an area row
+ * resolves against — a surface that was itself the component is the shape that
+ * made an area row resolve to `undefined` in `@12-apps/auth` for a release.
+ */
+export const notificationEmailPreviewsWebManifest = {
+  name: '@12-apps/notifications-email-previews',
+  surface: { create: createEmailPreviewScreen },
+} as const satisfies AnyWebManifest;

package/src/server/db.ts

@@ -246,7 +246,18 @@ export type NotificationsDbProvider = () => Promise<NotificationsDb>;
  * Returning `null` for a user id means "no such recipient", which `notify`
  * treats as a caller bug and throws on — a notification addressed to nobody is
  * never silently dropped.
+ *
+ * `locale` is the recipient's own language, and it is here rather than on the
+ * event because it is a fact about the PERSON, not about what happened
+ * The host owns it for the same reason it owns the address: this
+ * package has no user table to read it from. Absent — the field omitted, or
+ * `null` for a host that stores no language yet — means "nobody said", and
+ * every generator answers with its default exactly as before.
  */
 export interface NotificationContactDirectory {
-  getContact(userId: string): Promise<{ email: string | null; phone: string | null } | null>;
+  getContact(userId: string): Promise<{
+    email: string | null;
+    phone: string | null;
+    locale?: string | null;
+  } | null>;
 }

package/src/server/dispatch.ts

@@ -99,6 +99,10 @@ export async function loadRecipient(
     userId,
     email: contact.email,
     phone: contact.phone,
+    // Carried through UNRESOLVED and only where the host supplied one: the
+    // absent case has to stay distinguishable from a stated language, because
+    // that is what lets a generator apply its own default in one place.
+    ...(contact.locale === undefined ? {} : { locale: contact.locale }),
     pushSubscriptionCount: await deps.pushSubscriptions.count(userId),
   };
 }

package/src/server/router.ts

@@ -235,11 +235,27 @@ export function createNotificationRouter(deps: NotificationRouterDeps): Notifica
 
     async notify(event, options = {}) {
       const generator = deps.generators.resolve(event.type);
-      const content = generator.generate(event.payload as never);
 
+      /*
+        The recipient is loaded BEFORE the content is rendered, and the order is
+        the whole of the fix.
+
+        `notify` is already per-person — `event.recipient.userId` is one user,
+        and a permission fan-out resolves its audience and calls this once each
+        — so the reader was knowable here all along. Rendering first simply
+        threw that away: the row was written in whatever language the generator
+        had been bound to at boot, for everyone.
+
+        Loading first also means a notification addressed to nobody now throws
+        before any content is built, which is the cheaper order anyway.
+      */
       const recipient = await loadRecipient(deps, event.recipient.userId);
       if (!recipient) throw new UnknownNotificationRecipientError(event.recipient.userId);
 
+      // Forwarded exactly as the directory stated it, `undefined` included: the
+      // generator owns the fallback, in one place a reader can find.
+      const content = generator.generate(event.payload as never, { locale: recipient.locale });
+
       const channels = await resolveChannels(deps, event, generator.category, recipient);
       const notification = await commit(deps, event, generator.category, content, channels);