@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/node/prompt.js

@@ -0,0 +1,51 @@
+/**
+ * node:prompt — readline-backed `PromptInput` for use with the prompt
+ * renderable in a Node runtime.
+ *
+ * [LAW:locality-or-seam] `node:readline` lives only here, on the node side
+ * of the API boundary. The main barrel stays browser-safe; consumers that
+ * want interactive prompts in Node opt in by importing `nodeAsk` and
+ * passing it as the input capability:
+ *
+ *     import { Prompt } from "@promptctl/rich-js";
+ *     import { nodeAsk } from "@promptctl/rich-js/node/prompt";
+ *     const answer = await Prompt.ask("What's your name?", nodeAsk);
+ *     // 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, 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

@@ -0,0 +1,18 @@
+/**
+ * node:save — node-only file helpers that persist recorded console output.
+ *
+ * [LAW:locality-or-seam] These functions live outside the main barrel so
+ * Console can stop importing `fs`. Importing `Console` itself stays
+ * browser-safe; importing this module is the explicit opt-in for the
+ * fs-backed surface, and bundlers targeting the browser will (correctly)
+ * refuse to resolve `fs` if a consumer ever pulls it in by accident.
+ *
+ * [LAW:single-enforcer] One funnel per format: `saveText` consumes
+ * `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

@@ -0,0 +1,24 @@
+/**
+ * node:save — node-only file helpers that persist recorded console output.
+ *
+ * [LAW:locality-or-seam] These functions live outside the main barrel so
+ * Console can stop importing `fs`. Importing `Console` itself stays
+ * browser-safe; importing this module is the explicit opt-in for the
+ * fs-backed surface, and bundlers targeting the browser will (correctly)
+ * refuse to resolve `fs` if a consumer ever pulls it in by accident.
+ *
+ * [LAW:single-enforcer] One funnel per format: `saveText` consumes
+ * `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) {
+    writeFileSync(path, out.exportText(options), "utf-8");
+}
+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

@@ -0,0 +1,114 @@
+/**
+ * node:terminal-host — the `TerminalHost` implementation backed by node's
+ * process streams.
+ *
+ * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
+ * in `host/terminal-host.ts`, importable anywhere. *This* file is one
+ * value satisfying that interface, and it reads `process.stdin` /
+ * `process.stdout`, so it is a node subpath:
+ *
+ *     import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
+ *     const screen = new Screen(new NodeTerminalHost());
+ *
+ * The ambient `process` global is not an import, so it slips past the
+ * module-graph reasoning that keeps the main barrel browser-safe: reading
+ * `process.stdin` inside a constructor throws in a browser only when someone
+ * constructs it. Moving the class here makes the boundary structural — a
+ * browser bundle that never reaches for this subpath cannot reach the global
+ * either.
+ *
+ * [LAW:no-shared-mutable-globals] Which files may read the host, and what
+ * each takes off it, is `HOST_ACCESS` in `test/seam/ambient-process.ts` —
+ * this file's entry carries its `why`, and a test fails when anything joins
+ * the list. Deliberately not restated here: the sole-ownership sentence that
+ * used to stand in this spot is what that list replaced.
+ *
+ * So if you find yourself reaching for `process.stdin`, `process.stdout`, or
+ * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
+ * instead. The seam is already here.
+ */
+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
+ * to `process.stdin` / `process.stdout`.
+ */
+interface NodeReadable {
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    setRawMode?(raw: boolean): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+    readonly isTTY?: boolean;
+}
+interface NodeWritable {
+    write(chunk: string | Uint8Array): unknown;
+    on(event: "resize", listener: () => void): unknown;
+    off(event: "resize", listener: () => void): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+    readonly isTTY?: boolean;
+}
+/**
+ * Subset of node's `process` the host hears the program end through and
+ * suspends it with. Tests pass an `EventEmitter` that records `kill`, because
+ * the real one would stop the test runner.
+ */
+interface NodeProcess {
+    readonly pid: number;
+    on(event: string, listener: () => void): unknown;
+    prependListener(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+    listenerCount(event: string): number;
+    kill(pid: number, signal: NodeJS.Signals): unknown;
+}
+export interface NodeTerminalHostOptions {
+    /**
+     * Input stream. Defaults to `process.stdin` so production code does not
+     * have to construct one explicitly. Tests pass a `PassThrough`.
+     */
+    stdin?: NodeReadable;
+    /**
+     * Output stream. Defaults to `process.stdout` for the same reason.
+     * Tests pass a `Writable` mock.
+     */
+    stdout?: NodeWritable;
+    /**
+     * The environment colour detection reads. Defaults to `process.env`; tests
+     * pass a fixed map so what the host reports does not depend on the shell
+     * that ran them.
+     */
+    env?: Env;
+    /**
+     * What the host hears the program end through and suspends it with.
+     * Defaults to `process`; tests pass an emitter that records `kill`.
+     */
+    process?: NodeProcess;
+}
+export declare class NodeTerminalHost implements TerminalHost {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly process;
+    readonly env: Env;
+    private readonly dataHandlers;
+    private readonly resizeHandlers;
+    private dataListener;
+    private resizeListener;
+    private rawModeRequested;
+    constructor(options?: NodeTerminalHostOptions);
+    get isTTY(): boolean;
+    get writesToTerminal(): boolean;
+    write(data: Uint8Array | string): void;
+    size(): TerminalSize;
+    setRawMode(raw: boolean): void;
+    private applyRawMode;
+    onData(handler: DataHandler): Unsubscribe;
+    onResize(handler: ResizeHandler): Unsubscribe;
+    onExit(handler: ExitHandler): Unsubscribe;
+    suspend(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export {};

package/dist/node/terminal-host.js

@@ -0,0 +1,227 @@
+/**
+ * node:terminal-host — the `TerminalHost` implementation backed by node's
+ * process streams.
+ *
+ * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
+ * in `host/terminal-host.ts`, importable anywhere. *This* file is one
+ * value satisfying that interface, and it reads `process.stdin` /
+ * `process.stdout`, so it is a node subpath:
+ *
+ *     import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
+ *     const screen = new Screen(new NodeTerminalHost());
+ *
+ * The ambient `process` global is not an import, so it slips past the
+ * module-graph reasoning that keeps the main barrel browser-safe: reading
+ * `process.stdin` inside a constructor throws in a browser only when someone
+ * constructs it. Moving the class here makes the boundary structural — a
+ * browser bundle that never reaches for this subpath cannot reach the global
+ * either.
+ *
+ * [LAW:no-shared-mutable-globals] Which files may read the host, and what
+ * each takes off it, is `HOST_ACCESS` in `test/seam/ambient-process.ts` —
+ * this file's entry carries its `why`, and a test fails when anything joins
+ * the list. Deliberately not restated here: the sole-ownership sentence that
+ * used to stand in this spot is what that list replaced.
+ *
+ * So if you find yourself reaching for `process.stdin`, `process.stdout`, or
+ * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
+ * instead. The seam is already here.
+ */
+/**
+ * The events a program ends on without anyone having signalled it. `exit`
+ * is every orderly end, `process.exit` included. `uncaughtExceptionMonitor`
+ * is a crash, and node emits it ahead of every `uncaughtException` listener
+ * and ahead of its own report — so a terminal handed back here is handed back
+ * before any crash report prints, `installTraceback`'s included, whatever
+ * order the listeners were added in.
+ */
+const ENDINGS = ["exit", "uncaughtExceptionMonitor"];
+/** The signals that end a program from outside while it holds the terminal. */
+const TERMINATIONS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+export class NodeTerminalHost {
+    stdin;
+    stdout;
+    process;
+    env;
+    dataHandlers = new Set();
+    resizeHandlers = new Set();
+    dataListener;
+    resizeListener;
+    rawModeRequested = false;
+    constructor(options = {}) {
+        this.stdin = options.stdin ?? process.stdin;
+        this.stdout = options.stdout ?? process.stdout;
+        this.env = options.env ?? process.env;
+        this.process = options.process ?? process;
+    }
+    get isTTY() {
+        return !!this.stdin.isTTY && this.writesToTerminal;
+    }
+    get writesToTerminal() {
+        return !!this.stdout.isTTY;
+    }
+    write(data) {
+        this.stdout.write(data);
+    }
+    size() {
+        return {
+            cols: this.stdout.columns ?? DEFAULT_COLS,
+            rows: this.stdout.rows ?? DEFAULT_ROWS,
+        };
+    }
+    setRawMode(raw) {
+        this.rawModeRequested = raw;
+        this.applyRawMode(raw);
+    }
+    // [LAW:single-enforcer] One site decides what to do when toggling raw
+    // mode on the underlying transport fails. Both `setRawMode` (call from
+    // outside) and `stop` (cleanup) go through this helper so neither
+    // caller has to branch on capability or exception-handling.
+    //
+    // [LAW:dataflow-not-control-flow] Two shapes of "the transport can't do
+    // this" are absorbed identically: the optional chain handles "method
+    // missing" (non-TTY streams, PassThrough in tests); the try/catch
+    // handles "method exists but threw" (node's `setRawMode` throws on
+    // closed or non-TTY streams). Callers see neither shape — they always
+    // call `setRawMode(bool)`, and the host decides what's possible.
+    //
+    // The catch is silent because the only call sites are lifecycle
+    // transitions: if the stream is already gone, there is nothing
+    // semantically meaningful for the host to do, and surfacing the
+    // exception would only make teardown brittle without giving the caller
+    // a recovery path. The demos this replaces did `try { ... } catch {}`
+    // at every call site for exactly this reason — absorbing it once here
+    // means the pattern stops spreading.
+    applyRawMode(raw) {
+        try {
+            this.stdin.setRawMode?.(raw);
+        }
+        catch {
+            // Underlying stream couldn't honor the request (closed, no longer
+            // a TTY, etc.). Lifecycle continues.
+        }
+    }
+    onData(handler) {
+        this.dataHandlers.add(handler);
+        // [LAW:single-enforcer] One underlying `data` listener fans out to all
+        // subscribers — keeps stdin's flowing/paused state derivable from
+        // "any subscribers?" instead of from per-call ref-counts scattered
+        // through the runtime.
+        if (!this.dataListener) {
+            this.dataListener = (chunk) => {
+                for (const h of this.dataHandlers)
+                    h(chunk);
+            };
+            this.stdin.on("data", this.dataListener);
+            this.stdin.resume?.();
+        }
+        return () => {
+            this.dataHandlers.delete(handler);
+            if (this.dataHandlers.size === 0 && this.dataListener) {
+                this.stdin.off("data", this.dataListener);
+                this.dataListener = undefined;
+                // Returning stdin to paused state mirrors the symmetric "no
+                // subscribers → no flow" invariant. Without this, removing the
+                // last subscriber leaves stdin in flowing mode and the process
+                // hangs forever waiting for an event nobody is listening for.
+                this.stdin.pause?.();
+            }
+        };
+    }
+    onResize(handler) {
+        this.resizeHandlers.add(handler);
+        if (!this.resizeListener) {
+            this.resizeListener = () => {
+                const size = this.size();
+                for (const h of this.resizeHandlers)
+                    h(size);
+            };
+            this.stdout.on("resize", this.resizeListener);
+        }
+        return () => {
+            this.resizeHandlers.delete(handler);
+            if (this.resizeHandlers.size === 0 && this.resizeListener) {
+                this.stdout.off("resize", this.resizeListener);
+                this.resizeListener = undefined;
+            }
+        };
+    }
+    onExit(handler) {
+        const proc = this.process;
+        // [LAW:single-enforcer] Every path detaches every listener before the
+        // handler runs, which is what makes it run once: the second event of a
+        // crash — the monitor, then `exit` — finds nothing left to call.
+        const end = () => {
+            detach();
+            handler();
+        };
+        // A signal a program listens for no longer terminates it, so the
+        // listener owes the signal its outcome. Raised again once ours is gone,
+        // it terminates — unless the program listens for it too, in which case
+        // it was never going to, and that listener hears it next. Ours goes
+        // first and leaves before the rest are called: a listener keeping the
+        // same rule (`signal-exit`'s) then finds itself alone and raises it, where
+        // two that each counted the other would both have stood down.
+        const terminations = TERMINATIONS.map((signal) => {
+            const listener = () => {
+                end();
+                if (proc.listenerCount(signal) === 0)
+                    proc.kill(proc.pid, signal);
+            };
+            return { signal, listener };
+        });
+        const detach = () => {
+            for (const event of ENDINGS)
+                proc.off(event, end);
+            for (const { signal, listener } of terminations)
+                proc.off(signal, listener);
+        };
+        for (const event of ENDINGS)
+            proc.on(event, end);
+        for (const { signal, listener } of terminations)
+            proc.prependListener(signal, listener);
+        return detach;
+    }
+    // The shell's own job control: the signal Ctrl+Z would have sent outside
+    // raw mode, to the whole foreground job as the terminal sends it — a
+    // launcher (`npm run`, `sh -c`) waiting on this process stops too, so the
+    // shell sees the job stop and takes the terminal. A signal a process sends
+    // its own group is delivered before `kill` returns, so the process is
+    // stopped inside the call and running again when it returns: `fg` has
+    // continued it, or nothing was stopped at all — the kernel discards the
+    // signal in a job no shell controls, as it does Ctrl+Z's. Either way the
+    // terminal is the program's again.
+    suspend() {
+        this.process.kill(0, "SIGTSTP");
+        return Promise.resolve();
+    }
+    start() {
+        // No-op on node: stdin/stdout are always available. Lifecycle exists
+        // so `BrowserTerminalHost` can attach to the DOM here without the
+        // runtime branching on "do I need to start?"
+    }
+    stop() {
+        // [LAW:one-source-of-truth] Symmetric teardown: drop every subscriber
+        // and detach the underlying stream listeners. After stop(), the host
+        // is in the same shape a freshly-constructed one would be in. Calling
+        // stop() repeatedly is safe — the dataListener/resizeListener guards
+        // make later calls no-ops.
+        if (this.dataListener) {
+            this.stdin.off("data", this.dataListener);
+            this.dataListener = undefined;
+            this.stdin.pause?.();
+        }
+        if (this.resizeListener) {
+            this.stdout.off("resize", this.resizeListener);
+            this.resizeListener = undefined;
+        }
+        this.dataHandlers.clear();
+        this.resizeHandlers.clear();
+        if (this.rawModeRequested) {
+            this.applyRawMode(false);
+            this.rawModeRequested = false;
+        }
+    }
+}

package/dist/node/traceback.d.ts

@@ -0,0 +1,38 @@
+/**
+ * node:traceback — install `Traceback` as the process-wide crash renderer.
+ *
+ * [LAW:locality-or-seam] `process.on` / `process.exit` live only here, on the
+ * node side of the API boundary. The `Traceback` renderable itself is pure
+ * rendering and stays in the browser-safe barrel; installing it as a global
+ * handler is a node capability, so it is a node subpath:
+ *
+ *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
+ *     installTraceback({ suppress: ["node_modules"] });
+ *
+ * [LAW:dataflow-not-control-flow] Every crash is reported from one channel,
+ * `uncaughtException`. An unhandled rejection is thrown into it rather than
+ * reported beside it, so both kinds of crash are literally one code path. No
+ * 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` 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
+ * screen restores it on `uncaughtExceptionMonitor` (`NodeTerminalHost.onExit`),
+ * which node emits ahead of every `uncaughtException` listener. Reported
+ * straight from `unhandledRejection`, a crash skips that phase: the report
+ * draws inside the alternate screen and vanishes with it when `exit` restores
+ * the terminal. Node's crash sequence owns the order, not the order in which
+ * `installTraceback` and a host happened to add their listeners.
+ */
+import type { TracebackOptions } from "../renderables/traceback.js";
+/**
+ * Register rich tracebacks for uncaught exceptions and unhandled rejections.
+ *
+ * Calling this more than once replaces the previous handler — the last call
+ * wins, options included — so a process always has exactly one rich crash
+ * renderer no matter how many entry points reach for it.
+ */
+export declare function installTraceback(options?: TracebackOptions): void;

package/dist/node/traceback.js

@@ -0,0 +1,98 @@
+/**
+ * node:traceback — install `Traceback` as the process-wide crash renderer.
+ *
+ * [LAW:locality-or-seam] `process.on` / `process.exit` live only here, on the
+ * node side of the API boundary. The `Traceback` renderable itself is pure
+ * rendering and stays in the browser-safe barrel; installing it as a global
+ * handler is a node capability, so it is a node subpath:
+ *
+ *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
+ *     installTraceback({ suppress: ["node_modules"] });
+ *
+ * [LAW:dataflow-not-control-flow] Every crash is reported from one channel,
+ * `uncaughtException`. An unhandled rejection is thrown into it rather than
+ * reported beside it, so both kinds of crash are literally one code path. No
+ * 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` 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
+ * screen restores it on `uncaughtExceptionMonitor` (`NodeTerminalHost.onExit`),
+ * which node emits ahead of every `uncaughtException` listener. Reported
+ * straight from `unhandledRejection`, a crash skips that phase: the report
+ * draws inside the alternate screen and vanishes with it when `exit` restores
+ * the terminal. Node's crash sequence owns the order, not the order in which
+ * `installTraceback` and a host happened to add their listeners.
+ */
+import { Console } from "../core/console.js";
+import { Traceback } from "../renderables/traceback.js";
+/**
+ * The handler currently registered, or a no-op standing in for "none yet".
+ *
+ * [LAW:no-shared-mutable-globals] The process listener registry is a shared
+ * global, so the handler installed into it gets a single owner here rather
+ * than a caller appending to it once per call. Holding the reference is what
+ * lets `installTraceback` replace rather than accumulate.
+ *
+ * [LAW:types-are-the-program] A no-op rather than `null`: `process.off` on an
+ * unregistered listener does nothing, so the first call needs no null check
+ * and no "have we installed yet" branch. There is no absent case to handle.
+ */
+let installed = () => { };
+/**
+ * An unhandled rejection, raised as the uncaught exception it becomes when
+ * nobody listens — its reason unwrapped, which node's own conversion would
+ * bury in a message for any reason that is not an `Error`. Raised once the
+ * rejection's other listeners have heard it: a throw inside the emit would
+ * end it before them.
+ */
+function escalate(reason) {
+    queueMicrotask(() => {
+        throw reason;
+    });
+}
+/**
+ * Register rich tracebacks for uncaught exceptions and unhandled rejections.
+ *
+ * Calling this more than once replaces the previous handler — the last call
+ * wins, options included — so a process always has exactly one rich crash
+ * renderer no matter how many entry points reach for it.
+ */
+export function installTraceback(options) {
+    // [LAW:no-ambient-temporal-coupling] "This process is already crashing" is
+    // lifecycle state with one owner, not a fact left to the interleaving of two
+    // writes. A cascade — cleanup code rejecting a promise while the first
+    // report is still draining — would otherwise start a second write and a
+    // second `process.exit(1)`, and whichever drained first would cut the other
+    // off mid-frame. The first crash is the fault and the rest is its wake, so
+    // one complete report of the fault beats two corrupt ones.
+    let crashing = false;
+    const report = (reason) => {
+        if (crashing)
+            return;
+        crashing = true;
+        // [LAW:effects-at-boundaries] Render to a string first, then perform one
+        // write. `beginCapture` redirects the console's sink without setting
+        // `file:`, so stderr's TTY status still drives colour depth — a `file:`
+        // sink would report `isTTY === false` and silently strip colour.
+        const out = new Console({ stderr: true });
+        out.beginCapture();
+        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
+        // buffer — the longer the traceback, the more of it is lost, which is
+        // the reverse of what a crash report should do.
+        process.stderr.write(out.endCapture(), () => {
+            process.exit(1);
+        });
+    };
+    process.off("uncaughtException", installed);
+    process.off("unhandledRejection", escalate);
+    process.on("uncaughtException", report);
+    process.on("unhandledRejection", escalate);
+    installed = report;
+}

package/dist/renderables/align.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Align — wraps a renderable and places its output horizontally, as one block.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import { type Alignment } from "../core/place.js";
+export declare class Align implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly align: Alignment;
+    constructor(renderable: Renderable, align?: Alignment);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/align.js

@@ -0,0 +1,26 @@
+/**
+ * Align — wraps a renderable and places its output horizontally, as one block.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement } from "../core/measure.js";
+import { withBoundedWidth } from "../core/protocol.js";
+import { placeBlock } from "../core/place.js";
+export class Align {
+    renderable;
+    align;
+    constructor(renderable, align = "center") {
+        this.renderable = renderable;
+        this.align = align;
+    }
+    // [LAW:one-source-of-truth] `placeBlock` is the placement; `Console.print`'s
+    // `justify` uses the same one.
+    *render(options) {
+        for (const line of placeBlock(this.renderable, this.align, withBoundedWidth(options, this))) {
+            yield* line;
+            yield Segment.line();
+        }
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
+}