@company-semantics/contracts 35.1.0 → 37.0.0

package/src/notifications/content.ts

@@ -138,11 +138,24 @@ export interface Signature {
   signer?: string;
 }
 
-/** A leading image. `alt` is required — a text-only channel has nothing else. */
+/**
+ * A leading image. `alt` is required — a text-only channel has nothing else.
+ *
+ * `width`/`height` are the image's intrinsic pixel dimensions. They are optional
+ * because a channel that can measure an image itself does not need to be told, and
+ * requiring them would put a rendering constraint into channel-agnostic content.
+ * But a channel MAY be unable to draw one without them, and the constraint is real
+ * even though the surface that first raised it is gone: AMP's `<amp-img>` required
+ * explicit dimensions to reserve layout, and the email channel's AMP surface fell
+ * back to the `alt` text without them (retired in ADR-CONTRACTS-091). Supplying
+ * them is what makes the image drawable everywhere.
+ */
 export interface HeroImage {
   type: "heroImage";
   src: string;
   alt: string;
+  width?: number;
+  height?: number;
 }
 
 // =============================================================================

package/src/notifications/index.ts

@@ -58,17 +58,23 @@ export type { RenderedEmail } from "./renderers/email";
 
 export { emailRenderer } from "./renderers/email";
 
+// The `Slack*` block types this barrel used to export were a hand-written subset
+// of Block Kit and are GONE (ADR-CONTRACTS-090). Slack's own `@slack/types` is
+// the vocabulary now, re-exported here so a consumer need not depend on it
+// directly: `SlackBlock` -> `KnownBlock`, `SlackSectionBlock` -> `SectionBlock`,
+// `SlackMrkdwnText` -> `MrkdwnElement`, `SlackPlainText` -> `PlainTextElement`.
 export type {
-  SlackActionsBlock,
-  SlackBlock,
-  SlackButtonElement,
-  SlackContextBlock,
-  SlackDividerBlock,
-  SlackImageBlock,
+  ActionsBlock,
+  ContextBlock,
+  DividerBlock,
+  HeaderBlock,
+  ImageBlock,
+  KnownBlock,
+  MrkdwnElement,
+  PlainTextElement,
+  RichTextBlock,
+  SectionBlock,
   SlackMessage,
-  SlackMrkdwnText,
-  SlackPlainText,
-  SlackSectionBlock,
 } from "./renderers/slack";
 
 export { slackRenderer } from "./renderers/slack";

package/src/notifications/renderers/email/README.md

@@ -10,21 +10,81 @@ deleted, what replaced it. That layer offered templates a component per intent
 here the CONTENT names the intent and this directory is the only thing that knows
 the markup. The strings are the same strings.
 
-| module           | what it holds                                                           |
-| ---------------- | ----------------------------------------------------------------------- |
-| `index.ts`       | `emailRenderer` + `RenderedEmail`, the channel's natural type           |
-| `render.ts`      | each `NotificationElement` → its `<p>`/table markup, and spacing        |
-| `chat.ts`        | `chatUnit` → HTML bubbles and plain-text box art                        |
-| `cta.ts`         | the `>> LABEL <<` button, shared by a standalone CTA and a chat one     |
-| `shells.ts`      | `htmlShell` / `textShell` — what makes one email dual-output            |
-| `constants.ts`   | the styling vocabulary (`MONO`, `FONT_SIZE`, `SPACING`) + `COMPANY_URL` |
-| `escape-html.ts` | `escapeHtml`                                                            |
+| module           | what it holds                                                                          |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `index.ts`       | `emailRenderer` + `RenderedEmail`, the channel's natural type                          |
+| `render.ts`      | each `NotificationElement` → its class-only `<p>`/table markup, and spacing            |
+| `chat.ts`        | `chatUnit` → HTML bubbles and plain-text box art                                       |
+| `cta.ts`         | the `>> LABEL <<` button, shared by a standalone CTA and a chat one                    |
+| `shells.ts`      | `htmlShell` / `textShell` — what makes one email two surfaces                          |
+| `styles.ts`      | every declaration, as recipes — plus `inlineStyles`                                    |
+| `colors.ts`      | every colour, by role, in every scheme — and the dark stylesheet                       |
+| `constants.ts`   | typography and layout (`MONO_DECL`, `FONT_SIZE`, `SPACING`, `CTA_PAD`) + `COMPANY_URL` |
+| `escape-html.ts` | `escapeHtml`                                                                           |
 
 `constants.ts` and `escape-html.ts` moved here from the old `src/email/render`
 before it was deleted. The brand NAME is deliberately not among them: it is
 `../../context`'s `COMPANY_NAME`, because it is the same answer on every channel
 and renderers read it from `context.brand`.
 
