@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/wrap.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Word wrapping: the offsets one logical line is cut at so its pieces fit a
+ * cell budget.
+ *
+ * This is deliberately not in `cells.ts` next door. That module answers
+ * geometry — how wide is this, where does cell column N fall — and knows
+ * nothing about language. This one answers where a line may *break*, which is
+ * a fact about words, and the only thing it borrows from geometry is how to
+ * measure one.
+ *
+ * It returns offsets rather than pieces because the caller holds styled
+ * `Segment[]`, not a string: cutting the text here would drop every span
+ * attached to it. Offsets are the one representation both sides can act on —
+ * `Segment.divide` cuts the styled line at exactly the places this function
+ * found in the plain one.
+ *
+ * Wrapping is the *first* step, and overflow is the last resort applied to a
+ * line still too wide once wrapping is done. That order is the whole reason a
+ * long sentence in a table cell grows the row while an unbreakable word in the
+ * same cell still ellipsizes.
+ */
+import { type CellCol } from "./cells.js";
+/**
+ * The cell offsets `text` should be cut at to wrap it into lines of at most
+ * `width` cells, for `Segment.divide` to apply to the styled line.
+ *
+ * `fold` decides what happens to a word that fits on no line at all: folded,
+ * it is chopped across as many lines as it needs; unfolded, it is left whole
+ * on its own line for the caller's overflow method to cut. Only the `fold`
+ * overflow method folds — `crop` and `ellipsis` want the word intact so they
+ * can truncate it, which is what makes an unbreakable word ellipsize while the
+ * sentence around it merely wraps.
+ *
+ * Requires `width >= 1`. A zero-cell canvas gets no cuts, because "no cut
+ * fits" and "no cell fits" are different facts and only one of them is a list
+ * of offsets — the caller answers the second one by cropping the single
+ * uncut piece to nothing, which is what every overflow method does there.
+ */
+export declare function divideLine(text: string, width: CellCol, options: {
+    fold: boolean;
+}): CellCol[];

package/dist/core/wrap.js

