@promptctl/rich-js 0.17.0 → 0.18.1

package/README.md

@@ -24,7 +24,7 @@ Most of the library comes from the package name itself — `Console`, `Table`, `
 |---|---|---|---|
 | `@promptctl/rich-js/widgets` | Button, Checkbox, Toggle, TextInput, Dropdown, Slider, and the screen that mounts them | `mobx` | Carries a third-party runtime dependency of its own — MobX, for widget state |
 | `@promptctl/rich-js/template-bindings` | The styling vocabulary as Go-template functions, so styled text can be authored as a template | `@promptctl/go-template-js` | Carries a third-party runtime dependency of its own — the Go-template engine, for parsing and evaluating the templates |
-| `@promptctl/rich-js/host` | `TerminalHost`, `BrowserTerminalHost`, `hostStream` — the seam between rendering and a terminal | Nothing | A program that just wants to write bytes through a host shouldn't pay for the widget set to do it |
+| `@promptctl/rich-js/host` | `TerminalHost`, `BrowserTerminalHost`, `hostEnvironment` — the seam between rendering and a terminal | Nothing | A program that just wants to write bytes through a host shouldn't pay for the widget set to do it |
 | `@promptctl/rich-js/node/save`, `/node/prompt`, `/node/traceback`, `/node/terminal-host` | File export, readline input, the crash handler, and the node TTY host | Nothing | Each one reads node built-ins, and keeping them off the main entry point is what keeps that entry point browser-safe |
 
 Those two peer dependencies are yours to install — `npm install @promptctl/rich-js` deliberately fetches neither, because a program that prints a table shouldn't acquire a state library or a template engine to do it. Add the ones you need:
@@ -293,45 +293,31 @@ installTraceback();
 Everything above draws once and returns. Widgets stay on screen and respond — a button that highlights under the cursor, a text field with a cursor you can move, a dropdown you filter by typing. They come from the `widgets` subpath and need MobX installed alongside the package (see [Entry points](#entry-points)).
 
 ```typescript
-import { Button, TextInput, DefaultScreen, EventRouter } from "@promptctl/rich-js/widgets";
+import { Group } from "@promptctl/rich-js";
+import { Button, TextInput, WidgetApp } from "@promptctl/rich-js/widgets";
 import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
 
-const host = new NodeTerminalHost();
-const screen = new DefaultScreen({ host });
-const router = new EventRouter({ screen, host });
-
 const name = new TextInput({ placeholder: "your name" });
 const submit = new Button({ label: "Submit", variant: "primary" });
+const form = new Group(name, submit);
 
-const quit = (): void => {
-  router.stop();
-  screen.stop();
-  host.write("\n");
-};
+const app = new WidgetApp({ host: new NodeTerminalHost(), surface: "alternate", view: () => form });
 
-submit.onSubmit(() => {
-  quit();
-  host.write(`hello, ${name.value}\n`);
-  process.exit(0);
-});
+submit.onSubmit(() => app.stop());
 
 // Raw mode swallows Ctrl+C, so the app has to handle it itself.
