@uniflowed/tui 0.0.0-alpha.18

package/diff.js

@@ -0,0 +1,286 @@
+// @flow
+//
+// The difference between two frames, as the bytes that turn one into the other.
+//
+// This is the module the package exists for. Everything else — the tree, the
+// layout, the painter — could be replaced with something else and the result
+// would still be a terminal UI; without this it would be a terminal UI that
+// reprints the screen on every keystroke, which is what makes a slow one feel
+// slow. The bottleneck in a terminal program is not laying out a hundred
+// boxes. It is the bytes handed to a pseudo-terminal, which are copied,
+// parsed, and re-rendered by an emulator that is drawing them with a GPU on
+// the other side of a pipe.
+//
+// So the measurement that matters is bytes per frame, and the mechanism is
+// this: compare the two frames cell by cell, and emit only the cells that
+// differ. Changing one character of a status line in an 80×24 terminal costs
+// this renderer about a dozen bytes. A renderer that diffs *lines* — which is
+// what React Ink does, and what a naive implementation does — reprints from
+// the first changed line to the bottom of the frame, and the same edit costs
+// it however much of the screen is below it. `tui.test.js` measures both
+// numbers rather than asserting the shape of the claim.
+//
+// # Two cursor moves cost more than four spaces
+//
+// A cursor move is `ESC [ row ; col H`, which is six to nine bytes. Two runs
+// of changed cells separated by three unchanged ones are therefore cheaper to
+// write as one run — paying for three characters that did not need writing —
+// than as two runs with a jump between them. `JOIN_GAP` is where that trade
+// turns over. It was not there in the first version, and a progress bar whose
+// filled cells alternate with empty ones produced one cursor move per cell.
+//
+// # Colour is emitted only when it changes
+//
+// The SGR sequence for a truecolour foreground is nineteen bytes, which is
+// longer than most of the runs it introduces. Tracking the terminal's current
+// style across the whole frame and re-emitting only on a change turns a
+// coloured row from nineteen bytes per cell into nineteen bytes per *run of
+// one colour*, which for a syntax-highlighted line is an order of magnitude.
+
+import type { Capabilities, ColorLevel } from "./capability.js";
+import type { Color, Frame, Style } from "./cells.js";
+import { Attributes, INHERIT, PLAIN, sameSize } from "./cells.js";
+
+/**
+ * How many unchanged cells are worth writing through rather than jumping over.
+ *
+ * Four: a cursor move is at least six bytes and a plain unchanged cell is one,
+ * so the break-even is around six — but the cells being written through also
+ * have to carry their style, so the real figure is lower. Four is measured on
+ * the frames this package's own tests produce rather than derived.
+ */
+const JOIN_GAP = 4;
+
+/** What one diff produced, and what it cost. */
+export type Update = {
+  /** The bytes to write to the terminal. Empty when nothing changed. */
+  readonly output: string,
+  /** How many cells were re-sent. The number the performance claim is about. */
+  readonly cells: number,
+};
+
+/**
+ * Move the cursor to a zero-based cell.
+ *
+ * Terminals count rows and columns from one, and every off-by-one bug in a
+ * renderer's first week is this one. The escape is written as `\u001b` rather
+ * than as a literal control byte because a literal one is invisible in every
+ * editor and diff, which is how one gets deleted.
+ */
+const moveTo = (x: number, y: number): string => `\u001b[${y + 1};${x + 1}H`;
+
+/** Reset every attribute and colour. */
+const RESET = "\u001b[0m";
+
+/**
+ * The bytes that turn `previous` into `next`.
+ *
+ * A `null` previous frame, or one of a different size, means a full repaint:
+ * the terminal was just entered or has just been resized, and there is nothing
+ * on it this renderer can claim to know.
+ */
+export function diffFrames(
+  previous: Frame | null,
+  next: Frame,
+  capabilities: Capabilities,
+): Update {
+  const full = previous == null || !sameSize(previous, next);
+  let output = "";
+  let cells = 0;
+  let current: Style = PLAIN;
+  let styled = false;
+
+  for (let y = 0; y < next.height; y += 1) {
+    let x = 0;
+    while (x < next.width) {
+      if (!full && !changed(previous, next, y * next.width + x)) {
+        x += 1;
+        continue;
+      }
+      // The end of this run: the last changed cell, plus any unchanged cells
+      // close enough behind it that jumping over them would cost more.
+      let end = x;
+      let scan = x;
+      while (scan < next.width) {
+        if (full || changed(previous, next, y * next.width + scan)) {
+          end = scan;
+          scan += 1;
+        } else {
+          let gap = 0;
+          while (scan + gap < next.width && !changedOrFull(full, previous, next, y, scan + gap)) {
+            gap += 1;
+          }
+          if (gap > JOIN_GAP || scan + gap >= next.width) {
+            break;
+          }
+          scan += gap;
+        }
+      }
+
+      output += moveTo(x, y);
+      for (let column = x; column <= end; column += 1) {
+        const index = y * next.width + column;
+        const character = next.chars[index];
+        if (character === "") {
+          // A continuation cell. Its cluster was emitted by the cell to its
+          // left, and the terminal has already moved the cursor over it.
+          continue;
+        }
+        const style: Style = {
+          fg: next.fg[index],
+          bg: next.bg[index],
+          attributes: next.attributes[index],
+        };
+        if (!sameStyle(style, current)) {
+          const sequence = sgr(style, capabilities.color);
+          if (sequence !== "") {
+            output += sequence;
+            styled = true;
+          } else if (styled) {
+            output += RESET;
+            styled = false;
+          }
+          current = style;
+        }
+        output += character;
+        cells += 1;
+      }
+      x = end + 1;
+    }
+  }
+
+  if (styled) {
+    output += RESET;
+  }
+  return { output, cells };
+}
+
+const changedOrFull = (
+  full: boolean,
+  previous: Frame | null,
+  next: Frame,
+  y: number,
+  x: number,
+): boolean => full || changed(previous, next, y * next.width + x);
+
+function changed(previous: Frame | null, next: Frame, index: number): boolean {
+  if (previous == null) {
+    return true;
+  }
+  return (
+    previous.chars[index] !== next.chars[index] ||
+    previous.fg[index] !== next.fg[index] ||
+    previous.bg[index] !== next.bg[index] ||
+    previous.attributes[index] !== next.attributes[index]
+  );
+}
+
+const sameStyle = (a: Style, b: Style): boolean =>
+  a.fg === b.fg && a.bg === b.bg && a.attributes === b.attributes;
+
+/**
+ * The escape sequence that selects `style`.
+ *
+ * Empty at `"none"`, and that is the whole of the no-colour answer: a terminal
+ * that cannot carry colour also cannot carry bold or underline, because both
+ * are the same SGR mechanism and a `TERM=dumb` terminal prints them as
+ * literal text. The frame's *shape* still arrives — the layout, the borders in
+ * their ASCII vocabulary, the text — which is the part a reader needs.
+ */
+export function sgr(style: Style, level: ColorLevel): string {
+  if (level === "none") {
+    return "";
+  }
+  const parts: Array<string> = ["0"];
+  const attributes = style.attributes;
+  if (attributes & Attributes.BOLD) parts.push("1");
+  if (attributes & Attributes.DIM) parts.push("2");
+  if (attributes & Attributes.ITALIC) parts.push("3");
+  if (attributes & Attributes.UNDERLINE) parts.push("4");
+  if (attributes & Attributes.BLINK) parts.push("5");
+  if (attributes & Attributes.INVERSE) parts.push("7");
+  if (attributes & Attributes.STRIKETHROUGH) parts.push("9");
+  if (style.fg !== INHERIT) {
+    parts.push(colorParts(style.fg, level, false));
+  }
+  if (style.bg !== INHERIT) {
+    parts.push(colorParts(style.bg, level, true));
+  }
+  if (parts.length === 1) {
+    return "";
+  }
+  return `\u001b[${parts.join(";")}m`;
+}
+
+/**
+ * One colour, at the depth this terminal has.
+ *
+ * The downgrade is deliberate rather than a fallback to "no colour at all". A
+ * theme written in 24-bit values still has to mean something on a
+ * sixteen-colour terminal, and the nearest colour in the smaller palette is a
+ * far better answer than none — this is the same ladder
+ * `crates/uf_term/src/style.rs` walks for the CLI's own output.
+ */
+function colorParts(color: Color, level: ColorLevel, background: boolean): string {
+  const r = (color >> 16) & 0xff;
+  const g = (color >> 8) & 0xff;
+  const b = color & 0xff;
+  if (level === "truecolor") {
+    return `${background ? 48 : 38};2;${r};${g};${b}`;
+  }
+  if (level === "ansi256") {
+    return `${background ? 48 : 38};5;${cube(r, g, b)}`;
+  }
+  const base = nearestBasic(r, g, b);
+  const offset = background ? 40 : 30;
+  return base < 8 ? `${offset + base}` : `${offset + 60 + (base - 8)}`;
+}
+
+/** The 256-colour index nearest to an RGB triple. */
+function cube(r: number, g: number, b: number): number {
+  // The 24-step grey ramp is a better match than the colour cube whenever the
+  // three channels are close, and grey text is common enough — every dimmed
+  // hint in every CLI — that getting it wrong is visible.
+  if (Math.abs(r - g) < 8 && Math.abs(g - b) < 8) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return 232 + Math.round(((r - 8) / 247) * 24);
+  }
+  const step = (value: number) => Math.round((value / 255) * 5);
+  return 16 + 36 * step(r) + 6 * step(g) + step(b);
+}
+
+/** The 16 base colours, as RGB, in SGR order. */
+const BASIC: $ReadOnlyArray<[number, number, number]> = [
+  [0, 0, 0],
+  [205, 0, 0],
+  [0, 205, 0],
+  [205, 205, 0],
+  [0, 0, 238],
+  [205, 0, 205],
+  [0, 205, 205],
+  [229, 229, 229],
+  [127, 127, 127],
+  [255, 0, 0],
+  [0, 255, 0],
+  [255, 255, 0],
+  [92, 92, 255],
+  [255, 0, 255],
+  [0, 255, 255],
+  [255, 255, 255],
+];
+
+/** The base colour closest to an RGB triple, by squared distance. */
+function nearestBasic(r: number, g: number, b: number): number {
+  let best = 0;
+  let bestDistance = Number.MAX_SAFE_INTEGER;
+  for (let index = 0; index < BASIC.length; index += 1) {
+    const [cr, cg, cb] = BASIC[index];
+    const distance = (cr - r) ** 2 + (cg - g) ** 2 + (cb - b) ** 2;
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = index;
+    }
+  }
+  return best;
+}

