npm - @company-semantics/contracts - Versions diffs - 35.1.0 → 37.0.0 - Mend

@company-semantics/contracts 35.1.0 → 37.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/package.json +4 -1
package/src/notifications/__tests__/__snapshots__/render-snapshot.test.ts.snap +615 -215
package/src/notifications/content.ts +14 -1
package/src/notifications/index.ts +15 -9
package/src/notifications/renderers/email/README.md +120 -11
package/src/notifications/renderers/email/__tests__/colors.test.ts +227 -0
package/src/notifications/renderers/email/__tests__/render.test.ts +86 -0
package/src/notifications/renderers/email/__tests__/styles.test.ts +111 -0
package/src/notifications/renderers/email/chat.ts +42 -30
package/src/notifications/renderers/email/colors.ts +345 -0
package/src/notifications/renderers/email/constants.ts +27 -20
package/src/notifications/renderers/email/cta.ts +58 -10
package/src/notifications/renderers/email/index.ts +15 -3
package/src/notifications/renderers/email/render.ts +16 -15
package/src/notifications/renderers/email/shells.ts +49 -9
package/src/notifications/renderers/email/styles.ts +319 -0
package/src/notifications/renderers/slack/README.md +66 -25
package/src/notifications/renderers/slack/__tests__/index.test.ts +249 -41
package/src/notifications/renderers/slack/index.ts +192 -107

package/src/notifications/renderers/email/cta.ts CHANGED Viewed

@@ -7,19 +7,46 @@
  * (`./chat`), which place it at different margins.
  *
  * INVARIANTS:
- * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits.
+ * - Pure. The markup is CLASS-ONLY (ADR-CONTRACTS-089) — what ships is whatever
+ *   the surface's shell makes of it. `../../__tests__/render-snapshot.test.ts`
+ *   locks the html surface's bytes.
  * - `href` absent means the label IS the payload (an OTP code): the button must
  *   not become a link, and plain text must not print a URL under it.
  */
 import type { CallToAction } from "../../content";
-import { FONT_SIZE, MONO } from "./constants";
+import { CTA_PAD, type Spacing } from "./constants";
 import { escapeHtml } from "./escape-html";
