@company-semantics/contracts 52.0.0 → 53.0.0

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

@@ -0,0 +1,112 @@
+/**
+ * How wide the drawing may be, and everything that follows from it.
+ *
+ * One number is chosen — the column budget — and every other measurement in
+ * this directory is DERIVED from it. That is what makes the budget retunable:
+ * changing it is one edit, not a hunt for the constants that silently assumed
+ * the old value.
+ *
+ * **What the budget binds.** Lines this layer GENERATES: box borders, bubble
+ * frames, rules, padding, and prose it wraps itself.
+ *
+ * **What it does not bind.** Atomic content — URLs, OTP codes, identifiers,
+ * filenames, tokens, key/value cell values. Those may exceed the budget and
+ * must NEVER be broken to satisfy it. A line break inserted into a one-time
+ * code or a URL is a correctness bug wearing a layout costume, and no layout
+ * invariant is worth one.
+ *
+ * **What a "column" means.** 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 an emoji occupying two cells is not modelled.
+ * Promising otherwise would be a false precision, and this comment is the
+ * promise we are willing to keep.
+ */
+
+/** The assistant's avatar, drawn beside the last line of its bubble. */
+export const AVATAR = "[c_S]";
+
+/** The recipient's avatar, drawn beside the last line of their bubble. */
+export const KAOMOJI = "(•̀_ರ╮)";
+
+/** Spaces between an avatar and the box it sits beside. */
+const AVATAR_GAP = 2;
+
+/**
+ * Columns reserved on the RIGHT for the recipient's avatar.
+ *
+ * Both sides are reserved, exactly as the HTML reserves both `<td>`s and hides
+ * the one it is not using. Only one avatar shows per row, but the box must sit
+ * in the same columns whichever it is — an unreserved side would let a user
+ * bubble slide right and the conversation would read as two columns rather than
+ * one exchange.
+ *
+ * `KAOMOJI` is measured in string characters like everything else here. Its
+ * combining accent means it DRAWS about one column narrower than it measures, so
+ * this reserves a character more than it strictly needs. That is the safe
+ * direction of an error we already said we would not model.
+ */
+const RIGHT_AVATAR = AVATAR_GAP + KAOMOJI.length;
+
+/** `│ ` on the left and ` │` on the right of every bubble line. */
+const BUBBLE_BORDERS = 4;
+
+/** Padding columns each side of the `>> LABEL <<` line in a CTA box. */
+const CTA_BOX_PAD = 3;
+
+/** A chat message is clamped to this many lines, however long it is. */
+const MAX_MESSAGE_LINES = 3;
+
+/** Every derived measurement of one monospace layout. */
+export interface AsciiGeometry {
+  /** The column budget generated geometry fits inside. */
+  readonly columns: number;
+  /** Left gutter reserved for the sender's avatar, so bubbles align. */
+  readonly indent: number;
+  /** Characters of message text per bubble line. */
+  readonly messageWidth: number;
+  /**
+   * The column a bubble's right border sits in — the edge CTAs align to and
+   * dots centre over. Short of `columns` by the reserved right avatar, which
+   * hangs outside the box.
+   */
+  readonly boxRight: number;
+  /** Lines a message is clamped to before it is ellipsized. */
+  readonly maxMessageLines: number;
+  /** Padding each side of a CTA label. */
+  readonly ctaPad: number;
+}
+
+/**
+ * Derive a layout from a column budget.
+ *
+ * `columns` is the WIDEST line the layer will draw — the left avatar gutter,
+ * both box borders, the message text, and the right avatar hanging off the end.
+ * Measuring the budget at the box's edge instead would be measuring the wrong
+ * thing: the recipient's avatar sits outside that border, and it is the part
+ * that pushes a phone into horizontal scrolling.
+ *
+ * @throws RangeError when the budget cannot fit both avatar gutters, both
+ * borders and at least one character of message. A layout that cannot draw its
+ * own frame is a programming error, not a narrow screen, and silently clamping
+ * it would produce a plausible-looking box with content missing from it.
+ */
+export function geometryFor(columns: number): AsciiGeometry {
+  const indent = AVATAR.length + AVATAR_GAP;
+  const overhead = indent + BUBBLE_BORDERS + RIGHT_AVATAR;
+  const messageWidth = columns - overhead;
+  if (messageWidth < 1) {
+    throw new RangeError(
+      `Column budget ${columns} leaves no room for message text ` +
+        `(needs more than ${overhead}).`,
+    );
+  }
+  return {
+    columns,
+    indent,
+    messageWidth,
+    boxRight: indent + messageWidth + BUBBLE_BORDERS,
+    maxMessageLines: MAX_MESSAGE_LINES,
+    ctaPad: CTA_BOX_PAD,
+  };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * The monospace layout layer — the drawing every channel with a fixed-width
+ * surface shares.
+ *
+ * Not a renderer. It answers no `NotificationContent` and produces no channel's
+ * bytes; it draws box art and returns lines of runs, and the channels decide
+ * what those become. See `./README.md`.
+ */
+
+export type { AsciiGeometry } from "./geometry";
+export { AVATAR, geometryFor, KAOMOJI } from "./geometry";
+
+export type { MonospaceLine, MonospaceRun } from "./runs";
+export {
+  blockWidth,
+  flattenLine,
+  flattenLines,
+  indentLine,
+  lineLength,
+  padLineStart,
+  text,
+} from "./runs";
+
+export { clampMessage, proseLines, wrapClamped, wrapText } from "./wrap";
+
+export { ctaBoxWidth, renderCtaAscii } from "./cta";
+
+export { keyValueLines } from "./keyvalue";
+
+export { fullRuleAscii, ruleAscii } from "./rule";
+
+export { signatureLines } from "./signature";
+
+export type { ChatAlign, ChatPart } from "./chat";
+export {
+  planChatUnit,
+  renderBubbleAscii,
+  renderChatCtaAscii,
+  renderChatDotsAscii,
+} from "./chat";

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

@@ -0,0 +1,34 @@
+/**
+ * `Label: value` — the one place the separator the content model drops is put
+ * back.
+ *
+ * `KeyValueRow` carries a label and a value and no colon, because a colon is
+ * presentation (see `../../kinds/README.md`). Every monospace surface puts the
+ * same one back, so it is written once here rather than once per channel.
+ *
+ * **A value is atomic and is never wrapped.** A device string, an IP, an expiry
+ * or an identifier means what it means as one run of characters; breaking one
+ * across lines to satisfy the column budget would corrupt the fact
+ * (`../layout.ts`). A long value overhangs, and that is the correct failure.
+ */
+
+import type { KeyValueRow } from "../../content";
+
+import { type MonospaceLine, text } from "./runs";
+
+/**
+ * Rows as `Label: value` lines, optionally under a heading.
+ *
+ * The heading is the element's own label with a colon — `metadata`'s "Request
+ * details:" — and is a line of its own rather than a prefix, because it names
+ * the group rather than any one row.
+ */
+export function keyValueLines(
+  rows: KeyValueRow[],
+  heading?: string,
+): MonospaceLine[] {
+  return [
+    ...(heading ? [text(`${heading}:`)] : []),
+    ...rows.map((row) => text(`${row.label}: ${row.value}`)),
+  ];
+}

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

@@ -0,0 +1,53 @@
+/**
+ * A horizontal rule, sized to what it brackets.
+ *
+ * Lived in `./chat.ts` while a conversation was the only thing that needed
+ * bracketing. The title needs one too, so it moved here rather than being
+ * imported from a module whose name would have made it look chat-specific.
+ *
+ * The HTML surface draws the same idea as an `<hr>`; this is the monospace
+ * character that looks like one.
+ */
+
+import type { AsciiGeometry } from "./geometry";
+import { blockWidth, type MonospaceLine, text } from "./runs";
+
+/**
+ * `─` rather than `_`: an underscore sits on the baseline and reads as an
+ * underline under whatever is above it, while a box-drawing horizontal sits at
+ * mid-height and reads as a rule.
+ */
+const RULE = "─";
+
+/**
+ * A rule spanning the widest line it brackets, capped at the budget.
+ *
+ * Sized to the block rather than always to the budget: a short exchange draws a
+ * short rule, and a rule wider than what it brackets reads as a separator
+ * BETWEEN things rather than the frame of one.
+ *
+ * The cap is what stops an ATOMIC line dragging the layout out with it. A chat
+ * CTA prints its destination underneath, and a 67-character URL is allowed to
+ * overhang (`../layout.ts`) — but it must not recruit the rule into overhanging
+ * with it. The URL is content that happens to be long; the rule is geometry, and
+ * geometry answers to the budget.
+ */
+export function ruleAscii(
+  lines: MonospaceLine[],
+  geometry: AsciiGeometry,
+): MonospaceLine {
+  return text(RULE.repeat(Math.min(blockWidth(lines), geometry.columns)));
+}
+
+/**
+ * A rule spanning the whole budget, whatever it sits under.
+ *
+ * For the title, where `ruleAscii`'s size-to-content behaviour is wrong: a
+ * title underline that stops a couple of characters short of the rules further
+ * down the message reads as a miscalculation rather than a choice. Spanning the
+ * full measure says "this is the top of the message" in a way a ragged rule
+ * cannot.
+ */
+export function fullRuleAscii(geometry: AsciiGeometry): MonospaceLine {
+  return text(RULE.repeat(geometry.columns));
+}

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

@@ -0,0 +1,84 @@
+/**
+ * The monospace line vocabulary — the ONLY thing the ascii layer returns.
+ *
+ * A run is text, or text that is a link. A line is runs. That is the whole
+ * model, and it is deliberately dumb.
+ *
+ * **What must never move in here.** CTA-ness, warning-ness, chat turn, author,
+ * role, alignment, spacing — these stay INPUTS to the functions in this
+ * directory. The moment a run learns what a CTA is, `../ascii` has started
+ * becoming a second notification model competing with `../../content`, which is
+ * the fusion ADR-CONTRACTS-086 spent its effort undoing. If a field feels like
+ * it wants to live on a run, that is the signal it belongs in a function
+ * signature instead.
+ *
+ * **Why runs rather than `string[]`.** A rendered line can contain a URL, and
+ * the channels disagree about what to do with it: email's text surface prints
+ * it, Slack's `rich_text_preformatted` wants it as a `RichTextLink` so it stays
+ * clickable. Flattening to a string here would force Slack to go looking for
+ * the URL inside a string this layer had already dissolved it into — the exact
+ * hack this shape exists to prevent.
+ */
+
+/** A stretch of one line: plain text, or text that points somewhere. */
+export type MonospaceRun =
+  { type: "text"; text: string } | { type: "link"; text: string; href: string };
+
+/** One line of a monospace layout, left to right. */
+export type MonospaceLine = MonospaceRun[];
+
+/** A line of plain text — the common case, spelled once. */
+export function text(value: string): MonospaceLine {
+  return [{ type: "text", text: value }];
+}
+
+/** The characters on a line, ignoring where the links are. */
+export function lineLength(line: MonospaceLine): number {
+  return line.reduce((total, run) => total + run.text.length, 0);
+}
+
+/**
+ * The widest line in a block, in characters.
+ *
+ * Used to size rules that must span whatever they bracket. Empty input is 0
+ * rather than an error: a chat unit with no drawable items has no width.
+ */
+export function blockWidth(lines: MonospaceLine[]): number {
+  return lines.reduce((widest, line) => Math.max(widest, lineLength(line)), 0);
+}
+
+/**
+ * Collapse a line to its characters, discarding link identity.
+ *
+ * For surfaces that have no way to carry a link inline — email's plain-text
+ * body is the one today. A surface that CAN carry one (Slack) must map the runs
+ * instead, which is the entire reason they survive this far.
+ */
+export function flattenLine(line: MonospaceLine): string {
+  return line.map((run) => run.text).join("");
+}
+
+/** `flattenLine` over a block, joined with newlines. */
+export function flattenLines(lines: MonospaceLine[]): string {
+  return lines.map(flattenLine).join("\n");
+}
+
+/** Prepend `count` spaces to a line, as a text run. */
+export function indentLine(line: MonospaceLine, count: number): MonospaceLine {
+  if (count <= 0 || line.length === 0) return line;
+  return [{ type: "text", text: " ".repeat(count) }, ...line];
+}
+
+/**
+ * Right-align a line to `column`, as a leading text run.
+ *
+ * A line already at or past `column` is returned untouched — alignment pads,
+ * it never truncates. Truncation of content is `./wrap`'s business and is
+ * always a deliberate clamp, never a side effect of positioning.
+ */
+export function padLineStart(
+  line: MonospaceLine,
+  column: number,
+): MonospaceLine {
+  return indentLine(line, column - lineLength(line));
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The sign-off — the end-of-message marker, the copyright line, the URL.
+ *
+ * Drawn here so both monospace surfaces sign a notification the same way. It
+ * takes the signer, the year and the URL as ARGUMENTS rather than reading a
+ * brand: this directory knows about columns and characters, and the day it
+ * starts knowing who we are is the day it stops being a layout layer.
+ *
+ * The URL comes back as a `link` run. Email's `text/plain` body flattens it to
+ * the bare address, which is all that surface can do; Slack maps it onto a
+ * `RichTextLink`, which `rich_text_preformatted` explicitly admits
+ * (`(RichTextText | RichTextLink)[]`). Whether Slack's client then makes it
+ * clickable inside a code block is Slack's call and is not something this
+ * package can verify — but the address is VISIBLE either way, so the run costs
+ * nothing if it renders as plain text. Same drawing, two surfaces, no guess
+ * baked in.
+ */
+
+import { type MonospaceLine, text } from "./runs";
+
+/**
+ * The end-of-message marker.
+ *
+ * Borrowed from the C comment it looks like: a notification is a message with a
+ * definite end, and this says so in the one typographic register the brand
+ * uses everywhere else.
+ */
+const EOM = "/* EOM */";
+
+/** The marker, the copyright line, then the URL as a link. */
+export function signatureLines(
+  signer: string,
+  year: number,
+  url: string,
+): MonospaceLine[] {
+  return [
+    text(EOM),
+    text(`ⓒ ${year} • ${signer}`),
+    [{ type: "link", text: url, href: url }],
+  ];
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Word wrapping and the one truncation authority.
+ *
+ * Moved verbatim from `../email/chat.ts` (ADR-CONTRACTS-086 put it there; the
+ * ascii extraction moved it here) so that every channel drawing a monospace
+ * surface breaks and clamps text at exactly the same point. Two channels that
+ * wrap differently are two different messages, and the whole reason this
+ * directory exists is that they should not be.
+ *
+ * These operate on plain strings, not runs: wrapping is about where characters
+ * end, and a link's href plays no part in that. Callers reassemble runs around
+ * the result.
+ */
+
+import type { AsciiGeometry } from "./geometry";
+import { type MonospaceLine, text } from "./runs";
+
+/** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
+export 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 : [""];
+}
+
+/** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
+export 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 `maxLines` × `width`,
+ * ellipsized, rejoined into a single string.
+ *
+ * Every surface of a chat unit runs content through this, so they all truncate
+ * at exactly the same point — HTML bubbles, plain text box art, and Slack's
+ * preformatted block alike.
+ */
+export function clampMessage(
+  text: string,
+  width: number,
+  maxLines: number,
+): string {
+  return wrapClamped(text, width, maxLines).join(" ");
+}
+
+/**
+ * Prose as monospace lines, wrapped to the budget.
+ *
+ * A `\n` in the source separates lines the author wrote; each of those is then
+ * wrapped independently, so an authored break survives and a long sentence still
+ * gets broken. This is the prose path — key/value values, URLs and CTA labels
+ * are atomic and never come through here (`../layout.ts`).
+ *
+ * Wrapped at the FULL budget, not at a bubble's `messageWidth`. Prose is not
+ * inside a box and has no avatar gutters to pay for, so narrowing it to a
+ * bubble's interior would wrap the same sentence differently on the two channels
+ * — which is the drift this whole layer exists to prevent.
+ */
+export function proseLines(
+  value: string,
+  geometry: AsciiGeometry,
+): MonospaceLine[] {
+  return value
+    .split("\n")
+    .flatMap((line) => wrapText(line, geometry.columns))
+    .map(text);
+}

package/src/notifications/renderers/brand.ts

@@ -0,0 +1,12 @@
+/**
+ * Brand facts every channel signs with.
+ *
+ * The brand NAME and the copyright year are not here — they are
+ * `../context`'s, read from `RenderContext.brand` so a caller can render for a
+ * different brand or pin a year. The URL is not yet on that record, and it sits
+ * here rather than inside `./email/constants.ts` because more than one channel
+ * signs with it now: a constant shared by two channels belongs above both.
+ */
+
+/** The `companysemantics.ai` link under every signature. */
+export const COMPANY_URL = "https://companysemantics.ai";