package/index.js

@@ -0,0 +1,206 @@
+// @flow
+//
+// `@uniflowed/tui`: a React renderer whose host is a terminal.
+//
+// It follows OpenTUI, which is the terminal-UI library uf's declaration named
+// as its standard: the same component vocabulary, the same flexbox defaults
+// (`flexDirection` starts at `"column"`), the same canonical key names
+// (`"return"`, not `"enter"`), the same rule that focus is a prop rather than
+// a Tab traversal the library performs for you, and the same split between a
+// root that owns a React tree and a renderer that owns a terminal. A component
+// written against OpenTUI's documentation behaves the same way here, which is
+// the only thing "compatible with a standard" can usefully mean.
+//
+// # The decision: this is JavaScript, and the declaration used to say Rust
+//
+// The declaration this package replaced said `engine:
+// "uf-native-open-tui-compatible"` and `renderer: "cell-diff-native"`, which
+// is a promise that the renderer would be Rust with a binding. It is not, and
+// this is the argument, because "faster than Ink" and "no native bindings"
+// genuinely pull in opposite directions and the reason to pick one belongs in
+// the source rather than in a pull request nobody will read again.
+//
+// **Rust was rejected for three reasons, in order of weight.**
+//
+// *First, there is no bridge, and building one is a bigger and different
+// project than this.* Every `nativeRuntimeRequired` in `packages/` is a
+// promise of a JavaScript-to-native boundary that this repository does not
+// have: no Node-API addon, no FFI, no prebuilt platform binaries, no loader.
+// Choosing Rust here would have meant that the first deliverable was that
+// bridge and the second was a renderer, and until both existed
+// `@uniflowed/tui` would still have been a declaration. Replacing one
+// declaration with a differently-worded declaration is exactly the outcome
+// ubugeeei-prod/uf#247 exists to prevent.
+//
+// *Second, the rule that keeps Effect and Validator in Flow applies here for
+// its own reason rather than by its letter.* `ubugeeei-redundancy.md` names
+// Effect, Validator, state, immutable updates, forms, hooks and UI, and does
+// not name the TUI — but the reason it names them is that application-facing
+// libraries get *deployed*, to browsers and edge workers where a Rust binary
+// cannot go. A terminal application is the one case where that argument is
+// weakest: it runs where a terminal is, and a machine with a terminal can run
+// a binary. What survives is the smaller version of the same point. A native
+// dependency means prebuilt binaries for every platform uf supports, a
+// fallback for the ones it does not, and an `npm install` that can fail in a
+// way a Flow package cannot — for a library whose whole job runs at human
+// reading speed.
+//
+// *Third, and most concretely: the thing that makes a terminal UI slow is not
+// JavaScript.* The guide's native-hot-path rule is about "repeated,
+// repository-wide or CPU-intensive work", and says the execution phase decides
+// the boundary. This executes in one process, at one terminal's size, at the
+// rate a person presses keys. An 80×24 terminal is 1,920 cells; a large one is
+// 12,000. Laying out and painting that is microseconds in any language. What
+// costs milliseconds is the bytes handed to the terminal, because the emulator
+// on the other end parses and re-renders them — which is why React Ink,
+// written in JavaScript and using WebAssembly Yoga for the part that is
+// supposedly slow, is slow for a reason neither of those explains: it renders
+// to a *string* and reprints from the first changed line to the bottom of the
+// frame. `diff.js` writes the cells that changed and nothing else, and that is
+// an algorithm, not a language.
+//
+// The honest cost of this decision is written down rather than hidden: this
+// package depends on `react-reconciler`, which React publishes for custom
+// renderers and calls experimental, and which pins itself to a React minor.
+// `internal/host.js` says what that means for a React upgrade.
+//
+// # What is here, and what is not
+//
+// Implemented, tested, and true: a component tree, flexbox layout in whole
+// cells, a cell buffer with correct wide-grapheme handling, a diff that emits
+// only changed cells, keyboard input with OpenTUI's key names and propagation
+// rules, bracketed paste, declarative focus, mouse input — press, release,
+// hover, drag with capture, drop and wheel, routed by a hit grid the painter
+// records — text selection by drag, one per renderer, read back with
+// `getSelectedText()`, a scrolling window onto content taller than it,
+// terminal capability and *size* detection that agrees with the CLI's, and an
+// in-memory renderer that runs the same code the terminal one does.
+//
+// Not here: key *release* (which needs the Kitty keyboard protocol), the
+// repeated-press gestures that widen a selection to a word or a line, images,
+// the rich content components, and everything under OpenTUI's "application
+// APIs" — including the clipboard, which is why `getSelectedText()` hands a
+// string back rather than putting it somewhere. They are
+// ubugeeei-prod/uf#314, and they are absent rather than present as functions
+// that throw — because a stub is what this package used to be.
+//
+// Also not here, and worth saying because ubugeeei-prod/uf#247 asked for it:
+// uf's own CLI does not draw through this. It cannot — `crates/uf_term` is
+// Rust, this is JavaScript, and there is no way to run a Flow program in this
+// repository outside `uf test`, `uf dev` and `uf build`. ubugeeei-prod/uf#316
+// is that gap, what would close it, and why the two renderers are each right
+// for their own caller in the meantime. `tools/bench/tui/startup.js` now
+// measures the number that issue says has to exist first: a Flow entry point
+// that draws one frame costs 149 ms with a warm transform cache and 383 ms
+// with a cold one, against 8 ms for the whole of `uf info` and 58 ms for
+// `node -e 0`. A banner cannot be written this way; a session that already
+// starts Node and then runs for minutes can.
+//
+// What the two renderers must not do is silently disagree about the terminal,
+// and there are three guards rather than a promise. `capability.js` reproduces
+// `crates/uf_term/src/capability.rs`'s colour precedence and its size
+// precedence, `widths.js` holds the same Unicode tables as
+// `crates/uf_term/src/text/tables.rs`, and `tests/library/tui.test.js` reads
+// both Rust files and fails when either side is edited alone.
+//
+// # How the package is laid out
+//
+// Bottom to top, each module named for the one question it answers:
+//
+// - `widths.js` — how many columns a grapheme occupies.
+// - `cells.js` — what a frame is: the grid, the colours, the continuation cell.
+// - `layout.js` — flexbox, in whole cells.
+// - `diff.js` — two frames, as the bytes that turn one into the other.
+// - `keys.js` — terminal bytes, as key events, and a paste as one of them.
+// - `mouse.js` — the other half of that stream: what the pointer did.
+// - `selection.js` — what a drag over the frame selected, as two cells.
+// - `capability.js` — what this terminal can render and how big it is, by the
+//   CLI's own rules.
+// - `terminal.js` — a real terminal, and the in-memory one tests use.
+// - `components.js` — `Box`, `Text`, `Input`, `ScrollBox`, and the hooks.
+//
+// `internal/` holds the four that a consumer must not be able to reach past:
+// `tree.js` (props become a layout style once, here), `paint.js` (both passes
+// must break lines the same way), `hits.js` (what is under the pointer is only
+// true for the frame that recorded it) and `host.js` (one React root, one
+// terminal, one owner). Each says so in its own header. There is no
+// `internal/util.js`: a module that cannot say what it is about does not
+// belong in this package.
+
+export type {
+  BorderGlyphs,
+  BorderStyle,
+  Capabilities,
+  ColorChoice,
+  ColorLevel,
+  GlyphSet,
+  TerminalEnv,
+  TerminalReport,
+  TerminalSize,
+  Tty,
+} from "./capability.js";
+export {
+  FALLBACK_COLUMNS,
+  FALLBACK_ROWS,
+  borderGlyphs,
+  detectCapabilities,
+  detectSize,
+  plainCapabilities,
+} from "./capability.js";
+
+export type { Color, Frame, Rect, Style } from "./cells.js";
+export { Attributes, INHERIT, frameRow, frameText, parseColor } from "./cells.js";
+
+export type {
+  AlignItems,
+  AlignSelf,
+  Dimension,
+  FlexDirection,
+  JustifyContent,
+  LayoutStyle,
+  Overflow,
+} from "./layout.js";
+
+export type { WrapMode } from "./internal/paint.js";
+
+export type { Update } from "./diff.js";
+
+export type { InputDecoder, InputEvent, KeyEvent, KeySource } from "./keys.js";
+export { createInputDecoder, decodeInput, decodeKeys } from "./keys.js";
+
+export type { MouseEvent, MouseEventType, Scroll, ScrollDirection } from "./mouse.js";
+export { MouseButton } from "./mouse.js";
+
+export type { Selection, SelectionPoint } from "./selection.js";
+// `selectionContains` and not `selectionBetween`: the first answers a question
+// a caller has about a selection the renderer handed them, and the second
+// builds one, which is the renderer's job — there is no way to hand a
+// selection *back*, and an export that produced a value nothing accepts would
+// be a promise that there is.
+export { selectionContains } from "./selection.js";
+
+export type { Renderer, Root } from "./internal/host.js";
+
+export type { Handle, InputStream, OutputStream, RenderOptions, TestHandle } from "./terminal.js";
+export { render, testRender } from "./terminal.js";
+
+export type {
+  BoxLayoutProps,
+  BoxProps,
+  ColorValue,
+  InputProps,
+  MouseProps,
+  ScrollBoxProps,
+  TextProps,
+  TextStyleProps,
+  TitleAlignment,
+} from "./components.js";
+export {
+  Box,
+  Input,
+  ScrollBox,
+  Text,
+  useKeyboard,
+  useRenderer,
+  useTerminalSize,
+} from "./components.js";

