@uniflowed/tui 0.0.0-alpha.18

package/terminal.js

@@ -0,0 +1,457 @@
+// @flow
+//
+// The two things you can point a rendered tree at: a terminal, or memory.
+//
+// Everything below this module is a pure function of a tree and a size.
+// Everything a real terminal needs — raw mode, an alternate screen, a resize
+// signal, bytes on a file descriptor — is here and nowhere else, which is what
+// makes the in-memory renderer a first-class way to run an application rather
+// than a mock of one. `testRender` and `render` mount the same tree through
+// the same reconciler and produce the same frames; they differ in where the
+// frames go and in who presses the keys.
+//
+// # Why the cursor is never used to draw
+//
+// `crates/uf_term/src/prompt/draw.rs` ends every line of its frames with
+// `\r\n` and explains why: raw mode turns off the mapping that makes a bare
+// line feed also return to column zero, so a menu drawn with `\n` walks off
+// the right edge one row at a time. This renderer avoids that class of bug by
+// never writing a newline at all. Every cell it writes is preceded by an
+// absolute cursor position, so no frame depends on where the cursor was left,
+// on whether the terminal wraps at the right margin, or on the line-ending
+// translation the mode happens to be in.
+//
+// # A terminal nobody is watching gets text, not escapes
+//
+// Piping a TUI into a file or a CI log has one sensible answer, and it is not
+// "the same escape sequences". A log is read afterwards, in order, by
+// something that does not implement cursor addressing — so an incremental
+// renderer writing into one produces a file full of `ESC[12;40H`. Here, a
+// non-interactive stream gets no escapes and no incremental updates at all:
+// the final frame is written once, as plain lines, when the application stops.
+// That is the same answer `uf_term`'s progress bars give, for the same reason.
+
+import * as React from "@uniflowed/react";
+
+import type { Capabilities, ColorChoice, TerminalEnv } from "./capability.js";
+import { FALLBACK_COLUMNS, FALLBACK_ROWS, detectCapabilities, detectSize } from "./capability.js";
+import type { Frame } from "./cells.js";
+import { frameText } from "./cells.js";
+import type { Update } from "./diff.js";
+import type { Renderer } from "./internal/host.js";
+import {
+  RendererContext,
+  createRenderer,
+  createRoot,
+  nextUpdate,
+  pressKey,
+  pressMouse,
+  renderFrame,
+  resize,
+} from "./internal/host.js";
+import type { InputEvent } from "./keys.js";
+import { createInputDecoder } from "./keys.js";
+import type { Selection } from "./selection.js";
+
+/** Enter the alternate screen buffer, so the shell's scrollback survives. */
+const ENTER_ALTERNATE = "\u001b[?1049h";
+/** Leave it, putting back whatever the reader was looking at. */
+const LEAVE_ALTERNATE = "\u001b[?1049l";
+/** Hide the terminal's own cursor; the frame draws its own where it wants one. */
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+/** Clear the screen and put the cursor at the top left. */
+const CLEAR = "\u001b[2J\u001b[H";
+/**
+ * Ask the terminal to bracket pasted text.
+ *
+ * Without this a paste is indistinguishable from very fast typing, which is
+ * how pasting two lines into a prompt runs the first one: the `\r` between
+ * them is delivered as Enter. With it the text arrives wrapped in `ESC[200~`
+ * and `ESC[201~`, and `keys.js` turns the whole block into one `"paste"`
+ * event. Turned off again on the way out, because a terminal left in this mode
+ * hands the *shell* its own escape sequences around every paste.
+ */
+const ENABLE_PASTE = "\u001b[?2004h";
+const DISABLE_PASTE = "\u001b[?2004l";
+/**
+ * Ask the terminal to report the mouse, in the four modes that answer.
+ *
+ * `?1000h` turns reporting on at all — presses and releases. `?1002h` adds
+ * motion while a button is held, which is what makes a drag a sequence rather
+ * than a press and a release somewhere else. `?1003h` adds motion with nothing
+ * held, which is the only way `over` and `out` can fire before a reader has
+ * clicked anything; it is the expensive one, since crossing the screen is a
+ * report per cell, and it is included because a hover that only worked
+ * mid-drag would not be a hover. `?1006h` asks for the SGR encoding, which is
+ * the one `mouse.js` decodes and the only one that works past column 223.
+ *
+ * Turned off in the reverse order on the way out, and turned on only when the
+ * application asked for the mouse: a terminal in these modes stops doing its
+ * own click-and-drag text selection, so an application that does not read the
+ * mouse must not take that away from the reader.
+ */
+const ENABLE_MOUSE = "\u001b[?1000h\u001b[?1002h\u001b[?1003h\u001b[?1006h";
+const DISABLE_MOUSE = "\u001b[?1006l\u001b[?1003l\u001b[?1002l\u001b[?1000l";
+
+/** What `render` gives back. */
+export type Handle = {
+  /** Put the terminal back the way it was found and unmount the tree. */
+  stop(): void,
+  /** The frame currently on the screen. */
+  frame(): Frame,
+  /** That frame as text, which is what a snapshot asserts on. */
+  text(): string,
+  /**
+   * What the reader has selected with the mouse, or `""`.
+   *
+   * The same answer `useRenderer().getSelectedText()` gives a component, from
+   * outside the tree — which is where the caller wiring it to a clipboard
+   * usually is, since a program that wants to copy on Ctrl+C has a signal
+   * handler and not a component. `selection()` is the gesture behind it, for
+   * an application that wants to say something about how far it reaches.
+   */
+  selectedText(): string,
+  /** The reader's selection, or `null` when there is none. */
+  selection(): Selection | null,
+};
+
+/** What `testRender` gives back: a `Handle`, plus the terminal's side. */
+export type TestHandle = {
+  ...Handle,
+  /** Feed raw terminal input, as a terminal would deliver it. */
+  press(input: string): void,
+  /** Draw the next frame and report what writing it would cost. */
+  update(): Update,
+  /** Resize the terminal, discarding what was on it. */
+  resize(width: number, height: number): void,
+  /** Every update produced since mounting, in order. */
+  updates(): $ReadOnlyArray<Update>,
+};
+
+/** Anything that can be written to; `process.stdout`, or a string collector. */
+export type OutputStream = {
+  write(chunk: string): mixed,
+  readonly columns?: number,
+  readonly rows?: number,
+  readonly isTTY?: boolean,
+  /** A real `process.stdout` emits `"resize"`; a string collector does not. */
+  on?: (event: string, listener: () => mixed) => mixed,
+  off?: (event: string, listener: () => mixed) => mixed,
+  ...
+};
+
+/** Anything keys arrive from; `process.stdin`. */
+export type InputStream = {
+  readonly isTTY?: boolean,
+  setRawMode?: (raw: boolean) => mixed,
+  resume?: () => mixed,
+  pause?: () => mixed,
+  setEncoding?: (encoding: string) => mixed,
+  on?: (event: string, listener: (chunk: string) => mixed) => mixed,
+  off?: (event: string, listener: (chunk: string) => mixed) => mixed,
+  ...
+};
+
+/** How to mount onto a real terminal. */
+export type RenderOptions = {
+  readonly stdin?: InputStream,
+  readonly stdout?: OutputStream,
+  /** `--color`, when the application has such a flag. */
+  readonly color?: ColorChoice,
+  /** The environment to detect from. Defaults to the process's. */
+  readonly env?: TerminalEnv,
+  /**
+   * Whether to take over the whole screen.
+   *
+   * On by default because a full-screen application that scrolls the shell's
+   * history away has destroyed something it cannot put back. Off for an
+   * application that wants to leave its last frame in the scrollback, which is
+   * what a progress display wants.
+   */
+  readonly alternateScreen?: boolean,
+  /**
+   * Whether to ask the terminal to report the mouse.
+   *
+   * Off by default, which is a deliberate difference from OpenTUI's renderer.
+   * Mouse reporting is not free to a *reader*: a terminal in it stops handling
+   * click-and-drag itself, so selecting a line to copy out of an application
+   * that ignores the mouse anyway needs a modifier key the reader has to know
+   * about. An application that handles the mouse is trading that away on
+   * purpose; one that does not should not trade it away by default.
+   *
+   * What it trades it away *for* is this renderer's own selection, which
+   * arrives with the mouse and not separately: a drag over selectable text
+   * highlights it and `getSelectedText()` reads it back. That is a smaller
+   * promise than the terminal's, because the text it can offer is the text on
+   * the screen — but it is the same gesture, so a reader does not have to be
+   * told that this window is the one where dragging does nothing.
+   */
+  readonly mouse?: boolean,
+};
+
+/**
+ * Hand one decoded event to the renderer.
+ *
+ * The two drivers — a terminal and a test — read the same decoder and so face
+ * the same union, and routing it in one place is what keeps them from drifting
+ * into two answers about what a mouse report does.
+ */
+function deliver(renderer: Renderer, event: InputEvent): void {
+  if (event.kind === "mouse") {
+    pressMouse(renderer, event);
+    return;
+  }
+  pressKey(renderer, event);
+}
+
+/** Mount a tree into a renderer and return the pieces both drivers need. */
+function mount(element: React.Node, renderer: Renderer) {
+  const root = createRoot(renderer);
+  root.render(React.createElement(RendererContext.Provider, { value: renderer }, element));
+  return root;
+}
+
+/**
+ * Render into memory.
+ *
+ * The way an application is *tested*, and the way one is rendered anywhere
+ * that is not a terminal. No environment is read, no stream is touched, and
+ * the capabilities are the caller's to choose — which is the point: a test
+ * asserting how a box degrades on a terminal with no colour should not have to
+ * arrange for the machine running it to have no colour.
+ */
+export function testRender(
+  element: React.Node,
+  options: {
+    readonly width?: number,
+    readonly height?: number,
+    readonly capabilities?: Capabilities,
+    readonly mouse?: boolean,
+  } = {},
+): TestHandle {
+  const width = options.width ?? FALLBACK_COLUMNS;
+  const height = options.height ?? FALLBACK_ROWS;
+  const capabilities: Capabilities = options.capabilities ?? {
+    color: "truecolor",
+    glyphs: "unicode",
+    tty: "interactive",
+  };
+  // On by default here and off in `render`, and the difference is the whole
+  // reason the option exists: what `render` weighs is a terminal it would take
+  // click-and-drag selection away from, and there is no terminal here. A test
+  // that presses the mouse should not have to remember to enable it, and one
+  // that wants to assert an application ignores the mouse can say so.
+  const renderer = createRenderer(width, height, capabilities, options.mouse ?? true);
+  const root = mount(element, renderer);
+  const produced: Array<Update> = [];
+
+  // The same decoder a real terminal driver holds, for the same reason: a
+  // test that delivers a paste in two `press` calls is testing what an
+  // operating system does to a large one.
+  const decoder = createInputDecoder();
+
+  const handle: TestHandle = {
+    press(input: string) {
+      for (const event of decoder.push(input)) {
+        deliver(renderer, event);
+      }
+    },
+    update() {
+      const next = nextUpdate(renderer);
+      produced.push(next);
+      return next;
+    },
+    updates() {
+      return produced;
+    },
+    resize(nextWidth: number, nextHeight: number) {
+      resize(renderer, nextWidth, nextHeight);
+    },
+    frame() {
+      return renderFrame(renderer);
+    },
+    text() {
+      return frameText(renderFrame(renderer));
+    },
+    selectedText() {
+      return renderer.getSelectedText();
+    },
+    selection() {
+      return renderer.getSelection();
+    },
+    stop() {
+      root.unmount();
+    },
+  };
+  return handle;
+}
+
+/**
+ * Render onto a terminal.
+ *
+ * Returns as soon as the first frame is on the screen; the application keeps
+ * running because stdin is open, and stops when the caller calls `stop()`.
+ * That is deliberate — a `render` that never returned would make the calling
+ * program unable to do anything else, including install the signal handler
+ * that has to call `stop()`.
+ */
+export function render(element: React.Node, options: RenderOptions = {}): Handle {
+  // Three casts, and the same reason for all of them: Flow's library
+  // definition for `process` describes Node's classes, and these types
+  // describe the three things this renderer actually needs — so that a test
+  // can pass a string collector, and so that a runtime whose streams are not
+  // Node's is not excluded by a type. The narrowing is checked at run time by
+  // the `!= null` guards below rather than trusted.
+  const stdout: OutputStream = options.stdout ?? (process.stdout: $FlowFixMe);
+  const stdin: InputStream = options.stdin ?? (process.stdin: $FlowFixMe);
+  const env: TerminalEnv = options.env ?? (process.env: $FlowFixMe);
+  const capabilities = detectCapabilities(
+    options.color ?? "auto",
+    stdout.isTTY === true ? "interactive" : "piped",
+    env,
+  );
+  const interactive = capabilities.tty === "interactive";
+  const alternateScreen = (options.alternateScreen ?? true) && interactive;
+
+  // How big the terminal is, by the same rules `uf`'s own CLI resolves it
+  // with: `COLUMNS`/`LINES` first, then what the stream reports, then 80 by
+  // 24. Reading `stdout.columns` alone was one of the two renderers deciding
+  // the terminal's shape its own way — the thing the other duplications in
+  // this package exist to prevent.
+  const size = detectSize(env, stdout);
+  const mouse = (options.mouse ?? false) && interactive;
+  const renderer = createRenderer(size.columns, size.rows, capabilities, mouse);
+
+  let stopped = false;
+  let scheduled = false;
+
+  const draw = () => {
+    if (stopped || !interactive) {
+      return;
+    }
+    const update = nextUpdate(renderer);
+    if (update.output !== "") {
+      stdout.write(update.output);
+    }
+  };
+
+  // One draw per turn of the event loop, however many commits happened in it.
+  // A component that sets three pieces of state in one handler commits three
+  // times, and drawing three frames means writing two of them to a terminal
+  // nobody ever saw.
+  renderer.onCommit = () => {
+    if (scheduled || stopped) {
+      return;
+    }
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      draw();
+    });
+  };
+
+  if (interactive) {
+    stdout.write(
+      (alternateScreen ? ENTER_ALTERNATE : "") +
+        HIDE_CURSOR +
+        ENABLE_PASTE +
+        (mouse ? ENABLE_MOUSE : "") +
+        CLEAR,
+    );
+  }
+
+  const decoder = createInputDecoder();
+  const onData = (chunk: string) => {
+    for (const event of decoder.push(String(chunk))) {
+      deliver(renderer, event);
+    }
+    draw();
+  };
+
+  const onResize = () => {
+    // Resolved again rather than read off the stream, so that an application
+    // told its size explicitly keeps it. `process.env` is a snapshot taken
+    // when the process started and a shell does not export `COLUMNS` anyway,
+    // so this only pins the size for somebody who set it on purpose.
+    const next = detectSize(env, stdout);
+    resize(renderer, next.columns, next.rows);
+    draw();
+  };
+
+  const root = mount(element, renderer);
+  draw();
+
+  if (interactive && stdin.on != null) {
+    if (stdin.isTTY === true && stdin.setRawMode != null) {
+      stdin.setRawMode(true);
+    }
+    if (stdin.setEncoding != null) {
+      stdin.setEncoding("utf8");
+    }
+    if (stdin.resume != null) {
+      stdin.resume();
+    }
+    stdin.on("data", onData);
+  }
+  if (interactive && stdout.on != null) {
+    stdout.on("resize", onResize);
+  }
+
+  return {
+    stop() {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      // The last frame, read *before* the tree comes down. Unmounting empties
+      // the tree, and a frame rendered from an empty tree is a rectangle of
+      // spaces — which is exactly what a redirected stream received until this
+      // line existed, and exactly what no test that only drove a terminal
+      // would have noticed.
+      const farewell = interactive ? "" : `${frameText(renderFrame(renderer))}\n`;
+      // The tree comes down before the terminal is restored, so that effect
+      // cleanups run while the terminal is still in the state they were set up
+      // in. Restoring first is how a cleanup that writes a farewell line ends
+      // up writing it into the alternate screen, a millisecond before that
+      // screen is thrown away.
+      root.unmount();
+      if (stdin.off != null) {
+        stdin.off("data", onData);
+      }
+      if (stdout.off != null) {
+        stdout.off("resize", onResize);
+      }
+      if (interactive) {
+        if (stdin.isTTY === true && stdin.setRawMode != null) {
+          stdin.setRawMode(false);
+        }
+        if (stdin.pause != null) {
+          stdin.pause();
+        }
+        stdout.write(
+          (mouse ? DISABLE_MOUSE : "") +
+            DISABLE_PASTE +
+            SHOW_CURSOR +
+            (alternateScreen ? LEAVE_ALTERNATE : "\n"),
+        );
+      } else {
+        // Nobody was watching, so nothing has been written yet. The last frame
+        // goes out once, as text, which is what a log can carry.
+        stdout.write(farewell);
+      }
+    },
+    frame() {
+      return renderFrame(renderer);
+    },
+    text() {
+      return frameText(renderFrame(renderer));
+    },
+    selectedText() {
+      return renderer.getSelectedText();
+    },
+    selection() {
+      return renderer.getSelection();
+    },
+  };
+}

