@company-semantics/contracts 35.1.0 → 36.0.0

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

@@ -20,6 +20,7 @@ import { describe, expect, it } from "vitest";
 
 import type {
   NotificationContent,
+  NotificationElement,
   NotificationElementType,
 } from "../../../content";
 import type { RenderContext } from "../../../context";
@@ -143,6 +144,91 @@ describe("emailRenderer", () => {
     expect(html).not.toContain("<script>");
   });
 
+  it("escapes a URL, so it cannot close its attribute and forge another", () => {
+    // `href` and `src` are the two values that reach the markup as a URL rather
+    // than as text, and they used to be interpolated raw — an HTML injection on
+    // its own, and since ADR-CONTRACTS-089 a style injection too: `inlineStyles`
+    // rewrites class attributes, so a URL that can write `class="csr-body"` can
+    // write any declaration in the registry into someone else's element.
+    const html = (element: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [element] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const cta = html({
+      type: "callToAction",
+      label: "Open",
+      href: 'https://x.test/" data-forged="1',
+    });
+    // The quote survives as text, so the forged attribute never becomes one.
+    // Asserted against `data-forged="` — the ATTRIBUTE form — because the escaped
+    // payload still contains the string `data-forged=`, and a looser match would
+    // pass whether or not the fix is present.
+    expect(cta).toContain("&quot;");
+    expect(cta).not.toMatch(/data-forged="/);
+
+    const hero = html({
+      type: "heroImage",
+      src: '/x.png" onerror="alert(1)',
+      alt: "x",
+    });
+    expect(hero).not.toMatch(/onerror="/);
+  });
+
+  it("makes a linked CTA's whole box the click target, an unlinked one not clickable", () => {
+    // The click target is the anchor, so it must fill the box — `display: block` +
+    // the padding on the `<a>` itself, not the cell. An OTP code has no href: it
+    // must not become an anchor at all, which is what keeps it uncopiable-as-a-link
+    // and unclickable.
+    const box = (cta: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [cta] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const linked = box({
+      type: "callToAction",
+      label: "Open",
+      href: "https://example.com/x",
+    });
+    expect(linked).toMatch(
+      /<a [^>]*href="https:\/\/example\.com\/x"[^>]*style="display: block; padding:/,
+    );
+
+    const payload = box({ type: "callToAction", label: "123456" });
+    expect(payload).not.toContain("<a ");
+    // The cell carries the padding instead, so the code is still a padded box.
+    expect(payload).toMatch(/<td style="padding: /);
+  });
+
+  it("restores the CTA's cell padding for Outlook, which cannot fill the anchor", () => {
+    // Outlook's Word engine ignores `display: block`, so the full-box target
+    // degrades to today's text click there. The MSO block must put the padding
+    // back on the cell, or Outlook renders the button cramped.
+    const { html } = emailRenderer.render(
+      {
+        metadata: { kind: "org.invite", title: "t" },
+        sections: [
+          {
+            elements: [
+              { type: "callToAction", label: "Join", href: "https://x.test" },
+            ],
+          },
+        ],
+      },
+      FIXTURE_CONTEXT,
+    );
+    expect(html).toContain("<!--[if mso]>");
+    expect(html).toMatch(/\[if mso\]>.*\.cs-cta td \{ padding: .* \}/s);
+  });
+
   it("is pure — same inputs, same bytes", () => {
     const content = NOTIFICATION_DEFINITIONS["security.alert"].compose(
       {

package/src/notifications/renderers/email/__tests__/styles.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The style registry's contract (ADR-CONTRACTS-089).
+ *
+ * `../../__tests__/render-snapshot.test.ts` already proves the html surface's
+ * bytes, and it is the authority on what the email LOOKS like. What it cannot say
+ * is WHY those bytes are safe to derive, because a snapshot passes just as happily
+ * over markup that leaks a recipe class or drops a role hook. This file asserts the
+ * two properties the derivation rests on:
+ *
+ * - a `cs-` role hook SHIPS, because `darkStyle` needs it in the markup;
+ * - a `csr-` recipe class DOES NOT, because it is spent and dropped.
+ *
+ * Get either backwards and the snapshot still passes while dark mode silently
+ * stops working, or the shipped email carries dead classes nothing styles.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent } from "../../../content";
+import type { RenderContext } from "../../../context";
+import { emailRenderer } from "../index";
+import { inlineOf, inlineStyles, ruleOf, STYLE_NAMES } from "../styles";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** One of everything that carries a class, so the scan below has something to see. */
+const CONTENT: NotificationContent = {
+  metadata: { kind: "auth.otp", title: "t" },
+  sections: [
+    {
+      elements: [
+        { type: "greeting", recipientName: "Sam" },
+        { type: "warning" },
+        { type: "divider" },
+        { type: "callToAction", label: "Open", href: "https://x.test/a" },
+        { type: "callToAction", label: "123456" },
+        {
+          type: "chatUnit",
+          items: [
+            { type: "message", role: "user", text: "hi", from: "Sam" },
+            { type: "message", role: "assistant", text: "hello" },
+            { type: "continuation" },
+            { type: "callToAction", label: "Read", href: "https://x.test/b" },
+          ],
+        },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+/** Every class the shipped markup actually applies. */
+function shippedClasses(html: string): string[] {
+  return [...html.matchAll(/class="([^"]+)"/g)].flatMap((m) =>
+    m[1].split(/\s+/),
+  );
+}
+
+describe("the style registry", () => {
+  it("ships no recipe class — they are spent by the inliner, not delivered", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    // The whole document, not just the class attributes: a recipe class must not
+    // survive anywhere, including in a stylesheet the html surface never wants.
+    expect(html).not.toContain("csr-");
+  });
+
+  it("ships every role hook, because the dark stylesheet needs it there", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    const shipped = shippedClasses(html);
+    expect(shipped.length).toBeGreaterThan(0);
+    // A sample across the roles this content exercises. `cs-cta-hover` is the
+    // interesting one: it is the only reason `.cs-cta` and the hover state are
+    // separate roles, and it rides on the linked CTA above.
+    for (const hook of ["cs-link", "cs-cta", "cs-cta-hover", "cs-bubble"]) {
+      expect(shipped, `${hook} never reached the markup`).toContain(hook);
+    }
+  });
+
+  it("turns a recipe-only class attribute into a style, leaving no class behind", () => {
+    // The collapse that makes `<p class="csr-p-none">` render as the `<p style="…">`
+    // the channel shipped before this registry existed. A leftover `class=""` would
+    // be invisible in a client and a permanent diff in the snapshot.
+    expect(inlineStyles(`<p class="csr-p-none">x</p>`)).toBe(
+      `<p style="${inlineOf("p-none")}">x</p>`,
+    );
+  });
+
+  it("keeps role hooks and appends the style, in that order", () => {
+    // Order is not cosmetic: it is what makes the inliner reproduce the previous
+    // markup byte-for-byte rather than merely equivalently.
+    expect(inlineStyles(`<td class="cs-bubble csr-bubble-user">x</td>`)).toBe(
+      `<td class="cs-bubble" style="${inlineOf("bubble-user")}">x</td>`,
+    );
+  });
+
+  it("leaves markup with no classes untouched", () => {
+    const plain = `<tr><td></td></tr>`;
+    expect(inlineStyles(plain)).toBe(plain);
+  });
+
+  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

@@ -17,9 +17,9 @@
 
 import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
 
-import { FONT_SIZE, MONO } from "./constants";
 import { ctaButton } from "./cta";
 import { escapeHtml } from "./escape-html";
+import { styleClass } from "./styles";
 
 /** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
 function wrapText(text: string, width: number): string[] {
@@ -53,6 +53,17 @@ const MESSAGE_WIDTH = 36;
  * user box aligns with the assistant box. */
 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, 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";
+
 /** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
 function wrapClamped(text: string, width: number, maxLines: number): string[] {
   const lines = wrapText(text, width);
@@ -77,8 +88,7 @@ function clampMessage(text: string): string {
 /** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
  * outer side. */
 function chatRuleHtml(position: "top" | "bottom"): string {
-  const margin = position === "top" ? "12px 0 24px 0" : "24px 0 12px 0";
-  return `<hr style="border: none; border-top: 1px solid #bbb; margin: ${margin};">`;
+  return `<hr ${styleClass(`chat-rule-${position}`, "faint")}>`;
 }
 
 /**
@@ -90,34 +100,35 @@ function chatRuleHtml(position: "top" | "bottom"): string {
  */
 function renderBubble(
   turn: ChatTurn,
-  margin: string,
+  row: ChatRow,
 ): { html: string; text: string[] } {
   const clamped = clampMessage(turn.text);
   const isUser = turn.role === "user";
 
-  const radius = isUser ? "8px 8px 0 8px" : "8px 8px 8px 0";
-  const bubbleAlign = isUser ? " text-align: right;" : "";
-  const cellAlign = isUser ? "right" : "left";
-  const csHidden = isUser ? "visibility: hidden; " : "";
-  const kaomojiHidden = isUser ? "" : "visibility: hidden; ";
+  // Each side draws its own avatar and hides the other's, which is what reserves
+  // both columns and keeps the two bubbles aligned.
+  const bubble = isUser ? "bubble-user" : "bubble-assistant";
+  const channel = isUser ? "chat-channel-right" : "chat-channel-left";
+  const avatar = isUser ? "chat-avatar-left-hidden" : "chat-avatar-left";
+  const kaomoji = isUser ? "chat-avatar-right" : "chat-avatar-right-hidden";
 
   const attributionRow =
     isUser && turn.from
       ? `
   <tr>
     <td></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">${escapeHtml(turn.from)}</td>
+    <td ${styleClass("chat-attribution", "meta")}>${escapeHtml(turn.from)}</td>
     <td></td>
   </tr>`
       : "";
 
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: ${margin};">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass(row)}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; ${csHidden}white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${cellAlign};"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td style="border-radius: ${radius}; padding: 10px 14px;${bubbleAlign} ${MONO} font-size: ${FONT_SIZE}; color: #ffffff; background: #666;">${escapeHtml(clamped)}</td></tr>
+    <td ${styleClass(avatar)}>[c_S]</td>
+    <td ${styleClass(channel)}><table cellpadding="0" cellspacing="0" border="0" ${styleClass("chat-bubble-wrap")}>
+      <tr><td ${styleClass(bubble, "bubble")}>${escapeHtml(clamped)}</td></tr>
     </table></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; ${kaomojiHidden}white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass(kaomoji)}>(•̀_ರ╮)</td>
   </tr>${attributionRow}
 </table>`;
 
@@ -149,7 +160,7 @@ const CHAT_RIGHT_EDGE = CHAT_INDENT.length + MESSAGE_WIDTH + 4;
 /** Centered "⋮" HTML, sized to sit above and centered over a CTA box (they share
  * the same inline-block, so the dots span exactly the button's width). */
 function dotsOverCtaHtml(): string {
-  return `<div style="${MONO} font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0;">⋮</div>`;
+  return `<div ${styleClass("dots-over-cta", "dots")}>⋮</div>`;
 }
 
 /**
@@ -164,15 +175,15 @@ function renderChatCta(
   align: "left" | "right",
   withDots: boolean,
 ): { html: string; text: string[] } {
-  const { html: btnHtml, text: btnText } = ctaButton(cta, "0");
+  const { html: btnHtml, text: btnText } = ctaButton(cta, "none");
   // Dots + button share one inline-block so the dots center over the button's
   // exact width regardless of label length.
-  const stack = `<div style="display: inline-block; text-align: left;">${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  const stack = `<div ${styleClass("cta-stack")}>${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-24")}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${align};">${stack}</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass(`chat-channel-${align}`)}>${stack}</td>
+    <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
 </table>`;
 
@@ -204,11 +215,11 @@ function renderChatCta(
  * case folds the dots into the CTA via `renderChatCta`, centered over the box).
  */
 function renderChatDots(): { html: string; text: string[] } {
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-16")}>
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: center; ${MONO} font-size: 20px; font-weight: bold; color: #666;">⋮</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass("dots-cell", "dots")}>⋮</td>
+    <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
 </table>`;
   // Center the "⋮" over the message box (avatar gutter + box width + borders).
@@ -251,11 +262,11 @@ export function renderChatUnit(items: ChatUnitItem[]): {
     // A bubble directly above a CTA or continuation dots gets a tighter 16px
     // gap; else 24px.
     const next = items[i + 1]?.type;
-    const margin =
+    const row: ChatRow =
       next === "callToAction" || next === "continuation"
-        ? "0 0 16px 0"
-        : "0 0 24px 0";
-    parts.push(renderBubble(item, margin));
+        ? "chat-row-16"
+        : "chat-row-24";
+    parts.push(renderBubble(item, row));
   });
 
   const width = parts