@company-semantics/contracts 37.0.0 → 38.1.0

package/src/notifications/content.ts

@@ -144,11 +144,10 @@ export interface Signature {
  * `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.
+ * 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";

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

@@ -16,8 +16,8 @@ the markup. The strings are the same strings.
 | `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`                                    |
+| `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`                                                                           |
@@ -27,43 +27,58 @@ 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)
+## Three surfaces, one markup (ADR-CONTRACTS-089)
 
-An email is a `multipart/alternative`: `text/plain` and `text/html` are two
-presentations of ONE message, and `RenderedEmail` carries both.
+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.
 
-`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.
+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 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.
+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.
+
+### ⚠️ The AMP body is NEVER SENT
+
+Two of the three ship. `amp` is rendered, previewed in the Ladle gallery, and
+dropped — and **delivering it is a regression, not a feature**. The backend's
+`EmailDelivery.test.ts` fails if it reaches the transport; that test is the
+invariant, this section is its explanation.
+
+**Why not sent.** Gmail iOS inverts the `text/html` part post-delivery and does NOT
+touch a `text/x-amp-html` part. That inversion is the only dark mode a Gmail iOS
+reader gets — no Gmail client honours `prefers-color-scheme` on any surface — so an
+AMP part would switch it off and hand them a white email in a dark client. AMP buys
+`:hover` in Gmail and would cost dark mode in Gmail. Measured, not argued:
+`company-semantics-backend/docs/dark-mode-probe.md` (ADR-CONTRACTS-091, -092).
+
+**Why it exists.** AMP is the only email format with a real animation model —
+`amp-animation`, `amp-bind`, `amp-position-observer`, no arbitrary JS. Nothing else
+can make the kaomoji companions blink once, three seconds after open. Keeping the
+surface alive costs one inert field; rebuilding it later costs more. If Google ever
+allows `prefers-color-scheme` here, or Gmail starts inverting AMP too, the trade
+flips and this is ready.
+
+**Light-only, permanently.** `prefers-color-scheme` in `<style amp-custom>` is a hard
+validator error (explicit 14-feature allowlist, frozen since 2023, unchanged by
+`data-css-strict`). The `media` ATTRIBUTE takes the same feature, PASSES the
+validator — and Gmail's runtime ignores it. Both doors closed.
+
+`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
 
@@ -153,22 +168,32 @@ expect to style it properly rather than trust the placeholder.
   `__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.
+- 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). 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`.
+  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 that is why it is never SENT. AMP4EMAIL
+  disallows the `prefers-color-scheme` media feature (an explicit 14-feature
+  allowlist, unchanged by `data-css-strict`), so it cannot have one. ADR-CONTRACTS-089
+  called that free — "AMP's readers force-invert and never got our dark colours
+  anyway". Half right: they never got them, because no Gmail client honours the media
+  feature on any surface. But Gmail web recolours nothing, Yahoo does not invert, and
+  Gmail iOS inverts the html part while EXEMPTING an AMP part — so an AMP part does
+  not lose a scheme its readers never had, it switches off the inversion that IS
+  their dark mode. Measured; see the AMP section above.
+- 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>`.
@@ -181,7 +206,11 @@ expect to style it properly rather than trust the placeholder.
   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.
