@company-semantics/contracts 51.3.0 → 52.1.0

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

@@ -1,58 +1,43 @@
 /**
  * Email's answer to a `chatUnit` — bubbles in HTML, box art in plain text.
  *
- * 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.
+ * The box art and the positioning both moved to `../ascii`: two channels that
+ * wrap at different points are two different messages, and Slack draws this
+ * same conversation. What stays here is the part that is genuinely email's —
+ * the three-column `<table>` skeleton, the margin recipes, and the `<hr>`
+ * bracket.
+ *
+ * The HTML and the text are two renderings of ONE plan. `planChatUnit` makes the
+ * alignment decisions once and this file walks them; it does not re-derive which
+ * side a CTA hangs on, because the day that derivation drifted from Slack's copy
+ * of it would be the day the two channels disagreed about the same conversation.
  *
  * INVARIANTS:
  * - 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.
+ * - Both surfaces truncate at the same point — `clampMessage` in `../ascii` is
+ *   the one truncation authority, and HTML and plain text both run content
+ *   through it.
  */
 
 import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
-
+import {
+  ruleAscii,
+  clampMessage,
+  flattenLines,
+  type MonospaceLine,
+  planChatUnit,
+  renderBubbleAscii,
+  renderChatCtaAscii,
+  renderChatDotsAscii,
+} from "../ascii";
+
+import { EMAIL_GEOMETRY } 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[] {
-  const lines: string[] = [];
-  let cur = "";
-  for (const word of text.split(/\s+/).filter(Boolean)) {
-    let w = word;
-    while (w.length > width) {
-      if (cur) {
-        lines.push(cur);
-        cur = "";
-      }
-      lines.push(w.slice(0, width));
-      w = w.slice(width);
-    }
-    if (!cur) cur = w;
-    else if (cur.length + 1 + w.length <= width) cur += ` ${w}`;
-    else {
-      lines.push(cur);
-      cur = w;
-    }
-  }
-  if (cur) lines.push(cur);
-  return lines.length ? lines : [""];
-}
-
-/** Chat message truncation budget: at most MAX_MESSAGE_LINES lines of MESSAGE_WIDTH chars. */
-const MAX_MESSAGE_LINES = 3;
-const MESSAGE_WIDTH = 36;
-/** Plain-text left gutter (7 cols) reserved for the avatar on both sides, so the
- * 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).
@@ -64,25 +49,10 @@ const CHAT_INDENT = "       ";
  */
 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);
