@company-semantics/contracts 33.0.0 → 35.0.0

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

@@ -0,0 +1,74 @@
+# notifications/renderers/email/
+
+## Purpose
+
+The email channel (ADR-CONTRACTS-086) — `emailRenderer: Renderer<RenderedEmail>`.
+
+This is the old `src/email/render` turned inside out — and, now that it is
+deleted, what replaced it. That layer offered templates a component per intent
+(`greeting()`, `keyValue()`, `footer()`) and each template chose which to call;
+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`                                                            |
+
+`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`.
+
+## Spacing — the thing the content model does not carry
+
+The old layer passed a `Spacing` per block; `../../kinds` deliberately dropped
+it, because a margin is a channel's answer. So this channel re-derives one, with
+a single rule:
+
+> An element renders as one or more lines. Lines WITHIN an element hug
+> (`"tight"`); the element's LAST line carries the trailing gap, which is
+> `"normal"` — or `"none"` when a `signature` follows, because `signature` owns
+> the blank above its own rule.
+
+That reproduces every hand-authored spacing choice in all eleven old templates.
+The one place it did not fall out was `security.alert`'s reassurance/denial
+couplet, and the fix was to say so in the CONTENT — one `body` with a newline —
+rather than to special-case a kind here. See `../../kinds/security-alert.ts`.
+
+`list`, `divider` and `heroImage` have no counterpart in the old layer and no
+kind composes one, so their markup is invented rather than relocated. `supports`
+still answers true — email can depict them — but the first kind to use one should
+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.
+- 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
+  `signature()`.
+- `supports` answers true for EVERY element type. Email is the rich channel;
+  declining an element would be a lie about the channel rather than a fact about
+  the notification.
+- The `:` between a label and its value is presentation and lives in no element
+  (see `../../kinds/README.md`). `render.ts` puts it back — on key/value rows and
+  on the metadata heading.
+- 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
+  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.

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

@@ -0,0 +1,29 @@
+# notifications/renderers/email/\_\_tests\_\_/
+
+## Purpose
+
+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.
+
+## 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.
+- 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.

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

@@ -0,0 +1,180 @@
+/**
+ * The email renderer's correctness proof (ADR-CONTRACTS-086).
+ *
+ * The renderer has exactly one hard requirement: compose a kind, render it
+ * through this channel, and get the bytes the old `src/email/render` produced.
+ * So that is what this asserts — every fixture in the frozen output-parity
+ * golden, composed via `NOTIFICATION_DEFINITIONS` and rendered through
+ * `emailRenderer`, character-for-character.
+ *
+ * This does NOT replace `../../../__tests__/output-parity.test.ts`. That one
+ * pins the ENTRY POINT (`renderToChannel`, the whole pipeline) against the same
+ * golden; this pins the RENDERER alone, so a failure here says the markup moved
+ * rather than that the wiring did. Two levels, one golden: either drifting is a
+ * failure.
+ *
+ * There is no fake timer here, and that is the improvement being locked in: the
+ * year comes from `RenderContext`, so the golden's clock is just a number.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElementType,
+} from "../../../content";
+import type { RenderContext } from "../../../context";
+import { NOTIFICATION_DEFINITIONS } from "../../../registry";
+import {
+  OUTPUT_PARITY_CLOCK,
+  OUTPUT_PARITY_FIXTURES,
+  OUTPUT_PARITY_GOLDEN,
+  fixtureKey,
+} from "../../../__tests__/output-parity.golden";
+import { emailRenderer } from "../index";
+
+/**
+ * The golden's context, stated rather than ticked. The old layer reached for
+ * `new Date().getFullYear()` mid-render, which is why every render test had to
+ * freeze the clock; here the year the golden was captured under is simply a
+ * value.
+ */
+const GOLDEN_CONTEXT: RenderContext = {
+  brand: {
+    name: "Company Semantics",
+    copyrightYear: new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear(),
+  },
+};
+
+const ALL_TYPES: NotificationElementType[] = [
+  "greeting",
+  "body",
+  "keyValueTable",
+  "callToAction",
+  "list",
+  "divider",
+  "warning",
+  "metadata",
+  "notice",
+  "chatUnit",
+  "signature",
+  "heroImage",
+];
+
+describe("emailRenderer", () => {
+  it("declares the email channel", () => {
+    expect(emailRenderer.id).toBe("email");
+  });
+
+  it("supports every element type — email is the rich channel", () => {
+    for (const type of ALL_TYPES) {
+      expect(emailRenderer.supports(type), type).toBe(true);
+    }
+  });
+
+  it("renders the subject from the content's title, not a registry", () => {
+    const content: NotificationContent = {
+      metadata: { kind: "org.invite", title: "Join Acme" },
+      sections: [{ elements: [{ type: "body", text: "Hello." }] }],
+    };
+    expect(emailRenderer.render(content, GOLDEN_CONTEXT).subject).toBe(
+      "Join Acme",
+    );
+  });
+
+  it("takes the copyright year and signer from context, never from a clock", () => {
+    const content: NotificationContent = {
+      metadata: { kind: "org.invite", title: "t" },
+      sections: [{ elements: [{ type: "signature" }] }],
+    };
+    const pinned: RenderContext = {
+      brand: { name: "Acme", copyrightYear: 1999 },
+    };
+    expect(emailRenderer.render(content, pinned).text).toContain(
+      "ⓒ 1999 • Acme",
+    );
+  });
+
+  it("lets an element's signer override the context brand", () => {
+    const content: NotificationContent = {
+      metadata: { kind: "org.invite", title: "t" },
+      sections: [{ elements: [{ type: "signature", signer: "Grace" }] }],
+    };
+    expect(emailRenderer.render(content, GOLDEN_CONTEXT).text).toContain(
+      "• Grace",
+    );
+  });
+
+  it("puts back the ':' the content model does not carry", () => {
+    // The separator is presentation and lives in no element — a renderer that
+    // forgets it silently drops the colon from every fact in every email.
+    const content: NotificationContent = {
+      metadata: { kind: "auth.otp", title: "t" },
+      sections: [
+        {
+          elements: [
+            {
+              type: "keyValueTable",
+              rows: [{ label: "Status", value: "Valid" }],
+            },
+            {
+              type: "metadata",
+              label: "Request details",
+              rows: [{ label: "IP address", value: "203.0.113.1" }],
+            },
+          ],
+        },
+      ],
+    };
+    const { text } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    expect(text).toContain("Status: Valid");
+    expect(text).toContain("Request details:");
+    expect(text).toContain("IP address: 203.0.113.1");
+  });
+
+  it("escapes user-controlled content in the HTML surface", () => {
+    const content: NotificationContent = {
+      metadata: { kind: "org.invite", title: "t" },
+      sections: [
+        {
+          elements: [{ type: "greeting", recipientName: "<script>x</script>" }],
+        },
+      ],
+    };
+    const { html } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    expect(html).toContain("&lt;script&gt;");
+    expect(html).not.toContain("<script>");
+  });
+
+  it("is pure — same inputs, same bytes", () => {
+    const content = NOTIFICATION_DEFINITIONS["security.alert"].compose(
+      {
+        alertType: "excessive_otp_requests",
+        details: "5 codes in 2 minutes",
+        timestamp: "2026-07-15T00:00:00.000Z",
+      },
+      GOLDEN_CONTEXT,
+    );
+    expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
+      emailRenderer.render(content, GOLDEN_CONTEXT),
+    );
+  });
+
+  describe("output parity with the email layer at 32.0.0", () => {
+    for (const fixture of OUTPUT_PARITY_FIXTURES) {
+      const key = fixtureKey(fixture.kind, fixture.name);
+      it(`${key} renders byte-for-byte`, () => {
+        const definition = NOTIFICATION_DEFINITIONS[fixture.kind];
+        // `payload as never`: the fixture call sites are type-checked in the
+        // golden module; this only bridges compose's per-kind payload.
+        const content = definition.compose(
+          fixture.payload as never,
+          GOLDEN_CONTEXT,
+        );
+        expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
+          OUTPUT_PARITY_GOLDEN[key],
+        );
+      });
+    }
+  });
+});

package/src/{email/render → notifications/renderers/email}/chat.ts

@@ -1,32 +1,24 @@
 /**
- * Chat unit — the dual-output chat transcript block.
+ * Email's answer to a `chatUnit` — bubbles in HTML, box art in plain text.
  *
- * The one component with real layout of its own: message bubbles, an in-stream
- * CTA, and continuation dots, laid out as a bracketed "unit". Same contract as
- * every other component in `blocks.ts` (returns a `Block` = `{ html, text }`, so
- * both surfaces derive from one source); it lives apart because bubble geometry
- * — wrapping, truncation, avatar gutters, alignment — is a self-contained
- * concern that the paragraph/CTA primitives next door do not share.
+ * Moved verbatim from the deleted `src/email/render/blocks` (ADR-CONTRACTS-086), with
+ * one change: it lays out `ChatUnitItem`s from `../../content` rather than the
+ * old layer's parallel `ChatItem` vocabulary. The mapping is exact —
+ * `message` ↔ a bubble, `callToAction` ↔ an embedded button, `continuation` ↔
+ * the "⋮" dots.
  *
  * INVARIANTS:
- * - Pure functions, no side effects.
- * - Components escape their own content; templates pass raw text.
- * - HTML and plain text truncate at exactly the same point (`clampMessage` is
- *   the single truncation authority).
+ * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits. The
+ *   box art is real output: the output-parity golden asserts every column of it.
+ * - Both surfaces truncate at the same point — `clampMessage` is the one
+ *   truncation authority, and HTML and plain text both run content through it.
  */
 
-import {
-  type Block,
-  type CtaBoxOptions,
-  ctaButton,
-  FONT_SIZE,
-  MONO,
-} from "./blocks";
-import { escapeHtml } from "./escape-html";
+import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
 
-// =============================================================================
-// Text geometry
-// =============================================================================
+import { FONT_SIZE, MONO } from "./constants";
+import { ctaButton } from "./cta";
+import { escapeHtml } from "./escape-html";
 
 /** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
 function wrapText(text: string, width: number): string[] {
@@ -74,65 +66,13 @@ function wrapClamped(text: string, width: number, maxLines: number): string[] {
 
 /**
  * The one truncation authority: clamp a raw message to MAX_MESSAGE_LINES ×
- * MESSAGE_WIDTH, ellipsized. Both surfaces of a chat block run content through
+ * MESSAGE_WIDTH, ellipsized. Both surfaces of a chat unit run content through
  * this, so HTML and plain text truncate at exactly the same point.
  */
 function clampMessage(text: string): string {
   return wrapClamped(text, MESSAGE_WIDTH, MAX_MESSAGE_LINES).join(" ");
 }
 
-// =============================================================================
-// Chat items
-// =============================================================================
-
-/** One message in a chat unit. `chatUser`/`chatAssistant` build these; `chatUnit`
- * lays them out together. `from` is the user attribution (sender name). */
-export interface ChatMessage {
-  role: "user" | "assistant";
-  text: string;
-  from?: string;
-}
-
-/** A user (right-aligned) chat message with an optional `from` attribution. */
-export function chatUser(text: string, from?: string): ChatMessage {
-  return { role: "user", text, from };
-}
-
-/** An assistant (left-aligned) chat message. */
-export function chatAssistant(text: string): ChatMessage {
-  return { role: "assistant", text };
-}
-
-/** A CTA button placed inside a chat unit (below a message). */
-export interface ChatCta {
-  role: "cta";
-  cta: CtaBoxOptions;
-}
-
-/** Centered continuation dots inside a chat unit — a "conversation continues"
- * separator placed between a message bubble and a following CTA. */
-export interface ChatDots {
-  role: "dots";
-}
-
-/** An item in a chat unit: a message bubble, a CTA button, or continuation dots. */
-export type ChatItem = ChatMessage | ChatCta | ChatDots;
-
-/** A CTA button for a chat unit — pass it to `chatUnit` alongside messages. */
-export function chatCta(cta: CtaBoxOptions): ChatCta {
-  return { role: "cta", cta };
-}
-
-/** Continuation dots for a chat unit — pass it to `chatUnit` where the
- * conversation should read as continuing (e.g. between the preview and CTA). */
-export function chatDots(): ChatDots {
-  return { role: "dots" };
-}
-
-// =============================================================================
-// Item rendering
-// =============================================================================
-
 /** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
  * outer side. */
 function chatRuleHtml(position: "top" | "bottom"): string {
@@ -141,18 +81,18 @@ function chatRuleHtml(position: "top" | "bottom"): string {
 }
 
 /**
- * Render one message to its HTML `<table>` and plain-text box lines. Both roles
+ * Render one turn to its HTML `<table>` and plain-text box lines. Both roles
  * share the 3-column skeleton: a fixed avatar column on each side (the visible
  * avatar plus the opposite avatar rendered `visibility: hidden` to reserve its
  * width, so bubbles stay bounded and aligned), a middle cell that right/left-
  * aligns the bubble, and — for a user `from` — an attribution row below.
  */
 function renderBubble(
-  msg: ChatMessage,
+  turn: ChatTurn,
   margin: string,
 ): { html: string; text: string[] } {
-  const clamped = clampMessage(msg.text);
-  const isUser = msg.role === "user";
+  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;" : "";
@@ -161,11 +101,11 @@ function renderBubble(
   const kaomojiHidden = isUser ? "" : "visibility: hidden; ";
 
   const attributionRow =
-    isUser && msg.from
+    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(msg.from)}</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">${escapeHtml(turn.from)}</td>
     <td></td>
   </tr>`
       : "";