package/internal/hits.js

@@ -0,0 +1,156 @@
+// @flow
+//
+// What is under the pointer, and what a drag over it would select.
+//
+// # Internal to `@uniflowed/tui`
+//
+// Absent from `package.json#exports`, and for the same reason `tree.js` is:
+// the answer here is only correct for the frame that produced it. A grid held
+// across a commit points at nodes React has already replaced, and a consumer
+// that could keep one would be asking "what was under the pointer one frame
+// ago" while believing it asked something else.
+//
+// # Why a grid rather than walking the tree
+//
+// The obvious implementation of a hit test is to walk the tree looking for the
+// deepest node whose box contains the point. It gives the wrong answer here,
+// twice. A node that a scrolling ancestor put outside its window still has
+// last frame's geometry on it, so a walk finds boxes that are not on the
+// screen; and `overflow: "hidden"` clips a child to its parent, so a box whose
+// geometry contains the point may have been drawn nowhere near it.
+//
+// Both of those are already solved once — by the painter, whose clip rectangle
+// is exactly "the cells this node was allowed to write". So the hit test is
+// recorded *during* the paint that answers those questions, and reading it is
+// one array index. Overlap resolves the way the picture does: the node painted
+// last is the node on top, because it wrote the cell last.
+//
+// The grid costs one entry per cell of the frame — 1,920 of them on an 80×24
+// terminal — and is built only when a renderer has mouse reporting on, so an
+// application that does not use the mouse pays nothing for it.
+//
+// # Two answers, one walk
+//
+// A second array rides along, and it answers a second question: which cells
+// hold text a reader is allowed to select. It is here rather than in a grid of
+// its own because it is the same question asked of the same walk — *who wrote
+// this cell* — and because both answers are only true of the frame that
+// produced them, which is the whole reason this module is internal. Two grids
+// would be two allocations and two chances to keep one of them a frame too
+// long.
+//
+// They are separate arrays rather than one, because the two answers are about
+// different nodes and resolve differently. A hit is the innermost *box*, and a
+// box claims its whole rectangle whether it painted anything into it. A
+// selectable cell is the `<Text>` whose grapheme is actually in that cell, and
+// only where one is: a box's background is not text, so `recordHit` clears the
+// text array over the area it claims, and the painter fills it back in for
+// each cluster it writes. Last writer wins, exactly as it does in the frame.
+
+import type { Rect } from "../cells.js";
+import { intersect } from "../cells.js";
+import type { TuiNode } from "./tree.js";
+
+/** The node that owns each cell of one frame. */
+export type HitGrid = {
+  readonly width: number,
+  readonly height: number,
+  /** One entry per cell, row-major, `null` where nothing was drawn. */
+  readonly nodes: Array<TuiNode | null>,
+  /**
+   * The selectable `<Text>` whose grapheme is in each cell, or `null`.
+   *
+   * `null` covers three different cells and deliberately does not distinguish
+   * them: one nothing was drawn in, one a box's background or border owns, and
+   * one holding text that said `selectable={false}`. Nothing routed by this
+   * array cares which — a drag selects a cell or it does not.
+   */
+  readonly text: Array<TuiNode | null>,
+};
+
+/** An empty grid the size of a frame. */
+export function createHitGrid(width: number, height: number): HitGrid {
+  const size = width * height;
+  return {
+    width,
+    height,
+    nodes: new Array(size).fill(null),
+    text: new Array(size).fill(null),
+  };
+}
+
+/**
+ * Claim every cell of `area` that `clip` allows for `node`.
+ *
+ * Called by the painter as it descends, so a child overwrites its parent and
+ * a later sibling overwrites an earlier one — which is the order they are
+ * drawn in, and therefore the order a reader sees them stacked.
+ *
+ * It also *un*claims those cells for selection, because a box is about to
+ * paint over them: the text array is filled in afterwards by the clusters this
+ * box's descendants write. Without it a panel dropped over a paragraph would
+ * leave the paragraph selectable through its background — text a reader can no
+ * longer see, in a copy they did not expect it in.
+ */
+export function recordHit(grid: HitGrid, node: TuiNode, area: Rect, clip: Rect): void {
+  const box = intersect(clip, area);
+  const right = Math.min(grid.width, box.x + box.width);
+  const bottom = Math.min(grid.height, box.y + box.height);
+  for (let y = Math.max(0, box.y); y < bottom; y += 1) {
+    const row = y * grid.width;
+    for (let x = Math.max(0, box.x); x < right; x += 1) {
+      grid.nodes[row + x] = node;
+      grid.text[row + x] = null;
+    }
+  }
+}
+
+/**
+ * Say that `node`'s text occupies `width` columns from `x`, `y`.
+ *
+ * The two guards are `writeGrapheme`'s, repeated rather than shared, and the
+ * reason is what this array means: a cell a clip refused is a cell the node
+ * did not write, so it is not a cell the node owns. Deriving that from the
+ * write itself would be better, but `writeGrapheme` reports the columns a
+ * caller should advance by whether or not it wrote anything — it has to, or a
+ * clipped line would come out with its remaining clusters bunched up.
+ *
+ * `node` may be `null`, which is how the painter takes a cell back for
+ * something that is not selectable text — a scrollbar drawn over a line that
+ * ran into its column.
+ */
+export function recordText(
+  grid: HitGrid,
+  node: TuiNode | null,
+  x: number,
+  y: number,
+  width: number,
+  clip: Rect,
+): void {
+  if (y < clip.y || y >= clip.y + clip.height || y < 0 || y >= grid.height) {
+    return;
+  }
+  if (x < clip.x || x + width > clip.x + clip.width || x < 0 || x + width > grid.width) {
+    return;
+  }
+  const row = y * grid.width;
+  for (let column = x; column < x + width; column += 1) {
+    grid.text[row + column] = node;
+  }
+}
+
+/** The topmost node at a cell, or `null` when the pointer is over nothing. */
+export function hitAt(grid: HitGrid, x: number, y: number): TuiNode | null {
+  if (x < 0 || y < 0 || x >= grid.width || y >= grid.height) {
+    return null;
+  }
+  return grid.nodes[y * grid.width + x];
+}
+
+/** The selectable text node at a cell, or `null` when there is none. */
+export function textAt(grid: HitGrid, x: number, y: number): TuiNode | null {
+  if (x < 0 || y < 0 || x >= grid.width || y >= grid.height) {
+    return null;
+  }
+  return grid.text[y * grid.width + x];
+}