@company-semantics/contracts 52.0.0 → 53.0.0

package/src/notifications/__tests__/monospace-budget.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Which lines of a REAL notification are allowed past the column budget.
+ *
+ * `../renderers/ascii/__tests__/layout.test.ts` proves the drawing functions
+ * keep their generated geometry inside the budget. That is the half that can be
+ * asserted outright. This is the other half, and it cannot be: once a
+ * notification is rendered, generated geometry and atomic content are one
+ * string, and no predicate can reliably tell a deliberately-unwrapped device
+ * string from a wrapper that failed.
+ *
+ * So this snapshots the exemption list instead. Every plain-text line that
+ * overhangs, across every kind and variant, in one reviewable place. The
+ * property being defended is not "nothing overhangs" — URLs and one-time codes
+ * must overhang rather than be broken (`../renderers/layout.ts`). It is that
+ * **nothing overhangs by accident**: a new entry here is a diff someone has to
+ * look at and agree with.
+ *
+ * If an entry appears that is ordinary prose, the wrapper has a bug. If one
+ * appears that is a URL, an identifier or a key/value row, that is the design
+ * working.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { renderToChannel } from "../render";
+import { emailRenderer } from "../renderers/email";
+import { MONOSPACE_COLUMNS } from "../renderers/layout";
+
+import { NOTIFICATION_FIXTURES } from "./fixtures";
+
+describe("monospace budget", () => {
+  it("overhangs only where content is atomic", () => {
+    const overhanging = new Set<string>();
+
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      const rendered = renderToChannel(
+        fixture.kind,
+        fixture.payload as never,
+        emailRenderer,
+      );
+      for (const line of rendered.text.split("\n")) {
+        if (line.length > MONOSPACE_COLUMNS) overhanging.add(line.trim());
+      }
+    }
+
+    expect([...overhanging].sort()).toMatchSnapshot();
+  });
+
+  it("wraps ordinary prose rather than letting it overhang", () => {
+    // The regression this pins: `body` used to reach the plain-text surface
+    // unwrapped, so a long sentence became one 176-character line that a phone
+    // could only show by scrolling sideways. Prose has no claim to the atomic
+    // exemption — it is precisely the thing a wrapper is for, and this fixture
+    // carries the longest body in the corpus.
+    const fixture = NOTIFICATION_FIXTURES.find(
+      (f) => f.kind === "org.unit_owner_granted",
+    );
+    if (!fixture) throw new Error("fixture for org.unit_owner_granted is gone");
+
+    const rendered = renderToChannel(
+      fixture.kind,
+      fixture.payload as never,
+      emailRenderer,
+    );
+
+    // A line that overhangs AND contains a space AND holds no URL is prose the
+    // wrapper failed to break.
+    const prose = rendered.text
+      .split("\n")
+      .filter((line) => line.length > MONOSPACE_COLUMNS)
+      .filter((line) => line.includes(" ") && !line.includes("://"));
+
+    expect(prose).toEqual([]);
+  });
+});

package/src/notifications/renderers/README.md

@@ -12,8 +12,12 @@ only place in this package that knows what a sentence looks like.
   whole layer" to one channel among several.
 - `sms/` — `Renderer<string>`, a non-functional placeholder. The poorest channel
   the vocabulary will meet: no markup, no images, no layout.
-- `slack/` — `Renderer<SlackMessage>`, a non-functional placeholder. A minimal
-  Block Kit tree.
+- `slack/` — `Renderer<SlackMessage>`, which renders but does not send. Its
+  narrative content is monospace, drawn by `ascii/` and set in
+  `rich_text_preformatted`; its controls are Slack's own native primitives.
+- `ascii/` — NOT a channel. The monospace layout layer both `email/`'s
+  `text/plain` surface and `slack/` draw with, so a conversation cannot come out
+  a column apart on the two. It implements no `Renderer`.
 
 A channel is added by writing a directory here — not by editing `../content.ts`,
 `../definition.ts` or any kind. That is the property the seam exists for, and the
@@ -27,8 +31,8 @@ intention into a fact. They are placeholders on purpose: they do not send, and
 their copy is invented rather than relocated. Their SHAPE is not provisional.
 
 Three channels now answer `supports` differently over one content that carries no
