@uniflowed/tui 0.0.0-alpha.18

package/capability.js

@@ -0,0 +1,366 @@
+// @flow
+//
+// What the attached terminal can actually render.
+//
+// A TUI that assumes 24-bit colour, a mouse and box-drawing characters works
+// on the machine it was written on and produces unreadable noise on a build
+// agent, in a `TERM=dumb` shell, and in every terminal a screen reader is
+// pointed at. This module is where that assumption is refused, once, before
+// the first frame.
+//
+// # It is the CLI's answer, not a second one
+//
+// `crates/uf_term/src/capability.rs` already answers this question for `uf`
+// itself, and it answers it after a long argument with reality — the
+// precedence order below is its order, variable for variable, including the
+// parts that look arbitrary. `CLICOLOR_FORCE` beating `TERM=dumb` is not an
+// oversight; `FORCE_COLOR=` with an empty value meaning "on" is a convention
+// three other tools already established. Reproducing it exactly is the point:
+// a project whose CLI and whose TUI library disagree about whether this
+// terminal takes colour is a project that will be sent a screenshot of one of
+// them being wrong.
+//
+// # Detected once
+//
+// Capability is resolved at start-up from three inputs — an explicit choice,
+// the environment, and whether the stream is a terminal — and then carried as
+// a plain value. No write path re-reads `process.env`, which is both faster
+// and the only way the result can be tested without mutating the environment
+// of the process running the test.
+
+/** How much colour a stream can carry. */
+export type ColorLevel = "none" | "ansi16" | "ansi256" | "truecolor";
+
+/** Which glyph vocabulary is safe to print. */
+export type GlyphSet = "unicode" | "ascii";
+
+/** Whether a human is looking at the stream. */
+export type Tty = "interactive" | "piped";
+
+/** What a caller asked for, before the environment gets a say. */
+export type ColorChoice = "auto" | "always" | "never";
+
+/** The environment variables that influence terminal rendering. */
+export type TerminalEnv = {
+  readonly NO_COLOR?: string,
+  readonly FORCE_COLOR?: string,
+  readonly CLICOLOR?: string,
+  readonly CLICOLOR_FORCE?: string,
+  readonly TERM?: string,
+  readonly COLORTERM?: string,
+  readonly COLUMNS?: string,
+  readonly LINES?: string,
+  readonly LC_ALL?: string,
+  readonly LC_CTYPE?: string,
+  readonly LANG?: string,
+};
+
+/** The resolved rendering capability of one stream. */
+export type Capabilities = {
+  readonly color: ColorLevel,
+  readonly glyphs: GlyphSet,
+  readonly tty: Tty,
+};
+
+const LEVELS: $ReadOnlyArray<ColorLevel> = ["none", "ansi16", "ansi256", "truecolor"];
+
+/** Order colour levels so `max` and `min` mean what they say. */
+const rank = (level: ColorLevel): number => LEVELS.indexOf(level);
+
+const nonEmpty = (value: string | void): string | null =>
+  value != null && value !== "" ? value : null;
+
+const has = (haystack: string, needle: string): boolean => haystack.toLowerCase().includes(needle);
+
+/** The level `COLORTERM` and `TERM` advertise, before any switch is applied. */
+function declaredLevel(env: TerminalEnv): ColorLevel {
+  const colorterm = nonEmpty(env.COLORTERM);
+  if (colorterm != null && (has(colorterm, "truecolor") || has(colorterm, "24bit"))) {
+    return "truecolor";
+  }
+  const term = nonEmpty(env.TERM);
+  if (term == null) {
+    return "ansi16";
+  }
+  if (has(term, "direct")) {
+    return "truecolor";
+  }
+  return has(term, "256") ? "ansi256" : "ansi16";
+}
+
+/** `FORCE_COLOR`, which both disables colour (`0`) and picks a level (`1`–`3`). */
+function forceColorLevel(env: TerminalEnv): ColorLevel | null {
+  const raw = env.FORCE_COLOR;
+  if (raw == null) {
+    return null;
+  }
+  const value = raw.trim();
+  if (value === "0" || value === "false") {
+    return "none";
+  }
+  if (value === "2") {
+    return "ansi256";
+  }
+  if (value === "3") {
+    return "truecolor";
+  }
+  const declared = declaredLevel(env);
+  return rank(declared) > rank("ansi16") ? declared : "ansi16";
+}
+
+/**
+ * Whether the locale says this terminal understands UTF-8.
+ *
+ * An *unset* locale counts as yes. It is the common case on macOS and inside
+ * container images that render UTF-8 perfectly well, and treating it as a
+ * downgrade signal would give a plain-ASCII interface to most of the people
+ * who would rather have the box-drawing characters.
+ */
+function utf8Locale(env: TerminalEnv): boolean {
+  const locale = nonEmpty(env.LC_ALL) ?? nonEmpty(env.LC_CTYPE) ?? nonEmpty(env.LANG);
+  if (locale == null) {
+    return true;
+  }
+  return has(locale, "utf-8") || has(locale, "utf8");
+}
+
+/**
+ * Resolve capability from a choice, a stream classification, and an
+ * environment.
+ *
+ * Precedence, highest first — this list is
+ * `crates/uf_term/src/capability.rs`'s, and changing it here alone is how the
+ * CLI and the library start disagreeing:
+ *
+ * 1. an explicit `"never"` or `"always"`
+ * 2. `NO_COLOR` (any non-empty value)
+ * 3. `FORCE_COLOR`
+ * 4. `CLICOLOR_FORCE`
+ * 5. `TERM=dumb`
+ * 6. `CLICOLOR=0`
+ * 7. whether the stream is a terminal
+ * 8. `COLORTERM` / `TERM`
+ */
+export function detectCapabilities(choice: ColorChoice, tty: Tty, env: TerminalEnv): Capabilities {
+  const dumb = env.TERM === "dumb";
+  return {
+    color: detectColor(choice, tty, env, dumb),
+    // Glyphs do not follow colour. A terminal can be perfectly capable of
+    // UTF-8 while its output is being piped into a file, and replacing a box
+    // border with `+---+` in that file helps nobody.
+    glyphs: dumb || !utf8Locale(env) ? "ascii" : "unicode",
+    tty,
+  };
+}
+
+function detectColor(choice: ColorChoice, tty: Tty, env: TerminalEnv, dumb: boolean): ColorLevel {
+  if (choice === "never") {
+    return "none";
+  }
+  if (choice === "always") {
+    const declared = declaredLevel(env);
+    return rank(declared) > rank("ansi16") ? declared : "ansi16";
+  }
+  if (nonEmpty(env.NO_COLOR) != null) {
+    return "none";
+  }
+  const forced = forceColorLevel(env);
+  if (forced != null) {
+    return forced;
+  }
+  const clicolorForce = nonEmpty(env.CLICOLOR_FORCE);
+  if (clicolorForce != null && clicolorForce !== "0") {
+    const declared = declaredLevel(env);
+    return rank(declared) > rank("ansi16") ? declared : "ansi16";
+  }
+  if (dumb) {
+    return "none";
+  }
+  if (nonEmpty(env.CLICOLOR) === "0") {
+    return "none";
+  }
+  if (tty === "piped") {
+    return "none";
+  }
+  return declaredLevel(env);
+}
+
+/**
+ * The most conservative capability there is.
+ *
+ * What a redirected stream and a snapshot test both use: no escape sequences
+ * at all, ASCII glyphs, nobody watching.
+ */
+export function plainCapabilities(): Capabilities {
+  return { color: "none", glyphs: "ascii", tty: "piped" };
+}
+
+/** How wide a terminal is assumed to be when nothing will say. */
+export const FALLBACK_COLUMNS: number = 80;
+
+/** How tall a terminal is assumed to be when nothing will say. */
+export const FALLBACK_ROWS: number = 24;
+
+/** How big the terminal is, in cells. */
+export type TerminalSize = {
+  readonly columns: number,
+  readonly rows: number,
+};
+
+/**
+ * What the stream said about itself, if anything.
+ *
+ * `process.stdout.columns` is `undefined` on a stream that is not a terminal,
+ * and a stand-in a test wrote may not have the properties at all — so this is
+ * every field optional rather than a size, and the difference between "the
+ * terminal says 80" and "nothing said anything" is kept.
+ */
+export type TerminalReport = {
+  readonly columns?: number,
+  readonly rows?: number,
+  ...
+};
+
+/** `COLUMNS`, when it names a usable number of columns. */
+function declaredColumns(env: TerminalEnv): number | null {
+  return positive(env.COLUMNS);
+}
+
+/** `LINES`, when it names a usable number of rows. */
+function declaredRows(env: TerminalEnv): number | null {
+  return positive(env.LINES);
+}
+
+/** The columns the stream reported, when it reported a usable number. */
+function reportedColumns(reported: TerminalReport): number | null {
+  return usable(reported.columns);
+}
+
+/** The rows the stream reported, when it reported a usable number. */
+function reportedRows(reported: TerminalReport): number | null {
+  return usable(reported.rows);
+}
+
+/**
+ * A variable that names a positive whole number of cells, or nothing.
+ *
+ * `COLUMNS=0` and `COLUMNS=wide` are both a variable saying nothing useful,
+ * and both fall through to the next rule rather than produce a terminal zero
+ * columns across.
+ */
+function positive(value: string | void): number | null {
+  const raw = nonEmpty(value);
+  if (raw == null || !/^\d+$/.test(raw.trim())) {
+    return null;
+  }
+  return usable(Number.parseInt(raw, 10));
+}
+
+const usable = (value: number | void): number | null =>
+  typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+
+/**
+ * Resolve how big the terminal is.
+ *
+ * Precedence, highest first — this list is `crates/uf_term/src/capability.rs`'s
+ * `detect_size`, chain for chain, and `tests/library/tui.test.js` compares the
+ * two rather than believing this sentence:
+ *
+ * 1. `COLUMNS` and `LINES`, each on its own. POSIX makes them the override,
+ *    and they are what a `watch`, a `script` or a CI wrapper sets when the
+ *    stream itself cannot answer.
+ * 2. what the stream reported, which on Node is the terminal's own answer
+ * 3. 80 by 24
+ *
+ * The two dimensions are resolved separately, because `COLUMNS` without
+ * `LINES` is the common shape: a wrapper that cares about width sets one of
+ * them.
+ */
+export function detectSize(env: TerminalEnv, reported: TerminalReport): TerminalSize {
+  const columns = declaredColumns(env) ?? reportedColumns(reported) ?? FALLBACK_COLUMNS;
+  const rows = declaredRows(env) ?? reportedRows(reported) ?? FALLBACK_ROWS;
+  return { columns, rows };
+}
+
+/**
+ * The border characters this terminal can print.
+ *
+ * OpenTUI's four border styles, plus the ASCII fallback that is the whole
+ * reason this is a lookup rather than a constant. The ASCII set is not a
+ * different design, it is the same design drawn with the characters a
+ * `TERM=dumb` terminal will not replace with a question mark: every glyph
+ * below is one column wide in both vocabularies, so a box's geometry does not
+ * change when its characters do.
+ */
+export type BorderStyle = "single" | "double" | "rounded" | "heavy";
+
+/** Eight characters: the four corners, then top, right, bottom, left. */
+export type BorderGlyphs = {
+  readonly topLeft: string,
+  readonly topRight: string,
+  readonly bottomLeft: string,
+  readonly bottomRight: string,
+  readonly top: string,
+  readonly right: string,
+  readonly bottom: string,
+  readonly left: string,
+};
+
+const ASCII_BORDER: BorderGlyphs = {
+  topLeft: "+",
+  topRight: "+",
+  bottomLeft: "+",
+  bottomRight: "+",
+  top: "-",
+  right: "|",
+  bottom: "-",
+  left: "|",
+};
+
+const UNICODE_BORDERS: { [BorderStyle]: BorderGlyphs } = {
+  single: {
+    topLeft: "┌",
+    topRight: "┐",
+    bottomLeft: "└",
+    bottomRight: "┘",
+    top: "─",
+    right: "│",
+    bottom: "─",
+    left: "│",
+  },
+  double: {
+    topLeft: "╔",
+    topRight: "╗",
+    bottomLeft: "╚",
+    bottomRight: "╝",
+    top: "═",
+    right: "║",
+    bottom: "═",
+    left: "║",
+  },
+  rounded: {
+    topLeft: "╭",
+    topRight: "╮",
+    bottomLeft: "╰",
+    bottomRight: "╯",
+    top: "─",
+    right: "│",
+    bottom: "─",
+    left: "│",
+  },
+  heavy: {
+    topLeft: "┏",
+    topRight: "┓",
+    bottomLeft: "┗",
+    bottomRight: "┛",
+    top: "━",
+    right: "┃",
+    bottom: "━",
+    left: "┃",
+  },
+};
+
+/** The border glyphs for a style, downgraded to ASCII when they cannot be printed. */
+export function borderGlyphs(style: BorderStyle, glyphs: GlyphSet): BorderGlyphs {
+  return glyphs === "ascii" ? ASCII_BORDER : UNICODE_BORDERS[style];
+}

