@promptctl/rich-js 0.27.0 → 0.29.0

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 { SurfaceRenderer } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.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
+// colors 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
+// host alone decides the console's size, colors 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;
@@ -84,12 +91,21 @@ export class App {
     // What the frame on screen says about when it changes, on the clock.
     // Before a frame, nothing.
     said = undrawn(0);
-    // The one wait for the frame's `nextChange`, armed after each frame.
+    // The one wait for the frame's `validUntil`, armed after each frame.
     waking = 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
+    // its size, its colors, 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,16 +120,88 @@ 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.painter = new SurfaceRenderer(options.surface, (bytes) => this.host.write(bytes));
         this.view = hostView(options.view);
         this._clock = options.clock ?? systemClock();
         this._epoch = this._clock.now();
         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 colors a cell that sets none is drawn
+     * in, and the sixteen an ANSI color names — as given, or as the color
+     * 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;
@@ -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
@@ -258,7 +348,7 @@ export class App {
         return () => this.paintHandlers.delete(handler);
     }
     /**
-     * Hear every key the app does not quit on, by the `KeyPress` the terminal
+     * Hear every key the app does not quit on, by the `KeyEvent` the terminal
      * reported; `keyName` names it. A handler that throws fails the app.
      */
     onKey(handler) {
@@ -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();
@@ -383,8 +488,8 @@ export class App {
     // says whether the view moves.
     tick() {
         const running = this._phase === "running";
-        const { t, nextChange } = this.said;
-        const wanted = running && nextChange === t;
+        const { t, validUntil } = this.said;
+        const wanted = running && validUntil === t;
         if (this.ticking !== null && (!wanted || this.ticking.rate.perSecond !== this._rate.perSecond)) {
             this.ticking.stop();
             this.ticking = null;
@@ -393,7 +498,7 @@ export class App {
             this.ticking = { rate: this._rate, stop: this._clock.every(this._rate, () => this.paint()) };
         }
         this.waking?.();
-        this.waking = running && t < nextChange && nextChange < Number.POSITIVE_INFINITY ? this._clock.at(nextChange, () => this.paint()) : null;
+        this.waking = running && t < validUntil && validUntil < Number.POSITIVE_INFINITY ? this._clock.at(validUntil, () => this.paint()) : 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.

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

@@ -5,10 +5,10 @@
  *
  * [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
+ * what colors 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
+ * 16 colors. 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

package/dist/host/host-environment.js

@@ -5,10 +5,10 @@
  *
  * [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
+ * what colors 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
+ * 16 colors. 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

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, WheelEvent } 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 { KeyEvent, TerminalMouseEvent, 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

@@ -1,6 +1,6 @@
 /**
  * Terminal input: the bytes a terminal sends for keys and the pointer,
- * parsed into `KeyPress` and `ScreenMouseEvent` values, and the one name
+ * parsed into `KeyEvent` and `TerminalMouseEvent` values, and the one name
  * each key goes by.
  *
  * [LAW:single-enforcer] Escape-sequence parsing lives only here. `App` owns
@@ -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,10 +30,19 @@
  * 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. */
-export interface KeyPress {
+export interface KeyEvent {
     readonly key: string;
     /** The printable character the key types, or "" for a key that types none. */
     readonly character: string;
@@ -40,7 +50,7 @@ export interface KeyPress {
     readonly ctrl: boolean;
     readonly meta: boolean;
 }
-export type ScreenMouseEvent = {
+export type TerminalMouseEvent = {
     [T in MouseEventType]: MouseEventOf<T>;
 }[MouseEventType];
 type MouseEventType = "mouse_down" | "mouse_up" | "mouse_move" | "scroll_up" | "scroll_down" | "scroll_left" | "scroll_right";
@@ -60,11 +70,23 @@ interface MouseEventOf<Type extends string> {
  * `ctrl+c`, `shift+tab`, `meta+left`. Shift is not named on a character,
  * which already carries it: Shift+G is `G`.
  */
-export declare function keyName(press: KeyPress): string;
+export declare function keyName(press: KeyEvent): 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;
+    key(press: KeyEvent): void;
+    mouse(event: TerminalMouseEvent): 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;
+    private validity;
+    /**
+     * 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. */

package/dist/host/input.js

@@ -1,6 +1,6 @@
 /**
  * Terminal input: the bytes a terminal sends for keys and the pointer,
- * parsed into `KeyPress` and `ScreenMouseEvent` values, and the one name
+ * parsed into `KeyEvent` and `TerminalMouseEvent` values, and the one name
  * each key goes by.
  *
  * [LAW:single-enforcer] Escape-sequence parsing lives only here. `App` owns
@@ -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.
  */
 /**
  * The one name a key goes by — what a keymap is keyed by and what
@@ -136,6 +146,12 @@ const LANGLE = 0x3c; // <
 const O_BYTE = 0x4f; // O
 const M_UPPER = 0x4d; // M
 const M_LOWER = 0x6d; // m
+const BEL = 0x07;
+const BACKSLASH = 0x5c;
+// The control strings a terminal answers in, by the byte after ESC: OSC, DCS, APC.
+const STRING_REPLIES = { 0x5d: "osc", 0x50: "dcs", 0x5f: "apc" };
+// A CSI whose parameters open with one of these is a report, never a key.
+const PRIVATE_PREFIXES = new Set(["?", ">"]);
 // [LAW:single-enforcer] Shared encode/decode singletons. The parser
 // receives `Uint8Array | string` from the host and walks bytes through
 // its state machine; conversion happens at the two boundaries (string
@@ -198,6 +214,7 @@ export class InputParser {
     // [LAW:types-are-the-program] `setTimeout`/`clearTimeout` are universal
     // across node and browser; `setImmediate` is node-only.
     escTimer;
+    awaiting = false;
     constructor(sink, chunks) {
         this.sink = sink;
         this.chunks = chunks;
@@ -213,7 +230,9 @@ export class InputParser {
         // Any other next chunk means Escape was its own key, even when the hold
         // timer has not run yet: a busy worker can queue the next key ahead of it,
         // and joining them would read Escape then G as Alt+G (rich-host-input-0c4f).
-        const escaped = this.holdingEscape() && next.length > 0 && next[0] !== LBRACKET && next[0] !== O_BYTE;
+        // While a reply is awaited, a next chunk opening one of its control strings
+        // continues it too: a reply split right after its ESC.
+        const escaped = this.holdingEscape() && next.length > 0 && !this.continuesEscape(next[0]);
         this.cancelEscape();
         // The buffer is settled before the sink hears Escape, so a sink that
         // resets the parser on it (an app stopping) leaves nothing to drain.
@@ -231,7 +250,7 @@ export class InputParser {
             this.drainFully();
         }
         finally {
-            this.hold();
+            this.validity();
         }
     }
     // [LAW:no-ambient-temporal-coupling] Whatever drain leaves at an ESC is an
@@ -242,14 +261,41 @@ export class InputParser {
     // timer before it reads input queued behind a long frame, so the delay's end
     // settles the hold only after one more turn of the event loop has read what
     // was waiting. The parser holds one timer, so arming it replaces any other.
-    hold() {
+    // While a reply may arrive the delay settles no hold that may open one: a
+    // reply split over a slow link may take longer than it. The wait's end arms
+    // it afresh (`awaitReplies`), so what is held then gets the whole delay.
+    validity() {
         this.cancelEscape();
         if (this.buffer[0] !== ESC)
             return;
         this.escTimer = setTimeout(() => {
-            this.escTimer = setTimeout(() => this.flush(), 0);
+            this.escTimer = setTimeout(() => {
+                if (!this.replyMayArrive() || !opensString(this.buffer))
+                    this.flush();
+            }, 0);
         }, ESCAPE_DELAY_MS);
     }
+    /**
+     * 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) {
+        this.awaiting = awaiting;
+        if (!awaiting && this.chunks === "split")
+            this.validity();
+    }
+    // [LAW:single-enforcer] The one reading of whether an unfinished control
+    // string may be a reply still arriving: only a split host splits one, and
+    // only an ask awaits one.
+    replyMayArrive() {
+        return this.chunks === "split" && this.awaiting;
+    }
+    continuesEscape(byte) {
+        return byte === LBRACKET || byte === O_BYTE || (STRING_REPLIES[byte] !== undefined && this.replyMayArrive());
+    }
     // A whole-key chunk has ended, so an ESC still at the buffer head opens no
     // sequence, and is read as `reissue` reads it. Each key is taken off the
     // buffer before the sink hears it, so no byte of one chunk outlives it.
@@ -311,6 +357,8 @@ export class InputParser {
                 this.sink.key(result.event);
             else if (result.kind === "mouse")
                 this.sink.mouse(result.event);
+            else if (result.kind === "reply")
+                this.sink.reply(result.event);
             // skip → drop bytes silently
         }
     }
@@ -377,6 +425,15 @@ export class InputParser {
         // ESC [ ... → CSI
         if (b1 === LBRACKET)
             return this.consumeCSI(buf);
+        const string = STRING_REPLIES[b1];
+        if (string !== undefined) {
+            const result = consumeString(buf, string);
+            // Unterminated where no reply may arrive, it was never a reply: Alt on
+            // its key, and what followed is read on its own.
+            if (result.kind === "incomplete" && !this.replyMayArrive())
+                return { kind: "key", bytes: 2, event: altKey(b1) };
+            return result;
+        }
         // ESC O X → SS3 (F1–F4 / arrows on some terms)
         if (b1 === O_BYTE)
             return this.consumeSS3(buf);
@@ -555,7 +612,34 @@ function decodeMouseFromCb(cb, x, y, isPress) {
         ctrl,
     };
 }
+// A lone ESC, or one opening a control string: the holds a reply may be.
+function opensString(buf) {
+    return buf.length === 1 || STRING_REPLIES[buf[1]] !== undefined;
+}
+// A control string runs to its terminator, ST (`ESC \\`) or BEL, and holds
+// any byte but ESC before it. Terminated, it is a reply whether or not one was
+// awaited. Unterminated, it is unfinished, and `consumeEscape` decides by
+// whether a reply may arrive if that means held or Alt on its key. An ESC that
+// is not ST ends it before it closed: it was never a reply, so it is Alt on
+// its key and what followed is read on its own, as with none awaited.
+function consumeString(buf, kind) {
+    for (let i = 2; i < buf.length; i++) {
+        const b = buf[i];
+        if (b === BEL)
+            return { kind: "reply", bytes: i + 1, event: { kind, body: UTF8_DECODER.decode(buf.subarray(2, i)) } };
+        if (b !== ESC)
+            continue;
+        if (i + 1 === buf.length)
+            return { kind: "incomplete" };
+        if (buf[i + 1] !== BACKSLASH)
+            return { kind: "key", bytes: 2, event: altKey(buf[1]) };
+        return { kind: "reply", bytes: i + 2, event: { kind, body: UTF8_DECODER.decode(buf.subarray(2, i)) } };
+    }
+    return { kind: "incomplete" };
+}
 function decodeCSI(params, final, bytes) {
+    if (PRIVATE_PREFIXES.has(params[0] ?? ""))
+        return { kind: "reply", bytes, event: { kind: "csi", body: params + final } };
     // Handle modifier suffixes like `1;2A` (shift+up). We split params on `;`.
     const parts = params.split(";");
     const first = parts[0] ?? "";

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

@@ -0,0 +1,18 @@
+/**
+ * The terminal's own foreground and background, asked of it with OSC 10 and
+ * OSC 11 — the colors every contrast decision is measured against, which the
+ * library otherwise has to assume.
+ *
+ * [LAW:effects-at-boundaries] The ask is `App`'s, the one reader of its
+ * terminal's input; what is here is the query bytes and the parse of their
+ * replies, which stays pure.
+ */
+import { TerminalColors } from "../core/color.js";
+import type { App } from "./app.js";
+/**
+ * Ask the terminal `app` runs on for its foreground and background, and return
+ * the terminal `app` draws on with them in place — its sixteen ANSI colors
+ * kept, since nothing asks for those. `undefined` when the terminal did not
+ * answer both, so the caller keeps what it had. Set it as `app.terminal`.
+ */
+export declare function terminalColors(app: App): Promise<TerminalColors | undefined>;

package/dist/host/terminal-colors.js

@@ -0,0 +1,46 @@
+/**
+ * The terminal's own foreground and background, asked of it with OSC 10 and
+ * OSC 11 — the colors every contrast decision is measured against, which the
+ * library otherwise has to assume.
+ *
+ * [LAW:effects-at-boundaries] The ask is `App`'s, the one reader of its
+ * terminal's input; what is here is the query bytes and the parse of their
+ * replies, which stays pure.
+ */
+import { ColorRgba, TerminalColors } from "../core/color.js";
+import { pattern } from "../core/pattern.js";
+// OSC 10 and OSC 11 with `?` ask for the dynamic foreground and background.
+const QUERIES = ["\x1b]10;?\x1b\\", "\x1b]11;?\x1b\\"];
+// XParseColor's `rgb:` form, 1–4 hex digits a channel, as xterm and every
+// terminal that copies it answers, or `rgba:`, as urxvt answers with
+// transparency on; the alpha says nothing about the color a cell is drawn in.
+const RGB = pattern(/^rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})(?:\/[0-9a-f]{1,4})?$/i);
+// A channel of n hex digits is a fraction of 16ⁿ − 1, scaled to 8 bits.
+const channel = (hex) => Math.round((parseInt(hex, 16) / (16 ** hex.length - 1)) * 255);
+/**
+ * The color an OSC 10 or OSC 11 reply reports, or `undefined` when `reply`
+ * is not that answer to `slot`.
+ */
+function parseColorReply(reply, slot) {
+    if (reply.kind !== "osc")
+        return undefined;
+    const prefix = `${slot};`;
+    if (!reply.body.startsWith(prefix))
+        return undefined;
+    const match = RGB.exec(reply.body.slice(prefix.length));
+    return match === null ? undefined : new ColorRgba(channel(match[1]), channel(match[2]), channel(match[3]));
+}
+/**
+ * Ask the terminal `app` runs on for its foreground and background, and return
+ * the terminal `app` draws on with them in place — its sixteen ANSI colors
+ * kept, since nothing asks for those. `undefined` when the terminal did not
+ * answer both, so the caller keeps what it had. Set it as `app.terminal`.
+ */
+export async function terminalColors(app) {
+    const { replies } = await app.ask(QUERIES);
+    const foreground = replies.map((reply) => parseColorReply(reply, 10)).find((color) => color !== undefined);
+    const background = replies.map((reply) => parseColorReply(reply, 11)).find((color) => color !== undefined);
+    if (foreground === undefined || background === undefined)
+        return undefined;
+    return new TerminalColors(background, foreground, app.terminal.ansiColors);
+}

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

@@ -69,7 +69,8 @@ export interface TerminalHost {
     onData(handler: DataHandler): Unsubscribe;
     /**
      * Where `onData`'s chunks may end. The parser holds an unfinished escape
-     * sequence open for its rest, for the escape delay, only on a host whose
+     * sequence open for its rest — for the escape delay, or a control string
+     * for as long as an ask awaits its reply — only on a host whose
      * chunks can split one; a whole-keys host settles each chunk as it arrives,
      * because a busy worker there reads a queued next key before any timer
      * runs (rich-host-input-ab9n).
@@ -95,13 +96,13 @@ export interface TerminalHost {
     readonly isTTY: boolean;
     /**
      * Whether the bytes `write` sends land on a terminal, whatever the input
-     * is. Colour detection asks this: a program with piped stdin and a terminal
+     * is. Color detection asks this: a program with piped stdin and a terminal
      * stdout still draws on a terminal, and `isTTY` would call it plain.
      */
     readonly writesToTerminal: boolean;
     /**
      * The environment a program running on this terminal sees — `TERM`,
-     * `COLORTERM`, `NO_COLOR` and the rest. Colour detection reads it: what a
+     * `COLORTERM`, `NO_COLOR` and the rest. Color detection reads it: what a
      * terminal can draw is a fact about the host, so it travels with the host
      * rather than being read off whatever `process` the renderer happens to
      * share a runtime with, which in a browser is none.

package/dist/host/terminal-host.js

@@ -64,7 +64,7 @@ export class BrowserTerminalHost {
     }
     // What xterm.js is, stated the way a terminal states it: it identifies as
     // `xterm-256color` and draws 24-bit SGR. With no env at all, detection saw
-    // an unnamed TTY and drew every colour at 16-colour depth.
+    // an unnamed TTY and drew every color at 16-color depth.
     get env() {
         return XTERM_ENV;
     }