+## Two surfaces, one markup (ADR-CONTRACTS-089, -091)
+
+An email is a `multipart/alternative`: `text/plain` and `text/html` are two
+presentations of ONE message, and `RenderedEmail` carries both.
+
+`render.ts`, `cta.ts` and `chat.ts` emit CLASS-ONLY markup, and `htmlShell` runs
+`inlineStyles`, which turns recipe classes back into the exact inline styles this
+channel has always shipped.
+
+`EmailLine` gains no third field: `../../renderer.ts` warns against exactly that,
+and a surface is a way of SPENDING the lines rather than a thing a line carries.
+The cost is that `EmailLine.html` is an intermediate representation — `render.ts`
+does not read as the bytes it emits, and the snapshot is where the real markup is
+legible.
+
+### There was a third surface, and removing it is the point
+
+`text/x-amp-html` shipped in 36.0.0 and was retired in 37.0.0. The class-only split
+above exists BECAUSE of it — AMP forbids inline `style`, the html surface is built
+from it — and the split stays: the registry is now the single source for a recipe,
+and the markup is byte-identical either way (removing AMP changed the snapshot by
+1965 deletions and **zero** insertions).
+
+AMP bought `:hover` in Gmail. It cost Gmail iOS its dark mode, and we did not know
+that when we shipped it: **Gmail iOS inverts the html part and does NOT touch an AMP
+part**, so having one opts those readers out of the only dark scheme they get. That
+is measured, not argued — `company-semantics-backend/docs/dark-mode-probe.md`, and
+it is a fact the public record does not contain. A hover state is worth less than a
+legible email (ADR-CONTRACTS-091).
+
+Two things we learned the expensive way, so nobody re-derives them:
+
+- `prefers-color-scheme` in `<style amp-custom>` is a hard AMP4EMAIL validator
+  ERROR. Real, permanent, frozen since 2023.
+- The `media` ATTRIBUTE on an AMP element takes the same feature and PASSES the
+  validator — and Gmail's runtime ignores it entirely, rendering both a dark-gated
+  and a light-gated block. Validator-legal, runtime-inert. That door is closed.
+
+## Colour — the thing this channel has and the others do not
+
+`colors.ts` is the only place a colour lives, and it is the channel's own rather
+than the layer's. Email hand-authors colour because it is the only channel with
+no client-side semantic vocabulary to lean on: `../slack` says `:warning:` and
+`context` and lets Slack's client theme them (Block Kit exposes no author-set
+colour at all), and `../sms` has none to have. A shared `notifications/colors.ts`
+would look DRY and would put a channel's presentation back inside the
+channel-agnostic layer — the coupling `../../renderer.ts` exists to prevent. A
+channel that needs colour gets its own file next to its own renderer.
+
+Colour is named by ROLE, and a scheme owes an answer to every role. Roles are
+meaning, not coincidence: `border`, `bubble`, `meta` and `dots` all answer `#666`
+in light and are still four roles, because a CTA's border and a chat bubble's
+fill have no reason to move together.
+
+The channel renders in **one or more schemes** — two today (`light`, `dark`), and
+callers ask `palette(scheme)` rather than importing a concrete palette, so a
+third is an entry in a table rather than an edit to every call site.
+
 ## Spacing — the thing the content model does not carry
 
 The old layer passed a `Spacing` per block; `../../kinds` deliberately dropped