package/widths.js

@@ -0,0 +1,201 @@
+// @flow
+//
+// How many terminal columns a piece of text occupies.
+//
+// This is the first thing a terminal renderer has to get right and the easiest
+// one to get wrong, because JavaScript offers a number that looks like the
+// answer and is not: `"A界B".length` and `"ABC".length` are both `3`, and only
+// one of those strings fits in three columns. Everything downstream — where a
+// border's right edge lands, where a line wraps, which cell the cursor moves
+// to — is computed from the answer here, so a width that is one column out
+// does not produce a slightly wrong frame. It produces a frame whose every
+// subsequent row is shifted.
+//
+// # Two units, not one
+//
+// A *grapheme cluster* is what a reader calls a character: a base scalar plus
+// whatever combines onto it, up to and including a family emoji built from
+// four people and three joiners. A *cell* is one column of one row. The
+// mapping between them is many-to-many, and this module is the only place in
+// the package that knows it. `Intl.Segmenter` does the clustering — it is in
+// every runtime uf supports and it implements UAX #29, which is a standard
+// nobody should be reimplementing.
+//
+// # Why the tables are copied rather than shared
+//
+// `crates/uf_term/src/text/tables.rs` holds exactly these two range lists, and
+// `crates/uf_term/src/text.rs` implements exactly these rules, because the uf
+// CLI has to answer the same question in Rust before any JavaScript is
+// running. Two copies of a Unicode table is a thing to be uncomfortable about,
+// so the discomfort is made mechanical instead of moral: `tui.test.js` parses
+// the Rust file and asserts the ranges below are identical to it, and fails
+// when either side is edited alone. The copy is therefore checked, and the
+// alternative — shipping a native binding to a published Flow package so that
+// `@uniflowed/tui` can ask Rust how wide `界` is — is a far larger price for
+// the same answer.
+
+const ZERO_WIDTH: $ReadOnlyArray<number> = [
+  0x00ad, 0x00ad, 0x0300, 0x036f, 0x0483, 0x0489, 0x0591, 0x05bd, 0x05bf, 0x05bf, 0x05c1, 0x05c2,
+  0x05c4, 0x05c5, 0x05c7, 0x05c7, 0x0610, 0x061a, 0x064b, 0x065f, 0x0670, 0x0670, 0x06d6, 0x06dc,
+  0x06df, 0x06e4, 0x06e7, 0x06e8, 0x06ea, 0x06ed, 0x0711, 0x0711, 0x0730, 0x074a, 0x07a6, 0x07b0,
+  0x07eb, 0x07f3, 0x0816, 0x0819, 0x081b, 0x0823, 0x0825, 0x0827, 0x0829, 0x082d, 0x0859, 0x085b,
+  0x08e3, 0x0902, 0x093a, 0x093a, 0x093c, 0x093c, 0x0941, 0x0948, 0x094d, 0x094d, 0x0951, 0x0957,
+  0x0962, 0x0963, 0x0981, 0x0981, 0x09bc, 0x09bc, 0x09c1, 0x09c4, 0x09cd, 0x09cd, 0x09e2, 0x09e3,
+  0x0a01, 0x0a02, 0x0a3c, 0x0a3c, 0x0a41, 0x0a42, 0x0a47, 0x0a48, 0x0a4b, 0x0a4d, 0x0a70, 0x0a71,
+  0x0abc, 0x0abc, 0x0ac1, 0x0ac5, 0x0ac7, 0x0ac8, 0x0acd, 0x0acd, 0x0b01, 0x0b01, 0x0b3c, 0x0b3c,
+  0x0b3f, 0x0b3f, 0x0b41, 0x0b44, 0x0b4d, 0x0b4d, 0x0bc0, 0x0bc0, 0x0bcd, 0x0bcd, 0x0c00, 0x0c00,
+  0x0c3e, 0x0c40, 0x0c46, 0x0c48, 0x0c4a, 0x0c4d, 0x0cbc, 0x0cbc, 0x0ccc, 0x0ccd, 0x0d41, 0x0d44,
+  0x0d4d, 0x0d4d, 0x0dca, 0x0dca, 0x0e31, 0x0e31, 0x0e34, 0x0e3a, 0x0e47, 0x0e4e, 0x0eb1, 0x0eb1,
+  0x0eb4, 0x0ebc, 0x0ec8, 0x0ecd, 0x0f35, 0x0f35, 0x0f37, 0x0f37, 0x0f39, 0x0f39, 0x0f71, 0x0f7e,
+  0x0f80, 0x0f84, 0x0f86, 0x0f87, 0x102d, 0x1030, 0x1032, 0x1037, 0x1039, 0x103a, 0x1058, 0x1059,
+  0x135d, 0x135f, 0x1712, 0x1714, 0x17b4, 0x17b5, 0x17b7, 0x17bd, 0x17c6, 0x17c6, 0x17c9, 0x17d3,
+  0x180b, 0x180e, 0x18a9, 0x18a9, 0x1a17, 0x1a18, 0x1ab0, 0x1aff, 0x1b00, 0x1b03, 0x1b34, 0x1b34,
+  0x1b6b, 0x1b73, 0x1dc0, 0x1dff, 0x200b, 0x200f, 0x202a, 0x202e, 0x2060, 0x2064, 0x206a, 0x206f,
+  0x20d0, 0x20f0, 0x2cef, 0x2cf1, 0x302a, 0x302d, 0x3099, 0x309a, 0xa66f, 0xa672, 0xa674, 0xa67d,
+  0xa69e, 0xa69f, 0xa806, 0xa806, 0xa8c4, 0xa8c5, 0xa8e0, 0xa8f1, 0xfb1e, 0xfb1e, 0xfe00, 0xfe0f,
+  0xfe20, 0xfe2f, 0xfeff, 0xfeff, 0xfff9, 0xfffb, 0x101fd, 0x101fd, 0x1d167, 0x1d169, 0x1d17b,
+  0x1d182, 0x1d185, 0x1d18b, 0x1d1aa, 0x1d1ad, 0x1d242, 0x1d244, 0xe0100, 0xe01ef,
+];
+
+const WIDE: $ReadOnlyArray<number> = [
+  0x1100, 0x115f, 0x231a, 0x231b, 0x2329, 0x232a, 0x23e9, 0x23ec, 0x23f0, 0x23f0, 0x23f3, 0x23f3,
+  0x25fd, 0x25fe, 0x2614, 0x2615, 0x2648, 0x2653, 0x267f, 0x267f, 0x2693, 0x2693, 0x26a1, 0x26a1,
+  0x26aa, 0x26ab, 0x26bd, 0x26be, 0x26c4, 0x26c5, 0x26ce, 0x26ce, 0x26d4, 0x26d4, 0x26ea, 0x26ea,
+  0x26f2, 0x26f3, 0x26f5, 0x26f5, 0x26fa, 0x26fa, 0x26fd, 0x26fd, 0x2705, 0x2705, 0x270a, 0x270b,
+  0x2728, 0x2728, 0x274c, 0x274c, 0x274e, 0x274e, 0x2753, 0x2755, 0x2757, 0x2757, 0x2795, 0x2797,
+  0x27b0, 0x27b0, 0x27bf, 0x27bf, 0x2b1b, 0x2b1c, 0x2b50, 0x2b50, 0x2b55, 0x2b55, 0x2e80, 0x2e99,
+  0x2e9b, 0x2ef3, 0x2f00, 0x2fd5, 0x2ff0, 0x2ffb, 0x3000, 0x303e, 0x3041, 0x3096, 0x309b, 0x30ff,
+  0x3105, 0x312f, 0x3131, 0x318e, 0x3190, 0x31e3, 0x31f0, 0x321e, 0x3220, 0x3247, 0x3250, 0x4dbf,
+  0x4e00, 0xa48c, 0xa490, 0xa4c6, 0xa960, 0xa97c, 0xac00, 0xd7a3, 0xf900, 0xfaff, 0xfe10, 0xfe19,
+  0xfe30, 0xfe52, 0xfe54, 0xfe66, 0xfe68, 0xfe6b, 0xff01, 0xff60, 0xffe0, 0xffe6, 0x16fe0, 0x16fe4,
+  0x16ff0, 0x16ff1, 0x17000, 0x187f7, 0x18800, 0x18cd5, 0x1b000, 0x1b152, 0x1b164, 0x1b167, 0x1b170,
+  0x1b2fb, 0x1f004, 0x1f004, 0x1f0cf, 0x1f0cf, 0x1f18e, 0x1f18e, 0x1f191, 0x1f19a, 0x1f200, 0x1f320,
+  0x1f32d, 0x1f335, 0x1f337, 0x1f37c, 0x1f37e, 0x1f393, 0x1f3a0, 0x1f3ca, 0x1f3cf, 0x1f3d3, 0x1f3e0,
+  0x1f3f0, 0x1f3f4, 0x1f3f4, 0x1f3f8, 0x1f43e, 0x1f440, 0x1f440, 0x1f442, 0x1f4fc, 0x1f4ff, 0x1f53d,
+  0x1f54b, 0x1f54e, 0x1f550, 0x1f567, 0x1f57a, 0x1f57a, 0x1f595, 0x1f596, 0x1f5a4, 0x1f5a4, 0x1f5fb,
+  0x1f64f, 0x1f680, 0x1f6c5, 0x1f6cc, 0x1f6cc, 0x1f6d0, 0x1f6d2, 0x1f6d5, 0x1f6d7, 0x1f6eb, 0x1f6ec,
+  0x1f6f4, 0x1f6fc, 0x1f7e0, 0x1f7eb, 0x1f90c, 0x1f93a, 0x1f93c, 0x1f945, 0x1f947, 0x1f978, 0x1f97a,
+  0x1f9cb, 0x1f9cd, 0x1f9ff, 0x1fa70, 0x1fa74, 0x1fa78, 0x1fa7a, 0x1fa80, 0x1fa86, 0x1fa90, 0x1faa8,
+  0x1fab0, 0x1fab6, 0x1fac0, 0x1fac2, 0x1fad0, 0x1fad6, 0x20000, 0x2fffd, 0x30000, 0x3fffd,
+];
+
+/** Zero-width joiner: the scalar after it continues the cluster before it. */
+const ZWJ = 0x200d;
+
+/** Variation selector 16, which asks for the emoji presentation of a scalar. */
+const VS16 = 0xfe0f;
+
+/** One shared segmenter; constructing one costs more than using it. */
+const GRAPHEMES: Intl$Segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Whether `code` falls inside a sorted, non-overlapping flat range table.
+ *
+ * The table is `[low, high, low, high, …]` rather than an array of pairs
+ * because bisection over one flat array of numbers is both shorter to write
+ * and the shape a JavaScript engine keeps unboxed.
+ */
+function inRanges(table: $ReadOnlyArray<number>, code: number): boolean {
+  let low = 0;
+  let high = table.length / 2 - 1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    if (code < table[middle * 2]) {
+      high = middle - 1;
+    } else if (code > table[middle * 2 + 1]) {
+      low = middle + 1;
+    } else {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The columns one Unicode scalar occupies.
+ *
+ * Control characters and combining marks occupy none, East Asian Wide and
+ * Fullwidth characters and the default-emoji-presentation ranges occupy two,
+ * and everything else occupies one.
+ */
+export function scalarWidth(code: number): number {
+  if (code < 0x20 || (code >= 0x7f && code < 0xa0)) {
+    return 0;
+  }
+  if (inRanges(ZERO_WIDTH, code)) {
+    return 0;
+  }
+  return inRanges(WIDE, code) ? 2 : 1;
+}
+
+/**
+ * The columns one grapheme cluster occupies.
+ *
+ * A cluster is as wide as its widest scalar rather than the sum of them: the
+ * marks and joiners that make a cluster longer than one scalar are precisely
+ * the ones that draw on top of what came before. The exception is the emoji
+ * variation selector, which does not draw at all and instead widens the
+ * narrow scalar in front of it — `❤` is one column and `❤️` is two, and they
+ * differ by a code point that is invisible in every editor.
+ */
+export function graphemeWidth(cluster: string): number {
+  let width = 0;
+  let previousNarrow = false;
+  for (const character of cluster) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code === ZWJ) {
+      previousNarrow = false;
+      continue;
+    }
+    if (code === VS16) {
+      if (previousNarrow) {
+        width += 1;
+        previousNarrow = false;
+      }
+      continue;
+    }
+    const scalar = scalarWidth(code);
+    width = Math.max(width, scalar);
+    previousNarrow = scalar === 1;
+  }
+  return width;
+}
+
+/** One grapheme cluster, with the columns it will occupy. */
+export type Grapheme = {
+  /** The cluster itself, as a string. */
+  readonly text: string,
+  /** How many columns it occupies: 0, 1, or 2. */
+  readonly width: number,
+};
+
+/**
+ * Split text into grapheme clusters, each carrying its width.
+ *
+ * Zero-width clusters are dropped rather than kept: a renderer that writes
+ * them has to decide which cell they belong to, and the answer — "the one
+ * before, which has already been written" — means the only correct handling is
+ * to have merged them into that cluster, which `Intl.Segmenter` already did.
+ * A lone combining mark with nothing to combine with is the one case this
+ * loses, and losing it is better than reserving a column for something the
+ * terminal will not advance the cursor over.
+ */
+export function graphemes(text: string): Array<Grapheme> {
+  const out: Array<Grapheme> = [];
+  for (const segment of GRAPHEMES.segment(text)) {
+    const width = graphemeWidth(segment.segment);
+    if (width > 0) {
+      out.push({ text: segment.segment, width });
+    }
+  }
+  return out;
+}
+
+/** The columns a whole string occupies. */
+export function displayWidth(text: string): number {
+  let width = 0;
+  for (const segment of GRAPHEMES.segment(text)) {
+    width += graphemeWidth(segment.segment);
+  }
+  return width;
+}