-channel tags — email declines nothing, slack declines `chatUnit`, sms also
-declines `heroImage` and `divider` — and `Out` is a record, then a string, then a
+channel tags — email and slack decline nothing, sms declines `heroImage`,
+`chatUnit` and `divider` — and `Out` is a record, then a string, then a
 different record. Those are this layer's two design claims, stated by real modules
 rather than by test doubles.
 

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

@@ -0,0 +1,75 @@
+# notifications/renderers/ascii/
+
+## Purpose
+
+The monospace layout layer: box art, word wrapping, and the chat unit's
+positioning decisions, shared by every channel that draws on a fixed-width
+surface.
+
+This is **not a renderer**. It implements no `Renderer`, answers no
+`NotificationContent`, and produces no channel's bytes. It draws, and the
+channels decide what the drawing becomes — `email/` flattens it into a
+`text/plain` body, `slack/` maps it onto `rich_text_preformatted` elements.
+
+It exists because the box art was trapped inside `../email/chat.ts` and
+`../email/cta.ts`. The moment a second channel wanted to draw a conversation,
+those columns were going to be copied — and two channels that wrap at different
+points are two different messages.
+
+| module        | what it holds                                                          |
+| ------------- | ---------------------------------------------------------------------- |
+| `runs.ts`     | `MonospaceRun` / `MonospaceLine` and the line helpers                  |
+| `geometry.ts` | the column budget and every measurement derived from it                |
+| `wrap.ts`     | `wrapText` / `wrapClamped` / `clampMessage` — the truncation authority |
+| `cta.ts`      | the `>> LABEL <<` box                                                  |
+| `chat.ts`     | `planChatUnit` (the layout plan) + the bubble, CTA and dots drawings   |
+
+## Runs, not strings
+
+A rendered line can contain a URL, and the channels disagree about what to do
+with one: email's text body prints it, Slack wants a `RichTextLink` so it stays
+clickable. So a line is runs — `text` or `link` — and flattening is the
+CALLER's choice, made at the surface that knows its own capabilities.
+
+Returning `string[]` would dissolve the href into a string and force Slack to go
+looking for it again with a regex. That is the hack this shape exists to prevent.
+
+## Invariants
+
+- **Pure.** Every column is real output, locked by
+  `../../__tests__/render-snapshot.test.ts`. A stray space is a visibly broken
+  email, not a whitespace nit.
+- **The run vocabulary stays dumb.** `MonospaceRun` carries text, links and line
+  boundaries — nothing else, ever. CTA-ness, warning-ness, chat turn, author,
+  role and alignment are function INPUTS. A run that learns what a CTA is has
+  started building a second notification model beside `../../content`, which is
+  the fusion ADR-CONTRACTS-086 undid.
+- **The budget binds generated geometry only.** Box borders, frames, rules,
+  padding and prose this layer wraps itself must fit `AsciiGeometry.columns`.
+  Atomic content — URLs, OTP codes, identifiers, tokens, cell values — MAY
+  exceed it and must never be broken to satisfy it. A line break inserted into a
+  one-time code is a correctness bug wearing a layout costume.
+- **One truncation authority.** `clampMessage` clamps every surface of a chat
+  unit, so they all truncate at the same point.
+- **A "column" is a JavaScript string character.** The decorative geometry is
+  ASCII, so characters and columns coincide there. Wrapped prose uses the same
+  string semantics and makes no claim to Unicode terminal-cell precision — a CJK
+  glyph or emoji occupying two cells is not modelled, deliberately, because
+  promising otherwise would be a false precision.
+
+## Public API
+
+- `geometryFor(columns)` → `AsciiGeometry`; `AVATAR`, `KAOMOJI`.
+- `MonospaceRun`, `MonospaceLine`, and `text` / `lineLength` / `blockWidth` /
+  `flattenLine` / `flattenLines` / `indentLine` / `padLineStart`.
+- `wrapText`, `wrapClamped`, `clampMessage`.
+- `renderCtaAscii`, `ctaBoxWidth`.
+- `planChatUnit` → `ChatPart[]`, plus `renderBubbleAscii`,
+  `renderChatCtaAscii`, `renderChatDotsAscii`, `chatRuleAscii`.
+
+## Dependencies
+
+- `../../content` — `CallToAction`, `ChatTurn`, `ChatUnitItem`. Types only; this
+  layer reads the vocabulary and never extends it.
+
+Nothing else. It knows no channel, no colour, no markup and no `Renderer`.

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