-router.onKey(
+app.onKey(
   (event) => {
-    if (event.ctrl && event.key === "c") {
-      quit();
-      process.exit(0);
-    }
+    if (event.ctrl && event.key === "c") app.stop();
   },
   { priority: "high" },
 );
 
-screen.mount(name, submit);
-screen.start();
-router.start();
+await app.run();
+console.log(`hello, ${name.value}`);
 ```
 
-`DefaultScreen` builds a focus manager when you don't pass one, so the `TextInput` has focus before the user touches anything and Tab moves between the two widgets. The screen re-renders through a MobX reaction: change a widget's state and the frame redraws itself, with no explicit repaint call anywhere. See [docs/widgets.md](docs/widgets.md) for the full widget set, key dispatch, layout placements, and how to write your own.
+Widgets go anywhere a renderable goes — a `Group`, a `Panel`, a `Layout` pane — and the app finds them on the frame it paints. The `TextInput` has focus before the user touches anything, Tab moves between the two widgets in the order they are drawn, and a change to a widget's state repaints with no explicit call. `app.stop()` — or a crash, or a signal — hands the terminal back. See [docs/widgets.md](docs/widgets.md) for the full widget set, key dispatch, layout, and how to write your own.
 
 </details>
 
@@ -401,6 +387,7 @@ npm run demo
 | `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set `EXPORT_HTML=out.html` to save it as HTML too. |
 | `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
 | `npm run markup-plugins` | rich-markup-plugins | Custom markup tags registered through `MarkupRegistry`. Prints once and exits. |
+| `npm run viewport` | rich-viewport | A cursor walking a list taller than its window, kept in view by `Viewport.ensureVisible`. |
 
 `Ctrl-C` quits any demo that stays running.
 
@@ -410,5 +397,5 @@ npm run demo
 |---|---|
 | `NO_COLOR` | Disable all color (hyperlinks still print) |
 | `FORCE_COLOR` | Enable color regardless of `TERM` |
-| `TERM=dumb` | Disable color and style |
+| `TERM=dumb` | Disable color, style, and hyperlinks |
 | `COLUMNS` / `LINES` | Override terminal dimensions |

package/dist/core/anchor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Anchor — where a cell sat in the output of the thing that drew it.
+ *
+ * A widget nested inside a `Layout` cell inside a `Panel` does not know where
+ * it lands on screen, and nothing can tell it before it renders: `Align`
+ * centres each line only after rendering it, so the lines of one widget can
+ * start at different columns, and a `Viewport` shows whichever of its
+ * content's rows its offset selects. An origin handed down through the render
+ * options would be a number each container has to compute before it knows
+ * the answer, and one more thing every container must forward correctly.
+ *
+ * So the position travels up instead, on the cells themselves. The owner
+ * stamps each segment of its output with its row and column there
+ * (`Segment.anchorLines`), the stamp rides on the segment's `Style`, which
+ * every container already carries through untouched, and whoever holds the
+ * composed frame reads any cell's owner and position straight off it
+ * (`Segment.anchorAt`). Containers do nothing, so no container can get it
+ * wrong.
+ *
+ * [LAW:single-enforcer] Two things can falsify a stamp. Cutting a segment in
+ * two starts the right half at a later column than the stamp names:
+ * `Segment.splitCells` is where a segment is cut, and it shifts the right
+ * half's anchor (`shiftAnchor`); a crop that keeps the left half keeps a stamp
+ * that is already true. Laying the text out again moves every cell: a
+ * `RichText` does that, so it admits no anchor (`admitStyle` in `./text.ts`),
+ * and the owner that renders it stamps what it draws.
+ */
+/**
+ * The position of a segment's first cell in its owner's output, and the
+ * anchor that segment carried before this owner stamped it — the owner nested
+ * inside this one, if any. Innermost last: follow `inner` to reach the owner
+ * that drew the cell itself.
+ */
+export interface Anchor {
+    /** The thing that drew this cell, compared by identity. */
+    readonly owner: object;
+    readonly row: number;
+    readonly col: number;
+    readonly inner: Anchor | undefined;
+}
+/**
+ * The anchor of the cell `cells` to the right of the one `anchor` names, at
+ * every level of the nesting — each level names the same cell.
+ */
+export declare function shiftAnchor(anchor: Anchor, cells: number): Anchor;

package/dist/core/anchor.js

@@ -0,0 +1,39 @@
+/**
+ * Anchor — where a cell sat in the output of the thing that drew it.
+ *
+ * A widget nested inside a `Layout` cell inside a `Panel` does not know where
+ * it lands on screen, and nothing can tell it before it renders: `Align`
+ * centres each line only after rendering it, so the lines of one widget can
+ * start at different columns, and a `Viewport` shows whichever of its
+ * content's rows its offset selects. An origin handed down through the render
+ * options would be a number each container has to compute before it knows
+ * the answer, and one more thing every container must forward correctly.
+ *
+ * So the position travels up instead, on the cells themselves. The owner
+ * stamps each segment of its output with its row and column there
+ * (`Segment.anchorLines`), the stamp rides on the segment's `Style`, which
+ * every container already carries through untouched, and whoever holds the
+ * composed frame reads any cell's owner and position straight off it
+ * (`Segment.anchorAt`). Containers do nothing, so no container can get it
+ * wrong.
+ *
+ * [LAW:single-enforcer] Two things can falsify a stamp. Cutting a segment in
+ * two starts the right half at a later column than the stamp names:
+ * `Segment.splitCells` is where a segment is cut, and it shifts the right
+ * half's anchor (`shiftAnchor`); a crop that keeps the left half keeps a stamp
+ * that is already true. Laying the text out again moves every cell: a
+ * `RichText` does that, so it admits no anchor (`admitStyle` in `./text.ts`),
+ * and the owner that renders it stamps what it draws.
+ */
+/**
+ * The anchor of the cell `cells` to the right of the one `anchor` names, at
+ * every level of the nesting — each level names the same cell.
+ */
+export function shiftAnchor(anchor, cells) {
+    return {
+        owner: anchor.owner,
+        row: anchor.row,
+        col: anchor.col + cells,
+        inner: anchor.inner && shiftAnchor(anchor.inner, cells),
+    };
+}

package/dist/core/ansi.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ANSI bytes back into styled text — a port of Rich's `AnsiDecoder`
+ * (rich/ansi.py) and `Text.from_ansi`.
+ *
+ * The rendering pipeline runs one way, `Style` → SGR bytes; this runs it
+ * backwards, for output some program already wrote: a capture of an example's
+ * own `new Console()`, a CLI's output shown inside a Panel, a log replayed into
+ * a Table cell.
+ *
+ * [LAW:types-are-the-program] Every colour decodes to the `ColorSpec` its
+ * escape names — `31` the standard colour 1, `38;5;n` palette index n,
+ * `38;2;r;g;b` that truecolor — and none is resolved to RGB here. A standard
+ * colour is a slot in whatever theme draws it, so one captured run exports
+ * correctly under a light theme and a dark one; resolved here, dark mode would
+ * show light mode's colours. Resolution belongs to `export-lines`.
+ *
+ * [LAW:types-are-the-program] The link is decoder state of its own, beside
+ * the SGR style, not a field of it: a terminal ends a hyperlink only at an OSC
+ * 8 close, and an SGR reset inside the link leaves it open. Rich keeps the
+ * link in the SGR style, so its reset drops it.
+ *
+ * Carriage returns are the other departure, and the same argument. Rich splits
+ * lines with Python's `splitlines`, which also breaks at `\r`, so its `a\rb`
+ * is two lines. Here a line ends only at `\n`, and `\r` returns to the first
+ * column, so later text overwrites earlier text character by character:
+ * `50%\r100%` is `100%`, `Downloading\rDone` is `Doneloading`, and `done\r`
+ * is still `done`. Columns are counted in characters, not cells, so a wide
+ * character overwritten by a narrow one is where this and a terminal differ.
+ * Erase in line (`\x1b[K`) is honoured for the same reason, because a redraw
+ * is usually `\r\x1b[K` and the old text must not show through a shorter new
+ * one.
+ *
+ * Everything else follows Rich: malformed SGR parameters are skipped rather
+ * than refused, and every other escape is dropped. It is not a terminal
+ * emulator — any other cursor movement is dropped, not performed.
+ *
+ * Tier 5 of `src/core/`: it builds `RichText`, so it sits above `text`, and
+ * `RichText` cannot offer a `fromAnsi` static without importing upward.
+ */
+import { RichText } from "./text.js";
+import type { RichTextOptions } from "./text.js";
+/**
+ * A stateful decoder: the style an escape sets carries on across lines, and
+ * across calls, as it does on a terminal. Use one decoder per stream and hand
+ * it whole lines, so output read a line at a time decodes as it would have
+ * all at once. It buffers nothing: a chunk cut mid-line or mid-escape decodes
+ * as the line it appears to be.
+ */
+export declare class AnsiDecoder {
+    private sgr;
+    private link;
+    /** One `RichText` per line of `ansi`; a final newline ends a line rather than starting one. */
+    decode(ansi: string): RichText[];
+    /**
+     * One line of output, holding no `\n`, written the way a terminal writes
+     * it: `\r` returns to the first column, and text overwrites from there.
+     */
+    decodeLine(line: string): RichText;
+}
+/**
+ * `ansi` as one `RichText`, its lines joined by `\n` — Rich's
+ * `Text.from_ansi`. `options` describe the result the way they describe any
+ * `RichText`.
+ */
+export declare function decodeAnsi(ansi: string, options?: RichTextOptions): RichText;

package/dist/core/ansi.js

@@ -0,0 +1,231 @@
+/**
+ * ANSI bytes back into styled text — a port of Rich's `AnsiDecoder`
+ * (rich/ansi.py) and `Text.from_ansi`.
+ *
+ * The rendering pipeline runs one way, `Style` → SGR bytes; this runs it
+ * backwards, for output some program already wrote: a capture of an example's
+ * own `new Console()`, a CLI's output shown inside a Panel, a log replayed into
+ * a Table cell.
+ *
+ * [LAW:types-are-the-program] Every colour decodes to the `ColorSpec` its
+ * escape names — `31` the standard colour 1, `38;5;n` palette index n,
+ * `38;2;r;g;b` that truecolor — and none is resolved to RGB here. A standard
+ * colour is a slot in whatever theme draws it, so one captured run exports
+ * correctly under a light theme and a dark one; resolved here, dark mode would
+ * show light mode's colours. Resolution belongs to `export-lines`.
+ *
+ * [LAW:types-are-the-program] The link is decoder state of its own, beside
+ * the SGR style, not a field of it: a terminal ends a hyperlink only at an OSC
+ * 8 close, and an SGR reset inside the link leaves it open. Rich keeps the
+ * link in the SGR style, so its reset drops it.
+ *
+ * Carriage returns are the other departure, and the same argument. Rich splits
+ * lines with Python's `splitlines`, which also breaks at `\r`, so its `a\rb`
+ * is two lines. Here a line ends only at `\n`, and `\r` returns to the first
+ * column, so later text overwrites earlier text character by character:
+ * `50%\r100%` is `100%`, `Downloading\rDone` is `Doneloading`, and `done\r`
+ * is still `done`. Columns are counted in characters, not cells, so a wide
+ * character overwritten by a narrow one is where this and a terminal differ.
+ * Erase in line (`\x1b[K`) is honoured for the same reason, because a redraw
+ * is usually `\r\x1b[K` and the old text must not show through a shorter new
+ * one.
+ *
+ * Everything else follows Rich: malformed SGR parameters are skipped rather
+ * than refused, and every other escape is dropped. It is not a terminal
+ * emulator — any other cursor movement is dropped, not performed.
+ *
+ * Tier 5 of `src/core/`: it builds `RichText`, so it sits above `text`, and
+ * `RichText` cannot offer a `fromAnsi` static without importing upward.
+ */
+import { ColorSpec } from "./color.js";
+import { osc8Sequences } from "./osc8.js";
+import { ATTRIBUTE_NAMES, ATTRIBUTE_SGR, NULL_STYLE, Style } from "./style.js";
+import { RichText } from "./text.js";
+/**
+ * Every escape but OSC 8, which `osc8Sequences` reads before this runs. In
+ * order: a carriage return; an SGR sequence (group 1, its parameters — a
+ * private marker such as the `>` of `\x1b[>4;2m` makes it some other CSI);
+ * erase in line (group 2, its mode); any other CSI sequence; any other string
+ * escape — OSC, DCS, APC, PM, SOS — run to the terminators OSC 8 accepts or
+ * cut off by the end of the line; any other escape, ECMA-48's intermediates
+ * and one final byte (`\x1b(B`, `\x1b)0`, `\x1b#8`, `\x1bc`). Only the first
+ * three become tokens.
+ */
+const ESCAPE = /\r|\x1b\[([0-9;:]*)m|\x1b\[([012]?)K|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[\]P_^X][\s\S]*?(?:\x07|\x1b\\|\x9c|$)|\x1b[ -/]*[0-~]/g;
+function* escapeTokens(bytes) {
+    let at = 0;
+    for (const match of bytes.matchAll(ESCAPE)) {
+        if (match.index > at)
+            yield { kind: "text", text: bytes.slice(at, match.index) };
+        if (match[0] === "\r")
+            yield { kind: "return" };
+        if (match[1] !== undefined)
+            yield { kind: "sgr", params: match[1] };
+        if (match[2] !== undefined)
+            yield { kind: "erase", mode: (match[2] || "0") };
+        at = match.index + match[0].length;
+    }
+    if (at < bytes.length)
+        yield { kind: "text", text: bytes.slice(at) };
+}
+// [LAW:one-source-of-truth] OSC 8 is read by the reader `osc8.ts` owns, so
+// the terminators a link may end with cannot differ between writing and
+// reading it back.
+function* tokens(line) {
+    let at = 0;
+    for (const sequence of osc8Sequences(line)) {
+        yield* escapeTokens(line.slice(at, sequence.index));
+        yield { kind: "link", uri: sequence.uri };
+        at = sequence.index + sequence.length;
+    }
+    yield* escapeTokens(line.slice(at));
+}
+function adding(options) {
+    const added = new Style(options);
+    return (style) => style.add(added);
+}
+function next(rest) {
+    const step = rest.next();
+    return step.done ? undefined : step.value;
+}
+/**
+ * `5;n` or `2;r;g;b`, the arguments of `38` and `48`. A sequence cut short
+ * names no colour, and the codes it did consume are spent, as in Rich.
+ */
+function extendedColor(rest) {
+    const kind = next(rest);
+    if (kind === 5) {
+        const n = next(rest);
+        return n === undefined ? undefined : ColorSpec.fromAnsi(n);
+    }
+    if (kind === 2) {
+        const [r, g, b] = [next(rest), next(rest), next(rest)];
+        return b === undefined ? undefined : ColorSpec.fromRgb(r, g, b);
+    }
+    return undefined;
+}
+// [LAW:dataflow-not-control-flow] Every code is an operation on the style,
+// reset included; a code this table does not name is the identity.
+const SGR_OPS = new Map([
+    [0, () => NULL_STYLE],
+    // [LAW:one-source-of-truth] The codes that turn an attribute on are the
+    // ones `Style.toSgrCodes` writes; only the codes that turn one off are ours.
+    ...ATTRIBUTE_NAMES.map((name) => [ATTRIBUTE_SGR[name], adding({ [name]: true })]),
+    [22, adding({ bold: false, dim: false })],
+    [23, adding({ italic: false })],
+    // ECMA-48: 24 is "neither singly nor doubly underlined", 25 "steady" at
+    // either speed. Rich's table clears only the first of each pair.
+    [24, adding({ underline: false, underline2: false })],
+    [25, adding({ blink: false, blink2: false })],
+    [27, adding({ reverse: false })],
+    [28, adding({ conceal: false })],
+    [29, adding({ strike: false })],
+    [38, (style, rest) => style.add(new Style({ color: extendedColor(rest) }))],
+    [39, adding({ color: ColorSpec.default() })],
+    [48, (style, rest) => style.add(new Style({ bgcolor: extendedColor(rest) }))],
+    [49, adding({ bgcolor: ColorSpec.default() })],
+    // Underline colour has no field on Style; its arguments are still spent, or
+    // `58;2;1;2;3` would read on as bold, dim and italic.
+    [58, (style, rest) => (extendedColor(rest), style)],
+    [54, adding({ frame: false, encircle: false })],
+    [55, adding({ overline: false })],
+    ...Array.from({ length: 8 }, (_, n) => [
+        [30 + n, adding({ color: ColorSpec.fromAnsi(n) })],
+        [40 + n, adding({ bgcolor: ColorSpec.fromAnsi(n) })],
+        [90 + n, adding({ color: ColorSpec.fromAnsi(n + 8) })],
+        [100 + n, adding({ bgcolor: ColorSpec.fromAnsi(n + 8) })],
+    ]).flat(),
+]);
+const identity = (style) => style;
+/**
+ * `params` applied to `style`. An empty parameter is 0 and one above 255 is
+ * 255; one that is not a number — a colon sub-parameter — is skipped, as in
+ * Rich.
+ */
+function applySgr(style, params) {
+    const codes = params
+        .split(";")
+        .filter((code) => /^\d*$/.test(code))
+        .map((code) => Math.min(255, Number(code)))
+        .values();
+    let result = style;
+    for (const code of codes)
+        result = (SGR_OPS.get(code) ?? identity)(result, codes);
+    return result;
+}
+const BLANK = [" ", NULL_STYLE];
+/** Erase in line: the cells before the cursor go blank, the ones from it on go. */
+function erase(cells, column, mode) {
+    if (mode !== "0")
+        cells.fill(BLANK, 0, Math.min(column + 1, cells.length));
+    if (mode !== "1")
+        cells.length = Math.min(column, cells.length);
+}
+/**
+ * A stateful decoder: the style an escape sets carries on across lines, and
+ * across calls, as it does on a terminal. Use one decoder per stream and hand
+ * it whole lines, so output read a line at a time decodes as it would have
+ * all at once. It buffers nothing: a chunk cut mid-line or mid-escape decodes
+ * as the line it appears to be.
+ */
+export class AnsiDecoder {
+    sgr = NULL_STYLE;
+    link = undefined;
+    /** One `RichText` per line of `ansi`; a final newline ends a line rather than starting one. */
+    decode(ansi) {
+        return (ansi.match(/[^\n]*\n|[^\n]+/g) ?? []).map((line) => this.decodeLine(line.replace(/\r?\n$/, "")));
+    }
+    /**
+     * One line of output, holding no `\n`, written the way a terminal writes
+     * it: `\r` returns to the first column, and text overwrites from there.
+     */
+    decodeLine(line) {
+        const cells = [];
+        let column = 0;
+        for (const token of tokens(line)) {
+            switch (token.kind) {
+                case "text": {
+                    const style = this.sgr.withLink(this.link);
+                    for (const char of token.text)
+                        cells[column++] = [char, style];
+                    break;
+                }
+                case "return":
+                    column = 0;
+                    break;
+                case "erase":
+                    erase(cells, column, token.mode);
+                    break;
+                case "sgr":
+                    this.sgr = applySgr(this.sgr, token.params);
+                    break;
+                case "link":
+                    this.link = token.uri === "" ? undefined : token.uri;
+                    break;
+            }
+        }
+        const runs = [];
+        for (const [char, style] of cells) {
+            const last = runs.at(-1);
+            if (last?.[1].equals(style))
+                last[0] += char;
+            else
+                runs.push([char, style]);
+        }
+        return RichText.assemble(runs);
+    }
+}
+/**
+ * `ansi` as one `RichText`, its lines joined by `\n` — Rich's
+ * `Text.from_ansi`. `options` describe the result the way they describe any
+ * `RichText`.
+ */
+export function decodeAnsi(ansi, options) {
+    const result = new RichText("", options);
+    new AnsiDecoder().decode(ansi).forEach((line, index) => {
+        if (index > 0)
+            result.append("\n");
+        result.append(line);
+    });
+    return result;
+}

package/dist/core/box.d.ts

@@ -51,7 +51,6 @@ export declare class Box {
     readonly top: EdgeChars;
     readonly bottom: EdgeChars;
     private readonly grid;
-    private readonly ascii;
     private readonly headContent;
     private readonly headSeparator;
     private readonly bodyContent;

package/dist/core/box.js

@@ -26,19 +26,9 @@
  */
 import { cellLen } from "./cells.js";
 import { Segment } from "./segment.js";
+import { drawable } from "./protocol.js";
 const GRID_ROWS = 8;
 const GRID_COLUMNS = 4;
-/**
- * A grid a terminal without unicode support can already draw as written.
- *
- * [LAW:one-source-of-truth] Derived from the grid rather than declared per
- * constant the way the reference's `ascii=True` is. A `Box` is wholly its grid,
- * so the grid already answers this; a second, hand-written answer could
- * disagree with it. It also reaches boxes no constant can speak for —
- * `safeSubstitute` builds a fresh `Box` from an edited grid, and a flag carried
- * on the shipped constants would say nothing about that one.
- */
-const ASCII_GRID = /^[\x00-\x7F]*$/;
 /** Corners that a legacy Windows terminal cannot draw, and their square kin. */
 const SAFE_SUBSTITUTIONS = {
     "╭": "┌",
@@ -62,7 +52,6 @@ export class Box {
     top;
     bottom;
     grid;
-    ascii;
     headContent;
     headSeparator;
     bodyContent;
@@ -91,7 +80,6 @@ export class Box {
         }
         const rows = lines.map((line) => Array.from(line));
         this.grid = grid;
-        this.ascii = ASCII_GRID.test(grid);
         this.top = edgeOf(rows[0]);
         this.headContent = contentOf(rows[1]);
         this.headSeparator = edgeOf(rows[2]);
@@ -148,11 +136,11 @@ export class Box {
      * rounded corners a legacy Windows terminal draws as blanks.
      */
     substitute(options = {}) {
-        if (options.asciiOnly && !this.ascii)
-            return ASCII;
-        if (options.safe)
-            return this.safeSubstitute();
-        return this;
+        // [LAW:one-source-of-truth] A box is wholly its grid, so the grid is what
+        // says whether it is already drawable — for a box built by `safeSubstitute`
+        // as much as for a shipped constant.
+        const drawn = drawable(options, this, ASCII, (box) => box.grid);
+        return drawn === this && options.safe === true ? this.safeSubstitute() : drawn;
     }
     safeSubstitute() {
         return new Box(Array.from(this.grid, (char) => SAFE_SUBSTITUTIONS[char] ?? char).join(""));

package/dist/core/cells.d.ts

@@ -80,14 +80,25 @@ export declare function splitText(text: string, position: CellCol): [string, str
  */
 export declare function chopCells(text: string, maxWidth: CellCol): string[];
 /**
- * Returns the largest prefix of `text` whose cell width fits within `cap` cells.
- * No padding — the returned string may be narrower than `cap` when the next
- * character is wide and would overshoot. Never wider than `cap` cells.
+ * The grapheme clusters of `text`, in order: the unit `string-width` measures,
+ * and so the unit `cellLen` of a whole string is the sum of. Summing `cellLen`
+ * over code points instead disagrees with it on every glyph built from several:
+ * `❤️` is 1 + 0 by code point and 2 as a cluster, `👨‍👩‍👧` is 6 and 2, and a cut
+ * between two of its code points leaves half a glyph.
+ */
+export declare function graphemes(text: string): string[];
+/**
+ * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
+ * cut between grapheme clusters. No padding — the returned string may be
+ * narrower than `cap` when the next glyph is wide and would overshoot. Never
+ * wider than `cap` cells.
  *
- * When the first character already exceeds `cap` cells, returns "" (the caller
- * must decide whether to force-take the character or skip it).
+ * When the first glyph already exceeds `cap` cells, returns "" (the caller
+ * must decide whether to force-take the glyph or skip it).
  */
 export declare function cellFit(text: string, cap: CellCol): string;
+/** `cellFit` from the other end: the largest suffix of `text` within `cap` cells. */
+export declare function cellFitEnd(text: string, cap: CellCol): string;
 /**
  * Returns the largest code-unit end offset starting from `startCU` whose
  * prefix (from `startCU`) has cell width ≤ `cap`. Iterates from the given

package/dist/core/cells.js

@@ -127,25 +127,46 @@ export function chopCells(text, maxWidth) {
     }
     return lines;
 }
+// [LAW:no-shared-mutable-globals] A private memo, written only by `graphemes`.
+let segmenter;
 /**
- * Returns the largest prefix of `text` whose cell width fits within `cap` cells.
- * No padding — the returned string may be narrower than `cap` when the next
- * character is wide and would overshoot. Never wider than `cap` cells.
+ * The grapheme clusters of `text`, in order: the unit `string-width` measures,
+ * and so the unit `cellLen` of a whole string is the sum of. Summing `cellLen`
+ * over code points instead disagrees with it on every glyph built from several:
+ * `❤️` is 1 + 0 by code point and 2 as a cluster, `👨‍👩‍👧` is 6 and 2, and a cut
+ * between two of its code points leaves half a glyph.
+ */
+export function graphemes(text) {
+    segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" });
+    return Array.from(segmenter.segment(text), (s) => s.segment);
+}
+/**
+ * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
+ * cut between grapheme clusters. No padding — the returned string may be
+ * narrower than `cap` when the next glyph is wide and would overshoot. Never
+ * wider than `cap` cells.
  *
- * When the first character already exceeds `cap` cells, returns "" (the caller
- * must decide whether to force-take the character or skip it).
+ * When the first glyph already exceeds `cap` cells, returns "" (the caller
+ * must decide whether to force-take the glyph or skip it).
  */
 export function cellFit(text, cap) {
+    return fitClusters(graphemes(text), cap).join("");
+}
+/** `cellFit` from the other end: the largest suffix of `text` within `cap` cells. */
+export function cellFitEnd(text, cap) {
+    return fitClusters(graphemes(text).reverse(), cap).reverse().join("");
+}
+function fitClusters(clusters, cap) {
     let w = 0;
-    let i = 0;
-    for (const ch of text) {
-        const cw = cellLen(ch);
+    let n = 0;
+    for (const cluster of clusters) {
+        const cw = cellLen(cluster);
         if (w + cw > cap)
             break;
         w += cw;
-        i += ch.length;
+        n++;
     }
-    return text.slice(0, i);
+    return clusters.slice(0, n);
 }
 /**
  * Returns the largest code-unit end offset starting from `startCU` whose

package/dist/core/color.d.ts

@@ -215,14 +215,10 @@ export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade
  * A terminal theme — surface/foreground baseline, the ANSI 16/256 LUT, and a
  * semantic palette.
  *
- * **`ansiColors` is the canonical ANSI table, not a per-theme override.** All
- * preset themes in this codebase use `STANDARD_TABLE` for `ansiColors`. Theme
- * identity lives entirely in `palette` (primary, accent, text-*, surface, ...);
- * `ColorSpec.parse("red")` is intentionally consistent across themes — same
- * design as Textual itself, which models theming at the truecolor/semantic
- * layer rather than overloading the ANSI 16. Custom callers building bespoke
- * themes that *do* want to retint ANSI 16 are free to pass their own
- * `ColorTable`; that path is supported but not how the built-in presets work.
+ * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
+ * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * as it is in Rich, where each `TerminalTheme` carries its own table.
  */
 export declare class TerminalTheme {
     readonly backgroundColor: ColorRgba;