@company-semantics/contracts 36.0.0 → 38.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "36.0.0",
+  "version": "38.0.0",
   "private": false,
   "repository": {
     "type": "git",

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

@@ -50,11 +50,31 @@ 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.
+### ⚠️ 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
@@ -161,12 +181,15 @@ expect to style it properly rather than trust the placeholder.
   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.
+- 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
@@ -183,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

@@ -174,11 +174,19 @@ describe("the AMP surface", () => {
 
   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.
+    // 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.

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

@@ -270,12 +270,16 @@ const dark = PALETTES.dark;
  * 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.
+ * Whether any of it happens is the client's call. Apple Mail honours `:hover`, new
+ * Outlook for Mac and Yahoo partially, Gmail and classic Outlook not at all. There
+ * is no fallback to write: without it the button rests, which is how it looks
+ * today. Purely additive, like the dark path.
+ *
+ * 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
@@ -301,15 +305,26 @@ export const BASE_STYLE = hoverStyle(true);
  * 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.
+ * **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/index.ts

@@ -33,9 +33,11 @@ import { ampShell, type EmailLine, htmlShell, textShell } from "./shells";
  * 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.
+ * (ADR-CONTRACTS-089).
+ *
+ * **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`. */
@@ -45,8 +47,16 @@ export interface RenderedEmail {
   /** 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.
+   * 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;
 }

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

@@ -49,10 +49,17 @@ export interface EmailLine {
  * text colour sitting on top of it. The two ship together or not at all.
  *
  * Only Apple Mail, iOS Mail and Outlook for Mac read any of this. Clients that
- * force-invert (Outlook.com, Windows Outlook, Gmail Android) ignore both metas
- * and rewrite the inline styles post-delivery — nothing here can stop that, which
- * is why the body still states an explicit background rather than trusting a
- * default.
+ * recolour instead (Outlook.com, Windows Outlook, and — measured —
+ * **Gmail iOS**) ignore both metas and rewrite the inline styles post-delivery.
+ * Nothing here can stop that, which is why the body still states an explicit
+ * background rather than trusting a default.
+ *
+ * Do not read that as a degradation to fix: Gmail iOS's inversion of THIS part is
+ * the only dark mode a Gmail iOS reader gets, and preserving it is why `ampShell`'s
+ * output is never sent (ADR-CONTRACTS-092). Gmail web, by contrast, recolours
+ * nothing at all — a light email stays light in a dark client, and no surface fixes
+ * that. Gmail Android is untested: unknown, not negative.
+ * `company-semantics-backend/docs/dark-mode-probe.md`.
  *
  * The `<!--[if mso]>` block is the mirror image: it is read ONLY by the Outlook
  * Word engine, and undoes the one layout that engine cannot render — a linked
@@ -86,12 +93,38 @@ ${inner}
 }
 
 /**
- * Wrap rendered lines in the AMP4EMAIL shell (ADR-CONTRACTS-089).
+ * Wrap rendered lines in the AMP4EMAIL shell (ADR-CONTRACTS-089, -091, -092).
+ *
+ * ⚠️ **THIS BODY IS NEVER SENT, AND MUST NOT BE.** It is rendered, previewed in the
+ * Ladle gallery, and dropped. Delivering it is a REGRESSION, not a feature — see
+ * below. `company-semantics-backend`'s `EmailDelivery.test.ts` fails if it ever
+ * reaches the transport, and that test is the invariant; this comment is only its
+ * explanation.
+ *
+ * **Why it is 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 shipping an AMP part would switch it off and hand them a white email
+ * in a dark client. This surface buys `:hover` in Gmail and would cost dark mode in
+ * Gmail. That trade was measured and refused (ADR-CONTRACTS-091), and the measurement
+ * is `company-semantics-backend/docs/dark-mode-probe.md`. ADR-CONTRACTS-089 asserted
+ * the opposite — "AMP clients force-invert, so they never got our dark colours
+ * anyway" — and that is FALSE: Gmail web recolours nothing, Yahoo does not invert,
+ * and Gmail iOS exempts AMP.
  *
- * The third MIME part of the same email — `text/x-amp-html`, beside `text/html`
- * and `text/plain`. Gmail, Yahoo and Mail.ru read it; everyone else reads the
- * html part and never knows this existed. That is the point: `./colors.ts`'s
- * `hoverStyle` is absent in Gmail on the html surface, and here it simply works.
+ * **Why it exists at all, then.** AMP is the only email format with a real animation
+ * model — `amp-animation`, `amp-bind`, `amp-position-observer` — and no arbitrary JS
+ * needed. Nothing else can make the kaomoji companions blink once, three seconds
+ * after open. That is a future worth keeping the surface alive for, and rebuilding it
+ * later costs more than carrying it inert now (ADR-CONTRACTS-092). If Google ever
+ * allows `prefers-color-scheme` here, or Gmail starts inverting AMP too, the trade
+ * flips and this is ready.
+ *
+ * **Light-only, permanently.** AMP4EMAIL disallows the `prefers-color-scheme` media
+ * feature — a hard validator error, checked with and without `data-css-strict` — so
+ * `DARK_STYLE` cannot appear here in any form. The `media` ATTRIBUTE on an AMP
+ * element takes the same feature and PASSES the validator; Gmail's runtime ignores
+ * it. Both doors are closed. That is not a gap to close; it is the format.
  *
  * Everything AMP forbids is absent BY CONSTRUCTION rather than by stripping:
  *
@@ -103,16 +136,6 @@ ${inner}
  *   in a line, so nothing has to remove it. Outlook is not an AMP client, and
  *   `display: block` needs no correction in the three that are.
  *
- * **No dark scheme, and that is not an omission.** AMP4EMAIL disallows the
- * `prefers-color-scheme` media feature — verified against the AMP validator, with
- * and without `data-css-strict` — so `DARK_STYLE` cannot appear here in any form.
- * It costs nothing: that block is read by Apple Mail, iOS Mail and Outlook for Mac,
- * and this surface is read by Gmail, Yahoo and Mail.ru. The two sets are disjoint,
- * and the AMP clients force-invert rather than honour a stylesheet — so they were
- * never receiving our dark colours on the html surface either. What this surface
- * adds is `:hover`, which those clients DO honour and which the html surface cannot
- * reach them with. It trades nothing away.
- *
  * The boilerplate hides the body until the runtime unhides it — which is why an
  * AMP document that cannot run scripts shows nothing at all, rather than showing
  * an unstyled version of itself.