+- Dark reaches Apple Mail, iOS Mail and Outlook for Mac, and nobody else. Gmail
+  honours none of it on any surface, so a Gmail reader's dark mode is whatever their
+  client does to our light colours unaided: Gmail iOS inverts the html part, and
+  **Gmail web does nothing at all** — a light email in a dark client. That gap is
+  real and open, and the lever is inversion-indifferent authoring in `colors.ts`
+  (mid-tones, no pure `#ffffff`/`#000000` in large fields, solid-fill CTAs), not
+  another surface. The dark path is additive: 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,225 @@
+/**
+ * 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 (an explicit 14-feature allowlist in the validator's
+    // protoascii, `issues_as_error: true`, unchanged by `data-css-strict`, frozen
+    // since 2023), so this surface cannot have dark in any form.
+    //
+    // Nor can it via the back door: the `media` ATTRIBUTE on an AMP element takes
+    // the same feature and PASSES the validator — and Gmail's runtime ignores it,
+    // rendering a dark-gated and a light-gated block at once. Measured; see
+    // `company-semantics-backend/docs/dark-mode-probe.md`. Both doors are closed.
+    //
+    // The surface being light-only is exactly why it is never SENT: an AMP part
+    // switches off Gmail iOS's inversion, which is the only dark mode those readers
+    // get (ADR-CONTRACTS-091/-092). It is rendered for a future that needs AMP's
+    // animation model, not for delivery.
+    //
+    // 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__/styles.test.ts

@@ -19,7 +19,7 @@ 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";
+import { inlineOf, inlineStyles, ruleOf, STYLE_NAMES } from "../styles";
 
 const CONTEXT: RenderContext = {
   brand: { name: "Company Semantics", copyrightYear: 2026 },
@@ -100,11 +100,11 @@ describe("the style registry", () => {
     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.
+  it("states each recipe as a rule and as an inline style, from one source", () => {
+    // The two surfaces' only difference is the shape, never the content — which is
+    // the claim that lets `ampShell` and `htmlShell` share this registry.
     for (const name of STYLE_NAMES) {
+      expect(ruleOf(name)).toBe(`.csr-${name} { ${inlineOf(name)} }`);
       expect(inlineOf(name).endsWith(";")).toBe(true);
     }
   });

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

@@ -57,11 +57,10 @@ const CHAT_INDENT = "       ";
  * The gap under a chat row: 24px clears the bubbles, 16px hugs whatever the row
  * is introducing (a CTA, the dots).
  *
- * A recipe name rather than a margin string. The AMP surface first forced this —
- * a margin could not be inline there — and it earns its keep without that surface
- * (ADR-CONTRACTS-091): naming the two the layout actually has is what makes a third
- * one a deliberate addition to `./styles.ts` rather than a new string appearing at
- * a call site.
+ * A recipe name rather than a margin string, because a margin cannot be inline on
+ * the AMP surface (ADR-CONTRACTS-089) — and naming the two the layout actually has
+ * is what makes a third one a deliberate addition to `./styles.ts` rather than a
+ * new string appearing at a call site.
  */
 type ChatRow = "chat-row-16" | "chat-row-24";
 

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

@@ -275,22 +275,23 @@ const dark = PALETTES.dark;
  * is no fallback to write: without it the button rests, which is how it looks
  * today. Purely additive, like the dark path.
  *
- * Gmail never gets it, and that is now a settled trade rather than a gap. The AMP
- * surface existed to reach exactly this one role in Gmail — and cost Gmail iOS
- * readers their dark mode to do it, since Gmail leaves an AMP part un-inverted.
- * A hover state is worth less than a legible email (ADR-CONTRACTS-091).
- *
- * `!important` is load-bearing: the light colour is inline, inline beats a
- * stylesheet, and without it this rule silently loses. It used to be a parameter,
- * because the AMP surface had no inline style to beat and AMP forbids the keyword.
- * With that surface gone there is one caller, and a parameter with one caller is
- * not a seam.
+ * This is the ONE role whose reach the AMP surface would change — Gmail honours
+ * `:hover` there — and it is why that surface exists. It is NOT why the surface is
+ * unsent: shipping it would cost Gmail iOS its dark mode, which is worth more than
+ * a hover state (ADR-CONTRACTS-091/-092). The `important` parameter is what lets
+ * one rule serve both shells; see `./shells.ts`.
  *
  * `.cs-cta-hover` is present ONLY on a CTA that actually has an `href` — see
  * `./cta.ts`. An OTP code wears `.cs-cta` for its edge and never this, because a
  * hover state on something unclickable promises a click that will not happen.
  */