@@ -71,8 +131,57 @@ expect to style it properly rather than trust the placeholder.
 - Values arrive pre-formatted: dates, title-casing and truncation are `compose`'s
   work. Nothing here re-formats a value.
 - Every user-controlled field in the HTML surface passes through `escapeHtml`
-  before interpolation.
-- `MONO` / `FONT_SIZE` / `SPACING` are this channel's own and are NOT exported
+  before interpolation — INCLUDING `href` and `src`, which reach the markup as
+  URLs rather than as text and were interpolated raw until ADR-CONTRACTS-089. A
+  URL that can close its attribute can forge another; under `inlineStyles` it
+  could also forge a `csr-` class and write any declaration in the registry into
+  someone else's element. That is also what makes the regex in `inlineStyles` safe:
+  nothing that reaches it can contain an unescaped `"`.
+- The markup is CLASS-ONLY. `cs-` role classes SHIP (the dark stylesheet needs the
+  hook); `csr-` recipe classes DO NOT — `inlineStyles` spends and drops them. That
+  prefix split is a mechanism, not a convention: it is what lets one markup serve
+  two surfaces, and it is why `__tests__/colors.test.ts` needs no filter — it scans
+  rendered output, where recipe classes no longer exist.
+- `MONO_DECL` / `FONT_SIZE` / `SPACING` / `CTA_PAD` are this channel's own and are
+  NOT exported
   from the domain barrel: a margin is not vocabulary. They were duplicated from
   the old `email/render/blocks`'s private copies while both layers existed; that
   duplication ended with the directory, and these are now the only copies.
+  `colors.ts` is unexported for the same reason — a colour is not vocabulary
+  either.
+- NO module here states a colour. Every colour comes from `colors.ts` via a role;
+  `__tests__/colors.test.ts` fails on a raw hex anywhere else in the directory,
+  including one in a comment, because a comment naming a literal goes stale the
+  first time the palette is tuned.
+- Light is inline and dark is the `<style>` block, and that is the mechanism rather
+  than duplication: one source each for two schemes, both from `colors.ts`. Every
+  dark declaration carries `!important` because the inline light colour would
+  otherwise win on specificity and dark would silently do nothing.
+- `:hover` is the one exception, because it has no inline form: BOTH schemes state
+  it in the stylesheet (`BASE_STYLE` light, `DARK_STYLE` dark, resolved by source
+  order). It is opportunistic — Apple Mail honours it, Gmail and classic Outlook do
+  not — and needs no fallback, because without it the button simply rests.
+- **`DARK_STYLE` reaches Apple Mail, iOS Mail and Outlook for Mac, and nobody else.**
+  No Gmail client honours `prefers-color-scheme` on any surface; Yahoo rewrites the
+  query. A Gmail reader's dark mode is whatever their client does to our light
+  colours unaided: Gmail iOS inverts the html part, Gmail web does nothing at all.
+  Closing the Gmail-web gap means inversion-indifferent authoring HERE — mid-tones,
+  no pure `#ffffff`/`#000000` in large fields, solid-fill CTAs — not another surface.
+- Role hooks (`cs-faint`, `cs-bubble`, `cs-cta`, `cs-link`) carry their colours via
+  each recipe's `roleDecl`; their only stylesheet rules live in `DARK_STYLE`.
+- A hover hook goes on a CTA ONLY when it has an `href`. An unlinked label is a
+  payload (an OTP code), and a hover state on it would promise a click that does
+  not exist — the same invariant that keeps it a `<span>` rather than an `<a>`.
+- A linked CTA's whole box is the click target: the padding sits on the `<a>`
+  (`display: block`), not the cell. Outlook ignores `display`, so an
+  `<!--[if mso]>` block restores the cell padding there and the box degrades to
+  today's text click. The padding is one constant shared by the anchor, the cell,
+  and the MSO block — they must agree.
+- The `color-scheme` metas and `DARK_STYLE` ship together. The declaration is a
+  promise: made alone it stops Apple Mail protecting our colours while leaving
+  light text on a dark background — worse than declaring light-only. This channel
+  WAS light-only by construction until ADR-CONTRACTS-088; it is not any more.
+- Dark reaches Apple Mail, iOS Mail and Outlook for Mac. Gmail and Outlook
+  force-invert and are unreachable — the dark path is additive, and a client that
+  strips `<style>` keeps the inline light colours, which is the status quo rather
+  than a degradation.