@@ -0,0 +1,127 @@
+/**
+ * Word wrapping: the offsets one logical line is cut at so its pieces fit a
+ * cell budget.
+ *
+ * This is deliberately not in `cells.ts` next door. That module answers
+ * geometry — how wide is this, where does cell column N fall — and knows
+ * nothing about language. This one answers where a line may *break*, which is
+ * a fact about words, and the only thing it borrows from geometry is how to
+ * measure one.
+ *
+ * It returns offsets rather than pieces because the caller holds styled
+ * `Segment[]`, not a string: cutting the text here would drop every span
+ * attached to it. Offsets are the one representation both sides can act on —
+ * `Segment.divide` cuts the styled line at exactly the places this function
+ * found in the plain one.
+ *
+ * Wrapping is the *first* step, and overflow is the last resort applied to a
+ * line still too wide once wrapping is done. That order is the whole reason a
+ * long sentence in a table cell grows the row while an unbreakable word in the
+ * same cell still ellipsizes.
+ */
+import { cellLen, chopCells, asCellCol } from "./cells.js";
+/**
+ * Each word of `text` in order, where a "word" carries its own trailing
+ * whitespace — the run of spaces that follows it belongs to it, because that
+ * is the whitespace a break at the *next* word leaves hanging past the edge.
+ *
+ * The matches tile the text: each begins exactly where the last ended, so a
+ * caller can track absolute offsets by accumulating widths alone. Text with no
+ * non-whitespace character yields nothing, which is the honest answer — there
+ * is nowhere to break.
+ */
+function* words(text) {
+    // Constructed per call rather than hoisted: a sticky regex carries its
+    // `lastIndex` as mutable state, and a shared one would corrupt any two
+    // interleaved walks. [LAW:no-shared-mutable-globals]
+    const re = /\s*\S+\s*/y;
+    for (let match = re.exec(text); match !== null; match = re.exec(text)) {
+        yield match[0];
+    }
+}
+/**
+ * A word chopped into pieces of at most `width` cells, as the reference chops
+ * it.
+ *
+ * `chopCells` next door and Rich's `chop_cells` disagree in exactly one place.
+ * Rich opens a new line for any glyph that does not fit and emits whatever line
+ * it was already on, so a word beginning with a glyph wider than the entire
+ * canvas folds with an empty piece in front of it — and that piece reaches the
+ * output as a blank line. `chopCells` force-takes the glyph instead and never
+ * returns an empty piece.
+ *
+ * Restoring the blank is what keeps `test/core/text-wrap.golden.txt`
+ * regenerable from the reference. A fixture is only an oracle while the command
+ * in its header reproduces it byte for byte; smoothing away one byte the
+ * reference emits costs that, everywhere, to tidy a blank line reachable only
+ * by folding a two-cell glyph onto a one-cell canvas.
+ */
+function foldWord(word, width) {
+    const pieces = chopCells(word, width);
+    // `chopCells` overshoots the budget only when it force-takes one glyph, so an
+    // over-wide first piece is exactly the case Rich opens a blank line for.
+    return cellLen(pieces[0]) > width ? ["", ...pieces] : pieces;
+}
+/**
+ * The cell offsets `text` should be cut at to wrap it into lines of at most
+ * `width` cells, for `Segment.divide` to apply to the styled line.
+ *
+ * `fold` decides what happens to a word that fits on no line at all: folded,
+ * it is chopped across as many lines as it needs; unfolded, it is left whole
+ * on its own line for the caller's overflow method to cut. Only the `fold`
+ * overflow method folds — `crop` and `ellipsis` want the word intact so they
+ * can truncate it, which is what makes an unbreakable word ellipsize while the
+ * sentence around it merely wraps.
+ *
+ * Requires `width >= 1`. A zero-cell canvas gets no cuts, because "no cut
+ * fits" and "no cell fits" are different facts and only one of them is a list
+ * of offsets — the caller answers the second one by cropping the single
+ * uncut piece to nothing, which is what every overflow method does there.
+ */
+export function divideLine(text, width, options) {
+    if (width <= 0)
+        return [];
+    const cuts = [];
+    // A cut at the start of the text is not a cut: it would open the line with
+    // an empty piece. [LAW:single-enforcer] for that rule, so neither arm below
+    // has to restate it.
+    const cutAt = (cell) => {
+        if (cell > 0)
+            cuts.push(asCellCol(cell));
+    };
+    let used = 0; // cells already committed to the line being filled
+    let wordStart = 0; // absolute cell offset where the current word begins
+    for (const word of words(text)) {
+        // Measured without its trailing whitespace: a word is allowed to end the
+        // line with its spaces hanging past the edge, and the caller crops them.
+        const wordWidth = cellLen(word.trimEnd());
+        if (width - used >= wordWidth) {
+            used += cellLen(word);
+        }
+        else if (options.fold && wordWidth > width) {
+            // No line, however empty, can hold this word whole, and folding is
+            // allowed — so it is chopped across as many lines as it needs. Unfolded,
+            // it takes the arm below and is left whole for the overflow method.
+            const pieces = foldWord(word, width);
+            let pieceStart = wordStart;
+            for (let index = 0; index < pieces.length; index += 1) {
+                cutAt(pieceStart);
+                const piece = pieces[index];
+                // The last piece is what the *next* word finds already on the line;
+                // the rest are whole lines of their own.
+                if (index === pieces.length - 1)
+                    used = cellLen(piece);
+                else
+                    pieceStart += cellLen(piece);
+            }
+        }
+        else {
+            // It does not fit here. Either it fits on a line of its own, or nothing
+            // can hold it and the caller's overflow method will cut it there.
+            cutAt(wordStart);
+            used = cellLen(word);
+        }
+        wordStart += cellLen(word);
+    }
+    return cuts;
+}

package/dist/host/app.d.ts