@@ -0,0 +1,39 @@
+# notifications/renderers/ascii/\_\_tests\_\_/
+
+## Purpose
+
+Tests for the monospace layout layer.
+
+`layout.test.ts` asserts the half of the column budget that CAN be asserted
+outright: every line these functions **generate** — box borders, bubble frames,
+rules, padding, wrapped prose — fits `AsciiGeometry.columns`. It asserts this
+against the drawing functions directly, because that is the only place where
+generated geometry and atomic content are still distinguishable.
+
+It also pins the layout decisions `planChatUnit` makes (which side a CTA hangs
+on, whether continuation dots fold into the CTA below them), since those are
+shared by every channel that draws a conversation and a change to them is a
+change to all of them at once.
+
+The other half of the budget — which lines a REAL notification is allowed to
+overhang with — is `../../../__tests__/monospace-budget.test.ts`. It has to be a
+snapshot rather than an assertion, and that file explains why.
+
+## Invariants
+
+- **Pathological input is the point.** A wrapper is easy to get right on "Hello".
+  The cases that matter are a 200-character unbroken word, a long URL, emoji,
+  combining characters, CJK, the empty string, and a CTA label sitting exactly on
+  the boundary. Adding a case is cheaper than the bug it would have caught.
+- **Atomic content is expected to overhang, and is asserted to.** The tests that
+  look like they are permitting a failure — an over-long CTA label making a wide
+  box, a long display name past the box edge — are pinning a deliberate rule from
+  `../../layout.ts`. Breaking a one-time code or a URL across lines to satisfy a
+  width check would corrupt the thing the notification exists to deliver.
+- **Geometry, not markup.** No test here asserts HTML or Block Kit. What a
+  channel makes of these lines belongs to that channel's tests.
+
+## Dependencies
+
+- `../index` — the layer under test.
+- `../../../content` — `ChatUnitItem` and friends, for building inputs.

package/src/notifications/renderers/ascii/__tests__/layout.test.ts

