@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/core/wrap.d.ts

@@ -18,16 +18,30 @@
  * 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.
+ *
+ * Rich breaks only at whitespace, and that is what happens to any word holding
+ * nothing below: `test/core/text-wrap.golden.txt` pins it. Past that, a word
+ * breaks where its text says it may (UAX #14): after ZWSP, at a soft hyphen, and
+ * between the words of a script written without spaces. U+2060 and U+FEFF forbid
+ * a break, which here needs nothing but not being one.
  */
-import { type CellCol } from "./cells.js";
+import { type CellCol, type CodePoint } from "./cells.js";
+/** One place a line of text was cut. */
+export interface LineBreak {
+    /** Where the line is cut, in cells. */
+    readonly cell: CellCol;
+    /** The soft hyphen this break draws as `-`. Absent at any other break, and where no hyphen fits. */
+    readonly hyphen: CodePoint | undefined;
+}
 /**
- * The cells each word of `text` needs, in order — the widest is the narrowest
- * width `divideLine` can wrap it to without cutting a word.
+ * The cells each piece of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word. A hyphen is not in
+ * them: where it does not fit, the break goes without it.
  */
 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.
+ * The breaks that wrap `text` 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
@@ -36,6 +50,10 @@ export declare function wordWidths(text: string): number[];
  * can truncate it, which is what makes an unbreakable word ellipsize while the
  * sentence around it merely wraps.
  *
+ * A piece that ends in a soft hyphen stays on a line only with room for the
+ * hyphen, so a line it closes holds it, and a word that fits whole needs none. A
+ * piece as wide as the line breaks with no hyphen rather than lose a letter to one.
+ *
  * 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
@@ -43,4 +61,4 @@ export declare function wordWidths(text: string): number[];
  */
 export declare function divideLine(text: string, width: CellCol, options: {
     fold: boolean;
-}): CellCol[];
+}): LineBreak[];

package/dist/core/wrap.js

@@ -18,8 +18,28 @@
  * 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.
