@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/wrap.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 cells each word of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word.
+ */
+export declare function wordWidths(text: string): number[];
+/**
+ * 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,140 @@
+/**
+ * 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];
+    }
+}
+/**
+ * The cells a word needs on a line: all of it but its trailing whitespace,
+ * which may hang past the edge for the caller to crop. Its leading whitespace
+ * counts — that is a line's indent, and it is not a place to break.
+ */
+function widthOf(word) {
+    return cellLen(word.trimEnd());
+}
+/**
+ * The cells each word of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word.
+ */
+export function wordWidths(text) {
+    return Array.from(words(text), widthOf);
+}
+/**
+ * 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)) {
+        const wordWidth = widthOf(word);
+        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,133 @@
+/**
+ * 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 { type Clock, type FrameRate } from "../core/clock.js";
+import { type ConsoleOptions } from "../core/console.js";
+import { Segment } from "../core/segment.js";
+import { type Surface } from "../core/paint.js";
+import { type Renderable } from "../core/protocol.js";
+import type { Unsubscribe } from "../core/subscription.js";
+import type { TerminalHost } from "./terminal-host.js";
+/**
+ * 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";
+declare const DRAW_OPTIONS: readonly ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+type DrawOption = (typeof DRAW_OPTIONS)[number];
+type DrawOptions = Readonly<Pick<ConsoleOptions, DrawOption>>;
+export interface AppOptions extends DrawOptions {
+    /** 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. `t` is the
+     * frame's time in seconds on the app's `clock`, which is what an effect is
+     * sampled at.
+     */
+    readonly view: (t: number) => Renderable;
+    /** What the app reads the time from and ticks on. The platform's, unless given. */
+    readonly clock?: Clock;
+    /** How often the app paints while something is animating. 30 frames a second, unless given. */
+    readonly rate?: FrameRate;
+}
+export declare class App {
+    private readonly host;
+    private readonly surface;
+    private readonly view;
+    private readonly clock;
+    private readonly rate;
+    private readonly animations;
+    private stopTicking;
+    private readonly console;
+    private _phase;
+    private _frame;
+    private readonly painter;
+    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;
+    /**
+     * 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(): Unsubscribe;
+    /**
+     * 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 tick;
+    private paint;
+    private draw;
+}
+export {};

package/dist/host/app.js

@@ -0,0 +1,285 @@
+/**
+ * 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 { frameRate, systemClock } from "../core/clock.js";
+import { Console } from "../core/console.js";
+import { Segment } from "../core/segment.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.
+// 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: "" },
+};
+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 = [];
+    painter;
+    refreshQueued = false;
+    subscriptions = [];
+    paintHandlers = new Set();
+    settle = () => { };
+    constructor(options) {
+        this.host = options.host;
+        this.surface = options.surface;
+        this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
+        this.view = options.view;
+        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;
+    }
+    /** 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();
+            this.tick();
+        });
+    }
+    /**
+     * 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(() => {
+            // 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.
+            if (this._phase === "running")
+                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 —
+     * in raw mode Ctrl+Z arrives as a key.
+     */
+    async suspend() {
+        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
+        // handed back for good.
+        if (this._phase !== "suspended")
+            return;
+        this._phase = "running";
+        this.enter();
+        this.paint();
+        this.tick();
+    }
+    /**
+     * 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.painter.take();
+        this.host.write(POINTER[this.surface].on);
+    }
+    leave() {
+        this.host.write(POINTER[this.surface].off);
+        this.painter.handBack();
+        this.host.setRawMode(false);
+    }
+    end(outcome) {
+        const phase = this._phase;
+        if (phase === "idle" || phase === "stopped")
+            return;
+        this._phase = "stopped";
+        this.tick();
+        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: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() {
+        try {
+            this.draw();
+        }
+        catch (error) {
+            this.end({ kind: "failed", error });
+        }
+    }
+    draw() {
+        // This frame draws every change made before it, a queued refresh's included.
+        this.refreshQueued = false;
+        const options = this.console.options;
+        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 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;
+        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 };
+}