@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/host/host-environment.js

@@ -0,0 +1,44 @@
+/**
+ * hostEnvironment — a `TerminalHost` as the `ConsoleEnvironment` a `Console`
+ * consults, so a console writing through a host asks that host every question
+ * it has about its destination.
+ *
+ * [LAW:one-source-of-truth] A console asks its destination four things: where
+ * bytes go, is it a terminal, how big is it, and — through the environment —
+ * what colours it draws. A bare sink answers only the first, and the other
+ * three fall to the ambient `process`: some other stream's answer in node,
+ * none in a browser, where a console on xterm.js saw an unnamed TTY and drew
+ * 16 colours. Handing the console the whole environment keeps all four
+ * answers the host's.
+ *
+ * The host's size is `size()`, so the environment handed on carries no
+ * `COLUMNS` or `LINES`: a console reads those ahead of the stream, and an
+ * exported `COLUMNS` in the shell that launched a node host would pin the
+ * console's width while the terminal it draws on is resized. The stream's
+ * `columns` and `rows` are getters, so a console that was not given a fixed
+ * size follows the host through resizes.
+ */
+// [LAW:types-are-the-program] A host always has a stream, so the return type
+// says so rather than inheriting `ConsoleEnvironment`'s optional ones. It is
+// one terminal, so stdout and stderr are the same stream — which is where a
+// program's two streams land when both are attached to a terminal.
+export function hostEnvironment(host) {
+    const { COLUMNS: _columns, LINES: _lines, ...env } = host.env;
+    const stream = {
+        write(chunk) {
+            host.write(chunk);
+        },
+        // [LAW:one-source-of-truth] A console asks whether its output is a
+        // terminal, which is the host's `writesToTerminal`, not its `isTTY`.
+        get isTTY() {
+            return host.writesToTerminal;
+        },
+        get columns() {
+            return host.size().cols;
+        },
+        get rows() {
+            return host.size().rows;
+        },
+    };
+    return { env, stdout: stream, stderr: stream };
+}

package/dist/host/index.d.ts

@@ -1,3 +1,5 @@
 export { BrowserTerminalHost } from "./terminal-host.js";