-  if (lines.length <= maxLines) return lines;
-  const kept = lines.slice(0, maxLines);
-  const last = kept[maxLines - 1];
-  kept[maxLines - 1] =
-    (last.length > width - 3 ? last.slice(0, width - 3).trimEnd() : last) +
-    "...";
-  return kept;
-}
-
-/**
- * The one truncation authority: clamp a raw message to MAX_MESSAGE_LINES ×
- * 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(" ");
+/** One part of the unit, drawn on both surfaces. */
+interface ChatPartRender {
+  html: string;
+  text: MonospaceLine[];
 }
 
 /** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
@@ -98,11 +68,12 @@ function chatRuleHtml(position: "top" | "bottom"): string {
  * 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(
-  turn: ChatTurn,
-  row: ChatRow,
-): { html: string; text: string[] } {
-  const clamped = clampMessage(turn.text);
+function renderBubble(turn: ChatTurn, row: ChatRow): ChatPartRender {
+  const clamped = clampMessage(
+    turn.text,
+    EMAIL_GEOMETRY.messageWidth,
+    EMAIL_GEOMETRY.maxMessageLines,
+  );
   const isUser = turn.role === "user";
 
   // Each side draws its own avatar and hides the other's, which is what reserves
@@ -132,31 +103,9 @@ function renderBubble(
   </tr>${attributionRow}
 </table>`;
 
-  const border = "─".repeat(MESSAGE_WIDTH + 2);
-  const lines = wrapText(clamped, MESSAGE_WIDTH);
-  const body = lines.map(
-    (line) =>
-      `${CHAT_INDENT}│ ${isUser ? line.padStart(MESSAGE_WIDTH) : line.padEnd(MESSAGE_WIDTH)} │`,
-  );
-  // Avatar beside the last message line (one row up from the bottom border).
-  const last = body.length - 1;
-  if (isUser) body[last] += "  (•̀_ರ╮)";
-  else body[last] = `[c_S]  ${body[last].slice(CHAT_INDENT.length)}`;
-
-  const box = [
-    `${CHAT_INDENT}┌${border}┐`,
-    ...body,
-    `${CHAT_INDENT}└${border}┘`,
-  ];
-  if (isUser && turn.from) {
-    box.push(turn.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
-  }
-  return { html, text: box };
+  return { html, text: renderBubbleAscii(turn, EMAIL_GEOMETRY) };
 }
 
-/** The right-edge column the plain-text CTA/dots align to under a user bubble. */
-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 {
@@ -174,8 +123,8 @@ function renderChatCta(
   cta: CallToAction,
   align: "left" | "right",
   withDots: boolean,
-): { html: string; text: string[] } {
-  const { html: btnHtml, text: btnText } = ctaButton(cta, "none");
+): ChatPartRender {
+  const { html: btnHtml } = 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 ${styleClass("cta-stack")}>${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
@@ -187,26 +136,10 @@ function renderChatCta(
   </tr>
 </table>`;
 
-  // Right-align to the message box's right edge (under a user bubble); else the
-  // left avatar gutter.
-  const btnLines = btnText
-    .split("\n")
-    .map((l) =>
-      !l
-        ? l
-        : align === "right"
-          ? l.padStart(CHAT_RIGHT_EDGE)
-          : `${CHAT_INDENT}${l}`,
-    );
-  if (!withDots) return { html, text: btnLines };
-
-  // Center "⋮" over the ascii box (its first line spans the full box width).
-  const boxWidth = btnText.split("\n")[0].length;
-  const dotsCol =
-    align === "right"
-      ? CHAT_RIGHT_EDGE - Math.floor(boxWidth / 2)
-      : CHAT_INDENT.length + Math.ceil(boxWidth / 2);
-  return { html, text: ["⋮".padStart(dotsCol), "", ...btnLines] };
+  return {
+    html,
+    text: renderChatCtaAscii(cta, align, withDots, EMAIL_GEOMETRY),
+  };
 }
 
 /**
@@ -214,7 +147,7 @@ function renderChatCta(
  * 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[] } {
+function renderChatDots(): ChatPartRender {
   const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-16")}>
   <tr>
     <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
@@ -222,9 +155,7 @@ function renderChatDots(): { html: string; text: string[] } {
     <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
 </table>`;
-  // Center the "⋮" over the message box (avatar gutter + box width + borders).
-  const center = Math.round(CHAT_RIGHT_EDGE / 2);
-  return { html, text: ["⋮".padStart(center)] };
+  return { html, text: renderChatDotsAscii(EMAIL_GEOMETRY) };
 }
 
 /**
@@ -238,41 +169,26 @@ export function renderChatUnit(items: ChatUnitItem[]): {
   html: string;
   text: string;
 } {
-  const parts: { html: string; text: string[] }[] = [];
-  items.forEach((item, i) => {
-    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]?.type !== "callToAction") parts.push(renderChatDots());
-      return;
-    }
-    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].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;
+  const parts = planChatUnit(items).map((part): ChatPartRender => {
+    switch (part.kind) {
+      case "dots":
+        return renderChatDots();
+      case "cta":
+        return renderChatCta(part.cta, part.align, part.withDots);
+      case "bubble":
+        return renderBubble(
+          part.turn,
+          part.tight ? "chat-row-16" : "chat-row-24",
+        );
     }
-    // A bubble directly above a CTA or continuation dots gets a tighter 16px
-    // gap; else 24px.
-    const next = items[i + 1]?.type;
-    const row: ChatRow =
-      next === "callToAction" || next === "continuation"
-        ? "chat-row-16"
-        : "chat-row-24";
-    parts.push(renderBubble(item, row));
   });
 
-  const width = parts
-    .flatMap((part) => part.text)
-    .reduce((w, l) => Math.max(w, l.length), 0);
-  const rule = "_".repeat(width);
+  const rule = flattenLines([
+    ruleAscii(
+      parts.flatMap((part) => part.text),
+      EMAIL_GEOMETRY,
+    ),
+  ]);
 
   const html = [
     chatRuleHtml("top"),
@@ -282,7 +198,7 @@ export function renderChatUnit(items: ChatUnitItem[]): {
 
   const text =
     `${rule}\n\n` +
-    parts.map((part) => part.text.join("\n")).join("\n\n") +
+    parts.map((part) => flattenLines(part.text)).join("\n\n") +
     `\n${rule}`;
 
   return { html, text };

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

@@ -13,6 +13,9 @@
  * on every channel and renderers read it from `context.brand`.
  */
 
+import { geometryFor } from "../ascii";
+import { MONOSPACE_COLUMNS } from "../layout";
+
 // =============================================================================
 // Branding
 // =============================================================================
@@ -21,8 +24,20 @@
 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";
+/**
+ * Every derived monospace measurement of the plain-text surface.
+ *
+ * The budget itself is `../layout.ts`'s, not email's: Slack draws the same box
+ * art, and a width only one channel honoured would put the two back out of step.
+ */
+export const EMAIL_GEOMETRY = geometryFor(MONOSPACE_COLUMNS);
+
+/**
+ * Re-exported from `../brand.ts`, where it moved when Slack started signing with
+ * it too. Kept named here so this channel's modules still import their constants
+ * from one place.
+ */
+export { COMPANY_URL } from "../brand";
 
 // =============================================================================
 // Styling

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

@@ -16,13 +16,12 @@
 
 import type { CallToAction } from "../../content";
 
-import { CTA_PAD, type Spacing } from "./constants";
+import { flattenLines, renderCtaAscii } from "../ascii";
+
+import { CTA_PAD, EMAIL_GEOMETRY, type Spacing } from "./constants";
 import { escapeHtml } from "./escape-html";
 import { styleClass } from "./styles";
 
-/** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
-const CTA_BOX_PAD = 3;
-
 /**
  * Outlook's answer to a full-box click target.
  *
@@ -49,14 +48,6 @@ const CTA_BOX_PAD = 3;
 export const MSO_CTA_STYLE = `.cs-cta td { padding: ${CTA_PAD} !important; }
 .cs-cta a { padding: 0 !important; }`;
 
-/** `>> 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
@@ -107,7 +98,11 @@ export function ctaButton(
   </td></tr>
 </table>`;
 
-  const text = href ? `${asciiCtaBox(label)}\n\n${href}` : asciiCtaBox(label);
+  // The ascii form — box, and the destination beneath it when there is one — is
+  // drawn by `../ascii` so Slack draws the same box. This surface has no way to
+  // carry a link inline, so it flattens the href run to its bare URL, which is
+  // exactly what a `text/plain` body can say.
+  const text = flattenLines(renderCtaAscii(cta, EMAIL_GEOMETRY));
 
   return { html, text };
 }

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

@@ -45,6 +45,9 @@ import type {
 } from "../../content";
 import type { RenderContext } from "../../context";
 
+import { flattenLines, signatureLines, wrapText } from "../ascii";
+import { MONOSPACE_COLUMNS } from "../layout";
+
 import { COMPANY_URL, type Spacing } from "./constants";
 import { renderChatUnit } from "./chat";
 import { ctaButton } from "./cta";
@@ -52,6 +55,25 @@ import { escapeHtml } from "./escape-html";
 import type { EmailLine } from "./shells";
 import { styleClass } from "./styles";
 
+/**
+ * Wrap prose to the column budget — on the PLAIN-TEXT surface only.
+ *
+ * The two surfaces need opposite things from the same sentence. HTML reflows to
+ * whatever width the client gives it, so hard-wrapping the markup would fight
+ * the client and leave ragged breaks at every other width; plain text has no
+ * reflow at all, so an unwrapped sentence is one long line a phone can only show
+ * by scrolling sideways. So this touches `text` and never `html`, and one `<p>`
+ * stays one `<p>` however many physical lines its text becomes.
+ *
+ * Prose only. Key/value rows, the signature's URL and a CTA's label are atomic
+ * (`../layout.ts`) and are never routed through here — breaking a device string
+ * or a one-time code across lines would corrupt the thing the notification
+ * exists to deliver.
+ */
+function wrapProse(line: string): string {
+  return wrapText(line, MONOSPACE_COLUMNS).join("\n");
+}
+
 /** One `<p>` — the primitive every prose-ish element is built from. */
 function paragraph(html: string, text: string, spacing: Spacing): EmailLine {
   return {
@@ -95,7 +117,9 @@ function signatureLine(signer: string, year: number): EmailLine {
   const line = `ⓒ ${year} • ${signer}`;
   return {
     html: `<p ${styleClass("p-none")}><br><br><span ${styleClass("eom", "faint")}>/* EOM */</span><br>${escapeHtml(line)}<br><a href="${escapeHtml(COMPANY_URL)}" target="_blank" rel="noopener noreferrer" ${styleClass("signature-link", "link")}>${escapeHtml(COMPANY_URL)}</a></p>`,
-    text: `\n\n/* EOM */\n${line}\n${COMPANY_URL}`,
+    // The text form is drawn by `../ascii` so Slack signs identically; the two
+    // leading blank lines are this surface's own spacing and stay here.
+    text: `\n\n${flattenLines(signatureLines(signer, year, COMPANY_URL))}`,
     spacing: "none",
   };
 }
@@ -116,7 +140,7 @@ export function renderElement(
       const text = element.recipientName
         ? `Hi ${element.recipientName},`
         : "Hi there,";
-      return [paragraph(escapeHtml(text), text, trailing)];
+      return [paragraph(escapeHtml(text), wrapProse(text), trailing)];
     }
 
     case "body":
@@ -125,7 +149,7 @@ export function renderElement(
       return spaced(
         element.text.split("\n").map((line) => ({
           html: escapeHtml(line),
-          text: line,
+          text: wrapProse(line),
         })),
         trailing,
       );
@@ -168,7 +192,7 @@ export function renderElement(
       return [
         paragraph(
           element.lines.map(escapeHtml).join("<br>"),
-          element.lines.join("\n"),
+          element.lines.map(wrapProse).join("\n"),
           trailing,
         ),
       ];
@@ -201,7 +225,7 @@ export function renderElement(
       return spaced(
         element.items.map((item, i) => {
           const text = `${element.ordered ? `${i + 1}.` : "•"} ${item}`;
-          return { html: escapeHtml(text), text };
+          return { html: escapeHtml(text), text: wrapProse(text) };
         }),
         trailing,
       );

package/src/notifications/renderers/layout.ts

@@ -0,0 +1,31 @@
+/**
+ * The column budget every monospace surface draws inside.
+ *
+ * One number, shared by the channels that draw in a fixed-width face: email's
+ * `text/plain` body and Slack's `rich_text_preformatted` blocks. It lives above
+ * both because a budget only one channel honours is not a budget.
+ *
+ * **Why it is this narrow.** The surfaces are read on phones. A monospace block
+ * that overflows its container does not reflow — it scrolls sideways, or gets
+ * cut. So the budget is set by the narrowest surface we care about rather than
+ * by what a desktop mail client could show, and email accepts the stricter
+ * number even though it could afford more. Identical geometry across channels
+ * is worth more than the extra columns.
+ *
+ * **What it binds.** Lines the renderers GENERATE — box borders, bubble frames,
+ * rules, padding, and prose they wrap themselves.
+ *
+ * **What it does not bind.** Atomic content: URLs, one-time codes, identifiers,
+ * filenames, tokens, and key/value cell values. These may exceed the budget and
+ * must NEVER be broken to satisfy it. A newline inserted into an OTP or a URL is
+ * a correctness bug wearing a layout costume, and no layout invariant is worth
+ * one. `renderers/ascii/README.md` states the rule; the layout tests enforce the
+ * half of it that can be enforced.
+ *
+ * **What a column is.** A JavaScript string character — see
+ * `./ascii/geometry.ts`, which declines to claim Unicode terminal-cell precision
+ * and says why.
+ */
+
+/** Characters of generated monospace layout per line. */
+export const MONOSPACE_COLUMNS = 48;