@promptctl/rich-js 0.18.1 → 0.20.0

package/README.md

@@ -342,7 +342,7 @@ console.print(new Greeting());
 
 ```typescript
 const console = new Console({
-  colorSystem: "truecolor", // null | "auto" | "standard" | "256" | "truecolor" | "windows"
+  colorSystem: "truecolor", // null | "auto" | "none" | "ansi" | "256" | "truecolor"
   width: 120,               // override terminal width
   stderr: true,             // write to stderr
   record: true,             // record output for export
@@ -354,14 +354,15 @@ const console = new Console({
 When `record: true`, export output after the fact:
 
 ```typescript
-import { saveHtml } from "@promptctl/rich-js/node/save";
+import { SOLARIZED_LIGHT, SVG_EXPORT_THEME } from "@promptctl/rich-js";
+import { saveSvg } from "@promptctl/rich-js/node/save";
 
-const text = console.exportText();
-const html = console.exportHtml();
-saveHtml(console, "output.html");
+const text = console.exportText({ clear: false });
+const html = console.exportHtml({ theme: SOLARIZED_LIGHT, clear: false });
+saveSvg(console, "output.svg", { theme: SVG_EXPORT_THEME });
 ```
 
-`saveText` / `saveHtml` live on the `node/save` subpath because they import `node:fs`; the main barrel stays browser-safe.
+`saveText`, `saveHtml` and `saveSvg` live on the `node/save` subpath because they import `node:fs`; the main barrel stays browser-safe. The [console guide](https://brandon-fryslie.github.io/rich-js/master/console#exporting) covers what each export draws, the themes it takes, and when it clears the recording.
 
 ## Demos
 
@@ -384,10 +385,12 @@ npm run demo
 | `npm run demo-inputs` | rich-config | The widgets — checkbox, toggle, slider, dropdown, text input, button — driving a theme and palette viewer. |
 | `npm run demo:dropdown` | dropdown-demo | Three `Dropdown` widgets: a plain one, one filtered as you type, and one whose options change every few seconds. |
 | `npm run template-bindings` | rich-template-bindings | Type a template on the left and watch it render on the right. |
-| `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 themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set any of `EXPORT_HTML=out.html`, `EXPORT_SVG=out.svg` and `EXPORT_TEXT=out.txt` to also save it to each file named. |
 | `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
+| `npm run effects-feel` | effects-feel | Shimmer, a gentle pulse on chosen elements, sparkle, a hue wheel, fade-in and a dissolve-out that eddies back before it goes, on a powerline strip and a run of text, at a colour depth you choose, with keys to step the frame rate, the demo's pace and the theme while it runs. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags and keys. |
 | `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`. |
+| `npm run viewport` | rich-viewport | A selection you move through a list taller than its window with the arrow keys, `j`/`k`, PgUp/PgDn and Home/End, kept in view by `Viewport.ensureVisible`; the mouse wheel scrolls the window, and `q` quits. |
+| `npm run terminal-host` | terminal-host | Each key you press printed as the bytes the terminal sends for it, and each resize as the new size — a program written against `TerminalHost` alone. `examples/terminal-host/embed.ts` runs the same program on an xterm.js terminal in your own page. |
 
 `Ctrl-C` quits any demo that stays running.
 

package/dist/core/box.d.ts

@@ -117,7 +117,9 @@ export declare class Box {
     plainHeaded(): Box;
     /**
      * [LAW:dataflow-not-control-flow] Every full-width rule the box can draw is
-     * this one loop; which rule it is arrives as four characters, not a branch.
+     * this one join; which rule it is arrives as four characters, not a branch.
+     * The rule is one segment, as the reference's `get_top` is one string, so
+     * its bytes are one styled run.
      */
     private getEdge;
     private getRowChars;

package/dist/core/box.js

@@ -173,21 +173,14 @@ export class Box {
     }
     /**
      * [LAW:dataflow-not-control-flow] Every full-width rule the box can draw is
-     * this one loop; which rule it is arrives as four characters, not a branch.
+     * this one join; which rule it is arrives as four characters, not a branch.
+     * The rule is one segment, as the reference's `get_top` is one string, so
+     * its bytes are one styled run.
      */
     getEdge(widths, chars, style, edge) {
-        const segments = [];
-        if (edge)
-            segments.push(new Segment(chars.left, style));
-        for (let i = 0; i < widths.length; i++) {
-            if (i > 0)
-                segments.push(new Segment(chars.cross, style));
-            segments.push(new Segment(chars.horizontal.repeat(widths[i]), style));
-        }
-        if (edge)
-            segments.push(new Segment(chars.right, style));
-        segments.push(Segment.line());
-        return segments;
+        const inner = widths.map((width) => chars.horizontal.repeat(width)).join(chars.cross);
+        const rule = edge ? chars.left + inner + chars.right : inner;
+        return [new Segment(rule, style), Segment.line()];
     }
     getRowChars(level) {
         switch (level) {

package/dist/core/cells.d.ts

@@ -66,8 +66,19 @@ export declare function setCellSize(text: string, totalWidth: CellCol): string;
  * Splits text at a cell position. Returns [left, right].
  * When the position falls mid-wide-character, the left side is padded
  * to reach exactly `position` cells. The wide char remains in the right side.
+ *
+ * [LAW:one-source-of-truth] The left side is `cellFit`'s, so the cut falls
+ * between the grapheme clusters `cellLen` measures and never inside one.
  */
 export declare function splitText(text: string, position: CellCol): [string, string];
+/**
+ * Cuts `text` into exactly `position` cells and the rest, as the reference's
+ * `Segment.split_cells` does: a wide glyph the cut goes through fits neither
+ * side, so it leaves a space in each of its cells, where `splitText` keeps it
+ * whole on the right. Every other character lands on exactly one side.
+ * `position` must fall inside `text`, between 0 and its width.
+ */
+export declare function cutCells(text: string, position: CellCol): [string, string];
 /**
  * Wraps text into lines of at most `maxWidth` cells, preserving every code
  * point: `chopCells(t, w).join("") === t`. Unlike `splitText` this never pads,
@@ -79,6 +90,12 @@ export declare function splitText(text: string, position: CellCol): [string, str
  * or less is no budget at all, so the text comes back as one line.
  */
 export declare function chopCells(text: string, maxWidth: CellCol): string[];
+/**
+ * `line` split at each of `cuts`, in one walk over it. Converting each cut to a
+ * code-unit offset on its own rescans the line from the start every time, which
+ * is quadratic in a long enough string.
+ */
+export declare function splitAtCells(line: string, cuts: readonly CellCol[]): string[];
 /**
  * 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`