@@ -0,0 +1,228 @@
+/**
+ * The column budget, enforced where it is actually promised.
+ *
+ * The budget binds GENERATED geometry — box borders, bubble frames, rules,
+ * padding, and prose this layer wraps itself. So it is asserted here, against
+ * the drawing functions directly, rather than against a rendered notification
+ * where generated lines and atomic content are already mixed into one string and
+ * can no longer be told apart. `../../__tests__/monospace-budget.test.ts` covers
+ * the other half: which lines a real notification is allowed to overhang with.
+ *
+ * The pathological inputs are the point. A wrapper is easy to get right on
+ * "Hello" and easy to get wrong on a 200-character word, an empty string, or a
+ * label sitting exactly on the boundary.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { ChatUnitItem } from "../../../content";
+import {
+  ruleAscii,
+  geometryFor,
+  lineLength,
+  type MonospaceLine,
+  planChatUnit,
+  renderBubbleAscii,
+  renderChatCtaAscii,
+  renderChatDotsAscii,
+  renderCtaAscii,
+  wrapText,
+} from "../index";
+
+const COLUMNS = 40;
+const G = geometryFor(COLUMNS);
+
+/** The widest line, and the line itself, so a failure names the culprit. */
+function widest(lines: MonospaceLine[]): {
+  width: number;
+  line: MonospaceLine;
+} {
+  return lines.reduce(
+    (worst, line) =>
+      lineLength(line) > worst.width
+        ? { width: lineLength(line), line }
+        : worst,
+    { width: 0, line: [] as MonospaceLine },
+  );
+}
+
+const LONG_WORD = "A".repeat(200);
+const LONG_URL =
+  "https://app.companysemantics.ai/doc/handbook?request=req_456&from=notification";
+const EMOJI = "🎉 shipped 🚀 the 🧵 thing 🎊 today 🌟 and 🔥 again";
+const COMBINING = "é".repeat(30) + " " + "é".repeat(30);
+const CJK = "設計レビューのフィードバックをお願いします".repeat(3);
+
+describe("geometryFor", () => {
+  it("reserves BOTH avatar gutters, so a user bubble fits the budget too", () => {
+    // The recipient's avatar hangs outside the box on the right. Reserving only
+    // the left gutter is the bug this asserts against: it let a user bubble run
+    // nine columns past the budget while the assistant's stayed inside.
+    const bubble = renderBubbleAscii(
+      { type: "message", role: "user", text: "hello there" },
+      G,
+    );
+    expect(widest(bubble).width).toBeLessThanOrEqual(COLUMNS);
+  });
+
+  it("puts the box edge short of the budget by the reserved right avatar", () => {
+    expect(G.boxRight).toBeLessThan(G.columns);
+    expect(G.indent + G.messageWidth + 4).toBe(G.boxRight);
+  });
+
+  it("refuses a budget too small to draw its own frame", () => {
+    // Silently clamping would produce a plausible-looking box with content
+    // missing from it, which is worse than a thrown error at build time.
+    expect(() => geometryFor(8)).toThrow(RangeError);
+  });
+});
+
+describe("wrapText", () => {
+  it("hard-breaks a word longer than the width rather than overflowing", () => {
+    for (const line of wrapText(LONG_WORD, COLUMNS)) {
+      expect(line.length).toBeLessThanOrEqual(COLUMNS);
+    }
+  });
+
+  it("returns one empty line for empty input, not zero lines", () => {
+    // A body line that is empty is a blank line the reader sees; dropping it
+    // would silently close up the paragraph.
+    expect(wrapText("", COLUMNS)).toEqual([""]);
+  });
+
+  it("keeps a word that exactly fills the width on its own line", () => {
+    const exact = "B".repeat(COLUMNS);
+    expect(wrapText(exact, COLUMNS)).toEqual([exact]);
+  });
+});
+
+describe("bubble geometry stays inside the budget", () => {
+  const cases: Array<[string, string]> = [
+    ["a long unbroken word", LONG_WORD],
+    ["a long URL", LONG_URL],
+    ["emoji", EMOJI],
+    ["combining characters", COMBINING],
+    ["CJK", CJK],
+    ["empty", ""],
+    ["a single space", " "],
+    ["newlines", "one\ntwo\nthree"],
+  ];
+
+  for (const role of ["user", "assistant"] as const) {
+    for (const [name, text] of cases) {
+      it(`${role} · ${name}`, () => {
+        const lines = renderBubbleAscii({ type: "message", role, text }, G);
+        expect(widest(lines).width).toBeLessThanOrEqual(COLUMNS);
+      });
+    }
+  }
+
+  it("a long display name does not push the attribution past the box", () => {
+    const lines = renderBubbleAscii(
+      {
+        type: "message",
+        role: "user",
+        text: "hi",
+        from: "Bartholomew Fitzgerald-Montgomery III",
+      },
+      G,
+    );
+    // The name is atomic — it is a person's name and must not be broken — so it
+    // may overhang. What must NOT happen is the BOX growing to accommodate it.
+    const boxLines = lines.filter((line) => lineLength(line) <= COLUMNS);
+    expect(widest(boxLines).width).toBeLessThanOrEqual(COLUMNS);
+  });
+});
+
+describe("CTA geometry", () => {
+  it("draws a label that sits exactly on the boundary without overflowing", () => {
+    // The box adds 14 columns to the label (3 pad + '>> ' + ' <<' + 3 pad + 2
+    // borders), so this is the widest label that still fits.
+    const label = "C".repeat(COLUMNS - 14);
+    const lines = renderCtaAscii({ type: "callToAction", label }, G);
+    expect(widest(lines).width).toBe(COLUMNS);
+  });
+
+  it("lets an over-long label make a wide box rather than breaking the label", () => {
+    // A CTA label is atomic. Wrapping it would corrupt the payload when the
+    // label IS the payload, which is exactly the hrefless case.
+    const label = "D".repeat(60);
+    const lines = renderCtaAscii({ type: "callToAction", label }, G);
+    expect(widest(lines).width).toBeGreaterThan(COLUMNS);
+    expect(lines).toHaveLength(3);
+  });
+
+  it("carries the href as a link run, not as text", () => {
+    const lines = renderCtaAscii(
+      { type: "callToAction", label: "Accept", href: LONG_URL },
+      G,
+    );
+    const link = lines.at(-1)?.[0];
+    expect(link).toEqual({ type: "link", text: LONG_URL, href: LONG_URL });
+  });
+
+  it("prints no destination line when there is nothing to go to", () => {
+    // An OTP code is a box with no link in it. A URL underneath would be a
+    // fabricated destination.
+    const lines = renderCtaAscii({ type: "callToAction", label: "123456" }, G);
+    expect(lines).toHaveLength(3);
+  });
+});
+
+describe("chat unit rules", () => {
+  const withCta: ChatUnitItem[] = [
+    { type: "message", role: "user", text: "share this" },
+    { type: "callToAction", label: "SEE MORE", href: LONG_URL },
+  ];
+
+  it("caps the rule at the budget when an atomic URL overhangs", () => {
+    const parts = planChatUnit(withCta);
+    const drawn = parts.flatMap((part) =>
+      part.kind === "bubble"
+        ? renderBubbleAscii(part.turn, G)
+        : part.kind === "cta"
+          ? renderChatCtaAscii(part.cta, part.align, part.withDots, G)
+          : renderChatDotsAscii(G),
+    );
+    // The URL is allowed past the edge; the rule is not allowed to follow it.
+    expect(widest(drawn).width).toBeGreaterThan(COLUMNS);
+    expect(lineLength(ruleAscii(drawn, G))).toBe(COLUMNS);
+  });
+
+  it("draws a short rule for a short unit rather than always spanning the budget", () => {
+    const short = renderBubbleAscii(
+      { type: "message", role: "assistant", text: "ok" },
+      G,
+    );
+    expect(lineLength(ruleAscii(short, G))).toBeLessThan(COLUMNS);
+  });
+});
+
+describe("planChatUnit", () => {
+  it("folds continuation dots into the CTA that follows them", () => {
+    const parts = planChatUnit([
+      { type: "message", role: "user", text: "hi" },
+      { type: "continuation" },
+      { type: "callToAction", label: "GO", href: "https://example.com" },
+    ]);
+    expect(parts.map((p) => p.kind)).toEqual(["bubble", "cta"]);
+    expect(parts[1]).toMatchObject({ kind: "cta", withDots: true });
+  });
+
+  it("leaves dots standing alone when no CTA follows", () => {
+    const parts = planChatUnit([
+      { type: "message", role: "user", text: "hi" },
+      { type: "continuation" },
+    ]);
+    expect(parts.map((p) => p.kind)).toEqual(["bubble", "dots"]);
+  });
+
+  it("hangs a CTA on the side of the message it belongs to, skipping dots", () => {
+    const parts = planChatUnit([
+      { type: "message", role: "user", text: "hi" },
+      { type: "continuation" },
+      { type: "callToAction", label: "GO" },
+    ]);
+    expect(parts[1]).toMatchObject({ align: "right" });
+  });
+});

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

