@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/core/text.js

@@ -1,16 +1,16 @@
 /**
  * RichText — styled text with spans. The primary text type for the library.
  */
-import { cellLen, cellCount } from "./cells.js";
+import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol } from "./cells.js";
 import { divideLine } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
 import { stripOscTerminators } from "./osc8.js";
-import { getStyle, withBoundedWidth } from "./protocol.js";
+import { drawable, getStyle, withBoundedWidth } from "./protocol.js";
 // Strip control characters except \t and \n
 // [LAW:single-enforcer] Single place where control chars are sanitized
 const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
-function stripControlChars(text) {
+export function stripControlChars(text) {
     return text.replace(CONTROL_CHARS_RE, "");
 }
 const TRAILING_WHITESPACE_RE = /\s+$/;
@@ -66,9 +66,16 @@ function sanitizeStyleLink(style) {
  * RichText knows when the name arrives — the reference stores span styles the
  * same way. A string holds no link until it is parsed, so only a `Style` has
  * one to sanitize here.
+ *
+ * [LAW:single-enforcer] Nor does a RichText keep an anchor (`./anchor.ts`). It
+ * lays its text out anew, so a stamp naming where a cell sat in the output it
+ * came from would name the wrong cell once it wraps, slices or overlaps; the
+ * owner that renders the RichText is the one that stamps its cells.
  */
 function admitStyle(style) {
-    return style instanceof Style ? sanitizeStyleLink(style) : style;
+    if (!(style instanceof Style))
+        return style;
+    return sanitizeStyleLink(style.anchor ? style.withAnchor(undefined) : style);
 }
 /** A style that adds nothing: the empty definition, or a null `Style`. */
 function isEmptyStyle(style) {
@@ -264,6 +271,9 @@ export class RichText {
             }
             const offset = this._text.length;
             this._text += content._text;
+            // Its base style becomes a span under its own spans, as the reference's
+            // `append` does, so appended text looks as it did alone.
+            this._addSpan(offset, this._text.length, content._style);
             for (const span of content._spans) {
                 this._spans.push(span.move(offset));
             }
@@ -314,9 +324,10 @@ export class RichText {
      * is admitted as given.
      */
     _addSpan(start, end, style) {
-        if (isEmptyStyle(style))
+        const admitted = admitStyle(style);
+        if (isEmptyStyle(admitted))
             return;
-        this._spans.push(new Span(start, end, admitStyle(style)));
+        this._spans.push(new Span(start, end, admitted));
     }
     stylize(style, start, end) {
         const len = this._text.length;
@@ -486,7 +497,10 @@ export class RichText {
      *   in the middle.
      *
      * Marker default is `"\u2026"`. Pass `marker: ""` for raw cropping without an
-     * indicator glyph.
+     * indicator glyph. A marker wider than `width` is itself cut to the glyphs
+     * that fit, and the text takes whatever cells that leaves — all of them, when
+     * not one glyph of the marker fits — so the result is never wider than asked.
+     * Every cut, marker and text alike, falls between grapheme clusters.
      *
      * Spans are preserved through the cut: characters that survive keep their
      * styling; the marker (if any) is inserted as plain text with no span.
@@ -500,13 +514,12 @@ export class RichText {
         if (this.cellLength <= width)
             return this;
         const mode = options?.mode ?? "right";
-        const marker = options?.marker ?? "\u2026";
-        const markerWidth = cellLen(marker);
-        if (width <= 0) {
-            this.plain = "";
-            return this;
-        }
-        const budget = Math.max(0, width - markerWidth);
+        // [LAW:dataflow-not-control-flow] the marker is fitted to the width as a
+        // value, so width 0 and a marker wider than the width run the same walk
+        // as every other call: what is drawn plus what is kept is `cells` wide.
+        const cells = cellCount(width);
+        const marker = cellFit(options?.marker ?? "\u2026", cells);
+        const budget = asCellCol(cells - cellLen(marker));
         if (mode === "right") {
             this._cropRightTo(budget);
             if (marker)
@@ -522,11 +535,11 @@ export class RichText {
             return this;
         }
         // middle
-        const leftBudget = Math.floor(budget / 2);
-        const rightBudget = budget - leftBudget;
+        const leftBudget = asCellCol(Math.floor(budget / 2));
+        const rightBudget = asCellCol(budget - leftBudget);
         // Find the char-index ranges to keep from each side.
-        const leftEndCharIdx = this._cellPrefixCharLength(leftBudget);
-        const rightStartCharIdx = this._cellSuffixStartCharIndex(rightBudget);
+        const leftEndCharIdx = cellFit(this._text, leftBudget).length;
+        const rightStartCharIdx = this._text.length - cellFitEnd(this._text, rightBudget).length;
         const leftText = this._text.slice(0, leftEndCharIdx);
         const rightText = this._text.slice(rightStartCharIdx);
         const droppedStart = leftEndCharIdx;
@@ -557,11 +570,10 @@ export class RichText {
         return this;
     }
     _cropRightTo(targetWidth) {
-        const charIdx = this._cellPrefixCharLength(targetWidth);
-        this.plain = this._text.slice(0, charIdx);
+        this.plain = cellFit(this._text, targetWidth);
     }
     _cropLeftTo(targetWidth) {
-        const charIdx = this._cellSuffixStartCharIndex(targetWidth);
+        const charIdx = this._text.length - cellFitEnd(this._text, targetWidth).length;
         // Shift spans left by charIdx; clip spans that started before.
         const shift = -charIdx;
         this._spans = this._spans
@@ -575,34 +587,6 @@ export class RichText {
             .filter((s) => s !== undefined);
         this._text = this._text.slice(charIdx);
     }
-    /** Number of char-index code units that fit within `targetWidth` cell columns from the left. */
-    _cellPrefixCharLength(targetWidth) {
-        let width = 0;
-        let charIndex = 0;
-        for (const char of this._text) {
-            const charWidth = cellLen(char);
-            if (width + charWidth > targetWidth)
-                break;
-            width += charWidth;
-            charIndex += char.length;
-        }
-        return charIndex;
-    }
-    /** Char-index at which the suffix of `targetWidth` cell columns starts. */
-    _cellSuffixStartCharIndex(targetWidth) {
-        // Walk from right: accumulate widths of trailing chars until we hit the budget.
-        const chars = [...this._text];
-        let width = 0;
-        let kept = 0;
-        for (let i = chars.length - 1; i >= 0; i--) {
-            const w = cellLen(chars[i]);
-            if (width + w > targetWidth)
-                break;
-            width += w;
-            kept += chars[i].length;
-        }
-        return this._text.length - kept;
-    }
     // --- Alignment ---
     align(justify, width) {
         const currentWidth = this.cellLength;
@@ -671,9 +655,8 @@ export class RichText {
      * `{{ red "x" }}{{ blue "y" }}` evaluates to two fragments — one with
      * wrapping `style = red`, one with `blue` — and consumers that want a
      * single styled string for downstream rendering need both styles
-     * preserved as spans on the concatenated result. The plain `append()`
-     * propagates spans only, so this static does the additional work of
-     * lifting `frag.style` into a span before appending.
+     * preserved as spans on the concatenated result, which is what `append()`
+     * does with each fragment.
      *
      * Empty input → empty `RichText` with `end: ""`. Caller can override
      * `end` (defaults to `""` — the engine-output case rarely wants a
@@ -681,14 +664,8 @@ export class RichText {
      */
     static fromFragments(fragments, options) {
         const result = new RichText("", { end: options?.end ?? "" });
-        for (const frag of fragments) {
-            const start = result.length;
-            result.append(frag.plain);
-            result.stylize(frag.style, start, result.length);
-            for (const span of frag.spans) {
-                result.stylize(span.style, start + span.start, start + span.end);
-            }
-        }
+        for (const frag of fragments)
+            result.append(frag);
         return result;
     }
     // --- Renderable ---
@@ -704,21 +681,28 @@ export class RichText {
         // which pads — and `" ".repeat(Infinity)` throws.
         const maxWidth = cellCount(withBoundedWidth(options, this).maxWidth);
         const overflow = this._overflow ?? options.overflow ?? "fold";
-        const justify = this._justify ?? options.justify;
         const noWrap = this._noWrap || (options.noWrap ?? false);
-        // The width a line is cut to, which is not always the width it is
-        // justified in. `noWrap` means the line is not bounded at all: it leaves at
-        // its natural width and whatever asked for it decides about the overhang —
-        // `Console`'s soft wrap and `FlexStrip`'s too-wide fallback both want the
-        // text intact rather than cropped.
+        // Two widths, and they are the reference's `no_wrap` and `"ignore"` told
+        // apart. `edge` is where a line is cut: gone under `"ignore"`, so the line
+        // leaves at its natural width and whatever drew it decides about the
+        // overhang. `wrapAt` is where a line may break: gone under `noWrap` too,
+        // which keeps one line per line and still cuts it at the edge by the
+        // overflow method — Rich's `Text.wrap` truncates its no-wrap arm.
         //
-        // [LAW:dataflow-not-control-flow] It reaches the pipeline as a width, not
-        // as a step to skip: an unbounded budget has no edge to break at, so
+        // [LAW:dataflow-not-control-flow] Each reaches the pipeline as a width, not
+        // as a step to skip: an unbounded width has no edge to break at, so
         // `divideLine` finds no cuts and `_fitLine` finds nothing past the edge,
         // and every line runs the same three steps. `Infinity` is already this
         // library's spelling of an unbounded width offer — `withBoundedWidth` in
         // protocol.ts parses one on the way in.
-        const budget = noWrap ? cellCount(Infinity) : maxWidth;
+        const edge = overflow === "ignore" ? cellCount(Infinity) : maxWidth;
+        const wrapAt = noWrap ? cellCount(Infinity) : edge;
+        // A line with no edge has no width to be justified in, so under `"ignore"`
+        // it is not justified — the reference's `Text.wrap` returns that arm before
+        // `justify`. `undefined` is the placement that leaves a line as it is.
+        const justify = overflow === "ignore" ? undefined : this._justify ?? options.justify;
+        // One cell either way, so the marker's stand-in leaves the cut where it was.
+        const ellipsis = drawable(options, "\u2026", ".");
         const endsWithNewline = text.endsWith("\n");
         for (let index = 0; index < logicalLines.length; index += 1) {
             const line = logicalLines[index];
@@ -726,9 +710,9 @@ export class RichText {
             // Wrap first, overflow last — the reference's order, and the reason a
             // long sentence grows a table row while an unbreakable word in the same
             // column still ellipsizes.
-            const cuts = divideLine(plainOf(line), budget, { fold: overflow === "fold" });
+            const cuts = divideLine(plainOf(line), wrapAt, { fold: overflow === "fold" });
             const wrapped = Segment.divide(line, cuts);
-            const placed = this._justifyLines(wrapped.map((piece) => [...this._fitLine(piece, budget, overflow)]), maxWidth, base, justify);
+            const placed = this._justifyLines(wrapped.map((piece) => [...this._fitLine(piece, edge, overflow, ellipsis)]), maxWidth, base, justify);
             for (let piece = 0; piece < placed.length; piece += 1) {
                 yield* placed[piece];
                 if (piece < placed.length - 1 || terminateLine) {
@@ -954,11 +938,13 @@ export class RichText {
      *
      * Everything reaching here already survived wrapping, so the only text still
      * too wide is text no break could help: a word longer than the canvas under
-     * a non-folding overflow method, a glyph wider than the budget, or a canvas
-     * with no cells at all. That is what makes the overflow method a last
-     * resort rather than the first thing a long cell meets.
+     * a non-folding overflow method, a glyph wider than the budget, a canvas
+     * with no cells at all, or a `noWrap` line, which no break was allowed to
+     * help. That is what makes the overflow method a last resort rather than the
+     * first thing a long cell meets. `"fold"` has nothing left to fold here and
+     * cuts as `"crop"` does, as the reference's `truncate` does.
      */
-    *_fitLine(line, maxWidth, overflow) {
+    *_fitLine(line, maxWidth, overflow, ellipsis) {
         const lineWidth = Segment.getLineLength(line);
         const contentWidth = lineWidth - hangingWhitespace(line);
         // Whitespace hanging past the edge is the wrap's own padding: cropping it
@@ -982,7 +968,7 @@ export class RichText {
         // three different kinds of nothing.
         if (overflow === "ellipsis" && maxWidth > 0) {
             yield* Segment.adjustLineLength(line, maxWidth - 1, undefined, false);
-            yield new Segment("\u2026");
+            yield new Segment(ellipsis);
             return;
         }
         yield* Segment.adjustLineLength(line, maxWidth, undefined, false);

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;
+};