@@ -105,8 +122,8 @@ export declare function cellFitEnd(text: string, cap: CellCol): string;
  * offset without slicing the tail, avoiding O(N²) allocation when called
  * repeatedly across a long string.
  *
- * [LAW:types-are-the-program] returns CodePoint because for...of always
- * stops on a code-point boundary.
+ * [LAW:types-are-the-program] returns CodePoint because it stops between
+ * grapheme clusters, and every cluster boundary is a code-point boundary.
  */
 export declare function cellFitFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
 /**
@@ -123,37 +140,53 @@ export declare function cellFitFrom(text: string, startCU: CodePoint, cap: CellC
  */
 export declare function cellStepFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
 /**
- * Returns the largest code-unit offset into `content` whose prefix has
- * cell width ≤ `cellCol`. When `cellCol` falls mid-wide-character the
- * function stops before that character (never advances into it).
- * Clamps to `content.length` if `cellCol` exceeds the string's total
- * cell width.
- *
- * This is the inverse of `cellLen(content.slice(0, codeUnit))` — given a
- * visual column, return the corresponding string index.
- *
- * Returns `CodePoint` because `for...of` iteration always stops on a
- * code-point boundary.
+ * The code-unit offset a visual column falls at: the end of the largest
+ * prefix of `content` within `cellCol` cells, so a column inside a wide glyph
+ * lands before it. The inverse of `cellLen(content.slice(0, offset))`.
  */
 export declare function cellColToCodeUnitOffset(content: string, cellCol: CellCol): CodePoint;
 /**
- * Advance one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *next* code point. Returns `s.length` when
- * already at or past the end.
- *
- * Handles surrogate pairs: when the code point at `cu` is a supplementary
- * character (U+10000…U+10FFFF) it occupies 2 UTF-16 code units, so the
- * returned offset advances by 2.
+ * The offset just past the grapheme cluster at `cu`: one step of a cursor, a
+ * Delete, a transposition, so `👍🏽` or `👨‍👩‍👧` moves and goes as the one
+ * glyph `cellLen` measures, never a code point at a time. `cu` is a cluster
+ * boundary in `s` (see `graphemeBoundary`); `s.length` gives `s.length`.
+ */
+export declare function nextGrapheme(s: string, cu: CodePoint): CodePoint;
+/** `nextGrapheme` backwards: the start of the cluster ending at `cu`; 0 at the start. */
+export declare function prevGrapheme(s: string, cu: CodePoint): CodePoint;
+/**
+ * Where an offset into `s` comes to rest as a cursor: itself when it is a
+ * cluster boundary, else the end of the cluster it falls inside, and never
+ * past `s.length`. The one parse from any number to the boundaries
+ * `nextGrapheme` and `prevGrapheme` step between.
+ */
+export declare function graphemeBoundary(s: string, cu: CodeUnit): CodePoint;
+declare const _tabSize: unique symbol;
+/** Cells between tab stops: a positive integer, so every stop is a column. */
+export type TabSize = number & {
+    readonly [_tabSize]: true;
+};
+/**
+ * `n` as a `TabSize`, or a `RangeError` naming it. Rich divides by the tab
+ * size and raises on 0; here the value is refused where it is given, not at
+ * the first tab it meets.
  */