@@ -0,0 +1,179 @@
+/**
+ * A conversation, drawn in monospace — and the layout PLAN both channels walk.
+ *
+ * Moved from `../email/chat.ts`, which keeps its HTML `<table>` skeleton and
+ * now asks here for the plan and the ascii form.
+ *
+ * **Two things live here, and the split matters.**
+ *
+ * `planChatUnit` answers the layout QUESTIONS — which side a CTA hangs on,
+ * whether continuation dots fold into the CTA below them or stand alone,
+ * whether a bubble hugs what follows it. Those answers are the same on every
+ * channel, and they are the part that was silently duplicated the moment a
+ * second channel tried to draw a conversation. Email walks the plan into
+ * `<table>`s; Slack walks the SAME plan into preformatted blocks and native
+ * buttons. Neither re-derives the alignment.
+ *
+ * The `render*Ascii` functions answer the DRAWING question, and only surfaces
+ * that want box art call them.
+ *
+ * `ChatPart` is a plan, not a content model: it holds `../../content` types and
+ * adds only positioning. It must not grow fields describing what a turn MEANS —
+ * that is `../../content`'s job and duplicating it here is how this directory
+ * would turn into a second vocabulary.
+ *
+ * INVARIANTS:
+ * - Pure. Every column is real output and is locked by
+ *   `../../__tests__/render-snapshot.test.ts` — a stray space is a visibly
+ *   broken email, not a whitespace nit.
+ * - `clampMessage` from `./wrap` is the one truncation authority, so every
+ *   surface truncates at the same point.
+ */
+
+import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
+
+import { ctaBoxWidth, renderCtaAscii } from "./cta";
+import { AVATAR, type AsciiGeometry, KAOMOJI } from "./geometry";
+import { indentLine, type MonospaceLine, padLineStart, text } from "./runs";
+import { clampMessage, wrapText } from "./wrap";
+
+// =============================================================================
+// The plan
+// =============================================================================
+
+/** Which side of the channel a part hangs on. */
+export type ChatAlign = "left" | "right";
+
+/**
+ * One positioned item of a conversation.
+ *
+ * `tight` marks a bubble that is introducing whatever follows it (a CTA, the
+ * dots) and so should hug it. Named for the relationship rather than for a
+ * pixel gap, because the two channels spend it differently — email as a margin
+ * recipe, Slack as nothing at all.
+ */
+export type ChatPart =
+  | { kind: "bubble"; turn: ChatTurn; tight: boolean }
+  | { kind: "cta"; cta: CallToAction; align: ChatAlign; withDots: boolean }
+  | { kind: "dots" };
+
+/**
+ * Position a chat unit's items — the layout decisions, made once.
+ *
+ * Continuation dots immediately before a CTA are folded INTO that CTA (they
+ * render centered over its box); otherwise they stand alone, centered in the
+ * channel. A CTA mirrors the side of the nearest preceding message, skipping
+ * any dots between, so it sits under the bubble it belongs to.
+ */
+export function planChatUnit(items: ChatUnitItem[]): ChatPart[] {
+  const parts: ChatPart[] = [];
+  items.forEach((item, i) => {
+    if (item.type === "continuation") {
+      if (items[i + 1]?.type !== "callToAction") parts.push({ kind: "dots" });
+      return;
+    }
+    if (item.type === "callToAction") {
+      let j = i - 1;
+      while (j >= 0 && items[j].type === "continuation") j--;
+      const prev = items[j];
+      parts.push({
+        kind: "cta",
+        cta: item,
+        align:
+          prev?.type === "message" && prev.role === "user" ? "right" : "left",
+        withDots: items[i - 1]?.type === "continuation",
+      });
+      return;
+    }
+    const next = items[i + 1]?.type;
+    parts.push({
+      kind: "bubble",
+      turn: item,
+      tight: next === "callToAction" || next === "continuation",
+    });
+  });
+  return parts;
+}
+
+// =============================================================================
+// The drawing
+// =============================================================================
+
+/**
+ * One message as a box, with its speaker's avatar beside the last line.
+ *
+ * Both roles share the gutter so the two boxes align; the user's text is
+ * right-set inside it and the assistant's left-set, which is what makes the
+ * conversation readable without either box moving.
+ */
+export function renderBubbleAscii(
+  turn: ChatTurn,
+  geometry: AsciiGeometry,
+): MonospaceLine[] {
+  const { indent, messageWidth, maxMessageLines } = geometry;
+  const isUser = turn.role === "user";
+  const clamped = clampMessage(turn.text, messageWidth, maxMessageLines);
+
+  const border = "─".repeat(messageWidth + 2);
+  const gutter = " ".repeat(indent);
+  const body = wrapText(clamped, messageWidth).map(
+    (line) =>
+      `${gutter}│ ${isUser ? line.padStart(messageWidth) : line.padEnd(messageWidth)} │`,
+  );
+
+  // The avatar sits beside the LAST line of the box, one row up from the bottom
+  // border — the recipient's outside the right edge, ours replacing the gutter.
+  const last = body.length - 1;
+  if (isUser) body[last] += `  ${KAOMOJI}`;
+  else body[last] = `${AVATAR}  ${body[last].slice(indent)}`;
+
+  const box = [
+    text(`${gutter}┌${border}┐`),
+    ...body.map(text),
+    text(`${gutter}└${border}┘`),
+  ];
+
+  // A named recipient signs under their own bubble.
+  if (isUser && turn.from) {
+    box.push(padLineStart(text(turn.from), geometry.boxRight - 1));
+  }
+  return box;
+}
+
+/**
+ * A CTA inside the conversation, aligned to the side of the message it follows.
+ *
+ * When `withDots`, the continuation "⋮" render just above it, centered over the
+ * box's exact width regardless of how long the label is.
+ */
+export function renderChatCtaAscii(
+  cta: CallToAction,
+  align: ChatAlign,
+  withDots: boolean,
+  geometry: AsciiGeometry,
+): MonospaceLine[] {
+  // `boxRight`, not `columns`: a CTA lines up with the BUBBLE's right border,
+  // not with the recipient's avatar hanging past it.
+  const { boxRight, indent } = geometry;
+  const lines = renderCtaAscii(cta, geometry).map((line) =>
+    align === "right" ? padLineStart(line, boxRight) : indentLine(line, indent),
+  );
+  if (!withDots) return lines;
+
+  const width = ctaBoxWidth(cta, geometry);
+  const column =
+    align === "right"
+      ? boxRight - Math.floor(width / 2)
+      : indent + Math.ceil(width / 2);
+  return [padLineStart(text("⋮"), column), [], ...lines];
+}
+
+/**
+ * Standalone continuation dots, centered in the message channel.
+ *
+ * Used only when a `continuation` is NOT immediately followed by a
+ * `callToAction` — the common case folds the dots into the CTA above it.
+ */
+export function renderChatDotsAscii(geometry: AsciiGeometry): MonospaceLine[] {
+  return [padLineStart(text("⋮"), Math.round(geometry.boxRight / 2))];
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The `>> LABEL <<` box — the monospace drawing of a `callToAction`.
+ *
+ * Moved from `../email/cta.ts`, which keeps its HTML `<table>` and now asks
+ * here for the ascii form.
+ *
+ * **The href is a run, not a string.** A linked CTA draws its box and then puts
+ * the destination on its own line below — and that line comes back as a `link`
+ * run so a channel that can make it clickable still can. Email flattens it to
+ * the bare URL, which is what a plain-text body can do; Slack maps it to a
+ * `RichTextLink` inside its preformatted block, which is what Slack can do.
+ * Neither has to go looking for a URL inside a string.
+ *
+ * INVARIANTS:
+ * - Pure.
+ * - `href` absent means the label IS the payload (an OTP code): the box must
+ *   not become a link and no URL line may appear beneath it. Fabricating a
+ *   destination for a code is the one thing this element must never do.
+ * - The label is ATOMIC. It is never wrapped or truncated to fit the column
+ *   budget — a code broken across lines is not a code. A long label makes a
+ *   wide box, and that is the correct failure.
+ */
+
+import type { CallToAction } from "../../content";
+
+import type { AsciiGeometry } from "./geometry";
+import { type MonospaceLine, text } from "./runs";
+
+/**
+ * The `>> LABEL <<` box, and the destination line when there is one.
+ *
+ * Three lines of box, then — only when linked — a blank line and the href.
+ */
+export function renderCtaAscii(
+  cta: CallToAction,
+  geometry: AsciiGeometry,
+): MonospaceLine[] {
+  const pad = " ".repeat(geometry.ctaPad);
+  const inner = `${pad}>> ${cta.label} <<${pad}`;
+  const border = `*${"-".repeat(inner.length)}*`;
+
+  const box = [text(border), text(`|${inner}|`), text(border)];
+  if (!cta.href) return box;
+
+  // A blank line is `[]`, not a run holding "" — an empty line has no runs, and
+  // the alignment helpers in `./runs` deliberately leave it alone rather than
+  // padding whitespace onto a line nobody can see.
+  return [...box, [], [{ type: "link", text: cta.href, href: cta.href }]];
+}
+
+/** The drawn width of a CTA box — its first line spans the whole thing. */
+export function ctaBoxWidth(
+  cta: CallToAction,
+  geometry: AsciiGeometry,
+): number {
+  return cta.label.length + 6 + geometry.ctaPad * 2 + 2;
+}