@company-semantics/contracts 35.0.0 → 36.0.0

package/src/notifications/renderers/email/index.ts

@@ -11,10 +11,10 @@
  * - Pure. `render` is a function of `(content, context)` — no clock, no
  *   environment, no I/O. The copyright year comes from
  *   `context.brand.copyrightYear`.
- * - Output is byte-identical to what the old `src/email/render` emitted. That is
- *   the whole constraint of this migration, and `__tests__/render.test.ts`
- *   proves it against the frozen output-parity golden — which, now that the old
- *   layer is deleted, is the only surviving record of those bytes.
+ * - Output is locked by `../../__tests__/render-snapshot.test.ts`. Byte-identity
+ *   with the old `src/email/render` was the whole constraint of the migration
+ *   and it held; ADR-CONTRACTS-087 discharged that proof once it shipped, so
+ *   this channel's markup is now free to change — reviewably, via the snapshot.
  * - `supports` answers true for every element type: email is the rich channel,
  *   and there is nothing in the content model it cannot depict.
  */
@@ -25,16 +25,30 @@ import type { Renderer } from "../../renderer";
 
 import type { Spacing } from "./constants";
 import { renderElement } from "./render";
-import { type EmailLine, htmlShell, textShell } from "./shells";
+import { ampShell, type EmailLine, htmlShell, textShell } from "./shells";
 
-/** One rendered email — the email channel's natural output type. */
+/**
+ * One rendered email — the email channel's natural output type.
+ *
+ * Three bodies, because an email IS a `multipart/alternative`: one message, whose
+ * parts a client chooses between. This is NOT three channels — a recipient gets one
+ * email — which is why AMP lives here rather than behind a second `Renderer`
+ * (ADR-CONTRACTS-089). Assembling the parts is delivery's job, and delivery is not
+ * contracts': today the backend sends `text` and `html` over SES's simple send and
+ * `amp` goes nowhere.
+ */
 export interface RenderedEmail {
   /** Subject line — the notification's `metadata.title`. */
   subject: string;
-  /** Plain-text body. */
+  /** Plain-text body (`text/plain`). */
   text: string;
-  /** HTML body (every kind is dual-output). */
+  /** HTML body (`text/html`) — every kind is multi-output. */
   html: string;
+  /**
+   * AMP4EMAIL body (`text/x-amp-html`) — read by Gmail, Yahoo and Mail.ru, and
+   * the only surface where the CTA's `:hover` reaches most recipients.
+   */
+  amp: string;
 }
 
 /**
@@ -68,6 +82,7 @@ export const emailRenderer: Renderer<RenderedEmail> = {
       subject: content.metadata.title,
       text: textShell(lines),
       html: htmlShell(lines),
+      amp: ampShell(lines),
     };
   },
 };

package/src/notifications/renderers/email/render.ts

@@ -5,7 +5,9 @@
  * module offered templates a component per intent (`greeting()`, `keyValue()`,
  * `footer()`) and each template chose which to call; here the CONTENT names the
  * intent and this module is the only thing that knows the markup. The strings
- * are the same strings — the output-parity golden asserts them byte-for-byte.
+ * started as the same strings, byte-for-byte; they are free to diverge now
+ * (ADR-CONTRACTS-087) and `../../__tests__/render-snapshot.test.ts` is what
+ * makes each divergence a reviewed one.
  *
  * **Spacing is derived, because the content model does not carry it.** The old
  * layer passed a `Spacing` per block, and `../../kinds` deliberately dropped it:
@@ -43,22 +45,17 @@ import type {
 } from "../../content";
 import type { RenderContext } from "../../context";
 
-import {
-  COMPANY_URL,
-  FONT_SIZE,
-  MONO,
-  SPACING,
-  type Spacing,
-} from "./constants";
+import { COMPANY_URL, type Spacing } from "./constants";
 import { renderChatUnit } from "./chat";
 import { ctaButton } from "./cta";
 import { escapeHtml } from "./escape-html";
 import type { EmailLine } from "./shells";
+import { styleClass } from "./styles";
 
 /** One `<p>` — the primitive every prose-ish element is built from. */
 function paragraph(html: string, text: string, spacing: Spacing): EmailLine {
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
+    html: `<p ${styleClass(`p-${spacing}`)}>${html}</p>`,
     text,
     spacing,
   };
