@company-semantics/contracts 35.1.0 → 36.0.0

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

@@ -0,0 +1,342 @@
+/**
+ * The email channel's colour — every colour it emits, in every scheme it
+ * supports (ADR-CONTRACTS-088).
+ *
+ * This is the one place a colour changes. Everything else in this directory asks
+ * for a ROLE and gets whatever answer the scheme has; no module below emits a
+ * literal, and `__tests__/colors.test.ts` fails if one creeps back in.
+ *
+ * **Why this is email's and not the notification layer's.** Email is the only
+ * channel that hand-authors colour, because it is the only one with no
+ * client-side semantic vocabulary to lean on. `../slack` says `:warning:` and
+ * `context` and lets Slack's client theme it — Block Kit exposes no author-set
+ * colour at all, so Slack's dark mode costs us nothing. `../sms` has no colour to
+ * have. A shared `notifications/colors.ts` would look DRY and would put a
+ * channel's presentation back inside the channel-agnostic layer, which is the
+ * coupling `../../renderer.ts` exists to prevent. A channel that needs colour
+ * gets its own file, next to its own renderer.
+ *
+ * **Roles are meaning, not coincidence** — and this file has already been paid for
+ * saying so. `border`, `bubble`, `meta` and `dots` all answered `#666`, and a
+ * palette keyed by colour would have made them one entry. Then `border` alone
+ * moved to the link's blue, which under that shortcut would have dragged every
+ * chat bubble with it.
+ *
+ * The test is whether two things are two DECISIONS, not whether they currently
+ * agree — and it cuts both ways. `faint` and `rule` were split on that reasoning
+ * and it was wrong: the `/* EOM *\/` marker and the rules are one decision, "the
+ * marks that recede", wearing two names. They were merged. A role that can never
+ * be answered separately is not a role, it is a synonym, and synonyms cost the
+ * same as roles while buying nothing.
+ *
+ * **What tracks the app, and what does not.** `./constants.ts` explains that a
+ * copied token cannot follow the app, because contracts sits above it in the
+ * dependency flow — "that divergence is the cost of the arrow pointing one way".
+ * That cost is worth paying for the colours a recipient reads as OURS, and not
+ * for the rest:
+ *
+ * - `link`, `border` and `destructive` are copied, and named below with the token
+ *   they came from. A link is the brand's blue in a light email for the same
+ *   reason it is in the app, and a CTA's edge is that blue because the box IS the
+ *   link.
+ * - Every other role is this channel's own. Its look — monospace, rules, box art —
+ *   is not the app's, and inventing an app token to copy for `bubble` or `dots`
+ *   would be debt bought for nothing.
+ *
+ * INVARIANTS:
+ * - Pure data and pure functions of it. No clock, no environment, no I/O.
+ * - Nothing here is exported from the domain barrel. A colour is not vocabulary,
+ *   for the same reason `./constants.ts`'s margins are not.
+ */
+
+/**
+ * A scheme the channel can render. Two today; the shape is a set rather than a
+ * boolean because `highContrast` or `print` would join it rather than replace it.
+ */
+export type ColorScheme = "light" | "dark";
+
+/**
+ * Every colour decision this channel makes, named by what it means.
+ *
+ * `faint` is the marks that recede — the `/* EOM *\/` marker AND every rule. One
+ * decision, so one role, even though it lands on `color` in one place and
+ * `border-top-color` in the other. Which CSS property carries a colour is not
+ * what makes it a different colour.
+ */
+export type Role =
+  | "background"
+  | "text"
+  | "faint"
+  | "meta"
+  | "cta"
+  | "ctaHover"
+  | "bubble"
+  | "onBubble"
+  | "dots"
+  | "link"
+  | "destructive";
+
+/** One scheme's answer for every role. `Record` — a scheme owes an answer to all of them. */
+export type EmailPalette = Record<Role, string>;
+
+/** Every role, for tests to iterate. Source order is the table in ADR-CONTRACTS-088. */
+export const ROLES: readonly Role[] = [
+  "background",
+  "text",
+  "faint",
+  "meta",
+  "cta",
+  "ctaHover",
+  "bubble",
+  "onBubble",
+  "dots",
+  "link",
+  "destructive",
+];
+
+/**
+ * The roles carried by a class hook, and therefore needing a rule in
+ * `DARK_STYLE`. The absentees are not exceptions to tune — they are structural,
+ * each riding another role's rule because it can never move alone:
+ *
+ * - `background` and `text` land on `body`, which needs no class.
+ * - `onBubble` rides `.cs-bubble` — a bubble's fill and its text change together
+ *   or not at all.
+ */
+export const CLASS_ROLES: readonly Role[] = [
+  "faint",
+  "meta",
+  "cta",
+  "ctaHover",
+  "bubble",
+  "dots",
+  "link",
+  "destructive",
+];
+
+/**
+ * Roles whose rule is a `:hover` state rather than a resting colour.
+ *
+ * Two things follow, and both are departures from every other role:
+ *
+ * - **It cannot be inline.** `:hover` has no inline form, so BOTH schemes state it
+ *   in the stylesheet — light in `BASE_STYLE`, dark overriding in `DARK_STYLE`.
+ *   Every other role is inline-light with a dark override.
+ * - **It is opportunistic.** `:hover` support in mail clients is poor and
+ *   inconsistent: good in Apple Mail, partial in new Outlook for Mac and Yahoo,
+ *   absent in Gmail and classic Outlook. Where it does not work the button simply
+ *   rests, which is the state it has today — so this can only add, never subtract.
+ */
+export const HOVER_ROLES: readonly Role[] = ["ctaHover"];
+
+/**
+ * The app's `--primary`, per scheme — resolved with `pnpm color`, never eyeballed.
+ *
+ * TWO roles spend this: `link` and `cta`. A call to action is a link wearing a
+ * box, so its edge and its label are the link's colour and say which of these it
+ * is. They stay separate roles rather than collapsing into one, because "the CTA
+ * tracks the link" is a decision this states rather than a fact about colour —
+ * pull them apart by giving `cta` its own value, not by unpicking a shared
+ * constant.
+ */
+const PRIMARY: Record<ColorScheme, string> = {
+  // `:root --primary` (`oklch(0.5249 0.264881 263.0129)` → `#0050ff`). Left at the
+  // value the old layer shipped: deltaEOK to the token is 0.0167, inside the 0.02
+  // JND, so they are the same blue to a reader and "fixing" it would rewrite 25
+  // snapshots to change nothing anyone can see.
+  light: "#0047FF",
+  // `.dark --primary` (`oklch(0.91 0.165 195)`), gamut-mapped to sRGB. The token
+  // sits just outside sRGB and maps to aqua — `oklch(#00ffff)` is
+  // `L=0.9054 C=0.1546 H=194.77` against the token's `0.91 / 0.165 / 195` — so
+  // this is the token, not a clamping artifact.
+  dark: "#00ffff",
+};
+
+const PALETTES: Record<ColorScheme, EmailPalette> = {
+  light: {
+    background: "#ffffff",
+    text: "#1a1a1a",
+    faint: "#bbb",
+    meta: "#666",
+    cta: PRIMARY.light,
+    // The app's `:root --secondary-item-hover` — `--primary` at 20%,
+    // `oklch(0.9064 0.1527 194.8 / 20%)` — flattened over this scheme's
+    // `background`, because an email cannot lean on alpha:
+    //   pnpm color 'oklch(0.9064 0.1527 194.8 / 20%)' --over '#ffffff'
+    // A function of `background`; recompute if that moves.
+    ctaHover: "#d1ffff",
+    bubble: "#666",
+    onBubble: "#ffffff",
+    dots: "#666",
+    link: PRIMARY.light,
+    // The app's `:root --destructive` (`oklch(0.577 0.245 27.325)`) in sRGB.
+    destructive: "#e7000b",
+  },
+  dark: {
+    background: "#1a1a1a",
+    text: "#e8e8e8",
+    faint: "#666",
+    meta: "#8a8a8a",
+    cta: PRIMARY.dark,
+    // Same token and same arithmetic as `bubble` below, and the identical answer
+    // — both are `.dark --secondary-item-hover` over this `background`. Two roles
+    // because they are two decisions: a hovered button and a chat bubble have no
+    // reason to move together, and the day one of them changes, keying this
+    // palette by colour would have moved both.
+    ctaHover: "#154848",
+    // The app's `.dark --secondary-item-hover` (the tree-nav hover), which is
+    // `--primary` at 20% — `oklch(0.91 0.165 195 / 20%)` — FLATTENED over this
+    // scheme's `background`, because an email cannot lean on alpha:
+    //   pnpm color 'oklch(0.91 0.165 195 / 20%)' --over '#1a1a1a'
+    // It is a function of `background`, so recompute it if that moves. Hue
+    // survives the flattening (195.10), which is what makes it read as the same
+    // hover rather than a grey.
+    bubble: "#154848",
+    onBubble: "#ffffff",
+    dots: "#8a8a8a",
+    link: PRIMARY.dark,
+    destructive: "#ff6b6b",
+  },
+};
+
+/**
+ * One scheme's palette.
+ *
+ * Callers ask for a scheme rather than importing a `LIGHT` / `DARK` object, so a
+ * third scheme is an entry in `PALETTES` rather than an edit to every call site.
+ */
+export function palette(scheme: ColorScheme): EmailPalette {
+  return PALETTES[scheme];
+}
+
+/** The CSS properties a role's colour lands on. */
+export type ColorProp =
+  | "color"
+  | "background"
+  | "background-color"
+  | "border-color"
+  | "border-top-color";
+
+/**
+ * `onBubble` → `cs-on-bubble`. Derived, never hand-typed.
+ *
+ * The `cs-` prefix is load-bearing, and `./styles.ts` explains why: a role class
+ * survives into the shipped HTML because `DARK_STYLE` needs it there, while a
+ * `csr-` recipe class is consumed by the inliner and never ships. The prefixes
+ * are what make "a hook" and "a bundle of declarations" mechanically separable.
+ */
+export function classNameFor(role: Role): string {
+  return `cs-${role.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+}
+
+/**
+ * A class attribute for one or more roles, e.g. `class="cs-cta cs-cta-hover"`.
+ *
+ * Each class is DERIVED from its role, which is what makes a class that names one
+ * role while carrying another's colour unrepresentable rather than merely
+ * tested.
+ *
+ * Several roles land on one element when they are separately decidable but
+ * inseparably placed — a CTA's edge and its hover fill are both the box, and the
+ * hover one is present only when the box is actually clickable.
+ */
+export function roleClass(...roles: Role[]): string {
+  return `class="${roles.map(classNameFor).join(" ")}"`;
+}
+
+/**
+ * A role's LIGHT declaration, unterminated: `color: #666`.
+ *
+ * Light is the baseline every client gets, including the ones that strip
+ * `<style>`. Dark arrives via `darkStyle` instead — see it for why the two are
+ * not two sources of truth.
+ *
+ * Unterminated because a declaration is an ingredient: `./styles.ts` composes it
+ * into an ordered recipe and owns the separators, and that recipe is what BOTH
+ * surfaces are built from — inline for HTML, a rule for AMP. See `./constants.ts`'s
+ * `MONO_DECL`, which is unterminated for the same reason.
+ */
+export function roleDecl(role: Role, prop: ColorProp = "color"): string {
+  return `${prop}: ${PALETTES.light[role]}`;
+}
+
+const light = PALETTES.light;
+const dark = PALETTES.dark;
+
+/**
+ * The scheme-independent rules — everything that has no inline form.
+ *
+ * Only `:hover` lives here, and only because it cannot be inline. This block is
+ * the LIGHT hover; the dark block follows it in the shell and overrides it, so
+ * source order is what resolves them (same specificity).
+ *
+ * Whether any of it happens is the client's call, and this is the ONE role whose
+ * reach the AMP surface changes. Apple Mail honours `:hover`, new Outlook for Mac
+ * and Yahoo partially, Gmail and classic Outlook not at all — but Gmail is an AMP
+ * client, and there this rule simply works. On the html surface there is no
+ * fallback to write: without it the button rests, which is how it looks today.
+ * Purely additive, like the dark path. See `./styles.ts` for the surface split.
+ *
+ * `.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 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.
+ *
+ * A template rather than a generated string — it reads top to bottom as the CSS
+ * it is — but it interpolates `palette("dark")` rather than literals, so a
+ * colour still changes in exactly one place. What a template CAN do is forget a
+ * role; `__tests__/colors.test.ts` is what catches that.
+ *
+ * `!important` on every declaration is load-bearing, not defensive: the light
+ * colour is inline, inline beats a stylesheet on specificity, and without
+ * `!important` every rule here silently loses and dark quietly does nothing.
+ *
+ * **This block is the html surface's alone, and gives up nothing by being so.**
+ * AMP4EMAIL disallows the `prefers-color-scheme` media feature outright — verified
+ * against the AMP validator, with and without `data-css-strict` — so the AMP
+ * surface cannot carry these rules in any form, and does not try
+ * (ADR-CONTRACTS-089). It costs nothing, because the two audiences are disjoint:
+ * this block is read by Apple Mail, iOS Mail and Outlook for Mac (see
+ * `./shells.ts`), and AMP is read by Gmail, Yahoo and Mail.ru — clients that
+ * force-invert and never honoured it. Unlike `hoverStyle`, there was no version of
+ * this worth parameterizing.
+ *
+ * `.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
+ * second, each `<hr>` does the reverse. Two classes would be tidier to read and
+ * would mean the class no longer derives from the role, which is the property
+ * that makes a class carrying the wrong colour unrepresentable. A declaration an
+ * element ignores costs nothing; a class that can lie costs a debugging session.
+ *
+ * This block is additive and fail-safe. A client that strips `<style>` or ignores
+ * `prefers-color-scheme` keeps the inline light colours — which is exactly
+ * today's behaviour, not a degraded one.
+ *
+ * Custom properties would collapse all of this into one `:root` redefinition and
+ * are NOT used: caniemail puts them at ~45% support, and Outlook for Mac 16.80 —
+ * a current client, and one of the three that honours `prefers-color-scheme` at
+ * all — does not support them. In a client without them `color: var(--text, #1a1a1a)`
+ * is an invalid declaration and drops whole, so text loses its colour rather than
+ * falling back. They would break dark mode in a client we are building it for.
+ */
+export const DARK_STYLE = `@media (prefers-color-scheme: dark) {
+body { background-color: ${dark.background} !important; color: ${dark.text} !important; }
+.cs-faint { color: ${dark.faint} !important; border-top-color: ${dark.faint} !important; }
+.cs-meta { color: ${dark.meta} !important; }
+.cs-cta { border-color: ${dark.cta} !important; }
+.cs-cta-hover:hover { background-color: ${dark.ctaHover} !important; }
+.cs-bubble { background: ${dark.bubble} !important; color: ${dark.onBubble} !important; }
+.cs-dots { color: ${dark.dots} !important; }
+.cs-link { color: ${dark.link} !important; }
+.cs-destructive { color: ${dark.destructive} !important; }
+}`;

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

@@ -1,8 +1,12 @@
 /**
- * Email channel constants — the styling vocabulary and the one link in it
+ * Email channel constants — typography, layout, and the one link in them
  * (ADR-CONTRACTS-086). `EMAIL_FROM` (SES envelope) is infra and stays in the
  * backend.
  *
+ * Colour is NOT here: it moved to `./colors.ts` when the channel gained a second
+ * scheme (ADR-CONTRACTS-088). What is left is what has only ever had one answer —
+ * a font stack does not change in the dark.
+ *
  * These are the email channel's own answer and are deliberately NOT exported
  * from the domain barrel: a margin is not vocabulary. The brand NAME is not here
  * either — it is `../../context`'s `COMPANY_NAME`, because it is the same answer
@@ -24,8 +28,16 @@ export const COMPANY_URL = "https://companysemantics.ai";
 // Styling
 // =============================================================================
 
-/** The `font-family` declaration every element carries. */
-export const MONO = `font-family: ${MONO_FONT_STACK};`;
+/**
+ * The `font-family` declaration every element carries, WITHOUT its semicolon.
+ *
+ * Declarations are stored unterminated because `./styles.ts` composes them into
+ * an ordered list and puts the separators back — one `; ` between, one `;` at the
+ * end — for both surfaces. A declaration that carried its own terminator would
+ * make the joiner's output depend on which declaration it happened to be, which
+ * is exactly the drift the registry exists to prevent.
+ */
+export const MONO_DECL = `font-family: ${MONO_FONT_STACK}`;
 
 /**
  * The single font size for every email element (HTML). Plain text is monospace
@@ -33,23 +45,6 @@ export const MONO = `font-family: ${MONO_FONT_STACK};`;
  */
 export const FONT_SIZE = "13px";
 
-/**
- * The colour for a `warning` — the product's destructive token, resolved.
- *
- * This is `--destructive` from the app's `globals.css` `:root`
- * (`oklch(0.577 0.245 27.325)`) converted to sRGB hex. It is COPIED, not
- * imported, and it has to be: contracts sits ABOVE the app in the dependency
- * flow, so this package cannot read the app's stylesheet — and email cannot read
- * one either. There is no CSS to cascade from and no custom properties to
- * resolve, so every colour in this channel is a literal in an inline `style`.
- * If the token moves, this does not follow it; that divergence is the cost of
- * the arrow pointing one way.
- *
- * The `:root` value rather than `.dark`'s, because this channel is light-only by
- * construction — `./shells.ts` states `color: #1a1a1a` on the body.
- */
-export const DESTRUCTIVE = "#e7000b";
-
 /**
  * The gap AFTER a rendered line: `"normal"` is a blank line in plain text,
  * anything else is none.
@@ -62,3 +57,15 @@ export const SPACING: Record<Spacing, string> = {
   tight: "0 0 4px 0",
   none: "0",
 };
+
+/**
+ * A CTA button's inner padding.
+ *
+ * It lands in three places that MUST agree, or Outlook double-pads and the box
+ * collapses: `./styles.ts`'s `cta-anchor` (linked — the padding is what makes the
+ * whole box clickable), its `cta-cell-code` (unlinked), and `./cta.ts`'s
+ * `MSO_CTA_STYLE` (Outlook, which cannot do the first). It sits here rather than
+ * in `./cta.ts` because `./styles.ts` needs it and `./cta.ts` imports FROM
+ * `./styles.ts` — a constant shared by both belongs below both.
+ */
+export const CTA_PAD = "16px 24px";

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

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

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

@@ -25,16 +25,30 @@ import type { Renderer } from "../../renderer";
 
 import type { Spacing } from "./constants";
 import { renderElement } from "./render";
-import { type EmailLine, htmlShell, textShell } from "./shells";
+import { ampShell, type EmailLine, htmlShell, textShell } from "./shells";
 
-/** One rendered email — the email channel's natural output type. */
+/**
+ * One rendered email — the email channel's natural output type.
+ *
+ * Three bodies, because an email IS a `multipart/alternative`: one message, whose
+ * parts a client chooses between. This is NOT three channels — a recipient gets one
+ * email — which is why AMP lives here rather than behind a second `Renderer`
+ * (ADR-CONTRACTS-089). Assembling the parts is delivery's job, and delivery is not
+ * contracts': today the backend sends `text` and `html` over SES's simple send and
+ * `amp` goes nowhere.
+ */
 export interface RenderedEmail {
   /** Subject line — the notification's `metadata.title`. */
   subject: string;
-  /** Plain-text body. */
+  /** Plain-text body (`text/plain`). */
   text: string;
-  /** HTML body (every kind is dual-output). */
+  /** HTML body (`text/html`) — every kind is multi-output. */
   html: string;
+  /**
+   * AMP4EMAIL body (`text/x-amp-html`) — read by Gmail, Yahoo and Mail.ru, and
+   * the only surface where the CTA's `:hover` reaches most recipients.
+   */
+  amp: string;
 }
 
 /**
@@ -68,6 +82,7 @@ export const emailRenderer: Renderer<RenderedEmail> = {
       subject: content.metadata.title,
       text: textShell(lines),
       html: htmlShell(lines),
+      amp: ampShell(lines),
     };
   },
 };

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

@@ -45,23 +45,17 @@ import type {
 } from "../../content";
 import type { RenderContext } from "../../context";
 
-import {
-  COMPANY_URL,
-  DESTRUCTIVE,
-  FONT_SIZE,
-  MONO,
-  SPACING,
-  type Spacing,
-} from "./constants";
+import { COMPANY_URL, type Spacing } from "./constants";
 import { renderChatUnit } from "./chat";
 import { ctaButton } from "./cta";
 import { escapeHtml } from "./escape-html";
 import type { EmailLine } from "./shells";
+import { styleClass } from "./styles";
 
 /** One `<p>` — the primitive every prose-ish element is built from. */
 function paragraph(html: string, text: string, spacing: Spacing): EmailLine {
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
+    html: `<p ${styleClass(`p-${spacing}`)}>${html}</p>`,
     text,
     spacing,
   };
@@ -92,7 +86,7 @@ function keyValueLine(row: KeyValueRow): { html: string; text: string } {
 
 /** The standalone `>> LABEL <<` box. */
 function ctaLine(cta: CallToAction, trailing: Spacing): EmailLine {
-  const { html, text } = ctaButton(cta, SPACING[trailing]);
+  const { html, text } = ctaButton(cta, trailing);
   return { html, text, spacing: trailing };
 }
 
@@ -100,7 +94,7 @@ function ctaLine(cta: CallToAction, trailing: Spacing): EmailLine {
 function signatureLine(signer: string, year: number): EmailLine {
   const line = `ⓒ ${year} • ${signer}`;
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};"><br><br><span style="color: #bbb;">/* EOM */</span><br>${escapeHtml(line)}<br><a href="${COMPANY_URL}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(COMPANY_URL)}</a></p>`,
+    html: `<p ${styleClass("p-none")}><br><br><span ${styleClass("eom", "faint")}>/* EOM */</span><br>${escapeHtml(line)}<br><a href="${escapeHtml(COMPANY_URL)}" target="_blank" rel="noopener noreferrer" ${styleClass("signature-link", "link")}>${escapeHtml(COMPANY_URL)}</a></p>`,
     text: `\n\n/* EOM */\n${line}\n${COMPANY_URL}`,
     spacing: "none",
   };
@@ -161,7 +155,7 @@ export function renderElement(
       const text = "🆆🅰🆁🅽🅸🅽🅶";
       return [
         paragraph(
-          `<span style="color: ${DESTRUCTIVE};">${escapeHtml(text)}</span>`,
+          `<span ${styleClass("warning", "destructive")}>${escapeHtml(text)}</span>`,
           text,
           trailing,
         ),
@@ -215,20 +209,29 @@ export function renderElement(
     case "divider":
       return [
         {
-          html: `<hr style="border: none; border-top: 1px solid #bbb; margin: ${SPACING[trailing]};">`,
+          html: `<hr ${styleClass(`hr-${trailing}`, "faint")}>`,
           text: "---",
           spacing: trailing,
         },
       ];
 
-    case "heroImage":
+    case "heroImage": {
+      // Stated as attributes, not just style: they are the image's intrinsic
+      // size, every client uses them to reserve space before it loads, and
+      // `./styles.ts`'s `ampify` reads them to decide whether the AMP surface can
+      // draw an `<amp-img>` at all.
+      const dimensions =
+        element.width !== undefined && element.height !== undefined
+          ? ` width="${element.width}" height="${element.height}"`
+          : "";
       return [
         {
-          html: `<img src="${element.src}" alt="${escapeHtml(element.alt)}" style="max-width: 100%; margin: ${SPACING[trailing]};">`,
+          html: `<img src="${escapeHtml(element.src)}" alt="${escapeHtml(element.alt)}"${dimensions} ${styleClass(`hero-${trailing}`)}>`,
           text: element.alt,
           spacing: trailing,
         },
       ];
+    }
 
     default: {
       const _exhaustive: never = element;