@company-semantics/contracts 35.1.0 → 36.0.0

package/src/notifications/content.ts

@@ -138,11 +138,23 @@ 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: AMP's `<amp-img>` requires
+ * explicit dimensions to reserve layout before the image loads, so the email
+ * channel's AMP surface degrades to the `alt` text when they are absent
+ * (ADR-CONTRACTS-089). 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,76 @@ 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` / `ampShell` / `textShell` — what makes one email three surfaces           |
+| `styles.ts`      | every declaration, as recipes — plus `inlineStyles` and `ampify`                       |
+| `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`.
 
+## Three surfaces, one markup (ADR-CONTRACTS-089)
+
+An email is a `multipart/alternative`: `text/plain`, `text/html` and
+`text/x-amp-html` are three presentations of ONE message, and `RenderedEmail`
+carries all three. AMP is not a fourth channel — a recipient gets one email.
+
+The catch is that the two HTML-ish surfaces disagree about styling at the root.
+AMP4EMAIL forbids inline `style` attributes and `!important`; the html surface is
+built from both, deliberately (see Colour below). So **the markup belongs to
+neither**: `render.ts`, `cta.ts` and `chat.ts` emit CLASS-ONLY markup, and each
+shell spends `styles.ts` its own way —
+
+- `htmlShell` runs `inlineStyles`, which turns recipe classes back into the exact
+  inline styles this channel has always shipped;
+- `ampShell` runs `ampify` (the `<img>` → `<amp-img>` swap) and states the same
+  recipes as `<style amp-custom>`.
+
+`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 now an intermediate representation —
+`render.ts` no longer reads as the bytes it emits, and the snapshot is where the
+real markup is legible.
+
+**What AMP is for:** `:hover`. ADR-CONTRACTS-088 bought a hover state that Gmail
+does not honour, and Gmail is most opens. AMP is where that rule reaches people.
+
+**What AMP does not have:** dark. AMP4EMAIL disallows the `prefers-color-scheme`
+media feature outright. It costs nothing — see Colour.
+
+`pnpm validate:amp` runs the real AMP validator. `__tests__/amp.test.ts` asserts
+the constraints we KNOW on every run, which is not the same claim: it passed once
+while every fixture was invalid.
+
+## 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 +126,64 @@ 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.
+- On the HTML surface, 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. On
+  the AMP surface there is no inline style, so the recipes carry light and source
+  order alone would resolve a cascade — which is moot, because AMP has no dark.
+- `: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). On the HTML surface it is opportunistic — Apple Mail honours it, Gmail and
+  classic Outlook do not — and needs no fallback, because without it the button
+  simply rests. It is also the ONE rule the AMP surface shares, via
+  `hoverStyle(false)`; AMP forbids `!important`, which is why that template takes a
+  parameter and `DARK_STYLE` does not.
+- The AMP surface has NO dark scheme, and loses nothing by it. AMP4EMAIL disallows
+  the `prefers-color-scheme` media feature (checked against the AMP validator, with
+  and without `data-css-strict`), so it cannot. The audiences are disjoint: dark
+  reaches Apple Mail, iOS Mail and Outlook for Mac; AMP reaches Gmail, Yahoo and
+  Mail.ru — the force-inverting clients that never received our dark colours anyway.
+  AMP swaps a scheme its readers never got for a hover state they never got.
+- Role hooks ride the AMP surface unstyled (`cs-faint`, `cs-bubble`, `cs-cta`,
+  `cs-link`), because their only rules live in `DARK_STYLE`. Their colours arrive
+  via each recipe's `roleDecl`, so this is dead bytes rather than a bug — the price
+  of one markup. `.cs-cta-hover` is the exception: it is the feature.
+- 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__/amp.test.ts

@@ -0,0 +1,217 @@
+/**
+ * The AMP surface's constraints (ADR-CONTRACTS-089).
+ *
+ * **What this file can and cannot claim.** AMP validity is defined by the AMP
+ * validator, and the validator fetches itself over the network — so it cannot live
+ * in this package's pure suite and runs behind `pnpm validate:amp` instead. What is
+ * asserted here is narrower and honest: *the constraints we know*, checked over
+ * every fixture. A green run here means "we did not do any of the things we know
+ * AMP forbids", not "this is valid AMP".
+ *
+ * The constraints are structural rather than cosmetic. Each one is a thing the html
+ * surface does deliberately and this surface must not do at all — which is why the
+ * markup belongs to neither and both are derived from `../styles.ts`.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { hoverStyle } from "../colors";
+import { NOTIFICATION_FIXTURES, fixtureKey } from "../../../__tests__/fixtures";
+import type { RenderContext } from "../../../context";
+import { NOTIFICATION_DEFINITIONS } from "../../../registry";
+import { emailRenderer } from "../index";
+import { ampify } from "../styles";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** Gmail's `amp-custom` ceiling. */
+const AMP_CUSTOM_LIMIT = 75_000;
+
+/** Every fixture, rendered once. */
+const RENDERED = NOTIFICATION_FIXTURES.map((fixture) => {
+  const definition = NOTIFICATION_DEFINITIONS[fixture.kind];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const content = definition.compose(fixture.payload as any, CONTEXT);
+  return {
+    key: fixtureKey(fixture.kind, fixture.name),
+    ...emailRenderer.render(content, CONTEXT),
+  };
+});
+
+/** The `<style amp-custom>` block's contents. */
+function ampCustom(amp: string): string {
+  const open = "<style amp-custom>";
+  const start = amp.indexOf(open);
+  return amp.slice(start + open.length, amp.indexOf("</style></head>"));
+}
+
+/** Everything a reader would actually read, tags removed. */
+function visibleText(html: string): string {
+  return html
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/g, "")
+    .replace(/<script[\s\S]*?<\/script>/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+describe("the AMP surface", () => {
+  it("emits every fixture", () => {
+    // Guards every loop below: a fixture list that silently emptied would turn
+    // each of them into a vacuous pass.
+    expect(RENDERED.length).toBeGreaterThan(0);
+  });
+
+  describe.each(RENDERED)("$key", ({ amp }) => {
+    it("declares itself AMP, with the runtime and the boilerplate", () => {
+      expect(amp.startsWith("<!DOCTYPE html>\n<html amp4email")).toBe(true);
+      expect(amp).toContain(
+        '<script async src="https://cdn.ampproject.org/v0.js"></script>',
+      );
+      // The boilerplate hides the body until the runtime unhides it — which is
+      // why an AMP document that cannot run scripts renders blank rather than
+      // unstyled.
+      expect(amp).toContain(
+        "<style amp4email-boilerplate>body{visibility:hidden}</style>",
+      );
+    });
+
+    it("carries no inline style — the constraint the whole split exists for", () => {
+      expect(amp).not.toContain('style="');
+    });
+
+    it("carries no !important, which amp-custom forbids", () => {
+      expect(ampCustom(amp)).not.toContain("!important");
+    });
+
+    it("carries no conditional comment", () => {
+      // `MSO_CTA_STYLE` is `htmlShell`'s business. It lives in that shell's
+      // `<head>`, never in an `EmailLine`, so this holds by construction rather
+      // than by stripping.
+      expect(amp).not.toContain("<!--[if");
+    });
+
+    it("has exactly one amp-custom stylesheet, in the head", () => {
+      expect(amp.match(/<style amp-custom>/g)).toHaveLength(1);
+      expect(amp.indexOf("<style amp-custom>")).toBeLessThan(
+        amp.indexOf("</head>"),
+      );
+    });
+
+    it("fits Gmail's amp-custom budget", () => {
+      expect(ampCustom(amp).length).toBeLessThan(AMP_CUSTOM_LIMIT);
+    });
+
+    it("draws images as amp-img, never img", () => {
+      expect(amp).not.toMatch(/<img\s/);
+    });
+
+    it("styles every recipe class it applies", () => {
+      // The end-to-end direction: start from the output, so a recipe class that
+      // reaches the markup with no rule behind it is caught. On this surface a
+      // recipe is the ONLY thing carrying an element's appearance — `htmlShell`
+      // spends them inline and drops them; here they must all land as rules, or
+      // the element renders naked.
+      //
+      // Role hooks (`cs-`) are deliberately NOT required to have one. They ride
+      // along because the markup is shared with the html surface, where
+      // `DARK_STYLE` needs them — and dark is exactly what this surface cannot
+      // have. So `cs-faint`/`cs-bubble`/`cs-cta`/`cs-link` are inert here: their
+      // colours already arrived via their recipe's `roleDecl`. That is the price
+      // of one markup, and it is bytes rather than correctness. The one role rule
+      // this surface DOES carry is asserted separately below — it is the feature.
+      const body = amp.slice(amp.indexOf("<body"));
+      const applied = new Set(
+        [...body.matchAll(/class="([^"]+)"/g)].flatMap((m) =>
+          m[1].split(/\s+/),
+        ),
+      );
+      const recipes = [...applied].filter((c) => c.startsWith("csr-"));
+      expect(recipes.length).toBeGreaterThan(0);
+      const sheet = ampCustom(amp);
+      for (const className of recipes) {
+        expect(sheet, `${className} is applied but never styled`).toMatch(
+          new RegExp(`\\.${className} \\{`),
+        );
+      }
+    });
+  });
+
+  it("says exactly what the html surface says", () => {
+    // The claim `EmailLine` exists to make, now across three surfaces instead of
+    // two: the parts of a `multipart/alternative` are ALTERNATIVES, so a client
+    // choosing between them must not change what the notification said. This is
+    // what a second hand-authored AMP template could never promise.
+    for (const { key, html, amp } of RENDERED) {
+      expect(visibleText(amp), `${key} says something else in AMP`).toBe(
+        visibleText(html),
+      );
+    }
+  });
+
+  it("states the hover rule without !important, and the html surface with", () => {
+    // The one rule both surfaces carry, and the only thing they disagree on: the
+    // html surface must beat an inline style, this one has none to beat and
+    // forbids the keyword. One template, one parameter; see `../colors.ts`.
+    expect(hoverStyle(true)).toContain("!important");
+    expect(hoverStyle(false)).not.toContain("!important");
+    // The same rule, not merely two rules that both exist.
+    expect(hoverStyle(true).replaceAll(" !important", "")).toBe(
+      hoverStyle(false),
+    );
+  });
+
+  it("carries the hover rule — the reason this surface exists at all", () => {
+    // ADR-CONTRACTS-088 bought a `:hover` state that Gmail does not honour, and
+    // Gmail is most opens. This surface is where that rule finally reaches a
+    // recipient, so its presence is the feature, not an implementation detail.
+    const { amp } = RENDERED[0];
+    expect(ampCustom(amp)).toContain(".cs-cta-hover:hover");
+  });
+
+  it("carries no dark scheme, because AMP disallows the media feature", () => {
+    // NOT an omission to fix later: `prefers-color-scheme` is a disallowed media
+    // feature in amp-custom (verified against the AMP validator, with and without
+    // `data-css-strict`), so this surface cannot have dark in any form. It costs
+    // nothing — the dark block's clients (Apple Mail, iOS Mail, Outlook for Mac)
+    // and this surface's clients (Gmail, Yahoo, Mail.ru) are disjoint sets, and
+    // the latter force-invert rather than read a stylesheet.
+    //
+    // This test exists so that "add dark mode to AMP" fails here with the reason,
+    // rather than in `pnpm validate:amp` with a CSS syntax error.
+    for (const { key, amp } of RENDERED) {
+      expect(amp, `${key} would be invalid AMP`).not.toContain(
+        "prefers-color-scheme",
+      );
+    }
+  });
+
+  describe("ampify", () => {
+    it("gives a sized image explicit layout", () => {
+      expect(
+        ampify(
+          '<img src="a.png" alt="A" width="600" height="200" class="csr-hero-normal">',
+        ),
+      ).toBe(
+        '<amp-img src="a.png" alt="A" width="600" height="200" class="csr-hero-normal" layout="intrinsic"></amp-img>',
+      );
+    });
+
+    it("degrades an unsized image to its alt text, keeping its spacing", () => {
+      // `../../content.ts` makes dimensions optional, so this surface must have an
+      // answer for their absence. `alt` is required exactly so that a channel with
+      // nothing else has something to say.
+      expect(
+        ampify('<img src="a.png" alt="A logo" class="csr-hero-tight">'),
+      ).toBe('<p class="csr-p-tight">A logo</p>');
+    });
+
+    it("leaves markup with no image alone", () => {
+      const plain = '<p class="csr-p-none">x</p>';
+      expect(ampify(plain)).toBe(plain);
+    });
+  });
+});

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();
+    }
+  });
+});