-export declare function nextCodePoint(s: string, cu: CodeUnit): CodePoint;
+export declare function parseTabSize(n: number): TabSize;
+/** Text with its tabs expanded, and where each offset into the original went. */
+export interface TabExpansion {
+    readonly text: string;
+    offsetOf(offset: number): number;
+}
 /**
- * Step back one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *previous* code point. Returns 0 when already
- * at the start.
+ * `text` with each tab widened to the next tab stop — a multiple of `tabSize`
+ * cells from the start of its line — as Rich's `Text.expand_tabs` widens it, and
+ * `offsetOf`, where each code-unit offset into `text` lands in the result.
  *
- * Handles surrogate pairs: when the code unit at `cu - 1` is a low surrogate
- * AND the code unit at `cu - 2` is a high surrogate, steps back 2 code units.
- * Unpaired surrogates are treated as 1-CU characters.
+ * A tab is a column position, not a run of spaces: one that already sits a
+ * cell short of a stop widens to a single space. `offsetOf` is there because a
+ * caller that annotates the text by offset — a `RichText`'s spans — has to move
+ * its offsets with the characters, or every annotation after a tab lands short
+ * of what it styled.
  */
-export declare function prevCodePoint(s: string, cu: CodeUnit): CodePoint;
+export declare function expandTabs(text: string, tabSize: TabSize): TabExpansion;
 export {};

package/dist/core/cells.js

@@ -3,28 +3,17 @@
  * Handles ASCII, CJK (double-width), and emoji characters.
  */
 import stringWidth from "string-width";
+import { Memo } from "./memo.js";
 // [LAW:one-source-of-truth] string-width is the single authority for cell width
-const cellLenCache = new Map();
-const CACHE_MAX = 4096;
+const cellLenMemo = new Memo();
 /**
  * Returns the terminal cell width of a string.
  */
 export function cellLen(text) {
     if (text.length === 0)
         return 0;
-    // Fast path for pure ASCII
-    if (text.length <= 64) {
-        const cached = cellLenCache.get(text);
-        if (cached !== undefined)
-            return cached;
-    }
-    const width = stringWidth(text);
-    if (text.length <= 64) {
-        if (cellLenCache.size >= CACHE_MAX)
-            cellLenCache.clear();
-        cellLenCache.set(text, width);
-    }
-    return width;
+    // Short strings recur (words, cells, labels); a long one is rarely measured twice.
+    return text.length <= 64 ? cellLenMemo.get(text, stringWidth) : stringWidth(text);
 }
 /** Brand a raw number as a CellCol. Use only at trust boundaries. */
 export function asCellCol(n) { return n; }