package/cells.js

@@ -0,0 +1,332 @@
+// @flow
+//
+// The cell grid: what a frame *is*.
+//
+// A terminal is a rectangle of cells, and this module is the only description
+// of one in the package. Everything above it produces a frame — layout decides
+// where boxes go, `internal/paint.js` fills them in — and everything below it consumes
+// one: `diff.js` compares two frames and writes the difference, the test
+// renderer reads a frame back as text. Neither end knows how a cell is stored,
+// which is what let the storage change once already without either end
+// noticing.
+//
+// # Why parallel arrays rather than objects
+//
+// The obvious representation is `Array<{ char, fg, bg, attributes }>`, and it
+// was the first one. It is also the representation that makes the diff — the
+// operation this package exists to make cheap — allocate: comparing two frames
+// of a 200×60 terminal means 12,000 property loads on 12,000 objects that the
+// garbage collector has to keep alive between frames, and a frame is produced
+// on every keystroke.
+//
+// So a frame is four arrays of the same length: three typed, one not. The
+// three numeric ones make the common comparison — "is this cell unchanged?" —
+// three unboxed integer loads, and the string array carries the one field that
+// cannot be a number, because a cell holds a *grapheme cluster* and not a code
+// point. A family emoji is a dozen scalars in one cell.
+//
+// # The empty string means something
+//
+// `chars[i] === ""` is not a blank cell. A blank cell is `" "`. The empty
+// string is a **continuation cell**: the right-hand column of a two-column
+// grapheme whose cluster is stored in the cell to its left. The distinction
+// exists because a terminal advances its cursor two columns for `界` and
+// writing anything into the second of them corrupts the first, so both the
+// painter and the diff have to know that a cell is not independently
+// writable. Losing this distinction is the bug that makes a table of Japanese
+// paths look fine until one row contains an emoji.
+
+import { graphemeWidth } from "./widths.js";
+
+/**
+ * A colour, as a packed `0xRRGGBB`, or `INHERIT`.
+ *
+ * Colours are numbers rather than strings or objects because they sit in a
+ * typed array beside every cell, and because the comparison the diff performs
+ * a million times a second is `fg[i] === fg[i]`.
+ */
+export type Color = number;
+
+/**
+ * "Whatever the terminal's default is."
+ *
+ * Distinct from black: a reader with a light terminal theme and a renderer
+ * that resolved `INHERIT` to `0x000000` gets black text that stops being
+ * readable the moment the reader switches themes, and the terminal's own
+ * default is the only value that follows them.
+ */
+export const INHERIT: Color = -1;
+
+/**
+ * Text attributes, as a bit mask.
+ *
+ * The bits are OpenTUI's `TextAttributes`, in its order, so a value that
+ * crosses between the two libraries means the same thing.
+ */
+export const Attributes = {
+  NONE: 0,
+  BOLD: 1,
+  DIM: 2,
+  ITALIC: 4,
+  UNDERLINE: 8,
+  BLINK: 16,
+  INVERSE: 32,
+  STRIKETHROUGH: 64,
+};
+
+/** How one cell is painted. */
+export type Style = {
+  /** Foreground colour, or `INHERIT`. */
+  readonly fg: Color,
+  /** Background colour, or `INHERIT`. */
+  readonly bg: Color,
+  /** A mask of `Attributes`. */
+  readonly attributes: number,
+};
+
+/** The style of a cell nobody has painted. */
+export const PLAIN: Style = { fg: INHERIT, bg: INHERIT, attributes: Attributes.NONE };
+
+/**
+ * The sixteen colours every terminal has, by the names people write.
+ *
+ * The values are the widely-used xterm defaults rather than a standard,
+ * because there is no standard: a terminal is free to render `red` as whatever
+ * its theme says, and it will. These exist so that a caller who writes
+ * `fg="red"` gets a colour on a truecolour terminal that a reader recognises,
+ * and so that the downgrade back to `SGR 31` on a sixteen-colour terminal
+ * lands on the same name it started as.
+ */
+const NAMED: { [string]: Color } = {
+  black: 0x000000,
+  red: 0xcd0000,
+  green: 0x00cd00,
+  yellow: 0xcdcd00,
+  blue: 0x0000ee,
+  magenta: 0xcd00cd,
+  cyan: 0x00cdcd,
+  white: 0xe5e5e5,
+  gray: 0x7f7f7f,
+  grey: 0x7f7f7f,
+  brightblack: 0x7f7f7f,
+  brightred: 0xff0000,
+  brightgreen: 0x00ff00,
+  brightyellow: 0xffff00,
+  brightblue: 0x5c5cff,
+  brightmagenta: 0xff00ff,
+  brightcyan: 0x00ffff,
+  brightwhite: 0xffffff,
+};
+
+/**
+ * Read a colour written as a name, a hex string, or a packed number.
+ *
+ * Anything unrecognised resolves to `INHERIT` rather than raising. A colour is
+ * decoration: a typo in one should leave the interface readable in the
+ * terminal's own colours, not stop the program that was drawing it.
+ */
+export function parseColor(value: string | number | void | null): Color {
+  if (value == null) {
+    return INHERIT;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value & 0xffffff : INHERIT;
+  }
+  const text = value.trim().toLowerCase();
+  if (text.startsWith("#")) {
+    const digits = text.slice(1);
+    if (digits.length === 3) {
+      const r = Number.parseInt(digits[0] + digits[0], 16);
+      const g = Number.parseInt(digits[1] + digits[1], 16);
+      const b = Number.parseInt(digits[2] + digits[2], 16);
+      return Number.isNaN(r + g + b) ? INHERIT : (r << 16) | (g << 8) | b;
+    }
+    if (digits.length === 6) {
+      const packed = Number.parseInt(digits, 16);
+      return Number.isNaN(packed) ? INHERIT : packed;
+    }
+    return INHERIT;
+  }
+  return NAMED[text] ?? INHERIT;
+}
+
+/**
+ * One rendered frame.
+ *
+ * Mutable on purpose. A frame is filled in by one painter pass and then read
+ * by one diff, and copying it to keep it immutable would double the allocation
+ * this representation exists to avoid. The rule that keeps that safe is that a
+ * frame belongs to exactly one owner at a time: the painter owns it until
+ * `paint()` returns, the renderer owns it afterwards and never writes again.
+ */
+export type Frame = {
+  /** Columns. */
+  readonly width: number,
+  /** Rows. */
+  readonly height: number,
+  /** One grapheme cluster per cell, or `""` for a wide cluster's second cell. */
+  readonly chars: Array<string>,
+  /** Foreground per cell. */
+  readonly fg: Int32Array,
+  /** Background per cell. */
+  readonly bg: Int32Array,
+  /** Attribute mask per cell. */
+  readonly attributes: Uint8Array,
+};
+
+/** A rectangle in frame coordinates; `x`/`y` are the top-left cell. */
+export type Rect = {
+  readonly x: number,
+  readonly y: number,
+  readonly width: number,
+  readonly height: number,
+};
+
+/** A frame of blanks, `width` by `height`. */
+export function createFrame(width: number, height: number): Frame {
+  const size = Math.max(0, width * height);
+  const chars = new Array(size);
+  for (let i = 0; i < size; i += 1) {
+    chars[i] = " ";
+  }
+  return {
+    width,
+    height,
+    chars,
+    fg: new Int32Array(size).fill(INHERIT),
+    bg: new Int32Array(size).fill(INHERIT),
+    attributes: new Uint8Array(size),
+  };
+}
+
+/** Whether two frames describe the same rectangle. */
+export function sameSize(a: Frame, b: Frame): boolean {
+  return a.width === b.width && a.height === b.height;
+}
+
+/**
+ * Blank the cell at `index`, and any cell its content spans.
+ *
+ * A wide grapheme owns two cells and only one of them holds the cluster, so
+ * clearing "the cell at x" is not a single-index operation. Overwriting the
+ * *second* half of `界` and leaving the first half in place leaves a terminal
+ * printing half a character it has no way to draw; overwriting the first half
+ * and leaving the continuation marker leaves the diff convinced the second
+ * column is not writable. Both were bugs before this existed, and both were
+ * only visible with a non-ASCII string in the frame.
+ */
+function clearSpan(frame: Frame, index: number): void {
+  const row = Math.floor(index / frame.width);
+  let start = index;
+  if (frame.chars[index] === "") {
+    // A continuation cell: its cluster is to the left, on the same row.
+    start = index - 1;
+    if (start < row * frame.width) {
+      start = index;
+    }
+  }
+  const width = frame.chars[start] === "" ? 1 : graphemeWidth(frame.chars[start]);
+  for (let i = start; i < start + Math.max(1, width) && i < (row + 1) * frame.width; i += 1) {
+    frame.chars[i] = " ";
+  }
+}
+
+/**
+ * Write one grapheme cluster at `x`, `y`, in `style`.
+ *
+ * Returns the number of columns consumed, which is what a caller advances by:
+ * zero when the write fell outside the frame or outside `clip`, one or two
+ * otherwise. A two-column cluster that would straddle the right edge is
+ * written as a space instead of being split, because half of a wide character
+ * is not a character.
+ */
+export function writeGrapheme(
+  frame: Frame,
+  x: number,
+  y: number,
+  cluster: string,
+  width: number,
+  style: Style,
+  clip: Rect,
+): number {
+  if (y < clip.y || y >= clip.y + clip.height || y < 0 || y >= frame.height) {
+    return width;
+  }
+  if (x < clip.x || x + width > clip.x + clip.width || x < 0 || x + width > frame.width) {
+    return width;
+  }
+  const index = y * frame.width + x;
+  clearSpan(frame, index);
+  if (width === 2) {
+    clearSpan(frame, index + 1);
+  }
+  frame.chars[index] = cluster;
+  frame.fg[index] = style.fg;
+  frame.bg[index] = style.bg;
+  frame.attributes[index] = style.attributes;
+  if (width === 2) {
+    frame.chars[index + 1] = "";
+    frame.fg[index + 1] = style.fg;
+    frame.bg[index + 1] = style.bg;
+    frame.attributes[index + 1] = style.attributes;
+  }
+  return width;
+}
+
+/**
+ * Fill a rectangle with `style`, leaving the characters in it blank.
+ *
+ * Used for a box's background. It clears rather than preserving what is under
+ * it: a background is opaque, and a box drawn over another box's text has to
+ * hide that text or the terminal shows both.
+ */
+export function fillRect(frame: Frame, area: Rect, style: Style, clip: Rect): void {
+  const left = Math.max(area.x, clip.x, 0);
+  const top = Math.max(area.y, clip.y, 0);
+  const right = Math.min(area.x + area.width, clip.x + clip.width, frame.width);
+  const bottom = Math.min(area.y + area.height, clip.y + clip.height, frame.height);
+  for (let y = top; y < bottom; y += 1) {
+    for (let x = left; x < right; x += 1) {
+      const index = y * frame.width + x;
+      clearSpan(frame, index);
+      frame.chars[index] = " ";
+      frame.fg[index] = style.fg;
+      frame.bg[index] = style.bg;
+      frame.attributes[index] = style.attributes;
+    }
+  }
+}
+
+/** The intersection of two rectangles, empty when they do not overlap. */
+export function intersect(a: Rect, b: Rect): Rect {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return { x, y, width: Math.max(0, right - x), height: Math.max(0, bottom - y) };
+}
+
+/**
+ * One row of a frame, as the text a reader would see.
+ *
+ * Continuation cells contribute nothing, because their cluster was already
+ * emitted by the cell to their left. Trailing blanks are kept: a test that
+ * asserts on a row is asserting on a rectangle, and trimming would make
+ * "painted a space here" and "painted nothing here" indistinguishable.
+ */
+export function frameRow(frame: Frame, y: number): string {
+  let out = "";
+  for (let x = 0; x < frame.width; x += 1) {
+    out += frame.chars[y * frame.width + x];
+  }
+  return out;
+}
+
+/** Every row of a frame, newline separated. Snapshots and `toContain` read this. */
+export function frameText(frame: Frame): string {
+  const rows = [];
+  for (let y = 0; y < frame.height; y += 1) {
+    rows.push(frameRow(frame, y));
+  }
+  return rows.join("\n");
+}