package/src/notifications/renderers/email/__tests__/colors.test.ts

@@ -0,0 +1,227 @@
+/**
+ * The rules that keep `../colors.ts` the only place colour lives
+ * (ADR-CONTRACTS-088).
+ *
+ * The markup is not asserted here — `../../../__tests__/render-snapshot.test.ts`
+ * locks that. These are the claims a snapshot cannot make, because a snapshot
+ * records what the output IS and every one of these is about what it must never
+ * become:
+ *
+ * - A dark stylesheet is invisible to the snapshot's reviewer in the sense that
+ *   matters: you can read the `<style>` block in a diff and still not notice that
+ *   a role is missing from it, because the light bytes look perfect either way.
+ *   Dark mode fails silently. These tests are the alarm.
+ * - `DARK_STYLE` is a hand-written template, deliberately (it reads as the CSS it
+ *   is). The cost of a template over generated output is that it can forget a
+ *   role; this is where that cost is paid back.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElement,
+} from "../../../content";
+import type { RenderContext } from "../../../context";
+import {
+  BASE_STYLE,
+  CLASS_ROLES,
+  DARK_STYLE,
+  HOVER_ROLES,
+  palette,
+  ROLES,
+  roleClass,
+} from "../colors";
+import { emailRenderer } from "../index";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** The class name inside a role's attribute — `cs-meta` from `class="cs-meta"`. */
+function classNameOf(role: (typeof ROLES)[number]): string {
+  const match = roleClass(role).match(/class="([^"]+)"/);
+  if (!match) throw new Error(`roleClass(${role}) is not a class attribute`);
+  return match[1];
+}
+
+/**
+ * One notification exercising every colour-bearing element. The chat unit carries
+ * both continuation shapes on purpose: dots followed by a CTA fold into it, and
+ * dots followed by nothing render standalone — two different emitters, two
+ * chances to forget a class.
+ */
+const EVERY_COLOURED_ELEMENT: NotificationContent = {
+  metadata: { kind: "chat.shared", title: "Colour coverage" },
+  sections: [
+    {
+      elements: [
+        { type: "warning" },
+        { type: "divider" },
+        { type: "callToAction", label: "Open", href: "https://example.com/a" },
+        {
+          type: "chatUnit",
+          items: [
+            { type: "message", role: "user", text: "Hello", from: "Sam Chen" },
+            { type: "continuation" },
+            {
+              type: "callToAction",
+              label: "Reply",
+              href: "https://example.com/b",
+            },
+            { type: "message", role: "assistant", text: "Hi back" },
+            { type: "continuation" },
+          ],
+        },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+describe("email colours", () => {
+  it("gives every role a dark answer that reaches the stylesheet", () => {
+    const dark = palette("dark");
+    for (const role of ROLES) {
+      expect(DARK_STYLE, `role "${role}" is absent from DARK_STYLE`).toContain(
+        dark[role],
+      );
+    }
+  });
+
+  it("writes a rule for every class-bearing role", () => {
+    for (const role of CLASS_ROLES) {
+      // `:hover` roles are selected as `.cs-x:hover {`, resting ones as `.cs-x {`.
+      const selector = new RegExp(`\\.${classNameOf(role)}(:[a-z-]+)? \\{`);
+      expect(DARK_STYLE, `role "${role}" has a class but no dark rule`).toMatch(
+        selector,
+      );
+    }
+  });
+
+  it("states every hover role in BOTH schemes, since :hover cannot be inline", () => {
+    // Every other role is inline-light + dark override. A hover role has no inline
+    // form, so a light answer that never reaches BASE_STYLE is simply lost — and
+    // nothing else in this file would notice.
+    for (const role of HOVER_ROLES) {
+      const selector = new RegExp(`\\.${classNameOf(role)}:hover \\{`);
+      expect(BASE_STYLE, `hover role "${role}" has no light rule`).toMatch(
+        selector,
+      );
+      expect(BASE_STYLE, `hover role "${role}" light value`).toContain(
+        palette("light")[role],
+      );
+      expect(DARK_STYLE, `hover role "${role}" has no dark rule`).toMatch(
+        selector,
+      );
+    }
+  });
+
+  it("marks every declaration !important, in both blocks", () => {
+    // Load-bearing, not defensive: the light colour is inline, inline beats a
+    // stylesheet on specificity, and a rule that loses that fight does nothing
+    // at all while looking entirely correct.
+    const rules = `${BASE_STYLE}\n${DARK_STYLE}`.split("\n").filter((line) => {
+      const start = line.trimStart();
+      return start.startsWith(".") || start.startsWith("body");
+    });
+    // Guards the filter above: a reformat that matches no lines would turn the
+    // loop below into a vacuous pass. `body` is the +1; BASE_STYLE contributes
+    // one line per hover role.
+    expect(rules).toHaveLength(CLASS_ROLES.length + 1 + HOVER_ROLES.length);
+
+    for (const rule of rules) {
+      const body = rule.slice(rule.indexOf("{") + 1, rule.lastIndexOf("}"));
+      const declarations = body
+        .split(";")
+        .map((d) => d.trim())
+        .filter(Boolean);
+      expect(declarations.length).toBeGreaterThan(0);
+      for (const declaration of declarations) {
+        expect(
+          declaration,
+          `"${declaration}" would lose to the inline style`,
+        ).toContain("!important");
+      }
+    }
+  });
+
+  it("styles every class the renderer actually emits", () => {
+    // The end-to-end direction: the tests above start from the palette, this one
+    // starts from the output, so a class hook added to a tag without a matching
+    // rule is caught from the side the palette cannot see.
+    const { html } = emailRenderer.render(EVERY_COLOURED_ELEMENT, CONTEXT);
+    // One attribute can carry several classes (`class="cs-cta cs-cta-hover"`).
+    const emitted = new Set(
+      [...html.matchAll(/class="([^"]+)"/g)].flatMap((match) =>
+        match[1].split(/\s+/),
+      ),
+    );
+    expect(emitted.size).toBeGreaterThan(0);
+    const stylesheet = `${BASE_STYLE}\n${DARK_STYLE}`;
+    for (const className of emitted) {
+      expect(stylesheet, `${className} is emitted but never styled`).toMatch(
+        new RegExp(`\\.${className}(:[a-z-]+)? \\{`),
+      );
+    }
+  });
+
+  it("puts the hover hook on a CTA that links, and never on one that does not", () => {
+    // The invariant `./cta.ts` already carried — an unlinked label is a payload,
+    // not a button — extended to hover. Lighting up an OTP code under the pointer
+    // promises a click that does not exist.
+    const hoverClass = classNameOf("ctaHover");
+    // The classes the markup APPLIES, not every mention in the document — the
+    // stylesheet names `.cs-cta-hover` too, and matching that would pass whether
+    // or not any element wears it.
+    const applied = (cta: NotificationElement) => {
+      const { html } = emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [cta] }],
+        },
+        CONTEXT,
+      );
+      return [...html.matchAll(/class="([^"]+)"/g)].flatMap((match) =>
+        match[1].split(/\s+/),
+      );
+    };
+
+    const linked = applied({
+      type: "callToAction",
+      label: "Open",
+      href: "https://example.com/a",
+    });
+    const payload = applied({ type: "callToAction", label: "123456" });
+
+    expect(linked).toContain(hoverClass);
+    expect(payload).not.toContain(hoverClass);
+    // Both still wear the resting edge.
+    expect(payload).toContain(classNameOf("cta"));
+  });
+
+  it("leaves no raw colour anywhere else in the channel", () => {
+    // What stops `style="color:#888"` reappearing in chat.ts in six months. A
+    // test rather than a CI guard: guards live in company-semantics-ci and adding
+    // one is cross-repo plus its own ADR — revisit if this earns it.
+    const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const hex = /#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/;
+
+    const sources = readdirSync(dir).filter(
+      (file) => file.endsWith(".ts") && file !== "colors.ts",
+    );
+    expect(sources.length).toBeGreaterThan(0);
+
+    for (const file of sources) {
+      const found = readFileSync(join(dir, file), "utf8").match(hex);
+      expect(
+        found?.[0],
+        `${file} states ${found?.[0]} directly — give it a role in colors.ts`,
+      ).toBeUndefined();
+    }
+  });
+});

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