@@ -0,0 +1,121 @@
+/**
+ * App — the runtime a terminal application runs in: it takes the terminal,
+ * paints one renderable on it every frame, and hands the terminal back on
+ * every path out.
+ *
+ * [LAW:single-enforcer] Every change this runtime makes to the terminal —
+ * the alternate screen, pointer reporting, the hidden cursor, raw mode — is
+ * made by `enter` and
+ * undone by `leave`, and nothing else touches them. Stopping, suspending, an
+ * error in a frame and the program ending by a signal or a crash all hand the
+ * terminal back through `leave`, so there is one list of what to undo and no
+ * exit path can hold a shorter one.
+ *
+ * [LAW:one-source-of-truth] The frame on screen is one value: the rows last
+ * painted, carrying on every cell where its owner drew it (`core/anchor`).
+ * Nothing about it is cached beside it, so a resize invalidates nothing — it
+ * is input to the next frame, which replaces the rows and their anchors at
+ * once. An event arriving before that repaint lands on the frame on screen,
+ * which is the one the user pointed at.
+ *
+ * [LAW:locality-or-seam] The terminal's bytes are identical under every host
+ * and live here: entering and leaving the alternate screen, the cursor, the
+ * frame's encoding. What differs per host — whether the program can end
+ * 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 { Segment } from "../core/segment.js";
+import { type Renderable } from "../core/protocol.js";
+import type { Unsubscribe } from "../core/subscription.js";
+import type { TerminalHost } from "./terminal-host.js";
+/**
+ * Where the frame is painted. `alternate` is the whole terminal, in the
+ * alternate screen buffer, so the rows the program printed before it are
+ * there again when it stops; the terminal reports the pointer on it. `inline`
+ * starts at the cursor's line, as tall as the frame, and stays on the
+ * terminal when the app stops. It gets no pointer events: the terminal
+ * reports a pointer by its row on the screen, and the app does not know
+ * which row of the screen its frame starts on.
+ */
+export type Surface = "alternate" | "inline";
+/**
+ * Where an app is in its life. `idle` has not run; `running` holds the
+ * terminal and paints; `suspended` has handed it back until the host resumes
+ * the program; `stopped` has handed it back for good.
+ */
+export type AppPhase = "idle" | "running" | "suspended" | "stopped";
+export interface AppOptions {
+    /** The terminal the app runs on. The app starts and stops it. */
+    readonly host: TerminalHost;
+    readonly surface: Surface;
+    /**
+     * The app's root renderable, asked for once per frame, so a view of the
+     * app's state is drawn from the state as it is at that frame.
+     */
+    readonly view: () => Renderable;
+    /**
+     * The terminal can draw only ASCII, so every frame draws its boxes, guides
+     * and widget marks with ASCII characters. Default false.
+     */
+    readonly asciiOnly?: boolean;
+}
+export declare class App {
+    private readonly host;
+    private readonly surface;
+    private readonly view;
+    private readonly console;
+    private _phase;
+    private _frame;
+    private rows;
+    private refreshQueued;
+    private subscriptions;
+    private readonly paintHandlers;
+    private settle;
+    constructor(options: AppOptions);
+    get phase(): AppPhase;
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame(): readonly (readonly Segment[])[];
+    /**
+     * Take the terminal, paint the first frame, and resolve when the app stops
+     * — or reject with the error a frame threw or `fail` was given, the terminal
+     * handed back first.
+     * When the program ends under the app, `run` does not settle: nothing after
+     * it runs, as nothing after it would have without the app. An app runs once.
+     */
+    run(): Promise<void>;
+    /**
+     * Paint a new frame from the view, once, in a later task: every change made
+     * before then lands in the one frame.
+     *
+     * [LAW:no-ambient-temporal-coupling] A task, not a microtask. Input is read
+     * between tasks, so a view whose every frame asks for another still hears
+     * its keys — Ctrl+C included — where a microtask chain would starve them
+     * for as long as it ran.
+     */
+    refresh(): void;
+    /**
+     * 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 —
+     * in raw mode Ctrl+Z arrives as a key.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Hear each frame once it is on screen — what `frame` now returns. A
+     * handler that throws fails the app as a frame that throws does.
+     */
+    onPaint(handler: (frame: readonly (readonly Segment[])[]) => void): Unsubscribe;
+    /** Hand the terminal back for good; `run` resolves. */
+    stop(): void;
+    /**
+     * Hand the terminal back for good; `run` rejects with `error`. For an error
+     * thrown where the app's own code runs outside a frame — a key handler, a
+     * timer — which would otherwise reach neither `run`'s caller nor the
+     * terminal's hand-back.
+     */
+    fail(error: unknown): void;
+    private enter;
+    private leave;
+    private end;
+    private paint;
+    private draw;
+}

package/dist/host/app.js