@@ -196,8 +136,8 @@ function renderBubble(
     ...body,
     `${CHAT_INDENT}└${border}┘`,
   ];
-  if (isUser && msg.from) {
-    box.push(msg.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
+  if (isUser && turn.from) {
+    box.push(turn.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
   }
   return { html, text: box };
 }
@@ -219,7 +159,7 @@ function dotsOverCtaHtml(): string {
  * When `withDots`, continuation "⋮" render just above the button, centered over it.
  */
 function renderChatCta(
-  cta: CtaBoxOptions,
+  cta: CallToAction,
   align: "left" | "right",
   withDots: boolean,
 ): { html: string; text: string[] } {
@@ -259,8 +199,8 @@ function renderChatCta(
 
 /**
  * Standalone continuation dots — centered in the message channel. Used only when
- * `chatDots()` is NOT immediately followed by a CTA (the common case folds the
- * dots into the CTA via `renderChatCta`, centered over the box).
+ * a `continuation` is NOT immediately followed by a `callToAction` (the common
+ * 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;">
@@ -275,57 +215,63 @@ function renderChatDots(): { html: string; text: string[] } {
   return { html, text: ["⋮".padStart(center)] };
 }
 
-// =============================================================================
-// Chat unit
-// =============================================================================
-
 /**
- * Lay out one or more chat items — message bubbles and/or CTA buttons — as a
- * single block: a rule above and below (the real-chat "unit"), the items
+ * Lay out a chat unit's items — bubbles and/or CTA buttons — as a single
+ * rendered thing: a rule above and below (the real-chat "unit"), the items
  * between. The plain-text rule spans the widest line; a blank line follows the
- * top rule and the last item hugs the bottom rule. Continuation dots
- * (`chatDots`) sit above the CTA they precede, centered over the box.
+ * top rule and the last item hugs the bottom rule. Continuation dots sit above
+ * the CTA they precede, centered over the box.
  */
-export function chatUnit(...items: ChatItem[]): Block {
+export function renderChatUnit(items: ChatUnitItem[]): {
+  html: string;
+  text: string;
+} {
   const parts: { html: string; text: string[] }[] = [];
   items.forEach((item, i) => {
-    if (item.role === "dots") {
+    if (item.type === "continuation") {
       // Dots immediately before a CTA render with it (centered over the box);
       // otherwise fall back to channel-centered standalone dots.
-      if (items[i + 1]?.role !== "cta") parts.push(renderChatDots());
+      if (items[i + 1]?.type !== "callToAction") parts.push(renderChatDots());
       return;
     }
-    if (item.role === "cta") {
+    if (item.type === "callToAction") {
       // Mirror the side of the nearest preceding message (skip any dots between),
       // so the CTA sits under the bubble it belongs to — right under a user.
       let j = i - 1;
-      while (j >= 0 && items[j].role === "dots") j--;
-      const align = items[j]?.role === "user" ? "right" : "left";
-      parts.push(renderChatCta(item.cta, align, items[i - 1]?.role === "dots"));
+      while (j >= 0 && items[j].type === "continuation") j--;
+      const prev = items[j];
+      const align =
+        prev?.type === "message" && prev.role === "user" ? "right" : "left";
+      parts.push(
+        renderChatCta(item, align, items[i - 1]?.type === "continuation"),
+      );
       return;
     }
     // A bubble directly above a CTA or continuation dots gets a tighter 16px
     // gap; else 24px.
-    const next = items[i + 1]?.role;
+    const next = items[i + 1]?.type;
     const margin =
-      next === "cta" || next === "dots" ? "0 0 16px 0" : "0 0 24px 0";
+      next === "callToAction" || next === "continuation"
+        ? "0 0 16px 0"
+        : "0 0 24px 0";
     parts.push(renderBubble(item, margin));
   });
+
   const width = parts
-    .flatMap((b) => b.text)
+    .flatMap((part) => part.text)
     .reduce((w, l) => Math.max(w, l.length), 0);
   const rule = "_".repeat(width);
 
   const html = [
     chatRuleHtml("top"),
-    ...parts.map((b) => b.html),
+    ...parts.map((part) => part.html),
     chatRuleHtml("bottom"),
   ].join("\n");
 
   const text =
     `${rule}\n\n` +
-    parts.map((b) => b.text.join("\n")).join("\n\n") +
+    parts.map((part) => part.text.join("\n")).join("\n\n") +
     `\n${rule}`;
 
-  return { html, text, spacing: "normal" };
+  return { html, text };
 }

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

@@ -0,0 +1,47 @@
+/**
+ * Email channel constants — the styling vocabulary and the one link in it
+ * (ADR-CONTRACTS-086). `EMAIL_FROM` (SES envelope) is infra and stays in the
+ * backend.
+ *
+ * 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
+ * on every channel and renderers read it from `context.brand`.
+ */
+
+// =============================================================================
+// Branding
+// =============================================================================
+
+/** Monospace font stack for HTML emails. */
+const MONO_FONT_STACK =
+  "'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace";
+
+/** The `companysemantics.ai` link under every signature. */
+export const COMPANY_URL = "https://companysemantics.ai";
+
+// =============================================================================
+// Styling
+// =============================================================================
+
+/** The `font-family` declaration every element carries. */
+export const MONO = `font-family: ${MONO_FONT_STACK};`;
+
+/**
+ * The single font size for every email element (HTML). Plain text is monospace
+ * so it carries no size — this keeps one visual size across both surfaces.
+ */
+export const FONT_SIZE = "13px";
+
+/**
+ * The gap AFTER a rendered line: `"normal"` is a blank line in plain text,
+ * anything else is none.
+ */
+export type Spacing = "normal" | "tight" | "none";
+
+/** The HTML margin each `Spacing` maps to. */
+export const SPACING: Record<Spacing, string> = {
+  normal: "0 0 20px 0",
+  tight: "0 0 4px 0",
+  none: "0",
+};

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

@@ -0,0 +1,63 @@
+/**
+ * The `>> LABEL <<` button — email's answer to a `callToAction`.
+ *
+ * Moved verbatim from the deleted `src/email/render/blocks` (ADR-CONTRACTS-086). It
+ * lives in its own module because two callers need it: a standalone
+ * `callToAction` element (`./render`) and one inside a conversation
+ * (`./chat`), which place it at different margins.
+ *
+ * INVARIANTS:
+ * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits.
+ * - `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 { escapeHtml } from "./escape-html";
+
+/** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
+const CTA_BOX_PAD = 3;
+
+/** `>> LABEL <<` ASCII box (`*` corners): 3 lines, sized to the label. */
+function asciiCtaBox(label: string): string {
+  const pad = " ".repeat(CTA_BOX_PAD);
+  const inner = `${pad}>> ${label} <<${pad}`;
+  const border = `*${"-".repeat(inner.length)}*`;
+  return [border, `|${inner}|`, border].join("\n");
+}
+
+/**
+ * The bordered `>> LABEL <<` button (HTML table + ascii text), with `margin` on
+ * the table. A standalone element wraps it as its own line; a chat unit embeds
+ * it.
+ */
+export function ctaButton(
+  cta: CallToAction,
+  margin: string,
+): { 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};`;
+
+  // Underline only the label text (not the chevrons/spaces), and only when linked.
+  const labelHtml = href
+    ? `<span style="text-decoration: underline;">${escapeHtml(label)}</span>`
+    : escapeHtml(label);
+  const chevrons = `&gt;&gt; ${labelHtml} &lt;&lt;`;
+  const inner = href
+    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
+    : chevrons;
+
+  const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
+  <tr><td style="${tdStyle}">
+    ${inner}
+  </td></tr>
+</table>`;
+
+  const text = href ? `${asciiCtaBox(label)}\n\n${href}` : asciiCtaBox(label);
+
+  return { html, text };
+}

package/src/{email/render → notifications/renderers/email}/escape-html.ts

@@ -1,5 +1,9 @@
 /**
- * HTML escaping for email templates.
+ * HTML escaping for the email channel.
+ *
+ * Moved here from the deleted `src/email/render/escape-html`
+ * (ADR-CONTRACTS-086): escaping is one channel's concern, and the channel now
+ * owns it.
  *
  * INVARIANT: every user-controlled field in an HTML variant MUST pass through
  * this before interpolation (prevents XSS in email clients).