@@ -20,6 +20,7 @@ import { describe, expect, it } from "vitest";
 
 import type {
   NotificationContent,
+  NotificationElement,
   NotificationElementType,
 } from "../../../content";
 import type { RenderContext } from "../../../context";
@@ -143,6 +144,91 @@ describe("emailRenderer", () => {
     expect(html).not.toContain("<script>");
   });
 
+  it("escapes a URL, so it cannot close its attribute and forge another", () => {
+    // `href` and `src` are the two values that reach the markup as a URL rather
+    // than as text, and they used to be interpolated raw — an HTML injection on
+    // its own, and since ADR-CONTRACTS-089 a style injection too: `inlineStyles`
+    // rewrites class attributes, so a URL that can write `class="csr-body"` can
+    // write any declaration in the registry into someone else's element.
+    const html = (element: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [element] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const cta = html({
+      type: "callToAction",
+      label: "Open",
+      href: 'https://x.test/" data-forged="1',
+    });
+    // The quote survives as text, so the forged attribute never becomes one.
+    // Asserted against `data-forged="` — the ATTRIBUTE form — because the escaped
+    // payload still contains the string `data-forged=`, and a looser match would
+    // pass whether or not the fix is present.
+    expect(cta).toContain("&quot;");
+    expect(cta).not.toMatch(/data-forged="/);
+
+    const hero = html({
+      type: "heroImage",
+      src: '/x.png" onerror="alert(1)',
+      alt: "x",
+    });
+    expect(hero).not.toMatch(/onerror="/);
+  });
+
+  it("makes a linked CTA's whole box the click target, an unlinked one not clickable", () => {
+    // The click target is the anchor, so it must fill the box — `display: block` +
+    // the padding on the `<a>` itself, not the cell. An OTP code has no href: it
+    // must not become an anchor at all, which is what keeps it uncopiable-as-a-link
+    // and unclickable.
+    const box = (cta: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [cta] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const linked = box({
+      type: "callToAction",
+      label: "Open",
+      href: "https://example.com/x",
+    });
+    expect(linked).toMatch(
+      /<a [^>]*href="https:\/\/example\.com\/x"[^>]*style="display: block; padding:/,
+    );
+
+    const payload = box({ type: "callToAction", label: "123456" });
+    expect(payload).not.toContain("<a ");
+    // The cell carries the padding instead, so the code is still a padded box.
+    expect(payload).toMatch(/<td style="padding: /);
+  });
+
+  it("restores the CTA's cell padding for Outlook, which cannot fill the anchor", () => {
+    // Outlook's Word engine ignores `display: block`, so the full-box target
+    // degrades to today's text click there. The MSO block must put the padding
+    // back on the cell, or Outlook renders the button cramped.
+    const { html } = emailRenderer.render(
+      {
+        metadata: { kind: "org.invite", title: "t" },
+        sections: [
+          {
+            elements: [
+              { type: "callToAction", label: "Join", href: "https://x.test" },
+            ],
+          },
+        ],
+      },
+      FIXTURE_CONTEXT,
+    );
+    expect(html).toContain("<!--[if mso]>");
+    expect(html).toMatch(/\[if mso\]>.*\.cs-cta td \{ padding: .* \}/s);
+  });
+
   it("is pure — same inputs, same bytes", () => {
     const content = NOTIFICATION_DEFINITIONS["security.alert"].compose(
       {

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

@@ -0,0 +1,111 @@
+/**
+ * The style registry's contract (ADR-CONTRACTS-089).
+ *
+ * `../../__tests__/render-snapshot.test.ts` already proves the html surface's
+ * bytes, and it is the authority on what the email LOOKS like. What it cannot say
+ * is WHY those bytes are safe to derive, because a snapshot passes just as happily
+ * over markup that leaks a recipe class or drops a role hook. This file asserts the
+ * two properties the derivation rests on:
+ *
+ * - a `cs-` role hook SHIPS, because `darkStyle` needs it in the markup;
+ * - a `csr-` recipe class DOES NOT, because it is spent and dropped.
+ *
+ * Get either backwards and the snapshot still passes while dark mode silently
+ * stops working, or the shipped email carries dead classes nothing styles.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent } from "../../../content";
+import type { RenderContext } from "../../../context";
+import { emailRenderer } from "../index";
+import { inlineOf, inlineStyles, STYLE_NAMES } from "../styles";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** One of everything that carries a class, so the scan below has something to see. */
+const CONTENT: NotificationContent = {
+  metadata: { kind: "auth.otp", title: "t" },
+  sections: [
+    {
+      elements: [
+        { type: "greeting", recipientName: "Sam" },
+        { type: "warning" },
+        { type: "divider" },
+        { type: "callToAction", label: "Open", href: "https://x.test/a" },
+        { type: "callToAction", label: "123456" },
+        {
+          type: "chatUnit",
+          items: [
+            { type: "message", role: "user", text: "hi", from: "Sam" },
+            { type: "message", role: "assistant", text: "hello" },
+            { type: "continuation" },
+            { type: "callToAction", label: "Read", href: "https://x.test/b" },
+          ],
+        },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+/** Every class the shipped markup actually applies. */
+function shippedClasses(html: string): string[] {
+  return [...html.matchAll(/class="([^"]+)"/g)].flatMap((m) =>
+    m[1].split(/\s+/),
+  );
+}
+
+describe("the style registry", () => {
+  it("ships no recipe class — they are spent by the inliner, not delivered", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    // The whole document, not just the class attributes: a recipe class must not
+    // survive anywhere, including in a stylesheet the html surface never wants.
+    expect(html).not.toContain("csr-");
+  });
+
+  it("ships every role hook, because the dark stylesheet needs it there", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    const shipped = shippedClasses(html);
+    expect(shipped.length).toBeGreaterThan(0);
+    // A sample across the roles this content exercises. `cs-cta-hover` is the
+    // interesting one: it is the only reason `.cs-cta` and the hover state are
+    // separate roles, and it rides on the linked CTA above.
+    for (const hook of ["cs-link", "cs-cta", "cs-cta-hover", "cs-bubble"]) {
+      expect(shipped, `${hook} never reached the markup`).toContain(hook);
+    }
+  });
+
+  it("turns a recipe-only class attribute into a style, leaving no class behind", () => {
+    // The collapse that makes `<p class="csr-p-none">` render as the `<p style="…">`
+    // the channel shipped before this registry existed. A leftover `class=""` would
+    // be invisible in a client and a permanent diff in the snapshot.
+    expect(inlineStyles(`<p class="csr-p-none">x</p>`)).toBe(
+      `<p style="${inlineOf("p-none")}">x</p>`,
+    );
+  });
+
+  it("keeps role hooks and appends the style, in that order", () => {
+    // Order is not cosmetic: it is what makes the inliner reproduce the previous
+    // markup byte-for-byte rather than merely equivalently.
+    expect(inlineStyles(`<td class="cs-bubble csr-bubble-user">x</td>`)).toBe(
+      `<td class="cs-bubble" style="${inlineOf("bubble-user")}">x</td>`,
+    );
+  });
+
+  it("leaves markup with no classes untouched", () => {
+    const plain = `<tr><td></td></tr>`;
+    expect(inlineStyles(plain)).toBe(plain);
+  });
+
+  it("states every recipe as an inline style, from one source", () => {
+    // `ruleOf` — the same recipe as a CSS rule — went with the AMP surface
+    // (ADR-CONTRACTS-091). It had no other caller, and a rule nobody states is not
+    // a shape this registry needs to keep proving it can take.
+    for (const name of STYLE_NAMES) {
+      expect(inlineOf(name).endsWith(";")).toBe(true);
+    }
+  });
+});