@@ -74,36 +63,41 @@ export function setCellSize(text, totalWidth) {
     if (currentWidth < totalWidth) {
         return text + " ".repeat(totalWidth - currentWidth);
     }
-    return cropToWidth(text, totalWidth);
+    return splitText(text, totalWidth)[0];
 }
 /**
  * Splits text at a cell position. Returns [left, right].
  * When the position falls mid-wide-character, the left side is padded
  * to reach exactly `position` cells. The wide char remains in the right side.
+ *
+ * [LAW:one-source-of-truth] The left side is `cellFit`'s, so the cut falls
+ * between the grapheme clusters `cellLen` measures and never inside one.
  */
 export function splitText(text, position) {
     if (position <= 0)
         return ["", text];
-    const totalWidth = cellLen(text);
-    if (position >= totalWidth)
+    if (position >= cellLen(text))
         return [text, ""];
-    // Walk characters tracking cell width and source char index
-    let width = 0;
-    let charIndex = 0;
-    for (const char of text) {
-        const charWidth = cellLen(char);
-        if (width + charWidth > position)
-            break;
-        width += charWidth;
-        charIndex += char.length;
-    }
-    const left = text.slice(0, charIndex);
-    const right = text.slice(charIndex);
-    // If we stopped short of position (mid-wide-char), pad left with spaces
-    if (width < position) {
-        return [left + " ".repeat(position - width), right];
-    }
-    return [left, right];
+    const left = cellFit(text, position);
+    return [left + " ".repeat(position - cellLen(left)), text.slice(left.length)];
+}
+/**
+ * Cuts `text` into exactly `position` cells and the rest, as the reference's
+ * `Segment.split_cells` does: a wide glyph the cut goes through fits neither
+ * side, so it leaves a space in each of its cells, where `splitText` keeps it
+ * whole on the right. Every other character lands on exactly one side.
+ * `position` must fall inside `text`, between 0 and its width.
+ */
+export function cutCells(text, position) {
+    const head = cellFit(text, position);
+    // Cells of the glyph the cut goes through that lie left of it; 0 when the
+    // cut falls between glyphs, and then there is no such glyph.
+    const straddle = position - cellLen(head);
+    const [glyph = ""] = straddle > 0 ? clustersFrom(text, asCodePoint(head.length)) : [];
+    return [
+        head + " ".repeat(straddle),
+        " ".repeat(cellLen(glyph) - straddle) + text.slice(head.length + glyph.length),
+    ];
 }
 /**
  * Wraps text into lines of at most `maxWidth` cells, preserving every code
@@ -127,8 +121,39 @@ export function chopCells(text, maxWidth) {
     }
     return lines;
 }
-// [LAW:no-shared-mutable-globals] A private memo, written only by `graphemes`.
+/**
+ * `line` split at each of `cuts`, in one walk over it. Converting each cut to a
+ * code-unit offset on its own rescans the line from the start every time, which
+ * is quadratic in a long enough string.
+ */
+export function splitAtCells(line, cuts) {
+    const pieces = [];
+    let start = 0;
+    let offset = 0;
+    let cells = 0;
+    for (const ch of graphemes(line)) {
+        if (pieces.length < cuts.length && cells >= cuts[pieces.length]) {
+            pieces.push(line.slice(start, offset));
+            start = offset;
+        }
+        cells += cellLen(ch);
+        offset += ch.length;
+    }
+    return [...pieces, line.slice(start)];
+}
+// [LAW:no-shared-mutable-globals] Private memos, written only by `segmentsOf`:
+// the segmenter, and the segmentation of the last string walked, so a caller
+// stepping along one string does not re-segment the whole of it every step.
 let segmenter;
