@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/host/app.js

@@ -24,63 +24,65 @@
  * under us, how it is suspended — is the `TerminalHost`'s, so the same app
  * runs in node and in a browser with no path of its own for either.
  */
+import { frameRate, systemClock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
-import { segmentsToString } from "../core/render.js";
+import { SurfacePainter } from "../core/paint.js";
 import { fitHeight } from "../core/protocol.js";
 import { hostEnvironment } from "./host-environment.js";
+// [LAW:one-source-of-truth] How a frame draws — its glyphs, the style names
+// it knows, what happens to a style it cannot resolve, markup and
+// highlighting — is the console's to say, so App takes those options as the
+// console declares them. This list is both the type and what is copied: the
+// host alone decides the console's size, colours and sink, so no other
+// property of the options object reaches it, whatever the object carries.
+const DRAW_OPTIONS = ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+function drawOptions(options) {
+    const picked = {};
+    const copy = (key) => {
+        picked[key] = options[key];
+    };
+    DRAW_OPTIONS.forEach(copy);
+    return picked;
+}
+const DEFAULT_RATE = frameRate(30);
 // Button presses, motion and the wheel, in the SGR encoding: coordinates as
 // decimal numbers, so a terminal wider than 223 columns still reports them.
-const POINTER_ON = "\x1b[?1006h\x1b[?1000h\x1b[?1003h";
-const POINTER_OFF = "\x1b[?1003l\x1b[?1000l\x1b[?1006l";
-const SURFACES = {
-    alternate: {
-        exact: true,
-        enter: "\x1b[?1049h" + POINTER_ON,
-        leave: () => POINTER_OFF + "\x1b[?1049l",
-        home: () => "\x1b[H",
-        // The frame is every row of the screen, so there is nothing left under it
-        // — and after the terminal shrinks, painting the old count would scroll.
-        painted: (frameRows) => frameRows,
-    },
-    inline: {
-        exact: false,
-        enter: "",
-        // Below the frame, where the program's next line belongs.
-        leave: (rows) => (rows > 0 ? "\n" : ""),
-        // After N rows written with N-1 newlines between them, the cursor is on
-        // the last. `ESC[0A` still moves a row on some terminals, so a one-row
-        // frame is returned to with the carriage return alone.
-        home: (rows) => (rows > 1 ? `\x1b[${rows - 1}A\r` : "\r"),
-        // A shorter frame blanks the rows the last one left below it.
-        painted: (frameRows, lastRows) => Math.max(frameRows, lastRows),
-    },
+// The terminal reports a pointer by its row on the screen, and an inline
+// frame does not know which row of the screen it starts on, so only the
+// alternate surface gets them.
+const POINTER = {
+    alternate: { on: "\x1b[?1006h\x1b[?1000h\x1b[?1003h", off: "\x1b[?1003l\x1b[?1000l\x1b[?1006l" },
+    inline: { on: "", off: "" },
 };
-const HIDE_CURSOR = "\x1b[?25l";
-const SHOW_CURSOR = "\x1b[?25h";
-const RESET_STYLE = "\x1b[0m";
-const ERASE_LINE = "\x1b[2K";
 export class App {
     host;
     surface;
     view;
+    clock;
+    rate;
+    // What is animating now: one token per `animate()` not yet released.
+    animations = new Set();
+    stopTicking = null;
     // [LAW:one-source-of-truth] The host is the console's whole environment:
     // its size, its colours, where bytes go. Every frame renders with this
     // console's options and is encoded for its destination.
     console;
     _phase = "idle";
     _frame = [];
-    // The last frame's own rows on the terminal — what `home` rewinds.
-    rows = 0;
+    painter;
     refreshQueued = false;
     subscriptions = [];
     paintHandlers = new Set();
     settle = () => { };
     constructor(options) {
         this.host = options.host;
-        this.surface = SURFACES[options.surface];
+        this.surface = options.surface;
+        this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
         this.view = options.view;
-        this.console = new Console({ environment: hostEnvironment(options.host), asciiOnly: options.asciiOnly });
+        this.clock = options.clock ?? systemClock();
+        this.rate = options.rate ?? DEFAULT_RATE;
+        this.console = new Console({ ...drawOptions(options), environment: hostEnvironment(options.host) });
     }
     get phase() {
         return this._phase;
@@ -124,6 +126,7 @@ export class App {
             ];
             this.enter();
             this.paint();
+            this.tick();
         });
     }
     /**
@@ -140,6 +143,10 @@ export class App {
             return;
         this.refreshQueued = true;
         setTimeout(() => {
+            // A frame painted since it was asked for — a tick — drew every change
+            // made before it, so there is nothing left to paint.
+            if (!this.refreshQueued)
+                return;
             this.refreshQueued = false;
             // [LAW:types-are-the-program] Only a running app holds the terminal; a
             // suspended one repaints when it resumes, and a stopped one never does.
@@ -147,6 +154,24 @@ export class App {
                 this.paint();
         });
     }
+    /**
+     * Paint at the app's `rate` until the returned function is called: what an
+     * effect sampled at the frame's time asks for while it moves. The app ticks
+     * while anything is animating and it holds the terminal, and stops when
+     * nothing is, so a still app paints only when asked. The animation's first
+     * frame does not wait out an interval: at one frame every two seconds, that
+     * would hold its start off screen for two.
+     */
+    animate() {
+        const animation = {};
+        this.animations.add(animation);
+        this.tick();
+        this.refresh();
+        return () => {
+            this.animations.delete(animation);
+            this.tick();
+        };
+    }
     /**
      * Hand the terminal to whatever launched the program, and take it back and
      * repaint when that resumes it. What sends the app here is the app's own —
@@ -156,6 +181,7 @@ export class App {
         if (this._phase !== "running")
             return;
         this._phase = "suspended";
+        this.tick();
         this.leave();
         await this.host.suspend();
         // Stopped while suspended — by a signal, say: the terminal is already
@@ -163,11 +189,9 @@ export class App {
         if (this._phase !== "suspended")
             return;
         this._phase = "running";
-        // What the last frame occupied is gone under whatever ran meanwhile, so
-        // the next one starts where the cursor is.
-        this.rows = 0;
         this.enter();
         this.paint();
+        this.tick();
     }
     /**
      * Hear each frame once it is on screen — what `frame` now returns. A
@@ -193,10 +217,12 @@ export class App {
     // --- the terminal ---
     enter() {
         this.host.setRawMode(true);
-        this.host.write(this.surface.enter + HIDE_CURSOR);
+        this.painter.take();
+        this.host.write(POINTER[this.surface].on);
     }
     leave() {
-        this.host.write(RESET_STYLE + SHOW_CURSOR + this.surface.leave(this.rows));
+        this.host.write(POINTER[this.surface].off);
+        this.painter.handBack();
         this.host.setRawMode(false);
     }
     end(outcome) {
@@ -204,6 +230,7 @@ export class App {
         if (phase === "idle" || phase === "stopped")
             return;
         this._phase = "stopped";
+        this.tick();
         for (const unsubscribe of this.subscriptions)
             unsubscribe();
         this.subscriptions = [];
@@ -213,6 +240,22 @@ export class App {
         this.host.stop();
         this.settle(outcome);
     }
+    // [LAW:single-enforcer] Whether the clock is ticking follows from the
+    // phase and what is animating, and is brought in line with them here
+    // alone, after every change to either — so a timer runs exactly while a
+    // running app has something animating, and none outlives the app.
+    tick() {
+        const wanted = this._phase === "running" && this.animations.size > 0;
+        const ticking = this.stopTicking;
+        if (ticking === null) {
+            if (wanted)
+                this.stopTicking = this.clock.every(this.rate, () => this.paint());
+        }
+        else if (!wanted) {
+            ticking();
+            this.stopTicking = null;
+        }
+    }
     // [LAW:no-silent-failure] A frame that throws ends the app with that
     // error: the terminal is handed back, and `run` rejects with it.
     paint() {
@@ -224,31 +267,18 @@ export class App {
         }
     }
     draw() {
+        // This frame draws every change made before it, a queued refresh's included.
+        this.refreshQueued = false;
         const options = this.console.options;
-        const { maxWidth: cols } = options;
-        const height = { rows: options.height.rows, exact: this.surface.exact };
-        const lines = Segment.splitLines(this.view().render({ ...options, height }));
+        const height = this.painter.height(options.height.rows);
+        // [LAW:no-ambient-temporal-coupling] The frame owner reads the clock,
+        // once a frame; the view is handed the time as data.
+        const lines = Segment.splitLines(this.view(this.clock.now()).render({ ...options, height }));
         // The app set the budget, so the app shapes what comes back: no deeper
-        // than the terminal — a taller frame would scroll the rows `home` counts
-        // back over — and, as a region, exactly that deep. No row wider than the
-        // terminal either: one that soft-wrapped would push every row below it
-        // down a row the frame does not know about.
-        const frame = fitHeight(lines.slice(0, height.rows), height).map((line) => Segment.adjustLineLength(line, cols, undefined, false));
-        const painted = Math.min(this.surface.painted(frame.length, this.rows), height.rows);
-        // Each row is erased as it is reached rather than the frame cleared
-        // first, so no blank screen shows between two frames. The erase leads
-        // its row: after a row that fills the width, the cursor sits on its last
-        // cell, and an erase there would take it.
-        const destination = this.console.destination;
-        const body = Array.from({ length: painted }, (_, row) => ERASE_LINE + segmentsToString(frame[row] ?? [], destination)).join("\n");
-        // Rows blanked below the frame are not the frame's: the cursor goes back
-        // up to its last row, so the next frame and the program's next line start
-        // from the frame's own height.
-        const blanked = painted - Math.max(frame.length, 1);
-        const back = blanked > 0 ? `\x1b[${blanked}A` : "";
-        this.host.write(this.surface.home(this.rows) + body + back);
+        // than the terminal — a taller frame would scroll the rows the painter
+        // goes back over — and, as a region, exactly that deep.
+        const frame = this.painter.paint(() => fitHeight(lines.slice(0, height.rows), height), { rows: height.rows, cols: options.maxWidth }, this.console.destination);
         this._frame = frame;
-        this.rows = frame.length;
         for (const handler of [...this.paintHandlers])
             handler(frame);
     }

package/dist/host/index.d.ts

@@ -2,4 +2,5 @@ export { BrowserTerminalHost } from "./terminal-host.js";
 export type { TerminalHost, TerminalSize, DataHandler, ResizeHandler, ExitHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
-export type { AppOptions, AppPhase, Surface } from "./app.js";
+export type { AppOptions, AppPhase } from "./app.js";
+export type { Surface } from "../core/paint.js";

package/dist/host/terminal-host.d.ts

@@ -37,6 +37,7 @@
  * not an omniscient handle to "the process."
  */
 import type { Unsubscribe } from "../core/subscription.js";
+import type { Env } from "../core/env.js";
 export interface TerminalSize {
     readonly cols: number;
     readonly rows: number;
@@ -90,7 +91,7 @@ export interface TerminalHost {
      * rather than being read off whatever `process` the renderer happens to
      * share a runtime with, which in a browser is none.
      */
-    readonly env: NodeJS.ProcessEnv;
+    readonly env: Env;
     /**
      * Run `handler` once, when the program ends by any path this host can
      * observe, so whoever changed the terminal can hand it back. The program
@@ -166,7 +167,7 @@ export declare class BrowserTerminalHost implements TerminalHost {
     constructor(options: BrowserTerminalHostOptions);
     get isTTY(): boolean;
     get writesToTerminal(): boolean;
-    get env(): NodeJS.ProcessEnv;
+    get env(): Env;
     write(data: Uint8Array | string): void;
     size(): TerminalSize;
     setRawMode(_raw: boolean): void;

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { cellLen, setCellSize, splitText, chopCells, cellFit, asCellCol, asCodePoint, } from "./core/cells.js";
 export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
-export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
-export type { DetectColorOptions, Destination } from "./core/color.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export type { ColorSystemName, DetectColorOptions, Destination } from "./core/color.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
-export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
+export { resolveColorRef, ColorRefError } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
 export type { BaseColors } from "./themes/buildPalette.js";
 export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
@@ -13,10 +13,14 @@ export { getThemePalette, listThemePalettes } from "./themes/registry.js";
 export type { ThemeName } from "./themes/registry.js";
 export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
 export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
-export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
-export type { ColorStop, RampEasing } from "./themes/ramp.js";
+export { ColorRamp } from "./themes/ramp.js";
+export type { ColorStop } from "./themes/ramp.js";
+export { EASES, Phase, cubicBezier, parseEase, steps } from "./core/easing.js";
+export type { Ease, StepPosition } from "./core/easing.js";
+export { frameRate, systemClock } from "./core/clock.js";
+export type { Clock, FrameRate } from "./core/clock.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
-export type { StyleOptions } from "./core/style.js";
+export type { StyleOptions, TextStyle, LayeredStyle } from "./core/style.js";
 export { Segment, ControlType, } from "./core/segment.js";
 export type { ControlCode } from "./core/segment.js";
 export type { Anchor } from "./core/anchor.js";
@@ -48,8 +52,11 @@ export type { JSONOptions } from "./core/json.js";
 export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export type { SpinnerData } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
-export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, PrintOptions, } from "./core/console.js";
+export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, LiveRegion, PrintOptions, } from "./core/console.js";
+export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
+export { Effected } from "./renderables/effect.js";
+export type { CellColors, Effect, EffectCell, EffectedOptions } from "./renderables/effect.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";
@@ -78,13 +85,13 @@ export type { LiveOptions } from "./renderables/live.js";
 export { Status } from "./renderables/status.js";
 export type { StatusOptions } from "./renderables/status.js";
 export { Progress, TextColumn, BarColumn, TaskProgressColumn, TimeRemainingColumn, TimeElapsedColumn, SpinnerColumn, MofNCompleteColumn, track, } from "./renderables/progress.js";
-export type { ProgressOptions, TaskOptions, TaskUpdateOptions } from "./renderables/progress.js";
+export type { MofNCompleteColumnOptions, ProgressColumn, ProgressOptions, SpinnerColumnOptions, Task, TaskOptions, TaskUpdateOptions, TimeRemainingColumnOptions, } from "./renderables/progress.js";
 export { Prompt, IntPrompt, FloatPrompt, Confirm } from "./renderables/prompt.js";
-export type { PromptInput, PromptOptions } from "./renderables/prompt.js";
+export type { ConfirmOptions, PromptInput, PromptOptions } from "./renderables/prompt.js";
 export { Traceback } from "./renderables/traceback.js";
 export type { TracebackOptions } from "./renderables/traceback.js";
 export { Syntax } from "./renderables/syntax.js";
-export type { SyntaxOptions } from "./renderables/syntax.js";
+export type { SyntaxLanguage, SyntaxOptions } from "./renderables/syntax.js";
 export { Markdown } from "./renderables/markdown.js";
 export type { MarkdownOptions } from "./renderables/markdown.js";
 export { Layout } from "./renderables/layout.js";

package/dist/index.js

@@ -1,13 +1,13 @@
 // Core primitives
 export { cellLen, setCellSize, splitText, chopCells, cellFit, asCellCol, asCodePoint, } from "./core/cells.js";
-export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 // Perceptually-uniform color space (manipulation, transposition).
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 // Themes — semantic palettes (distinct from ColorTable quantization LUTs)
 export { Palette } from "./themes/palette.js";
 // The one checkpoint turning an author-written colour string — a palette
 // variable name or a `#RRGGBB` literal — into a colour. [LAW:parse-dont-validate]
-export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
+export { resolveColorRef, ColorRefError } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
 export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
 export { getThemePalette, listThemePalettes } from "./themes/registry.js";
@@ -24,9 +24,15 @@ export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "
 export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
 // A number → a color through ordered stops, interpolated in OKLCH — the one
 // color operation whose input is a measurement rather than a color, so a
-// gradient (or, with the `step` easing, a threshold cascade) stays inside the
+// gradient (or, with the `step` ease, a threshold cascade) stays inside the
 // theme system instead of being computed beside it.
-export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
+export { ColorRamp } from "./themes/ramp.js";
+// Progress in [0, 1]: phases turn seconds into it, eases reshape it. One
+// vocabulary for ramps and time-based effects alike, CSS's names throughout.
+export { EASES, Phase, cubicBezier, parseEase, steps } from "./core/easing.js";
+// The time source and timer whoever draws frames is handed, and the one
+// parser of the rate it ticks at.
+export { frameRate, systemClock } from "./core/clock.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
 export { Segment, ControlType, } from "./core/segment.js";
 export { Box } from "./core/box.js";
@@ -63,6 +69,7 @@ export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
+export { Effected } from "./renderables/effect.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, SCROLLBAR } from "./renderables/viewport.js";

package/dist/node/prompt.d.ts

@@ -13,6 +13,19 @@
  *     // or with options:
  *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
  *
+ * The prompt is printed by the `Console` it was asked on — the app's, when it
+ * passed one as `console`, a new default one otherwise — and then a line is
+ * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
+ * the prompt is coloured exactly as that console's own output would be and
+ * goes to its target: a console on stderr asks on stderr, beside the
+ * invalid-answer messages it prints. It goes as one logical line, never broken
+ * at the console's width: the terminal wraps it at whatever width it has.
+ *
+ * readline reads in non-terminal mode, the terminal's own cooked line
+ * discipline, as Python's `input()` does without its readline module: in
+ * terminal mode readline redraws the line itself, prompt included, and needs a
+ * whole `tty.WriteStream` to draw on, which a console's target need not be.
+ *
  * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
  * created, asked, closed. No shared `rl` across prompts, no listener-leak
  * pitfalls when callers stack prompts in a loop.

package/dist/node/prompt.js

@@ -13,18 +13,39 @@
  *     // or with options:
  *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
  *
+ * The prompt is printed by the `Console` it was asked on — the app's, when it
+ * passed one as `console`, a new default one otherwise — and then a line is
+ * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
+ * the prompt is coloured exactly as that console's own output would be and
+ * goes to its target: a console on stderr asks on stderr, beside the
+ * invalid-answer messages it prints. It goes as one logical line, never broken
+ * at the console's width: the terminal wraps it at whatever width it has.
+ *
+ * readline reads in non-terminal mode, the terminal's own cooked line
+ * discipline, as Python's `input()` does without its readline module: in
+ * terminal mode readline redraws the line itself, prompt included, and needs a
+ * whole `tty.WriteStream` to draw on, which a console's target need not be.
+ *
  * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
  * created, asked, closed. No shared `rl` across prompts, no listener-leak
  * pitfalls when callers stack prompts in a loop.
  */
 import * as readline from "node:readline";
-export const nodeAsk = (prompt) => new Promise((resolve) => {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    rl.question(prompt, (answer) => {
-        rl.close();
-        resolve(answer);
+export const nodeAsk = (prompt, console) => {
+    console.print(prompt, { end: "", softWrap: true });
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            // [LAW:types-are-the-program] exception: readline types its output as a
+            // whole `NodeJS.WritableStream`, and a console's target is only a
+            // `ConsoleSink`. With `terminal: false` readline only ever calls its
+            // `write`, whatever its `isTTY` says.
+            output: console.file,
+            terminal: false,
+        });
+        rl.question("", (answer) => {
+            rl.close();
+            resolve(answer);
+        });
     });
-});
+};

package/dist/node/save.d.ts

@@ -8,10 +8,11 @@
  * refuse to resolve `fs` if a consumer ever pulls it in by accident.
  *
  * [LAW:single-enforcer] One funnel per format: `saveText` consumes
- * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
- * The encoding and recording logic stays on Console; this file is purely
- * the IO sink.
+ * `Console.exportText()`, `saveHtml` consumes `Console.exportHtml()`, and
+ * `saveSvg` consumes `Console.exportSvg()`. The encoding and recording logic
+ * stays on Console; this file is purely the IO sink.
  */
 import type { Console } from "../core/console.js";
 export declare function saveText(out: Console, path: string, options?: Parameters<Console["exportText"]>[0]): void;
 export declare function saveHtml(out: Console, path: string, options?: Parameters<Console["exportHtml"]>[0]): void;
+export declare function saveSvg(out: Console, path: string, options?: Parameters<Console["exportSvg"]>[0]): void;

package/dist/node/save.js

@@ -8,9 +8,9 @@
  * refuse to resolve `fs` if a consumer ever pulls it in by accident.
  *
  * [LAW:single-enforcer] One funnel per format: `saveText` consumes
- * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
- * The encoding and recording logic stays on Console; this file is purely
- * the IO sink.
+ * `Console.exportText()`, `saveHtml` consumes `Console.exportHtml()`, and
+ * `saveSvg` consumes `Console.exportSvg()`. The encoding and recording logic
+ * stays on Console; this file is purely the IO sink.
  */
 import { writeFileSync } from "node:fs";
 export function saveText(out, path, options) {
@@ -19,3 +19,6 @@ export function saveText(out, path, options) {
 export function saveHtml(out, path, options) {
     writeFileSync(path, out.exportHtml(options), "utf-8");
 }
+export function saveSvg(out, path, options) {
+    writeFileSync(path, out.exportSvg(options), "utf-8");
+}

package/dist/node/terminal-host.d.ts

@@ -29,6 +29,7 @@
  */
 import type { DataHandler, ExitHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
 import type { Unsubscribe } from "../core/subscription.js";
+import type { Env } from "../core/env.js";
 /**
  * Subset of NodeJS stream API the node host actually depends on. Tests
  * construct a host over PassThrough / Writable mocks; production wires it
@@ -79,7 +80,7 @@ export interface NodeTerminalHostOptions {
      * pass a fixed map so what the host reports does not depend on the shell
      * that ran them.
      */
-    env?: NodeJS.ProcessEnv;
+    env?: Env;
     /**
      * What the host hears the program end through and suspends it with.
      * Defaults to `process`; tests pass an emitter that records `kill`.
@@ -90,7 +91,7 @@ export declare class NodeTerminalHost implements TerminalHost {
     private readonly stdin;
     private readonly stdout;
     private readonly process;
-    readonly env: NodeJS.ProcessEnv;
+    readonly env: Env;
     private readonly dataHandlers;
     private readonly resizeHandlers;
     private dataListener;

package/dist/node/traceback.d.ts

@@ -15,7 +15,8 @@
  * payload is trusted to be an `Error`: `@types/node` annotates
  * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
  * string, so the annotation is a claim about the common case rather than a
- * guarantee. `report` takes `unknown`.
+ * guarantee. `report` takes `unknown` and hands it to `Traceback` as it came,
+ * which reads a caught value of any shape.
  *
  * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
  * report after the terminal is handed back. A program holding the alternate

package/dist/node/traceback.js

@@ -15,7 +15,8 @@
  * payload is trusted to be an `Error`: `@types/node` annotates
  * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
  * string, so the annotation is a claim about the common case rather than a
- * guarantee. `report` takes `unknown`.
+ * guarantee. `report` takes `unknown` and hands it to `Traceback` as it came,
+ * which reads a caught value of any shape.
  *
  * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
  * report after the terminal is handed back. A program holding the alternate
@@ -26,45 +27,8 @@
  * the terminal. Node's crash sequence owns the order, not the order in which
  * `installTraceback` and a host happened to add their listeners.
  */
-import { inspect, types } from "node:util";
 import { Console } from "../core/console.js";
 import { Traceback } from "../renderables/traceback.js";
-/** A payload's own stack, when it carries one, or `""` when it does not. */
-function stackOf(reason) {
-    if (typeof reason !== "object" || reason === null)
-        return "";
-    if (!("stack" in reason))
-        return "";
-    return typeof reason.stack === "string" ? reason.stack : "";
-}
-/**
- * [LAW:parse-dont-validate] The checkpoint between a crash payload, which node
- * allows to be any value at all, and `Traceback`, which renders an `Error`.
- * The return type is the proof: nothing downstream re-asks whether the payload
- * was throwable, and no raw value can reach the renderable to have `.name` and
- * `.message` read off it as `undefined`.
- *
- * The gate is `isNativeError`, not `instanceof Error`. An error thrown inside a
- * `node:vm` context is a real error with real frames, but its prototype comes
- * from that realm, so `instanceof` answers false and the frames would be
- * discarded by the one component that exists to show them. `isNativeError`
- * reads V8's internal error slot and is realm-independent.
- *
- * Whatever survives that gate is not an error, so it has no call site of its
- * own; `stackOf` salvages a stack from a duck-typed thrower and otherwise
- * leaves it empty rather than reporting the frames of this function, which
- * point into rich-js and describe nothing about the fault. `inspect` renders
- * every payload shape, including circular objects, where `String(reason)`
- * would collapse them to `[object Object]`.
- */
-function toError(reason) {
-    if (types.isNativeError(reason))
-        return reason;
-    const error = new Error(inspect(reason));
-    error.name = "NonError";
-    error.stack = stackOf(reason);
-    return error;
-}
 /**
  * The handler currently registered, or a no-op standing in for "none yet".
  *
@@ -116,7 +80,7 @@ export function installTraceback(options) {
         // sink would report `isTTY === false` and silently strip colour.
         const out = new Console({ stderr: true });
         out.beginCapture();
-        out.print(new Traceback(toError(reason), options));
+        out.print(new Traceback(reason, options));
         // [LAW:no-silent-failure] Exit only once the bytes have drained. When
         // stderr is a pipe (CI logs, `2>&1 | tee`), writes are asynchronous and
         // an immediate `process.exit(1)` truncates the traceback at the pipe

package/dist/renderables/align.js

@@ -3,7 +3,7 @@
  */
 import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
-import { isMeasurable, withBoundedWidth } from "../core/protocol.js";
+import { withBoundedWidth } from "../core/protocol.js";
 import { placeBlock } from "../core/place.js";
 export class Align {
     renderable;
@@ -21,13 +21,6 @@ export class Align {
         }
     }
     measure(options) {
-        if (isMeasurable(this.renderable)) {
-            const measurement = Measurement.get(options, this.renderable);
-            return {
-                minimum: Math.max(1, measurement.minimum),
-                maximum: measurement.maximum,
-            };
-        }
-        return { minimum: 1, maximum: options.maxWidth };
+        return Measurement.get(options, this.renderable);
     }
 }