+ *
+ * Rich breaks only at whitespace, and that is what happens to any word holding
+ * nothing below: `test/core/text-wrap.golden.txt` pins it. Past that, a word
+ * breaks where its text says it may (UAX #14): after ZWSP, at a soft hyphen, and
+ * between the words of a script written without spaces. U+2060 and U+FEFF forbid
+ * a break, which here needs nothing but not being one.
  */
-import { cellLen, chopCells, asCellCol } from "./cells.js";
+import { asCellCol, asCodePoint, cellLen, chopCells } from "./cells.js";
+import { pattern } from "./pattern.js";
+const SOFT_HYPHEN = "\u00ad";
+const ZWSP = "\u200b";
+// The scripts UAX #14 sends to a dictionary (line break class SA) and ICU has one
+// for. Which words it finds varies by ICU, and a dictionary cannot be vendored as
+// the width table is; a word it misses is folded like any other.
+const UNSPACED = "[\\p{Script_Extensions=Thai}\\p{Script_Extensions=Lao}\\p{Script_Extensions=Khmer}\\p{Script_Extensions=Myanmar}]+";
+const BREAKABLE = pattern(new RegExp(`[${SOFT_HYPHEN}${ZWSP}]|${UNSPACED}`, "u"));
+const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+// A break needs a glyph on both sides of it: with none before, nothing breaks away
+// or takes a hyphen, and with none after, the word was already over.
+const UNDRAWN = "\\s\\p{Cf}\\p{Mn}";
+const OPENING = pattern(new RegExp(`^[${UNDRAWN}]*`, "u"));
+const THROUGH_LAST_GLYPH = pattern(new RegExp(`^[^]*[^${UNDRAWN}]`, "u"));
 /**
  * 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
@@ -34,7 +54,9 @@ 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;
+    // U+FEFF is outside it, as it is outside Python's `\s` and Rich's words: it is a
+    // no-break space that JavaScript's `\s` counts as a space.
+    const re = /[^\S\ufeff]*[\S\ufeff]+[^\S\ufeff]*/y;
     for (let match = re.exec(text); match !== null; match = re.exec(text)) {
         yield match[0];
     }
@@ -47,12 +69,46 @@ function* words(text) {
 function widthOf(word) {
     return cellLen(word.trimEnd());
 }
+/** The offsets inside `word`, ascending, that it may break at. */
+function breaksIn(word) {
+    if (word.match(BREAKABLE) === null)
+        return [];
+    const found = new Set();
+    // One break to a run of marks: a second would open a piece with nothing in it.
+    for (const { 0: mark, index } of word.matchAll(new RegExp(`(?<![${SOFT_HYPHEN}${ZWSP}])[${SOFT_HYPHEN}${ZWSP}]`, "gu")))
+        found.add(index + mark.length);
+    for (const { 0: run, index } of word.matchAll(new RegExp(UNSPACED, "gu"))) {
+        // A run's start is where the segmenter's input began, not a boundary it found:
+        // UAX #14 has these scripts break as letters do against what comes before them.
+        for (const { index: at } of WORD_SEGMENTER.segment(run))
+            if (at > 0)
+                found.add(index + at);
+    }
+    const start = OPENING.exec(word)[0].length;
+    const end = THROUGH_LAST_GLYPH.exec(word)?.[0].length ?? 0;
+    return [...found].filter((at) => at > start && at < end).sort((a, b) => a - b);
+}
+/** `text` as what wraps: its words, tiled further wherever one may break. */
+function* piecesOf(text) {
+    for (const word of words(text)) {
+        let start = 0;
+        for (const at of breaksIn(word)) {
+            const piece = word.slice(start, at);
+            const cells = widthOf(piece);
+            yield { text: piece, cells, hyphenates: cells > 0 && piece.endsWith(SOFT_HYPHEN) };
+            start = at;
+        }
+        const last = word.slice(start);
+        yield { text: last, cells: widthOf(last), hyphenates: false };
+    }
+}
 /**
- * The cells each word of `text` needs, in order — the widest is the narrowest
- * width `divideLine` can wrap it to without cutting a word.
+ * The cells each piece of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word. A hyphen is not in
+ * them: where it does not fit, the break goes without it.
  */
 export function wordWidths(text) {
-    return Array.from(words(text), widthOf);
+    return Array.from(piecesOf(text), (piece) => piece.cells);
 }
 /**
  * A word chopped into pieces of at most `width` cells, as the reference chops
@@ -78,8 +134,8 @@ function foldWord(word, width) {
     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.
+ * The breaks that wrap `text` 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
@@ -88,6 +144,10 @@ function foldWord(word, width) {
  * can truncate it, which is what makes an unbreakable word ellipsize while the
  * sentence around it merely wraps.
  *
+ * A piece that ends in a soft hyphen stays on a line only with room for the
+ * hyphen, so a line it closes holds it, and a word that fits whole needs none. A
+ * piece as wide as the line breaks with no hyphen rather than lose a letter to one.
+ *
  * 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
@@ -96,19 +156,22 @@ function foldWord(word, width) {
 export function divideLine(text, width, options) {
     if (width <= 0)
         return [];
-    const cuts = [];
+    const breaks = [];
     // 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));
+            breaks.push({ cell: asCellCol(cell), hyphen: width - used > 0 ? softHyphen : undefined });
     };
     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) {
+    let offset = 0; // code units before the current word
+    let softHyphen; // the one the line being filled ends in
+    for (const piece of piecesOf(text)) {
+        const word = piece.text;
+        const wordWidth = piece.cells;
+        if (width - used >= wordWidth + (piece.hyphenates ? 1 : 0)) {
             used += cellLen(word);
         }
         else if (options.fold && wordWidth > width) {
@@ -119,13 +182,14 @@ export function divideLine(text, width, options) {
             let pieceStart = wordStart;
             for (let index = 0; index < pieces.length; index += 1) {
                 cutAt(pieceStart);
-                const piece = pieces[index];
+                softHyphen = undefined;
+                const fold = 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);
+                    used = cellLen(fold);
                 else
-                    pieceStart += cellLen(piece);
+                    pieceStart += cellLen(fold);
             }
         }
         else {
@@ -135,6 +199,8 @@ export function divideLine(text, width, options) {
             used = cellLen(word);
         }
         wordStart += cellLen(word);
+        offset += word.length;
+        softHyphen = piece.hyphenates ? asCodePoint(offset - 1) : undefined;
     }
-    return cuts;
+    return breaks;
 }

package/dist/host/app.d.ts

@@ -31,14 +31,15 @@
  * — a focused field in a `WidgetApp` included — can swallow them.
  */
 import { type Clock, type FrameRate } from "../core/clock.js";
+import { type TerminalColors } from "../core/color.js";
 import { type ConsoleOptions } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { type Surface } from "../core/paint.js";
-import { type FrameHost } from "../core/protocol.js";
+import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
-import { type KeyPress, type ScreenMouseEvent } from "./input.js";
+import { type KeyPress, type ScreenMouseEvent, type TerminalReply } from "./input.js";
 import type { TerminalHost } from "./terminal-host.js";
 /**
  * Where an app is in its life. `idle` has not run; `running` holds the
@@ -46,7 +47,7 @@ import type { TerminalHost } from "./terminal-host.js";
  * the program; `stopped` has handed it back for good.
  */
 export type AppPhase = "idle" | "running" | "suspended" | "stopped";
-declare const DRAW_OPTIONS: readonly ["asciiOnly", "reducedMotion", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+declare const DRAW_OPTIONS: readonly ["asciiOnly", "reducedMotion", "textOrder", "terminal", "theme", "onStyleError", "markup", "highlight", "highlighter"];
 type DrawOption = (typeof DRAW_OPTIONS)[number];
 type DrawOptions = Readonly<Pick<ConsoleOptions, DrawOption>>;
 export interface AppOptions extends DrawOptions {
@@ -102,6 +103,21 @@ type WheelTurn = Extract<ScreenMouseEvent, {
 }>;
 /** A pointer event `onMouse` hears: every one but the vertical wheel, which is `onWheel`'s. */
 export type AppMouseEvent = Exclude<ScreenMouseEvent, WheelTurn>;
+/**
+ * How an ask ended, with the replies heard before it did. `answered`: the
+ * terminal answered DA1, so a query with no reply among `replies` is one it
+ * does not support. `timeout`: it answered nothing in time, DA1 included.
+ * `left`: the app handed the terminal back first. `unasked`: the host writes
+ * to no terminal, so nothing was asked.
+ */
+export interface Asked {
+    readonly ended: "answered" | "timeout" | "left" | "unasked";
+    readonly replies: readonly TerminalReply[];
+}
+export interface AskOptions {
+    /** Seconds to wait for a terminal that answers nothing. Half a second, unless given. */
+    readonly timeout?: number;
+}
 export declare class App implements FrameHost {
     private readonly host;
     private readonly surface;
@@ -113,7 +129,11 @@ export declare class App implements FrameHost {
     private ticking;
     private said;
     private waking;
-    private readonly console;
+    private console;
+    private drawing;
+    private asking;
+    private asked;
+    private owedDa1;
     private _phase;
     private _frame;
     private readonly painter;
@@ -127,6 +147,26 @@ export declare class App implements FrameHost {
     private readonly input;
     private settle;
     constructor(options: AppOptions);
+    /**
+     * The terminal the app draws on: the colours a cell that sets none is drawn
+     * in, and the sixteen an ANSI colour names — as given, or as the colour
+     * depth assumes (`resolveTerminal`).
+     */
+    get terminal(): TerminalColors;
+    /** Draw on `terminal` from the next frame on — what `terminalColors` learned, say. */
+    set terminal(terminal: TerminalColors);
+    /**
+     * Ask the terminal: write `queries`, then DA1, and resolve with the replies
+     * heard before DA1's, or before the timeout or the app handing the terminal
+     * back. It rejects only when writing to the terminal throws. Asks run one
+     * after another, and only while the app runs: it holds raw mode and reads
+     * the input, so a reply reaches the ask and never a key handler. A reply no
+     * ask is waiting for is dropped. `queries` must not ask for DA1 itself: its
+     * reply would end the ask early.
+     */
+    ask(queries: readonly string[], options?: AskOptions): Promise<Asked>;
+    private drawingConsole;
+    private askNow;
     get phase(): AppPhase;
     /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
     get clock(): Clock;
@@ -149,12 +189,12 @@ export declare class App implements FrameHost {
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
     /**
-     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
-     * clock's now, through the timeline. What a moment heard
+     * The frame this app draws now (`FrameHost`): the clock's now, through the
+     * timeline, on a frame it is the host of. Its time is what a moment heard
      * between frames — a key — is stamped with, so it is on the clock the
      * frame is.
      */
-    get frameTime(): number;
+    frameNow(): HostFrame;
     private _time;
     /**
      * Take the terminal, paint the first frame, and resolve when the app stops
@@ -217,6 +257,7 @@ export declare class App implements FrameHost {
     private enter;
     private leave;
     private end;
+    private reply;
     private key;
     private mouse;
     private hear;

package/dist/host/app.js

@@ -31,21 +31,22 @@
  * — a focused field in a `WidgetApp` included — can swallow them.
  */
 import { frameRate, systemClock } from "../core/clock.js";
+import { ColorDepth, resolveTerminal } from "../core/color.js";
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
-import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { drawView, frameNow, hostView, undrawn } from "../core/view.js";
 import { hostEnvironment } from "./host-environment.js";
 import { InputParser, keyName, parseKeyName } from "./input.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
+// [LAW:one-source-of-truth] How a frame draws — its glyphs, the terminal its
+// colours resolve on, 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", "reducedMotion", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+const DRAW_OPTIONS = ["asciiOnly", "reducedMotion", "textOrder", "terminal", "theme", "onStyleError", "markup", "highlight", "highlighter"];
 function drawOptions(options) {
     const picked = {};
     const copy = (key) => {
@@ -68,6 +69,12 @@ const POINTER = {
 // The sideways wheel is not here: nothing scrolls by columns, inside an app or
 // around it.
 const WHEEL_LINES = { scroll_up: -1, scroll_down: 1 };
+// Primary Device Attributes. Every VT100 descendant answers it, and a terminal
+// answers in the order it was asked, so its reply, sent after an ask's queries,
+// says every reply to them that is coming has come.
+const DA1 = "\x1b[c";
+const isDa1Reply = (reply) => reply.kind === "csi" && reply.body.startsWith("?") && reply.body.endsWith("c");
+const DEFAULT_ASK_TIMEOUT = 0.5;
 const isWheelTurn = (event) => event.type in WHEEL_LINES;
 export class App {
     host;
@@ -90,6 +97,15 @@ export class App {
     // its size, its colours, where bytes go. Every frame renders with this
     // console's options and is encoded for its destination.
     console;
+    drawing;
+    // [LAW:single-enforcer] One ask at a time, through the one input reader:
+    // the next waits on the last, and `leave` ends the one in flight.
+    asking = null;
+    asked = Promise.resolve();
+    // DA1 replies still owed to asks that timed out. A terminal answers in the
+    // order it was asked, so every reply before the last of them belongs to an
+    // ask that has ended, and none reaches the ask after it.
+    owedDa1 = 0;
     _phase = "idle";
     _frame = [];
     painter;
@@ -104,7 +120,7 @@ export class App {
     settle = () => { };
     constructor(options) {
         this.host = options.host;
-        this.input = new InputParser({ key: (press) => this.key(press), mouse: (event) => this.mouse(event) }, options.host.inputChunks);
+        this.input = new InputParser({ key: (press) => this.key(press), mouse: (event) => this.mouse(event), reply: (reply) => this.reply(reply) }, options.host.inputChunks);
         this.surface = options.surface;
         this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
         this.view = hostView(options.view);
@@ -113,7 +129,79 @@ export class App {
         this._timeline = options.timeline ?? Timeline.play(this._epoch);
         this._rate = options.rate ?? DEFAULT_RATE;
         this.quitKeys = new Set((options.quitKeys ?? DEFAULT_QUIT_KEYS).map(parseKeyName));
-        this.console = new Console({ ...drawOptions(options), environment: hostEnvironment(options.host) });
+        this.drawing = drawOptions(options);
+        this.console = this.drawingConsole();
+    }
+    /**
+     * The terminal the app draws on: the colours a cell that sets none is drawn
+     * in, and the sixteen an ANSI colour names — as given, or as the colour
+     * depth assumes (`resolveTerminal`).
+     */
+    get terminal() {
+        return resolveTerminal(this.console.options.terminal, this.console.colorSystem ?? ColorDepth.TRUECOLOR);
+    }
+    /** Draw on `terminal` from the next frame on — what `terminalColors` learned, say. */
+    set terminal(terminal) {
+        // [LAW:one-source-of-truth] The console is the one holder of how a frame
+        // draws, so the terminal changes by a new console, not beside the old one.
+        this.drawing = { ...this.drawing, terminal };
+        this.console = this.drawingConsole();
+        this.refresh();
+    }
+    /**
+     * Ask the terminal: write `queries`, then DA1, and resolve with the replies
+     * heard before DA1's, or before the timeout or the app handing the terminal
+     * back. It rejects only when writing to the terminal throws. Asks run one
+     * after another, and only while the app runs: it holds raw mode and reads
+     * the input, so a reply reaches the ask and never a key handler. A reply no
+     * ask is waiting for is dropped. `queries` must not ask for DA1 itself: its
+     * reply would end the ask early.
+     */
+    ask(queries, options = {}) {
+        // An ask before the app runs is a mistake in the program; one after it
+        // stopped ends `left`, so the error that stopped it is the one heard.
+        if (this._phase === "idle")
+            throw new Error("App.ask: an app asks its terminal once it runs, and this one has not started");
+        const timeout = options.timeout ?? DEFAULT_ASK_TIMEOUT;
+        if (!(timeout > 0 && Number.isFinite(timeout)))
+            throw new RangeError(`App.ask: a timeout is a positive, finite number of seconds, not ${timeout}`);
+        const turn = this.asked.then(() => this.askNow(queries, timeout));
+        // One ask's failure is its caller's; the asks queued after it still run.
+        this.asked = turn.catch(() => undefined);
+        return turn;
+    }
+    // The one way the app builds the console it draws with.
+    drawingConsole() {
+        return new Console({ ...this.drawing, environment: hostEnvironment(this.host) });
+    }
+    askNow(queries, timeout) {
+        return new Promise((resolve) => {
+            if (this._phase !== "running")
+                return resolve({ ended: "left", replies: [] });
+            if (!this.host.writesToTerminal)
+                return resolve({ ended: "unasked", replies: [] });
+            // Written before the ask takes the input, so a write that throws leaves
+            // no ask in flight and no timer armed.
+            this.host.write(queries.join("") + DA1);
+            const replies = [];
+            const timer = this._clock.at(this._clock.now() + timeout, () => {
+                this.owedDa1++;
+                asking.finish("timeout");
+            });
+            const asking = {
+                replies,
+                finish: (ended) => {
+                    timer();
+                    this.asking = null;
+                    // [LAW:single-enforcer] Every way an ask ends goes through here, so
+                    // what the parser held for its replies is settled on every one.
+                    this.input.awaitReplies(false);
+                    resolve({ ended, replies });
+                },
+            };
+            this.asking = asking;
+            this.input.awaitReplies(true);
+        });
     }
     get phase() {
         return this._phase;
@@ -153,13 +241,13 @@ export class App {
         return this._frame;
     }
     /**
-     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
-     * clock's now, through the timeline. What a moment heard
+     * The frame this app draws now (`FrameHost`): the clock's now, through the
+     * timeline, on a frame it is the host of. Its time is what a moment heard
      * between frames — a key — is stamped with, so it is on the clock the
      * frame is.
      */
-    get frameTime() {
-        return frameTime(this._time());
+    frameNow() {
+        return frameNow(this, this._time());
     }
     _time() {
         return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline };
@@ -238,6 +326,8 @@ export class App {
             return;
         this._phase = "suspended";
         this.tick();
+        // What is half-read belongs to no one once the terminal is handed back.
+        this.input.reset();
         this.leave();
         await this.host.suspend();
         // Stopped while suspended — by a signal, say: the terminal is already
@@ -306,6 +396,9 @@ export class App {
         this.host.write(POINTER[this.surface].on);
     }
     leave() {
+        this.asking?.finish("left");
+        // Whatever answers the terminal sends from here reach whoever holds it next.
+        this.owedDa1 = 0;
         this.host.write(POINTER[this.surface].off);
         this.painter.handBack();
         this.host.setRawMode(false);
@@ -332,6 +425,18 @@ export class App {
         this.settle(outcome);
     }
     // --- input ---
+    reply(reply) {
+        if (this.owedDa1 > 0) {
+            if (isDa1Reply(reply))
+                this.owedDa1--;
+            return;
+        }
+        if (this.asking === null)
+            return;
+        if (isDa1Reply(reply))
+            return this.asking.finish("answered");
+        this.asking.replies.push(reply);
+    }
     key(press) {
         if (this.quitKeys.has(keyName(press)))
             return this.stop();

package/dist/host/index.d.ts

@@ -2,7 +2,8 @@ export { BrowserTerminalHost } from "./terminal-host.js";
 export type { TerminalHost, TerminalSize, DataHandler, InputChunks, ResizeHandler, ExitHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
-export type { AppMouseEvent, AppOptions, AppPhase, Wheel } from "./app.js";
+export type { AppMouseEvent, AppOptions, AppPhase, Asked, AskOptions, Wheel } from "./app.js";
+export { terminalColors } from "./terminal-colors.js";
 export type { Surface } from "../core/paint.js";
 export { keyName } from "./input.js";
-export type { KeyPress, ScreenMouseEvent } from "./input.js";
+export type { KeyPress, ScreenMouseEvent, TerminalReply } from "./input.js";

package/dist/host/index.js

@@ -1,4 +1,5 @@
 export { BrowserTerminalHost } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
+export { terminalColors } from "./terminal-colors.js";
 export { keyName } from "./input.js";

package/dist/host/input.d.ts

@@ -13,8 +13,9 @@
  * "are we mid-sequence" mode flag — the buffer head carries that state, so on
  * a host whose chunks can split a key, a UTF-8 character or an escape
  * sequence split across two chunks is completed by the second. What a chunk
- * end means is the host's `InputChunks`, the one input to the parser that is
- * not a byte, and it decides only what becomes of an unfinished ESC.
+ * end means is the host's `InputChunks`, and whether an ask awaits a reply is
+ * what its owner last told `awaitReplies`: the two inputs to the parser that
+ * are not bytes, and both decide only what becomes of an unfinished ESC.
  *
  * An unfinished escape sequence is ambiguous: `ESC` alone is the Escape key
  * or the start of a sequence, and `ESC [` is Alt+[ or the start of a CSI.
@@ -29,6 +30,15 @@
  * lone ESC is also settled early by a next chunk that opens with anything but
  * `[` or `O`, because a busy worker can queue the next key behind it.
  * `flush()` settles the hold synchronously.
+ *
+ * `ESC ]`, `ESC P` and `ESC _` open the control strings a terminal replies
+ * in, and are also Alt+], Alt+P and Alt+_. A reply can arrive split only on
+ * a split host while an ask awaits one (`replyMayArrive`), and only then is an
+ * unterminated one, or a lone ESC that may open one, held — past the escape
+ * delay, until `awaitReplies(false)` arms the delay afresh. Otherwise it is Alt
+ * on its key at once. A terminated one is a reply either way, and one cut off
+ * by an ESC that is not ST was never a reply, and is Alt on its key, as with
+ * none awaited.
  */
 import type { InputChunks } from "./terminal-host.js";
 /** A key as the terminal reported it: plain data, with no say over who hears it. */
@@ -61,10 +71,22 @@ interface MouseEventOf<Type extends string> {
  * which already carries it: Shift+G is `G`.
  */
 export declare function keyName(press: KeyPress): string;
+/**
+ * What a terminal sends back when it is asked something: an OSC, DCS or APC
+ * string, its introducer and terminator taken off (`11;rgb:1e1e/1e1e/1e1e`
+ * for an OSC 11 reply), or a CSI report with a private prefix, its final byte
+ * kept (`?62;22c` for DA1, `?2026;2$y` for DECRQM). No key is sent in either
+ * form, so neither is ever read as one.
+ */
+export interface TerminalReply {
+    readonly kind: "osc" | "dcs" | "apc" | "csi";
+    readonly body: string;
+}
 /** Where a parser delivers what it parses. */
 export interface InputSink {
     key(press: KeyPress): void;
     mouse(event: ScreenMouseEvent): void;
+    reply(reply: TerminalReply): void;
 }
 /**
  * `name`, if `keyName` can produce it: modifiers in its order, then a named
@@ -87,11 +109,22 @@ export declare class InputParser {
     private readonly chunks;
     private buffer;
     private escTimer;
+    private awaiting;
     constructor(sink: InputSink, chunks: InputChunks);
     /** Feed a chunk of bytes (or a string of them) into the parser. */
     feed(chunk: Uint8Array | string): void;
     private drainAndHold;
     private hold;
+    /**
+     * Whether an ask is awaiting the terminal's replies, told by whoever asks
+     * at the ask's start and end. Only while one is does an unfinished
+     * `ESC ]`, `ESC P` or `ESC _` open a reply still arriving; otherwise it is
+     * Alt on that key. The wait's end restarts the escape delay for what is
+     * held, on a split host, the only one that holds.
+     */
+    awaitReplies(awaiting: boolean): void;
+    private replyMayArrive;
+    private continuesEscape;
     private settleChunk;
     private drainFully;
     /** Settle a held escape sequence now, as the end of a whole-key chunk. */