+let lastSegmented;
+/** The grapheme segmentation of `text`, reusing the last one when it is the same string. */
+function segmentsOf(text) {
+    if (lastSegmented?.text !== text) {
+        segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" });
+        lastSegmented = { text, segments: segmenter.segment(text) };
+    }
+    return lastSegmented.segments;
+}
 /**
  * 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`
@@ -137,8 +162,19 @@ let segmenter;
  * 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);
+    return Array.from(clustersFrom(text, asCodePoint(0)));
+}
+/**
+ * The clusters of `text` from code unit `start` on, lazily, so a walk that
+ * stops early pays only for the clusters it reads.
+ */
+function* clustersFrom(text, start) {
+    const segments = segmentsOf(text);
+    for (let at = start, s = segments.containing(at); s; s = segments.containing(at)) {
+        const end = s.index + s.segment.length;
+        yield text.slice(at, end);
+        at = asCodePoint(end);
+    }
 }
 /**
  * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
@@ -150,13 +186,14 @@ export function graphemes(text) {
  * must decide whether to force-take the glyph or skip it).
  */
 export function cellFit(text, cap) {
-    return fitClusters(graphemes(text), cap).join("");
+    return text.slice(0, fitLength(clustersFrom(text, asCodePoint(0)), cap));
 }
 /** `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("");
+    return text.slice(text.length - fitLength(graphemes(text).reverse(), cap));
 }
-function fitClusters(clusters, cap) {
+/** The code units of the leading `clusters` that fit within `cap` cells. */
+function fitLength(clusters, cap) {
     let w = 0;
     let n = 0;
     for (const cluster of clusters) {
@@ -164,9 +201,9 @@ function fitClusters(clusters, cap) {
         if (w + cw > cap)
             break;
         w += cw;
-        n++;
+        n += cluster.length;
     }
-    return clusters.slice(0, n);
+    return n;
 }
 /**
  * Returns the largest code-unit end offset starting from `startCU` whose
@@ -174,22 +211,11 @@ function fitClusters(clusters, cap) {
  * offset without slicing the tail, avoiding O(N²) allocation when called
  * repeatedly across a long string.
  *
- * [LAW:types-are-the-program] returns CodePoint because for...of always
- * stops on a code-point boundary.
+ * [LAW:types-are-the-program] returns CodePoint because it stops between
+ * grapheme clusters, and every cluster boundary is a code-point boundary.
  */
 export function cellFitFrom(text, startCU, cap) {
-    let w = 0;
-    let i = startCU;
-    while (i < text.length) {
-        const cp = text.codePointAt(i);
-        const ch = String.fromCodePoint(cp);
-        const cw = cellLen(ch);
-        if (w + cw > cap)
-            break;
-        w += cw;
-        i = asCodePoint(i + ch.length);
-    }
-    return i;
+    return asCodePoint(startCU + fitLength(clustersFrom(text, startCU), cap));
 }
 /**
  * Like `cellFitFrom`, but for any `startCU` inside `text` the result is
@@ -204,84 +230,105 @@ export function cellFitFrom(text, startCU, cap) {
  * `chopCells` did neither and hung.
  */
 export function cellStepFrom(text, startCU, cap) {
-    return asCodePoint(Math.max(cellFitFrom(text, startCU, cap), nextCodePoint(text, startCU)));
+    const [first = ""] = clustersFrom(text, startCU);
+    return asCodePoint(Math.max(cellFitFrom(text, startCU, cap), startCU + first.length));
 }
 /**
- * Returns the largest code-unit offset into `content` whose prefix has
- * cell width ≤ `cellCol`. When `cellCol` falls mid-wide-character the
- * function stops before that character (never advances into it).
- * Clamps to `content.length` if `cellCol` exceeds the string's total
- * cell width.
- *
- * This is the inverse of `cellLen(content.slice(0, codeUnit))` — given a
- * visual column, return the corresponding string index.
- *
- * Returns `CodePoint` because `for...of` iteration always stops on a
- * code-point boundary.
+ * The code-unit offset a visual column falls at: the end of the largest
+ * prefix of `content` within `cellCol` cells, so a column inside a wide glyph
+ * lands before it. The inverse of `cellLen(content.slice(0, offset))`.
  */
 export function cellColToCodeUnitOffset(content, cellCol) {
-    let w = 0;
-    let i = 0;
-    for (const ch of content) {
-        if (w >= cellCol)
-            break;
-        const cw = cellLen(ch);
-        if (w + cw > cellCol)
-            break;
-        w += cw;
-        i += ch.length;
-    }
-    return asCodePoint(i);
+    return cellFitFrom(content, asCodePoint(0), cellCol);
 }
 /**
- * Advance one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *next* code point. Returns `s.length` when
- * already at or past the end.
- *
- * Handles surrogate pairs: when the code point at `cu` is a supplementary
- * character (U+10000…U+10FFFF) it occupies 2 UTF-16 code units, so the
- * returned offset advances by 2.
+ * The offset just past the grapheme cluster at `cu`: one step of a cursor, a
+ * Delete, a transposition, so `👍🏽` or `👨‍👩‍👧` moves and goes as the one
+ * glyph `cellLen` measures, never a code point at a time. `cu` is a cluster
+ * boundary in `s` (see `graphemeBoundary`); `s.length` gives `s.length`.
  */
-export function nextCodePoint(s, cu) {
-    if (cu >= s.length)
-        return asCodePoint(s.length);
-    const cp = s.codePointAt(cu);
-    return asCodePoint(cu + (cp > 0xFFFF ? 2 : 1));
+export function nextGrapheme(s, cu) {
+    const [cluster = ""] = clustersFrom(s, cu);
+    return asCodePoint(cu + cluster.length);
 }
-/**
- * Step back one full Unicode code point from `cu`, returning the code-unit
- * offset of the start of the *previous* code point. Returns 0 when already
- * at the start.
- *
- * Handles surrogate pairs: when the code unit at `cu - 1` is a low surrogate
- * AND the code unit at `cu - 2` is a high surrogate, steps back 2 code units.
- * Unpaired surrogates are treated as 1-CU characters.
- */
-export function prevCodePoint(s, cu) {
+/** `nextGrapheme` backwards: the start of the cluster ending at `cu`; 0 at the start. */
+export function prevGrapheme(s, cu) {
     if (cu <= 0)
         return asCodePoint(0);
-    const low = s.charCodeAt(cu - 1);
-    if (low >= 0xDC00 && low <= 0xDFFF && cu >= 2) {
-        const high = s.charCodeAt(cu - 2);
-        if (high >= 0xD800 && high <= 0xDBFF)
-            return asCodePoint(cu - 2);
+    return asCodePoint(segmentsOf(s).containing(cu - 1).index);
+}
+/**
+ * Where an offset into `s` comes to rest as a cursor: itself when it is a
+ * cluster boundary, else the end of the cluster it falls inside, and never
+ * past `s.length`. The one parse from any number to the boundaries
+ * `nextGrapheme` and `prevGrapheme` step between.
+ */
+export function graphemeBoundary(s, cu) {
+    const at = Math.min(cu, s.length);
+    const cluster = segmentsOf(s).containing(at);
+    return asCodePoint(cluster === undefined || cluster.index === at ? at : cluster.index + cluster.segment.length);
+}
+/**
+ * `n` as a `TabSize`, or a `RangeError` naming it. Rich divides by the tab
+ * size and raises on 0; here the value is refused where it is given, not at
+ * the first tab it meets.
+ */
+export function parseTabSize(n) {
+    if (!Number.isInteger(n) || n < 1) {
+        throw new RangeError(`tabSize must be a positive integer, got ${n}`);
     }
-    return asCodePoint(cu - 1);
+    return n;
 }
-// --- internal ---
-function cropToWidth(text, targetWidth) {
-    let width = 0;
-    let i = 0;
-    // Use the string's code point iterator to handle surrogate pairs
-    for (const char of text) {
-        const charWidth = cellLen(char);
-        if (width + charWidth > targetWidth)
-            break;
-        width += charWidth;
-        i += char.length;
+/**
+ * `text` with each tab widened to the next tab stop — a multiple of `tabSize`
+ * cells from the start of its line — as Rich's `Text.expand_tabs` widens it, and
+ * `offsetOf`, where each code-unit offset into `text` lands in the result.
+ *
+ * A tab is a column position, not a run of spaces: one that already sits a
+ * cell short of a stop widens to a single space. `offsetOf` is there because a
+ * caller that annotates the text by offset — a `RichText`'s spans — has to move
+ * its offsets with the characters, or every annotation after a tab lands short
+ * of what it styled.
+ */
+export function expandTabs(text, tabSize) {
+    const [head, ...rest] = text.split("\t");
+    const tabAt = []; // offset of each tab in `text`
+    const grownBy = []; // code units added by this tab and every one before it
+    const columnAfter = (piece, column) => {
+        const newline = piece.lastIndexOf("\n");
+        return (newline < 0 ? column : 0) + cellLen(piece.slice(newline + 1));
+    };
+    // A piece's column is read only when a tab follows it, so text with no tab
+    // costs one `split` and no measuring.
+    let expanded = head;
+    let before = head; // the piece the next tab follows
+    let column = 0; // the column `before` starts at
+    let offset = head.length;
+    let grown = 0;
+    for (const piece of rest) {
+        column = columnAfter(before, column);
+        const spaces = tabSize - (column % tabSize);
+        grown += spaces - 1;
+        tabAt.push(offset);
+        grownBy.push(grown);
+        expanded += " ".repeat(spaces) + piece;
+        column += spaces;
+        before = piece;
+        offset += 1 + piece.length;
     }
-    const cropped = text.slice(0, i);
-    // Pad if we couldn't hit the exact width (wide char boundary)
-    const diff = targetWidth - width;
-    return diff > 0 ? cropped + " ".repeat(diff) : cropped;
+    // An offset moves by what every tab before it grew: the count of tabs at
+    // offsets below it, found by bisection since `tabAt` ascends.
+    const offsetOf = (at) => {
+        let low = 0;
+        let high = tabAt.length;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if (tabAt[mid] < at)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+        return at + (low === 0 ? 0 : grownBy[low - 1]);
+    };
+    return { text: expanded, offsetOf };
 }

package/dist/core/clock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Clock — the time source and timer whoever draws frames is handed, and the
+ * frame rate it ticks at.
+ *
+ * [LAW:no-ambient-temporal-coupling] Frame rate belongs to whoever draws the
+ * frames — an `App`, a `Live` — never to what is drawn, and each ticks on the
+ * `Clock` it was given. An `App` reads the frame's time through that clock and
+ * hands it to its view as data, so nothing rendered reads a clock, and an
+ * effect sampled thirty times a second or once every two seconds runs the
+ * same code.
+ *
+ * [LAW:effects-at-boundaries] The clock is a capability passed in, like the
+ * `TerminalHost`: a test hands over a clock whose time it moves by hand and
+ * counts frames with no real timer, and nothing it starts can outlive the
+ * thing that started it. `systemClock` is the one place the library reads the
+ * platform's clock and timers, and it reads them only when called.
+ */
+import type { Unsubscribe } from "./subscription.js";
+declare const parsed: unique symbol;
+/**
+ * How often frames are drawn: a positive, finite number of frames a second,
+ * fractional included — 0.5 is one frame every two seconds.
+ *
+ * [LAW:parse-dont-validate] Only `frameRate` makes one, so holding a
+ * `FrameRate` is the proof the number was checked, and nothing that takes one
+ * checks it again.
+ */
+export interface FrameRate {
+    readonly perSecond: number;
+    /** Seconds from one frame to the next. */
+    readonly interval: number;
+    readonly [parsed]: true;
+}
+/**
+ * `perSecond` as a `FrameRate`; anything but a positive, finite number throws,
+ * and so does a rate whose frames are further apart than a timer can wait —
+ * about 24.8 days.
+ */
+export declare function frameRate(perSecond: number): FrameRate;
+export interface Clock {
+    /** The time now, in seconds, on this clock's own timeline, which never runs backwards. */
+    now(): number;
+    /** Call `tick` once a frame at `rate` until the returned function is called. */
+    every(rate: FrameRate, tick: () => void): Unsubscribe;
+}
+/** The platform's monotonic clock and its interval timer. */
+export declare function systemClock(): Clock;
+export {};