-export type { TerminalHost, TerminalSize, DataHandler, ResizeHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
-export { hostStream } from "./host-stream.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";

package/dist/host/index.js

@@ -1,2 +1,3 @@
 export { BrowserTerminalHost } from "./terminal-host.js";
-export { hostStream } from "./host-stream.js";
+export { hostEnvironment } from "./host-environment.js";
+export { App } from "./app.js";

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

@@ -32,8 +32,9 @@
  *
  * [boundaries: capabilities over context] A `TerminalHost` grants exactly
  * the I/O capabilities the runtime needs: write bytes, read input, query
- * size, observe resize, switch raw mode, lifecycle. It is not an
- * omniscient handle to "the process."
+ * size, observe resize, switch raw mode, read the terminal's environment,
+ * hear the program end, hand the terminal back for a while, lifecycle. It is
+ * not an omniscient handle to "the process."
  */
 import type { Unsubscribe } from "../core/subscription.js";
 export interface TerminalSize {
@@ -42,10 +43,14 @@ export interface TerminalSize {
 }
 export type DataHandler = (chunk: Uint8Array | string) => void;
 export type ResizeHandler = (size: TerminalSize) => void;
+export type ExitHandler = () => void;
 export interface TerminalHost {
     /**
-     * Write raw bytes (or UTF-8 text) to the terminal. The byte sequence is
-     * written verbatim; no escape interpretation, no framing.
+     * Write raw bytes (or UTF-8 text) to the terminal as a program's output
+     * reaches it: no escape interpretation, no framing, and a terminal on a
+     * tty receives each newline as carriage return + newline, the tty's own
+     * output translation, which node's raw mode leaves on. A host with no tty
+     * in front of its terminal does that translation itself.
      */
     write(data: Uint8Array | string): void;
     /**
@@ -68,11 +73,38 @@ export interface TerminalHost {
      */
     setRawMode(raw: boolean): void;
     /**
-     * Whether the host is connected to a real interactive terminal. Drives
-     * default option values (e.g. `manageCursor`, `manageRawMode`) in the
-     * runtime; non-TTY hosts default those features off.
+     * Whether the host is connected to a real interactive terminal — input and
+     * output both: what an interactive program checks before it starts.
      */
     readonly isTTY: boolean;
+    /**
+     * Whether the bytes `write` sends land on a terminal, whatever the input
+     * is. Colour detection asks this: a program with piped stdin and a terminal
+     * stdout still draws on a terminal, and `isTTY` would call it plain.
+     */
+    readonly writesToTerminal: boolean;
+    /**
+     * The environment a program running on this terminal sees — `TERM`,
+     * `COLORTERM`, `NO_COLOR` and the rest. Colour detection reads it: what a
+     * terminal can draw is a fact about the host, so it travels with the host
+     * 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;
+    /**
+     * 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
+     * still ends as it would have without the handler: a signal still
+     * terminates and a crash is still reported.
+     */
+    onExit(handler: ExitHandler): Unsubscribe;
+    /**
+     * Hand the terminal to whatever launched the program, and resolve once it
+     * hands it back. Raw mode delivers Ctrl+Z as a key rather than a signal, so
+     * suspending is something a program asks for, and it restores the terminal
+     * before asking.
+     */
+    suspend(): Promise<void>;
     /**
      * Begin the host's lifecycle. Implementations attach whatever resources
      * they own — or no-op when there is nothing to attach. Idempotent. See
@@ -133,9 +165,13 @@ export declare class BrowserTerminalHost implements TerminalHost {
     private resizeSubscription;
     constructor(options: BrowserTerminalHostOptions);
     get isTTY(): boolean;
+    get writesToTerminal(): boolean;
+    get env(): NodeJS.ProcessEnv;
     write(data: Uint8Array | string): void;
     size(): TerminalSize;
     setRawMode(_raw: boolean): void;
+    onExit(_handler: ExitHandler): Unsubscribe;
+    suspend(): Promise<void>;
     onData(handler: DataHandler): Unsubscribe;
     onResize(handler: ResizeHandler): Unsubscribe;
     start(): void;

package/dist/host/terminal-host.js

@@ -32,9 +32,14 @@
  *
  * [boundaries: capabilities over context] A `TerminalHost` grants exactly
  * the I/O capabilities the runtime needs: write bytes, read input, query
- * size, observe resize, switch raw mode, lifecycle. It is not an
- * omniscient handle to "the process."
+ * size, observe resize, switch raw mode, read the terminal's environment,
+ * hear the program end, hand the terminal back for a while, lifecycle. It is
+ * not an omniscient handle to "the process."
  */
+const XTERM_ENV = Object.freeze({
+    TERM: "xterm-256color",
+    COLORTERM: "truecolor",
+});
 export class BrowserTerminalHost {
     terminal;
     dataHandlers = new Set();
@@ -51,8 +56,23 @@ export class BrowserTerminalHost {
     get isTTY() {
         return true;
     }
+    get writesToTerminal() {
+        return true;
+    }
+    // What xterm.js is, stated the way a terminal states it: it identifies as
+    // `xterm-256color` and draws 24-bit SGR. With no env at all, detection saw
+    // an unnamed TTY and drew every colour at 16-colour depth.
+    get env() {
+        return XTERM_ENV;
+    }
+    // [LAW:single-enforcer] xterm.js is a terminal with no tty in front of
+    // it, so this host is where the tty's newline translation happens. Left to
+    // the terminal, a bare newline moves down without returning, and every row
+    // a Console writes starts where the last one ended — every demo drew as a
+    // staircase. Here and not in each page's xterm options, so every writer
+    // through this host gets it.
     write(data) {
-        this.terminal.write(data);
+        this.terminal.write(returnBeforeNewline(data));
     }
     size() {
         return { cols: this.terminal.cols, rows: this.terminal.rows };
@@ -64,6 +84,16 @@ export class BrowserTerminalHost {
     // hosts. (Mirror: NodeTerminalHost on a non-TTY stream takes the same
     // no-op path via the optional-chain in `applyRawMode`.)
     setRawMode(_raw) { }
+    // The page owns the terminal's life: a program here ends when the page
+    // does, and nothing is left to restore.
+    onExit(_handler) {
+        return () => { };
+    }
+    // Nothing launched the program that could take the terminal back, so the
+    // hand-back is immediate.
+    suspend() {
+        return Promise.resolve();
+    }
     // [LAW:single-enforcer] One underlying `terminal.onData` subscription
     // fans out to every host-level handler — the same lazy-attach,
     // last-unsubscribe-detaches shape as NodeTerminalHost.onData. The
@@ -130,3 +160,27 @@ export class BrowserTerminalHost {
         this.resizeHandlers.clear();
     }
 }
+/**
+ * `data` with a carriage return before every newline — the tty's ONLCR. A
+ * newline byte never occurs inside a multi-byte UTF-8 character, so the bytes
+ * are translated as bytes. A newline already preceded by a carriage return
+ * gains a second one, which returns to a column the cursor is already in, as
+ * the kernel's translation does.
+ */
+function returnBeforeNewline(data) {
+    if (typeof data === "string")
+        return data.replaceAll("\n", "\r\n");
+    let newlines = 0;
+    for (let i = 0; i < data.length; i++)
+        newlines += Number(data[i] === 0x0a);
+    if (newlines === 0)
+        return data;
+    const out = new Uint8Array(data.length + newlines);
+    let at = 0;
+    for (let i = 0; i < data.length; i++) {
+        if (data[i] === 0x0a)
+            out[at++] = 0x0d;
+        out[at++] = data[i];
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -19,11 +19,12 @@ export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES,
 export type { StyleOptions } 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";
 export { Box } from "./core/box.js";
 export type { EdgeChars, ContentChars, RowLevel, SubstituteOptions } from "./core/box.js";
 export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
-export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, } from "./core/protocol.js";
-export type { RenderOptions, Renderable, Measurable, StyleErrorHandler, } from "./core/protocol.js";
+export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
+export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, StyleErrorHandler, } from "./core/protocol.js";
 export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
@@ -34,6 +35,7 @@ export { renderToString, segmentToString, segmentsToString, } from "./core/rende
 export type { RenderToStringOptions } from "./core/render.js";
 export { OSC8, osc8Sequences } from "./core/osc8.js";
 export type { Osc8Sequence } from "./core/osc8.js";
+export { AnsiDecoder, decodeAnsi } from "./core/ansi.js";
 export { MarkupRegistry, globalMarkupRegistry, renderMarkup, } from "./core/markup.js";
 export type { MarkupTagContext, MarkupTagHandler, RenderMarkupOptions, } from "./core/markup.js";
 export { EMOJI, emojiReplace, Emoji, NoEmoji } from "./core/emoji.js";
@@ -49,9 +51,11 @@ export { Console } from "./core/console.js";
 export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, PrintOptions, } from "./core/console.js";
 export { Constrain } from "./renderables/constrain.js";
 export { Align } from "./renderables/align.js";
-export type { Alignment } from "./renderables/align.js";
+export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";
 export type { PaddingDimensions } from "./renderables/padding.js";
+export { Viewport, SCROLLBAR } from "./renderables/viewport.js";
+export type { Scrollbar, ScrollbarPart, ViewportOptions } from "./renderables/viewport.js";
 export { Rule } from "./renderables/rule.js";
 export type { RuleAlign, RuleOptions } from "./renderables/rule.js";
 export { Panel } from "./renderables/panel.js";

package/dist/index.js

@@ -32,7 +32,7 @@ export { Segment, ControlType, } from "./core/segment.js";
 export { Box } from "./core/box.js";
 export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
 // Protocol
-export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, } from "./core/protocol.js";
+export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
 // Measurement
 export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
@@ -43,6 +43,8 @@ export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, Caps
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
 export { OSC8, osc8Sequences } from "./core/osc8.js";
+// ANSI bytes back into styled text
+export { AnsiDecoder, decodeAnsi } from "./core/ansi.js";
 // Markup plugin tags
 export { MarkupRegistry, globalMarkupRegistry, renderMarkup, } from "./core/markup.js";
 // Emoji
@@ -63,6 +65,7 @@ export { Console } from "./core/console.js";
 export { Constrain } from "./renderables/constrain.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
+export { Viewport, SCROLLBAR } from "./renderables/viewport.js";
 export { Rule } from "./renderables/rule.js";
 export { Panel } from "./renderables/panel.js";
 export { Group } from "./renderables/group.js";

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

@@ -3,7 +3,7 @@
  * process streams.
  *
  * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
- * in `widgets/terminal-host.ts`, importable anywhere. *This* file is one
+ * 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:
  *
@@ -27,7 +27,7 @@
  * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
  * instead. The seam is already here.
  */
-import type { DataHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
+import type { DataHandler, ExitHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
 import type { Unsubscribe } from "../core/subscription.js";
 /**
  * Subset of NodeJS stream API the node host actually depends on. Tests
@@ -50,6 +50,19 @@ interface NodeWritable {
     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
@@ -61,10 +74,23 @@ export interface NodeTerminalHostOptions {
      * 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?: NodeJS.ProcessEnv;
+    /**
+     * 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: NodeJS.ProcessEnv;
     private readonly dataHandlers;
     private readonly resizeHandlers;
     private dataListener;
@@ -72,12 +98,15 @@ export declare class NodeTerminalHost implements TerminalHost {
     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;
 }

package/dist/node/terminal-host.js

@@ -3,7 +3,7 @@
  * process streams.
  *
  * [LAW:locality-or-seam] The `TerminalHost` interface is the seam and lives
- * in `widgets/terminal-host.ts`, importable anywhere. *This* file is one
+ * 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:
  *
@@ -27,11 +27,24 @@
  * `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;
@@ -40,9 +53,14 @@ export class NodeTerminalHost {
     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.stdout.isTTY;
+        return !!this.stdin.isTTY && this.writesToTerminal;
+    }
+    get writesToTerminal() {
+        return !!this.stdout.isTTY;
     }
     write(data) {
         this.stdout.write(data);
@@ -130,6 +148,55 @@ export class NodeTerminalHost {
             }
         };
     }
+    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

package/dist/node/traceback.d.ts

@@ -9,12 +9,22 @@
  *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
  *     installTraceback({ suppress: ["node_modules"] });
  *
- * [LAW:dataflow-not-control-flow] Both crash channels register the same
- * `report` function, unadapted. Neither 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 both channels are
- * literally one code path.
+ * [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`.
+ *
+ * [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";
 /**

package/dist/node/traceback.js

@@ -9,12 +9,22 @@
  *     import { installTraceback } from "@promptctl/rich-js/node/traceback";
  *     installTraceback({ suppress: ["node_modules"] });
  *
- * [LAW:dataflow-not-control-flow] Both crash channels register the same
- * `report` function, unadapted. Neither 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 both channels are
- * literally one code path.
+ * [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`.
+ *
+ * [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 { inspect, types } from "node:util";
 import { Console } from "../core/console.js";
@@ -68,6 +78,18 @@ function toError(reason) {
  * 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.
  *
@@ -105,8 +127,8 @@ export function installTraceback(options) {
         });
     };
     process.off("uncaughtException", installed);
-    process.off("unhandledRejection", installed);
+    process.off("unhandledRejection", escalate);
     process.on("uncaughtException", report);
-    process.on("unhandledRejection", report);
+    process.on("unhandledRejection", escalate);
     installed = report;
 }

package/dist/renderables/align.d.ts

@@ -1,9 +1,9 @@
 /**
- * Align — wraps a renderable and aligns its output horizontally.
+ * 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";
-export type Alignment = "left" | "center" | "right";
+import { type Alignment } from "../core/place.js";
 export declare class Align implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly align: Alignment;

package/dist/renderables/align.js

@@ -1,9 +1,10 @@
 /**
- * Align — wraps a renderable and aligns its output horizontally.
+ * 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 { isMeasurable } from "../core/protocol.js";
+import { isMeasurable, withBoundedWidth } from "../core/protocol.js";
+import { placeBlock } from "../core/place.js";
 export class Align {
     renderable;
     align;
@@ -11,25 +12,11 @@ export class Align {
         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) {
-        const maxWidth = options.maxWidth;
-        const segments = [...this.renderable.render(options)];
-        const lines = Segment.splitLines(segments);
-        for (const line of lines) {
-            const lineWidth = Segment.getLineLength(line);
-            const gap = maxWidth - lineWidth;
-            // [LAW:dataflow-not-control-flow] Always compute padding; gap <= 0 produces empty strings
-            const leftPad = this.align === "right"
-                ? gap
-                : this.align === "center"
-                    ? Math.floor(gap / 2)
-                    : 0;
-            if (leftPad > 0)
-                yield new Segment(" ".repeat(leftPad));
+        for (const line of placeBlock(this.renderable, this.align, withBoundedWidth(options, this))) {
             yield* line;
-            const rightPad = gap - leftPad;
-            if (rightPad > 0)
-                yield new Segment(" ".repeat(rightPad));
             yield Segment.line();
         }
     }