@company-semantics/contracts 34.0.0 → 35.1.0

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

@@ -0,0 +1,78 @@
+# 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 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
+  `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,32 @@
+# notifications/renderers/email/\_\_tests\_\_/
+
+## Purpose
+
+Tests for the email channel (ADR-CONTRACTS-086).
+
+`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
+
+- 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.
+- 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__/render.test.ts

@@ -0,0 +1,188 @@
+/**
+ * The email renderer's behavioural rules (ADR-CONTRACTS-086) — the claims that
+ * hold no matter how the email is styled: it supports every element type, takes
+ * the subject from the content's title, takes the year and signer from context
+ * rather than a clock, restores the `:` the content model does not carry, and
+ * escapes user-controlled text.
+ *
+ * The MARKUP is not asserted here. `../../../__tests__/render-snapshot.test.ts`
+ * locks that, as a reviewable regenerable diff. Until ADR-CONTRACTS-087 this
+ * file also asserted every fixture byte-for-byte against the 32.0.0 golden, to
+ * prove the multi-channel generalisation moved no bytes; that proof shipped in
+ * 35.0.0 and was retired with the golden, because email design is now allowed to
+ * change and byte-equality to a deleted layer cannot survive it being exercised.
+ *
+ * There is no fake timer here, and that is the improvement being locked in: the
+ * year comes from `RenderContext`, so the fixtures' 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 {
+  FIXTURE_CLOCK,
+  NOTIFICATION_FIXTURES,
+  fixtureKey,
+} from "../../../__tests__/fixtures";
+import { emailRenderer } from "../index";
+
+/**
+ * The fixtures' 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 is simply a value.
+ */
+const FIXTURE_CONTEXT: RenderContext = {
+  brand: {
+    name: "Company Semantics",
+    copyrightYear: new Date(FIXTURE_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, FIXTURE_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, FIXTURE_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, FIXTURE_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, FIXTURE_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",
+      },
+      FIXTURE_CONTEXT,
+    );
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT)).toEqual(
+      emailRenderer.render(content, FIXTURE_CONTEXT),
+    );
+  });
+
+  describe("renders every fixture", () => {
+    // Was a byte-for-byte assertion against the 32.0.0 golden until
+    // ADR-CONTRACTS-087 retired it. The markup itself is locked by
+    // `../../../__tests__/render-snapshot.test.ts`; what is worth proving HERE
+    // is narrower and survives a redesign — that every kind in the registry
+    // composes and renders through this channel at all, on both surfaces. A kind
+    // whose `compose` reaches for a field its payload lacks fails here, at the
+    // renderer, rather than in whichever consumer sends it first.
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      const key = fixtureKey(fixture.kind, fixture.name);
+      it(`${key}`, () => {
+        const definition = NOTIFICATION_DEFINITIONS[fixture.kind];
+        // `payload as never`: the fixture call sites are type-checked in the
+        // fixtures module; this only bridges compose's per-kind payload.
+        const content = definition.compose(
+          fixture.payload as never,
+          FIXTURE_CONTEXT,
+        );
+        const { subject, text, html } = emailRenderer.render(
+          content,
+          FIXTURE_CONTEXT,
+        );
+        expect(subject).toBeTruthy();
+        expect(text).toBeTruthy();
+        expect(html).toContain("<!DOCTYPE html>");
+      });
+    }
+  });
+});

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

@@ -1,32 +1,25 @@
 /**
- * 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. The box art is real output, and every column of it is locked by
+ *   `../../__tests__/render-snapshot.test.ts` — a stray space is a visibly
+ *   broken email, not a whitespace nit.
+ * - 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 +67,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 +82,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 +102,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 +137,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 +160,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 +200,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 +216,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,64 @@
+/**
+ * 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 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.
+ */
+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",
+};