@@ -89,7 +86,7 @@ function keyValueLine(row: KeyValueRow): { html: string; text: string } {
 
 /** The standalone `>> LABEL <<` box. */
 function ctaLine(cta: CallToAction, trailing: Spacing): EmailLine {
-  const { html, text } = ctaButton(cta, SPACING[trailing]);
+  const { html, text } = ctaButton(cta, trailing);
   return { html, text, spacing: trailing };
 }
 
@@ -97,7 +94,7 @@ function ctaLine(cta: CallToAction, trailing: Spacing): EmailLine {
 function signatureLine(signer: string, year: number): EmailLine {
   const line = `ⓒ ${year} • ${signer}`;
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};"><br><br><span style="color: #bbb;">/* EOM */</span><br>${escapeHtml(line)}<br><a href="${COMPANY_URL}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(COMPANY_URL)}</a></p>`,
+    html: `<p ${styleClass("p-none")}><br><br><span ${styleClass("eom", "faint")}>/* EOM */</span><br>${escapeHtml(line)}<br><a href="${escapeHtml(COMPANY_URL)}" target="_blank" rel="noopener noreferrer" ${styleClass("signature-link", "link")}>${escapeHtml(COMPANY_URL)}</a></p>`,
     text: `\n\n/* EOM */\n${line}\n${COMPANY_URL}`,
     spacing: "none",
   };
@@ -151,8 +148,18 @@ export function renderElement(
     case "warning": {
       // Fieldless by design — the banner IS the content, and its wording is the
       // renderer's (see `../../content.ts`).
+      //
+      // The colour is this channel's answer to "this is a security notice", and
+      // only the HTML surface can give it: plain text has no colour, so there
+      // the banner's own glyphs carry the whole signal.
       const text = "🆆🅰🆁🅽🅸🅽🅶";
-      return [paragraph(escapeHtml(text), text, trailing)];
+      return [
+        paragraph(
+          `<span ${styleClass("warning", "destructive")}>${escapeHtml(text)}</span>`,
+          text,
+          trailing,
+        ),
+      ];
     }
 
     case "notice":
@@ -202,20 +209,29 @@ export function renderElement(
     case "divider":
       return [
         {
-          html: `<hr style="border: none; border-top: 1px solid #bbb; margin: ${SPACING[trailing]};">`,
+          html: `<hr ${styleClass(`hr-${trailing}`, "faint")}>`,
           text: "---",
           spacing: trailing,
         },
       ];
 
-    case "heroImage":
+    case "heroImage": {
+      // Stated as attributes, not just style: they are the image's intrinsic
+      // size, every client uses them to reserve space before it loads, and
+      // `./styles.ts`'s `ampify` reads them to decide whether the AMP surface can
+      // draw an `<amp-img>` at all.
+      const dimensions =
+        element.width !== undefined && element.height !== undefined
+          ? ` width="${element.width}" height="${element.height}"`
+          : "";
       return [
         {
-          html: `<img src="${element.src}" alt="${escapeHtml(element.alt)}" style="max-width: 100%; margin: ${SPACING[trailing]};">`,
+          html: `<img src="${escapeHtml(element.src)}" alt="${escapeHtml(element.alt)}"${dimensions} ${styleClass(`hero-${trailing}`)}>`,
           text: element.alt,
           spacing: trailing,
         },
       ];
+    }
 
     default: {
       const _exhaustive: never = element;

package/src/notifications/renderers/email/shells.ts

@@ -8,11 +8,21 @@
  *
  * INVARIANTS:
  * - Pure functions of their input lines. No clock, no environment, no I/O.
- * - Byte-identical to what that module emitted. These strings are the email's
- *   actual markup; the output-parity golden asserts them character-for-character.
+ * - These strings are the email's actual markup, and
+ *   `../../__tests__/render-snapshot.test.ts` asserts them
+ *   character-for-character.
  */
 
-import { MONO, type Spacing } from "./constants";
+import { BASE_STYLE, DARK_STYLE, hoverStyle } from "./colors";
+import type { Spacing } from "./constants";
+import { MSO_CTA_STYLE } from "./cta";
+import {
+  AMP_RECIPE_RULES,
+  ampify,
+  inlineOf,
+  inlineStyles,
+  styleClass,
+} from "./styles";
 
 /**
  * One rendered line — both presentations of one thing the notification says,
@@ -29,17 +39,111 @@ export interface EmailLine {
   spacing: Spacing;
 }
 
-/** Wrap rendered lines in the shared `<!DOCTYPE>` monospace shell. */
+/**
+ * Wrap rendered lines in the shared `<!DOCTYPE>` monospace shell.
+ *
+ * The two metas declare that this email renders in either scheme, and `<style>`
+ * is what makes the declaration true — see `./colors.ts`'s `DARK_STYLE`. The
+ * declaration is a promise: made without the stylesheet, Apple Mail would stop
+ * protecting our colours, apply its dark background, and leave the inline LIGHT
+ * text colour sitting on top of it. The two ship together or not at all.
+ *
+ * Only Apple Mail, iOS Mail and Outlook for Mac read any of this. Clients that
+ * force-invert (Outlook.com, Windows Outlook, Gmail Android) ignore both metas
+ * and rewrite the inline styles post-delivery — nothing here can stop that, which
+ * is why the body still states an explicit background rather than trusting a
+ * default.
+ *
+ * The `<!--[if mso]>` block is the mirror image: it is read ONLY by the Outlook
+ * Word engine, and undoes the one layout that engine cannot render — a linked
+ * CTA's full-box click target. See `./cta.ts`'s `MSO_CTA_STYLE`.
+ */
 export function htmlShell(lines: EmailLine[]): string {
-  const inner = lines
-    .map((line) => line.html)
-    .filter(Boolean)
-    .join("\n");
+  // `inlineStyles` is spent on the ELEMENT markup only. The shell states its own
+  // two slots directly: they are not `EmailLine`s, and keeping the inliner away
+  // from the `<head>` means a stylesheet can never be rewritten by it — CSS has
+  // attribute selectors (`[class="x"]`), and today's blocks happen not to use one.
+  const inner = inlineStyles(
+    lines
+      .map((line) => line.html)
+      .filter(Boolean)
+      .join("\n"),
+  );
   return `<!DOCTYPE html>
 <html lang="en">
-<head><meta charset="UTF-8"></head>
-<body style="${MONO} color: #1a1a1a; margin: 0; padding: 0;">
-<div style="max-width: 520px; margin: 0 auto;">
+<head><meta charset="UTF-8">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<style>${BASE_STYLE}
+${DARK_STYLE}</style>
+<!--[if mso]><style>${MSO_CTA_STYLE}</style><![endif]--></head>
+<body style="${inlineOf("body")}">
+<div style="${inlineOf("frame")}">
+${inner}
+</div>
+</body>
+</html>`;
+}
+
+/**
+ * Wrap rendered lines in the AMP4EMAIL shell (ADR-CONTRACTS-089).
+ *
+ * The third MIME part of the same email — `text/x-amp-html`, beside `text/html`
+ * and `text/plain`. Gmail, Yahoo and Mail.ru read it; everyone else reads the
+ * html part and never knows this existed. That is the point: `./colors.ts`'s
+ * `hoverStyle` is absent in Gmail on the html surface, and here it simply works.
+ *
+ * Everything AMP forbids is absent BY CONSTRUCTION rather than by stripping:
+ *
+ * - **No inline `style`.** The lines are class-only; only `htmlShell` inlines them.
+ * - **No `!important`.** `hoverStyle(false)` — there is no inline style to beat
+ *   here, so nothing needs to win a specificity fight, and AMP forbids the keyword
+ *   anyway.
+ * - **No `<!--[if mso]>`.** `MSO_CTA_STYLE` lives in `htmlShell`'s `<head>`, never
+ *   in a line, so nothing has to remove it. Outlook is not an AMP client, and
+ *   `display: block` needs no correction in the three that are.
+ *
+ * **No dark scheme, and that is not an omission.** AMP4EMAIL disallows the
+ * `prefers-color-scheme` media feature — verified against the AMP validator, with
+ * and without `data-css-strict` — so `DARK_STYLE` cannot appear here in any form.
+ * It costs nothing: that block is read by Apple Mail, iOS Mail and Outlook for Mac,
+ * and this surface is read by Gmail, Yahoo and Mail.ru. The two sets are disjoint,
+ * and the AMP clients force-invert rather than honour a stylesheet — so they were
+ * never receiving our dark colours on the html surface either. What this surface
+ * adds is `:hover`, which those clients DO honour and which the html surface cannot
+ * reach them with. It trades nothing away.
+ *
+ * The boilerplate hides the body until the runtime unhides it — which is why an
+ * AMP document that cannot run scripts shows nothing at all, rather than showing
+ * an unstyled version of itself.
+ */
+export function ampShell(lines: EmailLine[]): string {
+  const inner = ampify(
+    lines
+      .map((line) => line.html)
+      .filter(Boolean)
+      .join("\n"),
+  );
+  // `amp4email` rather than the `⚡4email` the spec also allows: both are valid,
+  // and one of them survives every editor, terminal and diff it will ever cross.
+  //
+  // `data-css-strict` opts into AMP's strict CSS validation. The validator warns
+  // when it is absent and says it "may become an error in the future"; our CSS
+  // passes with and without it, so taking it now costs nothing and means that
+  // future arrives already handled.
+  //
+  // The shell wears its own recipes as CLASSES, where `htmlShell` inlines them —
+  // that asymmetry is the whole surface split, and it means `body` and `frame`
+  // need no special case: `AMP_RECIPE_RULES` already states every recipe's rule.
+  return `<!DOCTYPE html>
+<html amp4email data-css-strict lang="en">
+<head><meta charset="utf-8">
+<script async src="https://cdn.ampproject.org/v0.js"></script>
+<style amp4email-boilerplate>body{visibility:hidden}</style>
+<style amp-custom>${AMP_RECIPE_RULES}
+${hoverStyle(false)}</style></head>
+<body ${styleClass("body")}>
+<div ${styleClass("frame")}>
 ${inner}
 </div>
 </body>

package/src/notifications/renderers/email/styles.ts

@@ -0,0 +1,361 @@
+/**
+ * Every declaration the email channel makes, and the two surfaces built from them
+ * (ADR-CONTRACTS-089).
+ *
+ * **Why this file exists.** AMP4EMAIL forbids inline `style` attributes; the html
+ * surface depends on them, because inline is the light baseline every client gets
+ * including the ones that strip `<style>` (see `./colors.ts`'s `roleDecl`). The two
+ * surfaces are opposed on exactly the styling axis, so the markup can belong to
+ * neither: `./render`, `./cta` and `./chat` emit CLASS-ONLY markup, and each shell
+ * spends this registry its own way — `htmlShell` inlines it, `ampShell` states it
+ * as `<style amp-custom>`. One markup, two transforms, no second copy to drift.
+ *
+ * This is deliberately NOT a third field on `EmailLine`. `../../renderer.ts`
+ * warns that the old `Block` "carried `html` and `text` together and would have
+ * carried a third surface bolted on"; a surface is a way of SPENDING the lines,
+ * not a thing a line carries.
+ *
+ * **Why this is not `./colors.ts`.** The split is not "colour vs layout" — it is
+ * *what a colour is* vs *which declarations an element makes, in what order*.
+ * Nothing here states a colour; it asks `./colors.ts` for one. That keeps colour
+ * changeable in exactly one place, and it means `__tests__/colors.test.ts`'s
+ * literal guard — which reads every `.ts` in this directory except `colors.ts` —
+ * covers this file for free. Keep it here, not in a subdirectory, and that stays
+ * true.
+ *
+ * **Why recipes and not utility classes.** A utility set (`cs-m-20`, `cs-fs-13`)
+ * cannot reproduce today's bytes, because declaration ORDER differs per slot:
+ * `dots-over-cta` is `font → dots → text-align → margin` and `dots-cell` is
+ * `width → text-align → font → dots`. Same declarations, different order, two
+ * recipes. A recipe carries the order; a utility set cannot. It also keeps the
+ * emitting modules readable — one class names one intent.
+ *
+ * INVARIANTS:
+ * - Pure data and pure functions of it. No clock, no environment, no I/O.
+ * - A recipe's declarations are UNTERMINATED. This module owns every separator,
+ *   so a declaration cannot decide the joiner's output.
+ * - `cs-` classes ship; `csr-` classes do not — `__tests__/styles.test.ts`.
+ * - The html surface's bytes are locked by `../../__tests__/render-snapshot.test.ts`,
+ *   which is what proves this registry reconstitutes them exactly.
+ */
+
+import { classNameFor, palette, type Role, roleDecl } from "./colors";
+import { CTA_PAD, FONT_SIZE, MONO_DECL, SPACING } from "./constants";
+
+/** One slot's declarations, in the order they are written. Unterminated. */
+type Recipe = readonly string[];
+
+/**
+ * Every styled slot in the channel, named by what it is.
+ *
+ * Spacing-parameterized families are written out per `Spacing` rather than
+ * generated: `../../constants.ts` closes `Spacing` at three, the names are what
+ * `./render` reads, and three explicit lines are worth more than a clever fold.
+ */
+const RECIPES = {
+  // --- ./shells.ts ---------------------------------------------------------
+  body: [
+    MONO_DECL,
+    roleDecl("text"),
+    roleDecl("background", "background-color"),
+    "margin: 0",
+    "padding: 0",
+  ],
+  /** The 520px column every email is poured into. */
+  frame: ["max-width: 520px", "margin: 0 auto"],
+
+  // --- ./render.ts ---------------------------------------------------------
+  "p-normal": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    `margin: ${SPACING.normal}`,
+  ],
+  "p-tight": [MONO_DECL, `font-size: ${FONT_SIZE}`, `margin: ${SPACING.tight}`],
+  "p-none": [MONO_DECL, `font-size: ${FONT_SIZE}`, `margin: ${SPACING.none}`],
+  /** The `/* EOM *\/` marker above the signer. */
+  eom: [roleDecl("faint")],
+  "signature-link": [roleDecl("link"), "text-decoration: none"],
+  warning: [roleDecl("destructive")],
+  "hr-normal": [
+    "border: none",
+    `border-top: 1px solid ${palette("light").faint}`,
+    `margin: ${SPACING.normal}`,
+  ],
+  "hr-tight": [
+    "border: none",
+    `border-top: 1px solid ${palette("light").faint}`,
+    `margin: ${SPACING.tight}`,
+  ],
+  "hr-none": [
+    "border: none",
+    `border-top: 1px solid ${palette("light").faint}`,
+    `margin: ${SPACING.none}`,
+  ],
+  "hero-normal": ["max-width: 100%", `margin: ${SPACING.normal}`],
+  "hero-tight": ["max-width: 100%", `margin: ${SPACING.tight}`],
+  "hero-none": ["max-width: 100%", `margin: ${SPACING.none}`],
+
+  // --- ./cta.ts ------------------------------------------------------------
+  "cta-box-normal": [
+    "display: inline-block",
+    `border: 1px solid ${palette("light").cta}`,
+    "border-radius: 2px",
+    `margin: ${SPACING.normal}`,
+    "max-width: 220px",
+  ],
+  "cta-box-tight": [
+    "display: inline-block",
+    `border: 1px solid ${palette("light").cta}`,
+    "border-radius: 2px",
+    `margin: ${SPACING.tight}`,
+    "max-width: 220px",
+  ],
+  "cta-box-none": [
+    "display: inline-block",
+    `border: 1px solid ${palette("light").cta}`,
+    "border-radius: 2px",
+    `margin: ${SPACING.none}`,
+    "max-width: 220px",
+  ],
+  /** A linked button's cell holds no padding — the anchor carries it. */
+  "cta-cell-linked": [
+    "text-align: center",
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+  ],
+  /** An unlinked code is not clickable, so its padding stays on the cell. */
+  "cta-cell-code": [
+    `padding: ${CTA_PAD}`,
+    "text-align: center",
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+  ],
+  "cta-label": ["text-decoration: underline"],
+  /** `display: block` + the padding is what makes the WHOLE box the click target. */
+  "cta-anchor": [
+    "display: block",
+    `padding: ${CTA_PAD}`,
+    roleDecl("link"),
+    "text-decoration: none",
+  ],
+  "cta-code": [roleDecl("link")],
+
+  // --- ./chat.ts -----------------------------------------------------------
+  "chat-rule-top": [
+    "border: none",
+    `border-top: 1px solid ${palette("light").faint}`,
+    "margin: 12px 0 24px 0",
+  ],
+  "chat-rule-bottom": [
+    "border: none",
+    `border-top: 1px solid ${palette("light").faint}`,
+    "margin: 24px 0 12px 0",
+  ],
+  /** A row that clears the bubbles: 24px. */
+  "chat-row-24": ["margin: 0 0 24px 0"],
+  /** A row hugging what follows it (a CTA, the dots): 16px. */
+  "chat-row-16": ["margin: 0 0 16px 0"],
+  "chat-attribution": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    roleDecl("meta"),
+    "text-align: right",
+    "padding-top: 6px",
+    "padding-right: 1ch",
+  ],
+  "chat-avatar-left": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    "padding-right: 8px",
+    "vertical-align: bottom",
+    "white-space: nowrap",
+  ],
+  /** The mirror that reserves the column's width without drawing the avatar. */
+  "chat-avatar-left-hidden": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    "padding-right: 8px",
+    "vertical-align: bottom",
+    "visibility: hidden",
+    "white-space: nowrap",
+  ],
+  "chat-avatar-right": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    "padding-left: 8px",
+    "vertical-align: bottom",
+    "white-space: nowrap",
+  ],
+  "chat-avatar-right-hidden": [
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    "padding-left: 8px",
+    "vertical-align: bottom",
+    "visibility: hidden",
+    "white-space: nowrap",
+  ],
+  "chat-channel-left": ["width: 100%", "text-align: left"],
+  "chat-channel-right": ["width: 100%", "text-align: right"],
+  "chat-bubble-wrap": [
+    "display: inline-block",
+    "max-width: 100%",
+    "vertical-align: bottom",
+  ],
+  "bubble-user": [
+    "border-radius: 8px 8px 0 8px",
+    "padding: 10px 14px",
+    "text-align: right",
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    roleDecl("onBubble"),
+    roleDecl("bubble", "background"),
+  ],
+  "bubble-assistant": [
+    "border-radius: 8px 8px 8px 0",
+    "padding: 10px 14px",
+    MONO_DECL,
+    `font-size: ${FONT_SIZE}`,
+    roleDecl("onBubble"),
+    roleDecl("bubble", "background"),
+  ],
+  /** Dots sharing the CTA's inline-block, so they centre over its exact width. */
+  "dots-over-cta": [
+    MONO_DECL,
+    "font-size: 20px",
+    "font-weight: bold",
+    roleDecl("dots"),
+    "text-align: center",
+    "margin: 0 0 16px 0",
+  ],
+  /** Standalone dots, centred in the message channel. */
+  "dots-cell": [
+    "width: 100%",
+    "text-align: center",
+    MONO_DECL,
+    "font-size: 20px",
+    "font-weight: bold",
+    roleDecl("dots"),
+  ],
+  "cta-stack": ["display: inline-block", "text-align: left"],
+} as const satisfies Record<string, Recipe>;
+
+/** Every styled slot, named. */
+export type StyleName = keyof typeof RECIPES;
+
+/** Every recipe name, for tests to iterate. */
+export const STYLE_NAMES = Object.keys(RECIPES) as StyleName[];
+
+/**
+ * The prefix that marks a class as the inliner's to consume.
+ *
+ * This is the whole mechanism. A `cs-` role class is a HOOK: `darkStyle` needs it
+ * in the shipped markup, so it survives. A `csr-` recipe class is a BUNDLE OF
+ * DECLARATIONS: the html surface spends it and drops it, the AMP surface keeps it
+ * and states its rule. One prefix test separates them — for `inlineStyles` below,
+ * and for `__tests__/colors.test.ts`, which asserts every SHIPPED class has a dark
+ * rule and would otherwise trip over every recipe class in this file.
+ */
+const RECIPE_PREFIX = "csr-";
+
+/** `bubble-user` → `csr-bubble-user`. Derived, never hand-typed. */
+function recipeClass(name: StyleName): string {
+  return `${RECIPE_PREFIX}${name}`;
+}
+
+/**
+ * The class attribute for one slot: its roles, then its recipe.
+ *
+ * Roles come FIRST so that dropping the recipe leaves exactly the class attribute
+ * the html surface shipped before this registry existed — which is what makes
+ * `inlineStyles` a byte-for-byte identity rather than a re-render.
+ */
+export function styleClass(name: StyleName, ...roles: Role[]): string {
+  const classes = [...roles.map(classNameFor), recipeClass(name)];
+  return `class="${classes.join(" ")}"`;
+}
+
+/** `border-radius: 8px; padding: 10px 14px;` — one recipe, inline. */
+export function inlineOf(name: StyleName): string {
+  return `${RECIPES[name].join("; ")};`;
+}
+
+/** `.csr-bubble-user { border-radius: 8px; … }` — one recipe, as a rule. */
+export function ruleOf(name: StyleName): string {
+  return `.${recipeClass(name)} { ${inlineOf(name)} }`;
+}
+
+/**
+ * Class-only markup → the html surface's markup.
+ *
+ * It never looks for elements; it rewrites CLASS ATTRIBUTES. Recipe classes become
+ * an inline `style`, role classes survive untouched, and a class attribute left
+ * with nothing in it disappears — which is what collapses `<p class="csr-p-normal">`
+ * back to `<p style="…">` rather than leaving a `class=""` behind.
+ *
+ * **Why a regex is safe here, and only here.** We control every class this can
+ * match, and `./escape-html.ts` escapes `"` — so no escaped content can close an
+ * attribute and forge one. The two values that do NOT pass through `escapeHtml`
+ * would be the hole, which is why `./cta.ts` and `./render.ts` escape `href` and
+ * `src` before interpolating: without that, a URL containing `" class="csr-body`
+ * is an HTML injection today and a style injection here.
+ */
+export function inlineStyles(html: string): string {
+  return html.replace(/class="([^"]*)"/g, (_match, value: string) => {
+    const names = value.split(" ").filter(Boolean);
+    const hooks = names.filter((name) => !name.startsWith(RECIPE_PREFIX));
+    const decls = names
+      .filter((name) => name.startsWith(RECIPE_PREFIX))
+      .flatMap(
+        (name) => RECIPES[name.slice(RECIPE_PREFIX.length) as StyleName],
+      );
+    return [
+      hooks.length ? `class="${hooks.join(" ")}"` : "",
+      decls.length ? `style="${decls.join("; ")};"` : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+  });
+}
+
+/**
+ * Class-only markup → the AMP surface's markup.
+ *
+ * The mirror of `inlineStyles`, and the reason both exist: that one resolves the
+ * surfaces' disagreement about STYLE, this one their disagreement about TAGS. AMP
+ * keeps the classes (its stylesheet is what needs them), so all this has to do is
+ * the one structural swap the surfaces cannot share.
+ *
+ * `<img>` → `<amp-img>`, which AMP requires and which needs explicit dimensions to
+ * reserve layout before the image loads. `../../content.ts` makes them optional,
+ * because a channel that can measure an image should not be told — so when they
+ * are absent this surface CANNOT draw the image, and says the `alt` text instead.
+ * That is a degradation, not a lie: `alt` is required exactly so a channel with
+ * nothing else has something to say, and the html surface still draws the picture.
+ *
+ * This does not contradict `supports("heroImage") === true` — `../../renderer.ts`
+ * puts `supports` on the RENDERER, and AMP is one of the email renderer's surfaces,
+ * not a renderer. Email can depict a hero image. One of its three MIME parts is
+ * plain text, which cannot, and that has never made the claim false.
+ */
+export function ampify(html: string): string {
+  return html.replace(/<img ([^>]*)>/g, (_match, attrs: string) => {
+    const sized = /\bwidth="\d+"/.test(attrs) && /\bheight="\d+"/.test(attrs);
+    if (sized) return `<amp-img ${attrs} layout="intrinsic"></amp-img>`;
+    const alt = /\balt="([^"]*)"/.exec(attrs)?.[1] ?? "";
+    // Carry the image's own spacing over to the paragraph replacing it, so the
+    // gap below it does not change with the fallback.
+    const spacing = /\bcsr-hero-(\w+)\b/.exec(attrs)?.[1] ?? "normal";
+    return `<p class="${RECIPE_PREFIX}p-${spacing}">${alt}</p>`;
+  });
+}
+
+/**
+ * Every recipe as a rule, for `<style amp-custom>`.
+ *
+ * ALL of them, always — not just the ones this email happens to use. Emitting the
+ * used subset would make the stylesheet a function of the content, so two emails
+ * would carry two different stylesheets and the snapshot would stop being a
+ * statement about the channel. ~40 rules is about 4KB against AMP's 75,000-byte
+ * budget, which `__tests__/amp.test.ts` holds us to.
+ */
+export const AMP_RECIPE_RULES = STYLE_NAMES.map(ruleOf).join("\n");