@company-semantics/contracts 35.0.0 → 36.0.0

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
@@ -48,12 +103,16 @@ expect to style it properly rather than trust the placeholder.
 
 ## Invariants
 
-- Output is byte-identical to what the old `src/email/render` emitted. This is
-  the whole constraint of the migration. `__tests__/render.test.ts` proves it by
-  composing every fixture in the frozen output-parity golden and rendering it
-  through this channel — a diff there means a real sent email changed. The golden
-  is the only record of those bytes now, so it is the authority: fix the
-  renderer, never the golden.
+- Output is locked by `../../__tests__/render-snapshot.test.ts`, across every
+  fixture in `../../__tests__/fixtures.ts` — a diff there means a real sent email
+  changed, so review it before regenerating. Byte-identity with the old
+  `src/email/render` was the whole constraint of the migration; it held, shipped
+  in 35.0.0, and ADR-CONTRACTS-087 retired the golden that proved it, because
+  that proof could not double as permission to change the design.
+- `__tests__/render.test.ts` asserts the rules that outlive any redesign — every
+  element type supported, subject from the content's title, year and signer from
+  context, the `:` restored, user content escaped. Markup belongs in the
+  snapshot, not there.
 - PURE. `render` is a function of `(content, context)`: no clock, no environment,
   no I/O. The copyright year comes from `context.brand.copyrightYear`, which is
   what retires the `new Date().getFullYear()` hidden inside the old
@@ -67,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__/README.md

@@ -4,26 +4,29 @@
 
 Tests for the email channel (ADR-CONTRACTS-086).
 
-`render.test.ts` holds the renderer's one load-bearing proof: every fixture in
-`../../../__tests__/output-parity.golden.ts`, composed through
-`NOTIFICATION_DEFINITIONS` and rendered through `emailRenderer`, byte-for-byte.
-The rest of the file pins the properties the golden cannot see — that `supports`
-is total, that the year comes from `RenderContext`, that the `:` separator the
-content model drops is put back, and that user-controlled fields are escaped.
+`render.test.ts` pins the renderer's behavioural rules — the claims that hold no
+matter how the email is styled: that `supports` is total, that the subject comes
+from the content's title, that the year and signer come from `RenderContext`
+rather than a clock, that the `:` separator the content model drops is put back,
+and that user-controlled fields are escaped. It also renders every fixture in
+`../../../__tests__/fixtures.ts` through `NOTIFICATION_DEFINITIONS`, which proves
+each kind composes and renders on both surfaces at all.
+
+The MARKUP is not here. `../../../__tests__/render-snapshot.test.ts` locks that.
 
 ## Invariants
 
-- The golden is the ORACLE, not this renderer's output. When the two disagree,
-  the renderer is wrong: the golden records what the old `src/email/render`
-  emitted at 32.0.0, and "no rendered email changed" is the migration's whole
-  promise. It is never regenerated to make this file pass — and since that layer
-  is now deleted, the golden is the only record of those bytes, so regenerating
-  it destroys the evidence rather than updating it.
+- Rules here, markup there. A test in this file that asserts what the HTML looks
+  like is in the wrong file: it belongs in the snapshot, where a redesign shows
+  up as a reviewable diff instead of a wall of broken assertions.
 - NO fake timers. The old layer's `signature()` read the wall clock, which is why
   every render test had to freeze it; here the year is a field on
   `RenderContext`, and keeping this file clock-free is the improvement being
   locked in.
-- Parity is asserted at two levels against one golden: here through the RENDERER
-  (composed content → bytes), and in `../../../__tests__/output-parity.test.ts`
-  through the ENTRY POINT (`renderToChannel`, the whole pipeline). Either one
-  drifting from the golden is a failure.
+- This file used to assert every fixture byte-for-byte against a frozen golden of
+  what `src/email/render` emitted at 32.0.0 — the migration's "no rendered email
+  changed" promise, checked here at the RENDERER and in a companion suite at the
+  ENTRY POINT (`renderToChannel`). The promise held and shipped in 35.0.0;
+  ADR-CONTRACTS-087 retired both, because byte-equality with a deleted layer
+  cannot survive email design being deliberately changed. The bytes are in git at
+  `v35.0.0`.

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