+import { styleClass } from "./styles";
 /** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
 const CTA_BOX_PAD = 3;
+/**
+ * Outlook's answer to a full-box click target.
+ *
+ * A linked button makes its whole box clickable by moving the padding onto the
+ * `<a>` and setting `display: block`. Outlook's Word engine supports `display:
+ * none` and no other value, so the anchor stays inline there, and Word drops
+ * vertical padding on an inline element — the button would render cramped against
+ * its border. This MSO-only block puts the padding back on the cell and zeroes it
+ * on the anchor, so Outlook renders exactly today's padded, text-clickable box
+ * while every honouring client gets the full-box target.
+ *
+ * Lives here rather than in `./styles.ts`: that registry holds the declarations an
+ * ELEMENT makes, and `htmlShell` spends them inline. This is a `<head>` rule aimed
+ * at one engine, and `./shells.ts` composes it behind an `<!--[if mso]>` gate the
+ * same way it composes the colour blocks. It rides on `.cs-cta`, a ROLE class, so
+ * it survives `inlineStyles` untouched — and its `!important` still beats the
+ * inline padding, exactly as before.
+ *
+ * It lives in the `<head>`, not in an `EmailLine`, which is why no surface ever had
+ * to strip it.
+ */
+export const MSO_CTA_STYLE = `.cs-cta td { padding: ${CTA_PAD} !important; }
+.cs-cta a { padding: 0 !important; }`;
 /** `>> LABEL <<` ASCII box (`*` corners): 3 lines, sized to the label. */
 function asciiCtaBox(label: string): string {
   const pad = " ".repeat(CTA_BOX_PAD);
@@ -35,24 +62,45 @@ function asciiCtaBox(label: string): string {
  */
 export function ctaButton(
   cta: CallToAction,
-  margin: string,
+  margin: Spacing,
 ): { html: string; text: string } {
   const { label, href } = cta;
-  const tableStyle = `display: inline-block; border: 1px solid #666; border-radius: 2px; margin: ${margin}; max-width: 220px;`;
-  const tdStyle = `padding: 16px 24px; text-align: center; ${MONO} font-size: ${FONT_SIZE};`;
+  // The hover hook goes on ONLY when there is somewhere to go. An OTP code is a
+  // box with no link in it, and lighting it up under the pointer would promise a
+  // click that does not exist. `:hover` is opportunistic — see `./colors.ts`'s
+  // `BASE_STYLE` — so it adds a state in Apple Mail and changes nothing in Gmail.
+  // Reaching Gmail with it was the AMP surface's whole purpose, and cost Gmail iOS
+  // its dark mode to do it (ADR-CONTRACTS-091).
+  const boxClass = href
+    ? styleClass(`cta-box-${margin}`, "cta", "ctaHover")
+    : styleClass(`cta-box-${margin}`, "cta");
+  // A linked button carries its padding on the anchor (below), so the WHOLE box is
+  // the click target; the cell then holds none. An unlinked code is not clickable,
+  // so its padding stays on the cell and the label is a bare `<span>` — today's
+  // box exactly. Outlook ignores the anchor's `display: block` and is corrected by
+  // `MSO_CTA_STYLE`, which puts this same padding back on the cell there.
+  const cellClass = href
+    ? styleClass("cta-cell-linked")
+    : styleClass("cta-cell-code");
   // Underline only the label text (not the chevrons/spaces), and only when linked.
   const labelHtml = href
-    ? `<span style="text-decoration: underline;">${escapeHtml(label)}</span>`
+    ? `<span ${styleClass("cta-label")}>${escapeHtml(label)}</span>`
     : escapeHtml(label);
   const chevrons = `&gt;&gt; ${labelHtml} &lt;&lt;`;
+  // Both wear the `link` colour — a call to action looks like one whether or not
+  // it goes anywhere, and the box's edge is already that colour. What separates
+  // them is the UNDERLINE above and the `<a>` itself: an unlinked label is a
+  // `<span>`, so an OTP code is still not clickable and still prints no URL. The
+  // linked anchor fills the box (`display: block` + the padding) so a click
+  // anywhere in it counts.
   const inner = href
-    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
-    : chevrons;
+    ? `<a href="${escapeHtml(href)}" ${styleClass("cta-anchor", "link")}>${chevrons}</a>`
+    : `<span ${styleClass("cta-code", "link")}>${chevrons}</span>`;
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
-  <tr><td style="${tdStyle}">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" ${boxClass}>
+  <tr><td ${cellClass}>
     ${inner}
   </td></tr>
 </table>`;

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

@@ -27,13 +27,25 @@ import type { Spacing } from "./constants";
 import { renderElement } from "./render";
 import { 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.
+ *
+ * Two bodies, because an email IS a `multipart/alternative`: one message, whose
+ * parts a client chooses between. Assembling the parts is delivery's job, and
+ * delivery is not contracts'.
+ *
+ * There was a third — `amp`, an AMP4EMAIL body — and it is gone
+ * (ADR-CONTRACTS-091). It bought `:hover` on the CTA for Gmail readers and cost
+ * them their dark mode: Gmail iOS inverts the html part and does NOT touch the AMP
+ * part, so an AMP part opts those readers OUT of the only dark scheme they receive.
+ * That is measured, not argued — `company-semantics-backend/docs/dark-mode-probe.md`.
+ */
 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;
 }

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

@@ -45,23 +45,17 @@ import type {
 } from "../../content";
 import type { RenderContext } from "../../context";
-import {
-  COMPANY_URL,
-  DESTRUCTIVE,
-  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,
   };
@@ -92,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 };
 }
@@ -100,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",
   };
@@ -161,7 +155,7 @@ export function renderElement(
       const text = "🆆🅰🆁🅽🅸🅽🅶";
       return [
         paragraph(
-          `<span style="color: ${DESTRUCTIVE};">${escapeHtml(text)}</span>`,
+          `<span ${styleClass("warning", "destructive")}>${escapeHtml(text)}</span>`,
           text,
           trailing,
         ),
@@ -215,20 +209,27 @@ 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
+      // and every client uses them to reserve space before it loads.
+      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 CHANGED Viewed

@@ -6,6 +6,9 @@
  * composes ONE list of `EmailLine`s and both surfaces derive from it, so the two
  * can never disagree about what the email says.
  *
+ * There was a third shell — `ampShell` — retired in ADR-CONTRACTS-091. See
+ * `./index.ts`: the AMP part cost Gmail readers their dark mode.
+ *
  * INVARIANTS:
  * - Pure functions of their input lines. No clock, no environment, no I/O.
  * - These strings are the email's actual markup, and
@@ -13,7 +16,10 @@
  *   character-for-character.
  */
-import { MONO, type Spacing } from "./constants";
+import { BASE_STYLE, DARK_STYLE } from "./colors";
+import type { Spacing } from "./constants";
+import { MSO_CTA_STYLE } from "./cta";
+import { inlineOf, inlineStyles } from "./styles";
 /**
  * One rendered line — both presentations of one thing the notification says,
@@ -30,17 +36,51 @@ 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. No Gmail client
+ * honours `prefers-color-scheme` on any surface; what Gmail iOS does instead is
+ * invert this part post-delivery, which nothing here can stop — and which is why
+ * the body still states an explicit background rather than trusting a default.
+ * That inversion is not a fallback we tolerate, it is the ONLY dark mode a Gmail
+ * iOS reader gets, and preserving it is why the AMP surface was retired
+ * (ADR-CONTRACTS-091): Gmail leaves an AMP part alone, so having one would have
+ * turned this inversion off. Measured in
+ * `company-semantics-backend/docs/dark-mode-probe.md` — Gmail web, by contrast,
+ * recolours nothing at all.
+ *
+ * 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>

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

@@ -0,0 +1,319 @@
+/**
+ * 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. 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.
+ *
+ * The registry once had a second consumer — the AMP surface kept these classes and
+ * stated their rules, and that opposition (html inlines, AMP does not) is why it
+ * exists. AMP is gone (ADR-CONTRACTS-091) and the registry stays: it is now the
+ * single source for a recipe, spent in one place, and the markup it produces is
+ * byte-identical either way.
+ */
+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("; ")};`;
+}
+/**
+ * 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(" ");
+  });
+}