@@ -0,0 +1,255 @@
+/**
+ * App — the runtime a terminal application runs in: it takes the terminal,
+ * paints one renderable on it every frame, and hands the terminal back on
+ * every path out.
+ *
+ * [LAW:single-enforcer] Every change this runtime makes to the terminal —
+ * the alternate screen, pointer reporting, the hidden cursor, raw mode — is
+ * made by `enter` and
+ * undone by `leave`, and nothing else touches them. Stopping, suspending, an
+ * error in a frame and the program ending by a signal or a crash all hand the
+ * terminal back through `leave`, so there is one list of what to undo and no
+ * exit path can hold a shorter one.
+ *
+ * [LAW:one-source-of-truth] The frame on screen is one value: the rows last
+ * painted, carrying on every cell where its owner drew it (`core/anchor`).
+ * Nothing about it is cached beside it, so a resize invalidates nothing — it
+ * is input to the next frame, which replaces the rows and their anchors at
+ * once. An event arriving before that repaint lands on the frame on screen,
+ * which is the one the user pointed at.
+ *
+ * [LAW:locality-or-seam] The terminal's bytes are identical under every host
+ * and live here: entering and leaving the alternate screen, the cursor, the
+ * frame's encoding. What differs per host — whether the program can end
+ * 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 { Console } from "../core/console.js";
+import { Segment } from "../core/segment.js";
+import { segmentsToString } from "../core/render.js";
+import { fitHeight } from "../core/protocol.js";
+import { hostEnvironment } from "./host-environment.js";
+// 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),
+    },
+};
+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;
+    // [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;
+    refreshQueued = false;
+    subscriptions = [];
+    paintHandlers = new Set();
+    settle = () => { };
+    constructor(options) {
+        this.host = options.host;
+        this.surface = SURFACES[options.surface];
+        this.view = options.view;
+        this.console = new Console({ environment: hostEnvironment(options.host), asciiOnly: options.asciiOnly });
+    }
+    get phase() {
+        return this._phase;
+    }
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame() {
+        return this._frame;
+    }
+    /**
+     * Take the terminal, paint the first frame, and resolve when the app stops
+     * — or reject with the error a frame threw or `fail` was given, the terminal
+     * handed back first.
+     * When the program ends under the app, `run` does not settle: nothing after
+     * it runs, as nothing after it would have without the app. An app runs once.
+     */
+    run() {
+        if (this._phase !== "idle") {
+            return Promise.reject(new Error(`App.run: an app runs once, and this one is ${this._phase}`));
+        }
+        return new Promise((resolve, reject) => {
+            this.settle = (outcome) => {
+                switch (outcome.kind) {
+                    case "stopped":
+                        return resolve();
+                    case "failed":
+                        return reject(outcome.error);
+                    // The rest of a crash — its report, then its exit — is still
+                    // running, and code resumed after `run` would run inside it.
+                    case "ended":
+                        return;
+                }
+            };
+            this._phase = "running";
+            this.host.start();
+            this.subscriptions = [
+                this.host.onResize(() => this.refresh()),
+                // The program is ending under the app — by a signal, a crash, or an
+                // exit the app's own code never saw. Ending hands the terminal back,
+                // and the program then ends as it was going to.
+                this.host.onExit(() => this.end({ kind: "ended" })),
+            ];
+            this.enter();
+            this.paint();
+        });
+    }
+    /**
+     * Paint a new frame from the view, once, in a later task: every change made
+     * before then lands in the one frame.
+     *
+     * [LAW:no-ambient-temporal-coupling] A task, not a microtask. Input is read
+     * between tasks, so a view whose every frame asks for another still hears
+     * its keys — Ctrl+C included — where a microtask chain would starve them
+     * for as long as it ran.
+     */
+    refresh() {
+        if (this.refreshQueued)
+            return;
+        this.refreshQueued = true;
+        setTimeout(() => {
+            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.
+            if (this._phase === "running")
+                this.paint();
+        });
+    }
+    /**
+     * 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 —
+     * in raw mode Ctrl+Z arrives as a key.
+     */
+    async suspend() {
+        if (this._phase !== "running")
+            return;
+        this._phase = "suspended";
+        this.leave();
+        await this.host.suspend();
+        // Stopped while suspended — by a signal, say: the terminal is already
+        // handed back for good.
+        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();
+    }
+    /**
+     * Hear each frame once it is on screen — what `frame` now returns. A
+     * handler that throws fails the app as a frame that throws does.
+     */
+    onPaint(handler) {
+        this.paintHandlers.add(handler);
+        return () => this.paintHandlers.delete(handler);
+    }
+    /** Hand the terminal back for good; `run` resolves. */
+    stop() {
+        this.end({ kind: "stopped" });
+    }
+    /**
+     * Hand the terminal back for good; `run` rejects with `error`. For an error
+     * thrown where the app's own code runs outside a frame — a key handler, a
+     * timer — which would otherwise reach neither `run`'s caller nor the
+     * terminal's hand-back.
+     */
+    fail(error) {
+        this.end({ kind: "failed", error });
+    }
+    // --- the terminal ---
+    enter() {
+        this.host.setRawMode(true);
+        this.host.write(this.surface.enter + HIDE_CURSOR);
+    }
+    leave() {
+        this.host.write(RESET_STYLE + SHOW_CURSOR + this.surface.leave(this.rows));
+        this.host.setRawMode(false);
+    }
+    end(outcome) {
+        const phase = this._phase;
+        if (phase === "idle" || phase === "stopped")
+            return;
+        this._phase = "stopped";
+        for (const unsubscribe of this.subscriptions)
+            unsubscribe();
+        this.subscriptions = [];
+        // A suspended app handed the terminal back when it suspended.
+        if (phase === "running")
+            this.leave();
+        this.host.stop();
+        this.settle(outcome);
+    }
+    // [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() {
+        try {
+            this.draw();
+        }
+        catch (error) {
+            this.end({ kind: "failed", error });
+        }
+    }
+    draw() {
+        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 }));
+        // 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);
+        this._frame = frame;
+        this.rows = frame.length;
+        for (const handler of [...this.paintHandlers])
+            handler(frame);
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+import type { ConsoleEnvironment, ConsoleStream } from "../core/console.js";
+import type { TerminalHost } from "./terminal-host.js";
+export declare function hostEnvironment(host: TerminalHost): ConsoleEnvironment & {
+    readonly stdout: ConsoleStream;
+    readonly stderr: ConsoleStream;
+};

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

@@ -0,0 +1,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";

package/dist/host/index.js

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