@company-semantics/contracts 30.0.0 → 32.0.0

package/src/email/render/__tests__/render-snapshot.test.ts

@@ -58,41 +58,45 @@ add("org.invite", "Admin", {
   orgName: "Acme Corp",
   role: "admin",
   acceptUrl: `${APP}/invite/abc123`,
-  expiresInDays: 7,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 add("org.invite", "Member", {
   inviterName: "Alex Rivera",
   orgName: "Acme Corp",
   role: "member",
   acceptUrl: `${APP}/invite/def456`,
-  expiresInDays: 7,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",
   recipientName: "Sam Chen",
+  orgName: "Acme Corp",
   unitName: "Platform Engineering",
   roleLabel: "Unit owner",
   ctaUrl: `${APP}/org/unit/42`,
   message: "Welcome aboard — glad to have you owning this team.",
 });
-add("org.unit_owner_granted", "Delegate, no message", {
+add("org.unit_owner_granted", "Delegate with expiry", {
   granterName: "Jordan Lee",
+  orgName: "Acme Corp",
   unitName: "Platform Engineering",
   roleLabel: "Delegate",
   ctaUrl: `${APP}/org/unit/42`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
-add("org.ownership_transfer", "With note", {
+add("org.ownership_transfer", "With note + from", {
   orgName: "Acme Corp",
   acceptUrl: `${APP}/owner-transfer/accept/tok123`,
-  expiresInDays: 14,
+  expiresAt: "2026-06-13T00:00:00.000Z",
   note: "Handing this over as I move to an advisory role.",
+  fromName: "Jordan Lee",
 });
-add("org.ownership_transfer", "No note", {
+add("org.ownership_transfer", "No note (admin)", {
   orgName: "Acme Corp",
   acceptUrl: `${APP}/owner-transfer/accept/tok456`,
-  expiresInDays: 14,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
 add("org.ownership_transfer_completed", "Default", {

package/src/email/render/auth-otp.ts

@@ -10,8 +10,11 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  ctaBox,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   footer,
+  greeting,
   keyValue,
   paragraph,
   signature,
@@ -32,9 +35,13 @@ export function renderAuthOtp(
   const { otp, expiresInMinutes, requestIp, userAgent } = payload;
 
   const blocks: Block[] = [
-    paragraph("Copy/paste code in login form:"),
-    ctaBox({ label: otp, variant: "code" }),
-    keyValue("Status", "VALID"),
+    greeting(),
+    paragraph("A login code was requested."),
+    chatUnit(
+      chatAssistant("Copy + paste this code in the login form."),
+      chatCta({ label: otp }),
+    ),
+    keyValue("Status", "Valid"),
     keyValue(
       "Expires in",
       `${expiresInMinutes} ${expiresInMinutes === 1 ? "minute" : "minutes"}`,
@@ -55,10 +62,10 @@ export function renderAuthOtp(
 
   blocks.push(
     footer(
-      `This code was generated to authorize a login to ${COMPANY_NAME}.`,
-      "It expires automatically and cannot be reused.",
+      `This login code was sent via ${COMPANY_NAME}.`,
+      "If this wasn't you, no action is required.",
+      "none",
     ),
-    paragraph("If this wasn't you, no action is required."),
     signature(),
   );
 

package/src/email/render/blocks.ts

@@ -8,7 +8,8 @@
  * text, across the backend (real sends) and the app (Ladle preview).
  *
  * INVARIANTS:
- * - Pure functions, no side effects.
+ * - Pure functions, no side effects — except `signature()`, which reads the
+ *   current year (`new Date().getFullYear()`) for the copyright line.
  * - Components escape their own content; templates pass raw text (+ `bold(...)`
  *   for inline emphasis). No template hand-writes markup or raw strings.
  */
@@ -43,9 +44,17 @@ export interface Inline {
 /** Paragraph content: raw string(s) (auto-escaped for HTML) and/or `bold(...)`. */
 export type InlineContent = string | Inline | Array<string | Inline>;
 
-/** Bold inline emphasis (plain in text). */
+/** Inline emphasis segment. Emphasis is currently visually flat — it renders
+ * plain (no bold) in both surfaces; the seam is kept so all inline emphasis can
+ * be restyled in one place. */
 export function bold(s: string): Inline {
-  return { html: `<b>${escapeHtml(s)}</b>`, text: s };
+  return { html: escapeHtml(s), text: s };
+}
+
+/** Title-case a display value — capitalize the first letter of each word, e.g. a
+ * role like "admin" → "Admin". Leaves already-capitalized letters untouched. */
+export function titleCase(s: string): string {
+  return s.replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /** Normalize a segment: a raw string is escaped for HTML, passed through for text. */
@@ -83,7 +92,9 @@ export function htmlShell(blocks: Block[]): string {
 <html lang="en">
 <head><meta charset="UTF-8"></head>
 <body style="${MONO} color: #1a1a1a; margin: 0; padding: 0;">
+<div style="max-width: 520px; margin: 0 auto;">
 ${inner}
+</div>
 </body>
 </html>`;
 }
@@ -120,9 +131,30 @@ export function paragraph(
   };
 }
 
-/** "Hi Name," / "Hi," greeting. */
+/** "Hi Name," greeting; falls back to "Hi there," when the name is unknown. */
 export function greeting(recipientName?: string): Block {
-  return paragraph(recipientName ? `Hi ${recipientName},` : "Hi,");
+  return paragraph(recipientName ? `Hi ${recipientName},` : "Hi there,");
+}
+
+/** Security banner — the "WARNING" wordmark, sits atop security emails. */
+export function security(): Block {
+  return paragraph("🆆🅰🆁🅽🅸🅽🅶");
+}
+
+/**
+ * Format an ISO timestamp as "Jun 13, 2026". Pinned to en-US + UTC so the
+ * output is locale-/timezone-independent and render snapshots stay
+ * deterministic. Returns the raw input unchanged if it is not a parseable date.
+ */
+export function formatExpiry(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    timeZone: "UTC",
+  });
 }
 
 /** "Label: **value**" key/value row (value bold in HTML; tight by default). */
@@ -152,12 +184,16 @@ export function footer(
 }
 
 /**
- * Trailing sign-off — the company (or custom `signer`) name.
+ * Trailing sign-off — a leading blank line, the `---` rule, then the company
+ * (or custom `signer`) name. Owns the blank above the rule so every sign-off is
+ * spaced identically; the block before it carries no trailing gap.
  */
 export function signature(signer: string = COMPANY_NAME): Block {
+  const line = `ⓒ ${new Date().getFullYear()} • ${signer}`;
+  const url = "https://companysemantics.ai";
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};">${escapeHtml(signer)}</p>`,
-    text: `---\n${signer}`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};"><br><br><span style="color: #bbb;">/* EOM */</span><br>${escapeHtml(line)}<br><a href="${url}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(url)}</a></p>`,
+    text: `\n\n/* EOM */\n${line}\n${url}`,
     spacing: "none",
   };
 }
@@ -173,56 +209,19 @@ export const ACCESS_PHRASE: Record<"editor" | "commenter" | "viewer", string> =
     viewer: "can view",
   };
 
-/** Centered continuation dots separator (chat-shared). */
-export function chatDots(): Block {
-  return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: 0 0 16px 0; max-width: 320px; text-align: center;">⋮</p>`,
-    text: "                  ⋮",
-    spacing: "normal",
-  };
-}
-
 // =============================================================================
 // CTA box
 // =============================================================================
 
-/** Options for the `>> LABEL <<` call-to-action box. */
+/** Options for the `>> LABEL <<` call-to-action box. Styling is component-owned
+ * (the only allowable UI is the component) — callers supply only content. */
 export interface CtaBoxOptions {
   /** Text between the chevrons (already display-safe). */
   label: string;
   /** When present, the label links to this URL (and the URL rides under the
    * plain-text box). */
   href?: string;
-  /** Visual kind. `"action"` = link CTA (default); `"code"` = copy/paste code
-   * box (square corners, letter-spaced). */
-  variant?: "action" | "code";
-}
-
-/** Component-owned styling per CTA variant. Templates supply only `label`/`href`/
- * `variant` — the only allowable UI is the component, so all CSS lives here,
- * never at the call site. */
-interface CtaVariantStyle {
-  padding: string;
-  fontSize: string;
-  maxWidth?: string;
-  square: boolean;
-  letterSpacing?: string;
-}
-const CTA_VARIANTS: Record<"action" | "code", CtaVariantStyle> = {
-  action: {
-    padding: "16px 24px",
-    fontSize: FONT_SIZE,
-    maxWidth: "220px",
-    square: false,
-  },
-  code: {
-    padding: "16px 24px",
-    fontSize: FONT_SIZE,
-    maxWidth: "220px",
-    square: true,
-    letterSpacing: "4px",
-  },
-};
+}
 
 /** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
 const CTA_BOX_PAD = 3;
@@ -235,26 +234,24 @@ function asciiCtaBox(label: string): string {
   return [border, `|${inner}|`, border].join("\n");
 }
 
-/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
- * `href` is given, HTML links the label and plain text prints the URL below. */
-export function ctaBox(opts: CtaBoxOptions): Block {
-  const { label, href, variant = "action" } = opts;
-  const { padding, fontSize, maxWidth, square, letterSpacing } =
-    CTA_VARIANTS[variant];
-
-  const tableStyle =
-    `border: 2px solid #1a1a1a;` +
-    (square ? ` border-radius: 0;` : ``) +
-    ` margin: 0 0 20px 0;` +
-    (maxWidth ? ` max-width: ${maxWidth};` : ``);
-
-  const tdStyle =
-    `padding: ${padding}; text-align: center; ${MONO} font-size: ${fontSize};` +
-    (letterSpacing ? ` letter-spacing: ${letterSpacing};` : ``);
-
-  const chevrons = `<b>&gt;&gt; ${escapeHtml(label)} &lt;&lt;</b>`;
+/** The bordered `>> LABEL <<` button (HTML table + ascii text), with `margin` on
+ * the table. `ctaBox` wraps it as a standalone block; a chat unit embeds it. */
+function ctaButton(
+  opts: CtaBoxOptions,
+  margin: string,
+): { html: string; text: string } {
+  const { label, href } = opts;
+
+  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: underline;">${chevrons}</a>`
+    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
     : chevrons;
 
   const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
@@ -265,6 +262,13 @@ export function ctaBox(opts: CtaBoxOptions): Block {
 
   const text = href ? `${asciiCtaBox(label)}\n\n${href}` : asciiCtaBox(label);
 
+  return { html, text };
+}
+
+/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
+ * `href` is given, HTML links the label and plain text prints the URL below. */
+export function ctaBox(opts: CtaBoxOptions): Block {
+  const { html, text } = ctaButton(opts, "0 0 20px 0");
   return { html, text, spacing: "normal" };
 }
 
@@ -299,7 +303,10 @@ function wrapText(text: string, width: number): string[] {
 
 /** Chat message truncation budget: at most MAX_MESSAGE_LINES lines of MESSAGE_WIDTH chars. */
 const MAX_MESSAGE_LINES = 3;
-const MESSAGE_WIDTH = 35;
+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 = "       ";
 
 /** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
 function wrapClamped(text: string, width: number, maxLines: number): string[] {
@@ -322,59 +329,239 @@ function clampMessage(text: string): string {
   return wrapClamped(text, MESSAGE_WIDTH, MAX_MESSAGE_LINES).join(" ");
 }
 
+/** 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" };
+}
+
+/** 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};">`;
+}
+
 /**
- * Right-aligned user chat message. Truncated by clampMessage. In plain text the
- * face sits beside the last message line. When `from` is given (the sender's
- * name) it renders as an attribution below, right-aligned to the message's right
- * edge.
+ * Render one message 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.
  */
-export function chatUser(content: string, from?: string): Block {
-  const clamped = clampMessage(content);
-
-  const attributionRow = from
-    ? `
+function renderBubble(
+  msg: ChatMessage,
+  margin: string,
+): { html: string; text: string[] } {
+  const clamped = clampMessage(msg.text);
+  const isUser = msg.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; ";
+
+  const attributionRow =
+    isUser && msg.from
+      ? `
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; color: #888; text-align: right; padding-top: 4px;">${escapeHtml(from)}</td>
+    <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></td>
   </tr>`
-    : "";
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="margin: 0 0 16px 0;">
+      : "";
+
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: ${margin};">
   <tr>
-    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 0 12px; padding: 10px 14px; min-width: 280px; text-align: right; ${MONO} font-size: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom;">(•̀_ರ╮)</td>
+    <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>
+    </table></td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; ${kaomojiHidden}white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>${attributionRow}
 </table>`;
 
-  const border = "─".repeat(MESSAGE_WIDTH + 1);
+  const border = "─".repeat(MESSAGE_WIDTH + 2);
   const lines = wrapText(clamped, MESSAGE_WIDTH);
-  const body = lines.map((line) => `│${line.padStart(MESSAGE_WIDTH)} │`);
-  // Face beside the last message line (one row up from the bottom border).
-  body[body.length - 1] += "  (•̀_ರ╮)";
-  const box = [`┌${border}┐`, ...body, `└${border}┘`];
-  if (from) box.push(from.padStart(MESSAGE_WIDTH + 3));
+  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 && msg.from) {
+    box.push(msg.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
+  }
+  return { html, text: box };
+}
+
+/** 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;
 
-  return { html, text: box.join("\n"), spacing: "normal" };
+/** 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>`;
 }
 
-/** Left-aligned assistant chat message with `[c_S]` avatar; in plain text the
- * avatar sits beside the last message line (one row up from the bottom border). */
-export function chatAssistant(content: string): Block {
-  const clamped = clampMessage(content);
+/**
+ * A CTA button inside the chat stream — aligned to the side of the message it
+ * follows (`right` under a user bubble, `left` otherwise). Hidden avatar mirrors
+ * reserve both columns, so it sits in the message channel and never enters the
+ * kaomoji column. The button carries no margin; the row's 24px matches the bubbles.
+ * When `withDots`, continuation "⋮" render just above the button, centered over it.
+ */
+function renderChatCta(
+  cta: CtaBoxOptions,
+  align: "left" | "right",
+  withDots: boolean,
+): { html: string; text: string[] } {
+  const { html: btnHtml, text: btnText } = ctaButton(cta, "0");
+  // 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;">
+  <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>
+  </tr>
+</table>`;
 
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="margin: 16px 0;">
+  // 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] };
+}
+
+/**
+ * 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).
+ */
+function renderChatDots(): { html: string; text: string[] } {
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
   <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom;">[c_S]</td>
-    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 12px 0; padding: 10px 14px; min-width: 280px; ${MONO} font-size: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
+    <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>
   </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)] };
+}
 
-  const lineWidth = 36;
-  const lines = wrapText(clamped, lineWidth);
-  const top = "       ┌──────────────────────────────────────┐";
-  const bot = "       └──────────────────────────────────────┘";
-  const boxLines = lines.map((line) => `       │ ${line.padEnd(lineWidth)} │`);
-  // Avatar beside the last message line (one row up from the bottom border).
-  boxLines[boxLines.length - 1] = `[c_S]  ${boxLines[boxLines.length - 1].slice(7)}`;
+/**
+ * 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
+ * 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.
+ */
+export function chatUnit(...items: ChatItem[]): Block {
+  const parts: { html: string; text: string[] }[] = [];
+  items.forEach((item, i) => {
+    if (item.role === "dots") {
+      // 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());
+      return;
+    }
+    if (item.role === "cta") {
+      // 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"));
+      return;
+    }
+    // A bubble directly above a CTA or continuation dots gets a tighter 16px
+    // gap; else 24px.
+    const next = items[i + 1]?.role;
+    const margin =
+      next === "cta" || next === "dots" ? "0 0 16px 0" : "0 0 24px 0";
+    parts.push(renderBubble(item, margin));
+  });
+  const width = parts
+    .flatMap((b) => b.text)
+    .reduce((w, l) => Math.max(w, l.length), 0);
+  const rule = "_".repeat(width);
+
+  const html = [
+    chatRuleHtml("top"),
+    ...parts.map((b) => b.html),
+    chatRuleHtml("bottom"),
+  ].join("\n");
+
+  const text =
+    `${rule}\n\n` +
+    parts.map((b) => b.text.join("\n")).join("\n\n") +
+    `\n${rule}`;
 
-  return { html, text: [top, ...boxLines, bot].join("\n"), spacing: "normal" };
+  return { html, text, spacing: "normal" };
 }

package/src/email/render/chat-shared.ts

@@ -7,10 +7,12 @@ import type { EmailPayloads } from "../types";
 import {
   type Block,
   chatAssistant,
+  chatCta,
   chatDots,
+  chatUnit,
   chatUser,
-  ctaBox,
   footer,
+  greeting,
   NOTICE,
   paragraph,
   signature,
@@ -20,22 +22,18 @@ import { COMPANY_NAME } from "./constants";
 export type ChatSharedPayload = EmailPayloads["chat.shared"];
 
 export function renderChatShared(payload: ChatSharedPayload): Block[] {
-  const { chatTitle, shareUrl, previewText } = payload;
-
-  const blocks: Block[] = [
-    paragraph("A chat has been shared with you."),
-    chatUser(chatTitle),
-  ];
-
-  if (previewText) blocks.push(chatAssistant(previewText));
-
-  blocks.push(
-    chatDots(),
-    ctaBox({ label: "SEE MORE", href: shareUrl }),
-    footer(`This share was sent via ${COMPANY_NAME}.`),
-    paragraph(NOTICE, "tight"),
+  const { chatTitle, shareUrl, previewText, sharedByName } = payload;
+
+  return [
+    greeting(),
+    paragraph("A chat was shared with you."),
+    chatUnit(
+      chatUser(chatTitle, sharedByName),
+      ...(previewText ? [chatAssistant(previewText)] : []),
+      chatDots(),
+      chatCta({ label: "SEE MORE", href: shareUrl }),
+    ),
+    footer(`This share was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
-  );
-
-  return blocks;
+  ];
 }