-export const BASE_STYLE = `.cs-cta-hover:hover { background-color: ${light.ctaHover} !important; }`;
+export function hoverStyle(important: boolean): string {
+  const bang = important ? " !important" : "";
+  return `.cs-cta-hover:hover { background-color: ${light.ctaHover}${bang}; }`;
+}
+
+/** The html surface's hover block. See `hoverStyle` for why it is `important`. */
+export const BASE_STYLE = hoverStyle(true);
 
 /**
  * The dark override.
@@ -304,15 +305,26 @@ export const BASE_STYLE = `.cs-cta-hover:hover { background-color: ${light.ctaHo
  * colour is inline, inline beats a stylesheet on specificity, and without
  * `!important` every rule here silently loses and dark quietly does nothing.
  *
- * **Read by Apple Mail, iOS Mail and Outlook for Mac, and by nobody else.** No
- * Gmail client honours `prefers-color-scheme` on any surface, and Yahoo rewrites
- * the query rather than honouring it — so this block has never reached them and a
- * Gmail reader's dark mode is whatever their client does to our light colours on
- * its own. On Gmail iOS that is a post-delivery inversion of the html part; on
- * Gmail web it is nothing at all, and a light email stays light in a dark client.
- * Closing THAT gap is inversion-indifferent authoring here — mid-tones, no pure
- * #ffffff/#000000 in large fields, solid-fill CTAs — not another surface. See
- * `company-semantics-backend/docs/dark-mode-probe.md` and ADR-CONTRACTS-091.
+ * **This block is the html surface's alone, and that is why the AMP surface is
+ * never sent.** AMP4EMAIL disallows the `prefers-color-scheme` media feature
+ * outright — a hard validator error, checked with and without `data-css-strict` —
+ * so the AMP surface cannot carry these rules in any form (ADR-CONTRACTS-089).
+ * Unlike `hoverStyle`, there was no version of this worth parameterizing.
+ *
+ * ADR-CONTRACTS-089 called that free, on the grounds that AMP's readers force-invert
+ * and never received these colours anyway. **The first half is true and the second is
+ * false.** Nobody in Gmail or Yahoo honours `prefers-color-scheme`, so this block
+ * genuinely never reached them — but Gmail web recolours nothing, Yahoo does not
+ * invert, and Gmail iOS inverts the html part while EXEMPTING an AMP part. So an AMP
+ * part does not lose a scheme its readers never got; it switches off the client-side
+ * inversion that IS their dark mode. Measured in
+ * `company-semantics-backend/docs/dark-mode-probe.md`; the surface stays unsent
+ * (ADR-CONTRACTS-091/-092).
+ *
+ * **Which leaves a real gap this block cannot close.** Gmail web recolours nothing
+ * and honours nothing, so a light email stays light in a dark client. The lever there
+ * is inversion-indifferent authoring in this file — mid-tones, no pure `#ffffff` /
+ * `#000000` in large fields, solid-fill CTAs — not another surface.
  *
  * `.cs-faint` states both `color` and `border-top-color` because one role lands
  * on two properties — the `/* EOM *\/` span takes the first and ignores the

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

@@ -41,8 +41,10 @@ const CTA_BOX_PAD = 3;
  * 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.
+ * The AMP surface never composes it: Outlook's Word engine is not an AMP client,
+ * `display: block` works natively in Gmail/Yahoo/Mail.ru, and AMP forbids both
+ * conditional comments and `!important`. Nothing has to strip it — it lives in the
+ * `<head>`, not in an `EmailLine`.
  */
 export const MSO_CTA_STYLE = `.cs-cta td { padding: ${CTA_PAD} !important; }
 .cs-cta a { padding: 0 !important; }`;
@@ -68,10 +70,10 @@ export function ctaButton(
 
   // 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).
+  // click that does not exist. On the html surface `:hover` is opportunistic — see
+  // `./colors.ts`'s `hoverStyle` — so it adds a state in Apple Mail and changes
+  // nothing in Gmail; on the AMP surface it simply works, which is what that
+  // surface is FOR (ADR-CONTRACTS-089).
   const boxClass = href
     ? styleClass(`cta-box-${margin}`, "cta", "ctaHover")
     : styleClass(`cta-box-${margin}`, "cta");

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

@@ -25,20 +25,19 @@ 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.
  *
- * 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'.
+ * 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).
  *
- * 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`.
+ * **Two of them ship.** Assembling the parts is delivery's job, and delivery is not
+ * contracts' — but the `amp` body is not merely un-plumbed, it is deliberately unsent
+ * and must stay that way (ADR-CONTRACTS-092). See the field.
  */
 export interface RenderedEmail {
   /** Subject line — the notification's `metadata.title`. */
@@ -47,6 +46,19 @@ export interface RenderedEmail {
   text: string;
   /** HTML body (`text/html`) — every kind is multi-output. */
   html: string;
+  /**
+   * AMP4EMAIL body (`text/x-amp-html`).
+   *
+   * ⚠️ **Rendered, and deliberately NEVER SENT** (ADR-CONTRACTS-092). Delivering it
+   * is a regression: Gmail iOS inverts the html part and does NOT touch an AMP
+   * part, so an AMP part switches off the only dark mode a Gmail iOS reader gets.
+   * `EmailDelivery.test.ts` in the backend fails if this reaches the transport.
+   *
+   * It is kept alive for AMP's animation model (`amp-animation`, `amp-bind`),
+   * which no other email format has, and which is the one thing that could make it
+   * worth sending. See `./shells.ts`'s `ampShell`.
+   */
+  amp: string;
 }
 
 /**
@@ -80,6 +92,7 @@ export const emailRenderer: Renderer<RenderedEmail> = {
       subject: content.metadata.title,
       text: textShell(lines),
       html: htmlShell(lines),
+      amp: ampShell(lines),
     };
   },
 };