@textui/terminal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Softov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @textui/terminal
+
+What [`@textui/core`](https://github.com/softov/textui/tree/main/packages/core) needs to reach an actual terminal: adapters,
+capability detection, ANSI writing and input decoding.
+
+```bash
+npm install @textui/terminal
+```
+
+```ts
+import { createApp } from '@textui/core';
+import { createNodeTerminal } from '@textui/terminal';
+
+const app = createApp({ terminal: createNodeTerminal(), root: <App /> });
+await app.start();
+```
+
+## Two adapters
+
+`createNodeTerminal()` is the real one - stdin, stdout, resize, and the signal
+handling that puts the screen back the way it found it when the process dies.
+
+`createVirtualTerminal()` has no tty at all. It is what the test harness and
+`--static` run on, and it is the reason a component that only works
+interactively is a component nobody can test cheaply.
+
+## Capabilities are detected, and can be lied to
+
+Unicode level, colour depth, mouse, hyperlinks, the kitty keyboard protocol -
+detection is right almost always, and the times it is not are the times nobody
+is watching. So every capability can be forced, which is how you see the
+terminal somebody else is sitting at:
+
+```ts
+createNodeTerminal({ capabilities: { unicode: 'ascii', colors: 4 } });
+```
+
+Under the kitty protocol, `ctrl+shift+f` is a distinct stroke from `ctrl+f`.
+Without it the terminal sends the same byte for both, and no amount of decoding
+recovers the difference.
+
+## A frame you can keep
+
+The screen is the output, so the next redraw destroys the frame that was wrong.
+Two functions write one out instead - both from the buffer the runtime last
+painted, neither needing a tty.
+
+`captureBuffer` gives a frame a terminal can replay: every cell in order, no
+cursor control, so it can go in a file or an issue. `colors: false` strips the
+colour, which is the copy a diff can read.
+
+`bufferToSvg` gives one a repository page can show, because an `.ans` file is
+only a screenshot on a terminal:
+
+```ts
+const svg = bufferToSvg(app.buffer(), {
+  background: app.theme.colors.canvas,
+  foreground: app.theme.colors.text,
+});
+```
+
+Self-contained - no font, no stylesheet, no script, nothing fetched - which is
+what survives GitHub's image proxy. And it is text, so a committed screenshot
+diffs and CI can check it instead of somebody re-taking it.
+
+## What it needs from a stream
+
+`TerminalInput` and `TerminalOutput`, which say what the adapter uses rather
+than which stream it is - `setRawMode`, `columns`, `write`, and half a dozen
+more. `process.stdin` and `process.stdout` satisfy them, so nothing changes for
+a caller, and so do the streams of runtimes that are not node.
+
+That is also why the published types name no Node interfaces: a package with no
+dependencies should not need `@types/node` installed to compile.
+
+## Runtime
+
+No dependencies beyond `@textui/core`. Uses `process` for stdio and signals, and
+no other Node API. Node 22+ and Bun.
+
+## Documentation
+
+<https://softov.github.io/textui/>

package/dist/ansi.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ANSI escape sequences.
+ *
+ * Everything the writer can emit is named here, so a capability check happens
+ * once - at the adapter - rather than scattered through the render path.
+ * Sequences are written with `\x1b` escapes rather than literal bytes so this
+ * file stays readable in a diff.
+ */
+export declare const ESC = "\u001B";
+export declare const CSI = "\u001B[";
+export declare const OSC = "\u001B]";
+export declare const ST = "\u001B\\";
+export declare const BEL = "\u0007";
+export declare const cursorTo: (x: number, y: number) => string;
+export declare const cursorHome = "\u001B[H";
+export declare const cursorHide = "\u001B[?25l";
+export declare const cursorShow = "\u001B[?25h";
+export declare const cursorSave = "\u001B7";
+export declare const cursorRestore = "\u001B8";
+export declare const cursorUp: (n?: number) => string;
+export declare const cursorDown: (n?: number) => string;
+export declare const cursorForward: (n?: number) => string;
+export declare const cursorBack: (n?: number) => string;
+export declare const cursorColumn: (x: number) => string;
+/** Cursor shapes, for a text field that wants a bar rather than a block. */
+export declare const cursorShape: (shape: "block" | "underline" | "bar", blinking?: boolean) => string;
+export declare const eraseLine = "\u001B[2K";
+export declare const eraseLineRight = "\u001B[0K";
+export declare const eraseScreen = "\u001B[2J";
+export declare const eraseDown = "\u001B[0J";
+export declare const scrollUp: (n?: number) => string;
+export declare const altScreenEnter = "\u001B[?1049h";
+export declare const altScreenLeave = "\u001B[?1049l";
+export declare const bracketedPasteOn = "\u001B[?2004h";
+export declare const bracketedPasteOff = "\u001B[?2004l";
+export declare const focusEventsOn = "\u001B[?1004h";
+export declare const focusEventsOff = "\u001B[?1004l";
+/** SGR mouse reporting: any-event tracking plus extended coordinates. */
+export declare const mouseOn = "\u001B[?1000h\u001B[?1002h\u001B[?1003h\u001B[?1006h";
+export declare const mouseOff = "\u001B[?1006l\u001B[?1003l\u001B[?1002l\u001B[?1000l";
+/** Click and drag only - no motion events, which are noisy over ssh. */
+export declare const mouseButtonsOn = "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
+export declare const mouseButtonsOff = "\u001B[?1006l\u001B[?1002l\u001B[?1000l";
+/** DEC 2026: draw the whole frame before showing any of it. */
+export declare const syncStart = "\u001B[?2026h";
+export declare const syncEnd = "\u001B[?2026l";
+/** Kitty keyboard protocol - disambiguates ctrl+i from tab, and so on. */
+export declare const kittyKeyboardPush = "\u001B[>1u";
+export declare const kittyKeyboardPop = "\u001B[<u";
+export declare const wrapOff = "\u001B[?7l";
+export declare const wrapOn = "\u001B[?7h";
+export declare const queryDeviceAttributes = "\u001B[c";
+export declare const queryCursorPosition = "\u001B[6n";
+/** XTGETTCAP for truecolor support. */
+export declare const queryTruecolor = "\u001BP+q524742\u001B\\";
+export declare const querySync = "\u001B[?2026$p";
+export declare const setTitle: (title: string) => string;
+export declare const link: (url: string, text: string) => string;
+export declare const linkOpen: (url: string) => string;
+export declare const linkClose = "\u001B]8;;\u001B\\";
+/** OSC 52: put text on the system clipboard, base64-encoded. */
+export declare const clipboardWrite: (text: string) => string;
+export declare const reset = "\u001B[0m";
+export declare const SGR: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 3;
+    readonly underline: 4;
+    readonly blink: 5;
+    readonly inverse: 7;
+    readonly hidden: 8;
+    readonly strike: 9;
+    readonly noBold: 22;
+    readonly noItalic: 23;
+    readonly noUnderline: 24;
+    readonly noBlink: 25;
+    readonly noInverse: 27;
+    readonly noHidden: 28;
+    readonly noStrike: 29;
+    readonly fgDefault: 39;
+    readonly bgDefault: 49;
+};
+//# sourceMappingURL=ansi.d.ts.map

package/dist/ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../src/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,WAAS,CAAC;AAC1B,eAAO,MAAM,GAAG,YAAU,CAAC;AAC3B,eAAO,MAAM,GAAG,YAAU,CAAC;AAC3B,eAAO,MAAM,EAAE,aAAW,CAAC;AAC3B,eAAO,MAAM,GAAG,WAAS,CAAC;AAG1B,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAAoC,CAAC;AACrF,eAAO,MAAM,UAAU,aAAY,CAAC;AACpC,eAAO,MAAM,UAAU,gBAAe,CAAC;AACvC,eAAO,MAAM,UAAU,gBAAe,CAAC;AACvC,eAAO,MAAM,UAAU,YAAY,CAAC;AACpC,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,QAAQ,GAAI,UAAK,KAAG,MAAuB,CAAC;AACzD,eAAO,MAAM,UAAU,GAAI,UAAK,KAAG,MAAuB,CAAC;AAC3D,eAAO,MAAM,aAAa,GAAI,UAAK,KAAG,MAAuB,CAAC;AAC9D,eAAO,MAAM,UAAU,GAAI,UAAK,KAAG,MAAuB,CAAC;AAC3D,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,MAA2B,CAAC;AAErE,4EAA4E;AAC5E,eAAO,MAAM,WAAW,GACtB,OAAO,OAAO,GAAG,WAAW,GAAG,KAAK,EACpC,kBAAe,KACd,MAGF,CAAC;AAGF,eAAO,MAAM,SAAS,cAAa,CAAC;AACpC,eAAO,MAAM,cAAc,cAAa,CAAC;AACzC,eAAO,MAAM,WAAW,cAAa,CAAC;AACtC,eAAO,MAAM,SAAS,cAAa,CAAC;AACpC,eAAO,MAAM,QAAQ,GAAI,UAAK,KAAG,MAAuB,CAAC;AAGzD,eAAO,MAAM,cAAc,kBAAiB,CAAC;AAC7C,eAAO,MAAM,cAAc,kBAAiB,CAAC;AAC7C,eAAO,MAAM,gBAAgB,kBAAiB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,kBAAiB,CAAC;AAChD,eAAO,MAAM,aAAa,kBAAiB,CAAC;AAC5C,eAAO,MAAM,cAAc,kBAAiB,CAAC;AAE7C,yEAAyE;AACzE,eAAO,MAAM,OAAO,yDAAqD,CAAC;AAC1E,eAAO,MAAM,QAAQ,yDAAqD,CAAC;AAC3E,wEAAwE;AACxE,eAAO,MAAM,cAAc,4CAAyC,CAAC;AACrE,eAAO,MAAM,eAAe,4CAAyC,CAAC;AAEtE,+DAA+D;AAC/D,eAAO,MAAM,SAAS,kBAAiB,CAAC;AACxC,eAAO,MAAM,OAAO,kBAAiB,CAAC;AAEtC,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,eAAc,CAAC;AAC7C,eAAO,MAAM,gBAAgB,cAAa,CAAC;AAE3C,eAAO,MAAM,OAAO,eAAc,CAAC;AACnC,eAAO,MAAM,MAAM,eAAc,CAAC;AAGlC,eAAO,MAAM,qBAAqB,aAAY,CAAC;AAC/C,eAAO,MAAM,mBAAmB,cAAa,CAAC;AAC9C,uCAAuC;AACvC,eAAO,MAAM,cAAc,4BAA4B,CAAC;AACxD,eAAO,MAAM,SAAS,mBAAkB,CAAC;AAGzC,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,KAAG,MAA+C,CAAC;AACzF,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,KAAG,MACS,CAAC;AAC3D,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAA6C,CAAC;AACrF,eAAO,MAAM,SAAS,uBAAmB,CAAC;AAE1C,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAK7C,CAAC;AASF,eAAO,MAAM,KAAK,cAAa,CAAC;AAEhC,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;CAmBN,CAAC"}

package/dist/ansi.js

@@ -0,0 +1,102 @@
+/**
+ * ANSI escape sequences.
+ *
+ * Everything the writer can emit is named here, so a capability check happens
+ * once - at the adapter - rather than scattered through the render path.
+ * Sequences are written with `\x1b` escapes rather than literal bytes so this
+ * file stays readable in a diff.
+ */
+export const ESC = '\x1b';
+export const CSI = '\x1b[';
+export const OSC = '\x1b]';
+export const ST = '\x1b\\';
+export const BEL = '\x07';
+// --- cursor ---
+export const cursorTo = (x, y) => `${CSI}${y + 1};${x + 1}H`;
+export const cursorHome = `${CSI}H`;
+export const cursorHide = `${CSI}?25l`;
+export const cursorShow = `${CSI}?25h`;
+export const cursorSave = `${ESC}7`;
+export const cursorRestore = `${ESC}8`;
+export const cursorUp = (n = 1) => `${CSI}${n}A`;
+export const cursorDown = (n = 1) => `${CSI}${n}B`;
+export const cursorForward = (n = 1) => `${CSI}${n}C`;
+export const cursorBack = (n = 1) => `${CSI}${n}D`;
+export const cursorColumn = (x) => `${CSI}${x + 1}G`;
+/** Cursor shapes, for a text field that wants a bar rather than a block. */
+export const cursorShape = (shape, blinking = true) => {
+    const base = shape === 'block' ? 1 : shape === 'underline' ? 3 : 5;
+    return `${CSI}${blinking ? base : base + 1} q`;
+};
+// --- erasing ---
+export const eraseLine = `${CSI}2K`;
+export const eraseLineRight = `${CSI}0K`;
+export const eraseScreen = `${CSI}2J`;
+export const eraseDown = `${CSI}0J`;
+export const scrollUp = (n = 1) => `${CSI}${n}S`;
+// --- modes ---
+export const altScreenEnter = `${CSI}?1049h`;
+export const altScreenLeave = `${CSI}?1049l`;
+export const bracketedPasteOn = `${CSI}?2004h`;
+export const bracketedPasteOff = `${CSI}?2004l`;
+export const focusEventsOn = `${CSI}?1004h`;
+export const focusEventsOff = `${CSI}?1004l`;
+/** SGR mouse reporting: any-event tracking plus extended coordinates. */
+export const mouseOn = `${CSI}?1000h${CSI}?1002h${CSI}?1003h${CSI}?1006h`;
+export const mouseOff = `${CSI}?1006l${CSI}?1003l${CSI}?1002l${CSI}?1000l`;
+/** Click and drag only - no motion events, which are noisy over ssh. */
+export const mouseButtonsOn = `${CSI}?1000h${CSI}?1002h${CSI}?1006h`;
+export const mouseButtonsOff = `${CSI}?1006l${CSI}?1002l${CSI}?1000l`;
+/** DEC 2026: draw the whole frame before showing any of it. */
+export const syncStart = `${CSI}?2026h`;
+export const syncEnd = `${CSI}?2026l`;
+/** Kitty keyboard protocol - disambiguates ctrl+i from tab, and so on. */
+export const kittyKeyboardPush = `${CSI}>1u`;
+export const kittyKeyboardPop = `${CSI}<u`;
+export const wrapOff = `${CSI}?7l`;
+export const wrapOn = `${CSI}?7h`;
+// --- queries ---
+export const queryDeviceAttributes = `${CSI}c`;
+export const queryCursorPosition = `${CSI}6n`;
+/** XTGETTCAP for truecolor support. */
+export const queryTruecolor = `${ESC}P+q524742${ESC}\\`;
+export const querySync = `${CSI}?2026$p`;
+// --- osc ---
+export const setTitle = (title) => `${OSC}0;${sanitizeOsc(title)}${BEL}`;
+export const link = (url, text) => `${OSC}8;;${sanitizeOsc(url)}${ST}${text}${OSC}8;;${ST}`;
+export const linkOpen = (url) => `${OSC}8;;${sanitizeOsc(url)}${ST}`;
+export const linkClose = `${OSC}8;;${ST}`;
+/** OSC 52: put text on the system clipboard, base64-encoded. */
+export const clipboardWrite = (text) => {
+    const b64 = typeof globalThis.btoa === 'function'
+        ? globalThis.btoa(unescape(encodeURIComponent(text)))
+        : Buffer.from(text, 'utf8').toString('base64');
+    return `${OSC}52;c;${b64}${BEL}`;
+};
+/** A string inside an OSC must not contain a terminator of its own. */
+function sanitizeOsc(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/[\x00-\x1f\x7f]/g, '');
+}
+// --- SGR ---
+export const reset = `${CSI}0m`;
+export const SGR = {
+    reset: 0,
+    bold: 1,
+    dim: 2,
+    italic: 3,
+    underline: 4,
+    blink: 5,
+    inverse: 7,
+    hidden: 8,
+    strike: 9,
+    noBold: 22,
+    noItalic: 23,
+    noUnderline: 24,
+    noBlink: 25,
+    noInverse: 27,
+    noHidden: 28,
+    noStrike: 29,
+    fgDefault: 39,
+    bgDefault: 49,
+};

package/dist/capabilities.d.ts

@@ -0,0 +1,22 @@
+import type { CapabilityOverrides, TerminalCapabilities, ColorDepth, UnicodeLevel } from '@textui/core';
+export interface DetectionInput {
+    env: Record<string, string | undefined>;
+    isTTY: boolean;
+    columns?: number;
+    rows?: number;
+    platform?: string;
+}
+/**
+ * Capability detection.
+ *
+ * Detection is best-effort and deliberately conservative: claiming a
+ * capability the terminal lacks corrupts the frame, while missing one only
+ * costs polish. Anything detection cannot settle, an adapter override can.
+ */
+export declare function detectColorDepth(env: Record<string, string | undefined>, isTTY: boolean): ColorDepth;
+export declare function detectUnicode(env: Record<string, string | undefined>): UnicodeLevel;
+export declare function detectCapabilities(input: DetectionInput): TerminalCapabilities;
+export declare function applyOverrides(base: TerminalCapabilities, overrides: CapabilityOverrides | undefined): TerminalCapabilities;
+/** Describe the environment, for `textui doctor` and the inspector. */
+export declare function describeEnvironment(input: DetectionInput): Record<string, string>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGxG,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,CA4BpG;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,YAAY,CAYnF;AAWD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,oBAAoB,CA8C9E;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,oBAAoB,EAC1B,SAAS,EAAE,mBAAmB,GAAG,SAAS,GACzC,oBAAoB,CAEtB;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYjF"}

package/dist/capabilities.js

@@ -0,0 +1,130 @@
+import { MINIMAL_CAPABILITIES } from '@textui/core';
+/**
+ * Capability detection.
+ *
+ * Detection is best-effort and deliberately conservative: claiming a
+ * capability the terminal lacks corrupts the frame, while missing one only
+ * costs polish. Anything detection cannot settle, an adapter override can.
+ */
+export function detectColorDepth(env, isTTY) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return 0;
+    if (env.FORCE_COLOR !== undefined) {
+        const level = Number.parseInt(env.FORCE_COLOR, 10);
+        if (env.FORCE_COLOR === 'true')
+            return 24;
+        if (level === 0)
+            return 0;
+        if (level === 1)
+            return 4;
+        if (level === 2)
+            return 8;
+        if (level >= 3)
+            return 24;
+    }
+    if (!isTTY)
+        return 0;
+    const term = env.TERM ?? '';
+    if (term === 'dumb')
+        return 0;
+    const colorterm = (env.COLORTERM ?? '').toLowerCase();
+    if (colorterm === 'truecolor' || colorterm === '24bit')
+        return 24;
+    const program = env.TERM_PROGRAM ?? '';
+    if (['iTerm.app', 'WezTerm', 'vscode', 'Hyper', 'ghostty'].includes(program))
+        return 24;
+    if (env.WT_SESSION)
+        return 24;
+    if (env.KITTY_WINDOW_ID)
+        return 24;
+    if (env.ALACRITTY_LOG || term.startsWith('alacritty'))
+        return 24;
+    if (term.includes('256'))
+        return 8;
+    if (term.includes('color') || term.startsWith('xterm') || term.startsWith('screen'))
+        return 4;
+    if (term === '')
+        return 0;
+    return 4;
+}
+export function detectUnicode(env) {
+    const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG ?? '';
+    if (!/utf-?8/i.test(locale)) {
+        // Windows Terminal and modern macOS terminals are UTF-8 without saying so.
+        if (env.WT_SESSION || env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'Apple_Terminal') {
+            return 'full';
+        }
+        return 'ascii';
+    }
+    const term = env.TERM ?? '';
+    if (term === 'linux')
+        return 'bmp';
+    return 'full';
+}
+/**
+ * Some terminals report a TERM their multiplexer chose. tmux and screen pass
+ * most sequences through but swallow a few, so they are treated as capable
+ * with the known gaps closed.
+ */
+function inMultiplexer(env) {
+    return Boolean(env.TMUX) || (env.TERM ?? '').startsWith('screen');
+}
+export function detectCapabilities(input) {
+    const { env, isTTY } = input;
+    const term = env.TERM ?? '';
+    if (!isTTY || term === 'dumb') {
+        return { ...MINIMAL_CAPABILITIES, colorDepth: detectColorDepth(env, isTTY) };
+    }
+    const colorDepth = detectColorDepth(env, isTTY);
+    const unicode = detectUnicode(env);
+    const mux = inMultiplexer(env);
+    const program = env.TERM_PROGRAM ?? '';
+    // Terminals that speak the kitty keyboard protocol, which is what makes
+    // `ctrl+enter` a different key from `enter` rather than the same byte.
+    //
+    // VS Code belongs here: its terminal is xterm.js, which has implemented the
+    // protocol since 6.1, and `terminal.integrated.enableKittyKeyboardProtocol`
+    // defaults to on. Without it in this list nothing ever pushes `CSI > 1 u`,
+    // so the terminal keeps sending legacy codes and every modified enter,
+    // tab and escape arrives as its unmodified twin.
+    const kitty = Boolean(env.KITTY_WINDOW_ID) || program === 'WezTerm'
+        || program === 'ghostty' || program === 'vscode';
+    const modern = kitty || program === 'iTerm.app' || Boolean(env.WT_SESSION) ||
+        term.startsWith('alacritty') || program === 'vscode';
+    return {
+        colorDepth,
+        unicode,
+        wideChars: unicode !== 'ascii',
+        mouse: true,
+        wheel: true,
+        focusEvents: true,
+        paste: true,
+        // tmux rewrites OSC 8, and Apple Terminal ignores it.
+        hyperlinks: modern && !mux && program !== 'Apple_Terminal',
+        clipboard: modern || mux,
+        altScreen: true,
+        cursor: true,
+        // Synchronized output is safe when supported and harmless when not, but
+        // tmux below 3.4 mangles it, so it is off inside a multiplexer.
+        synchronizedOutput: modern && !mux,
+        title: true,
+        kittyKeyboard: kitty && !mux,
+    };
+}
+export function applyOverrides(base, overrides) {
+    return overrides ? { ...base, ...overrides } : base;
+}
+/** Describe the environment, for `textui doctor` and the inspector. */
+export function describeEnvironment(input) {
+    const { env } = input;
+    return {
+        TERM: env.TERM ?? '(unset)',
+        COLORTERM: env.COLORTERM ?? '(unset)',
+        TERM_PROGRAM: env.TERM_PROGRAM ?? '(unset)',
+        LANG: env.LC_ALL ?? env.LANG ?? '(unset)',
+        multiplexer: env.TMUX ? 'tmux' : (env.TERM ?? '').startsWith('screen') ? 'screen' : 'none',
+        ssh: env.SSH_TTY || env.SSH_CONNECTION ? 'yes' : 'no',
+        tty: String(input.isTTY),
+        size: `${input.columns ?? '?'}x${input.rows ?? '?'}`,
+    };
+}

package/dist/capture.d.ts

@@ -0,0 +1,24 @@
+import type { CellBuffer, ColorDepth, TerminalCapabilities } from '@textui/core';
+/**
+ * A frame, as a string you can keep.
+ *
+ * This is not what `Writer` does. The writer's job is to get from the frame on
+ * screen to the next one in as few bytes as it can, so what it emits is cursor
+ * moves and the differences between them - correct on a live terminal and
+ * meaningless in a file. A capture is the opposite: every cell, in order, rows
+ * separated by newlines and no cursor control at all, so it can be written to
+ * a file, piped, pasted into a bug report, or `cat`ed back with nothing else
+ * on screen having to be true.
+ *
+ * A terminal application cannot show you what it looked like when it went
+ * wrong - the screen is the output, and the next redraw destroys the evidence.
+ * This is how it hands you the evidence instead.
+ */
+export interface CaptureOptions {
+    /** Emit SGR colour. Off gives plain text, which is what a diff can read. */
+    colors?: boolean;
+    /** Reduce colour to this depth. Defaults to what the terminal reported. */
+    colorDepth?: ColorDepth;
+}
+export declare function captureBuffer(buffer: CellBuffer, capabilities: TerminalCapabilities, options?: CaptureOptions): string;
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAKjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,oBAAoB,EAClC,OAAO,GAAE,cAAmB,GAC3B,MAAM,CAgER"}

package/dist/capture.js

@@ -0,0 +1,72 @@
+import { COLOR_DEFAULT, packColor } from '@textui/core';
+import { ATTR_ON, bgSequence, fgSequence } from './writer.js';
+import * as ansi from './ansi.js';
+export function captureBuffer(buffer, capabilities, options = {}) {
+    const depth = options.colorDepth ?? capabilities.colorDepth;
+    const colors = (options.colors ?? true) && depth > 0;
+    const rows = [];
+    for (let y = 0; y < buffer.height; y++) {
+        let row = '';
+        let fg = COLOR_DEFAULT;
+        let bg = COLOR_DEFAULT;
+        let attrs = 0;
+        // Where the row last stopped being blank. A run of default-styled spaces
+        // at the end is trailing whitespace; the same run with a background is a
+        // part of the picture, so only the first kind is trimmed.
+        let end = 0;
+        let plain = '';
+        for (let x = 0; x < buffer.width; x++) {
+            const cell = buffer.get(x, y);
+            if (!cell || cell.continuation === true)
+                continue;
+            const cellFg = packColor(cell.fg);
+            const cellBg = packColor(cell.bg);
+            const cellAttrs = cell.attrs;
+            if (colors && (cellFg !== fg || cellBg !== bg || cellAttrs !== attrs)) {
+                const codes = [];
+                // One reset and a restatement, rather than eight ways to turn things
+                // off - the same trade the writer makes, for the same reason.
+                if ((attrs & ~cellAttrs) !== 0) {
+                    codes.push(ansi.SGR.reset);
+                    fg = COLOR_DEFAULT;
+                    bg = COLOR_DEFAULT;
+                    attrs = 0;
+                }
+                for (const [bit, code] of ATTR_ON) {
+                    if (cellAttrs & bit & ~attrs)
+                        codes.push(code);
+                }
+                if (cellFg !== fg)
+                    codes.push(fgSequence(cellFg, depth));
+                if (cellBg !== bg)
+                    codes.push(bgSequence(cellBg, depth));
+                if (codes.length > 0)
+                    row += `${ansi.CSI}${codes.join(';')}m`;
+                fg = cellFg;
+                bg = cellBg;
+                attrs = cellAttrs;
+            }
+            row += cell.char;
+            plain += cell.char;
+            if (cell.char !== ' ' || cellBg !== COLOR_DEFAULT || cellAttrs !== 0)
+                end = plain.length;
+        }
+        const styled = colors && (fg !== COLOR_DEFAULT || bg !== COLOR_DEFAULT || attrs !== 0);
+        if (end < plain.length) {
+            // Nothing after the last real cell, so drop it - and reset first, or the
+            // last colour bleeds to the edge of whatever terminal shows this.
+            row = trimTail(row, plain.length - end);
+            if (styled)
+                row += `${ansi.CSI}${ansi.SGR.reset}m`;
+        }
+        else if (styled) {
+            row += `${ansi.CSI}${ansi.SGR.reset}m`;
+        }
+        rows.push(row);
+    }
+    return rows.join('\n');
+}
+/** Drop `count` characters from the end, which are known to be plain spaces. */
+function trimTail(row, count) {
+    return count <= 0 ? row : row.slice(0, row.length - count);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * as ansi from './ansi.js';
+export { Writer, createWriter } from './writer.js';
+export { captureBuffer } from './capture.js';
+export type { CaptureOptions } from './capture.js';
+export { bufferToSvg } from './svg.js';
+export type { SvgOptions } from './svg.js';
+export { detectCapabilities, detectColorDepth, detectUnicode, applyOverrides, describeEnvironment, } from './capabilities.js';
+export type { DetectionInput } from './capabilities.js';
+export { InputDecoder, createDecoder } from './input.js';
+export type { DecoderOptions } from './input.js';
+export { NodeTerminalAdapter, createNodeTerminal } from './node.js';
+export type { NodeAdapterOptions, TerminalInput, TerminalOutput, TerminalSignal } from './node.js';
+export { VirtualTerminalAdapter, createVirtualTerminal } from './virtual.js';
+export type { VirtualAdapterOptions } from './virtual.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EACL,kBAAkB,EAAE,gBAAgB,EAAE,aAAa,EACnD,cAAc,EAAE,mBAAmB,GACpC,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACzD,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACnG,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * as ansi from './ansi.js';
+export { Writer, createWriter } from './writer.js';
+export { captureBuffer } from './capture.js';
+export { bufferToSvg } from './svg.js';
+export { detectCapabilities, detectColorDepth, detectUnicode, applyOverrides, describeEnvironment, } from './capabilities.js';
+export { InputDecoder, createDecoder } from './input.js';
+export { NodeTerminalAdapter, createNodeTerminal } from './node.js';
+export { VirtualTerminalAdapter, createVirtualTerminal } from './virtual.js';

package/dist/input.d.ts

@@ -0,0 +1,28 @@
+import type { InputEvent } from '@textui/core';
+export interface DecoderOptions {
+    /** How long to wait before a lone ESC is reported as the escape key. */
+    escapeTimeoutMs?: number;
+}
+export declare class InputDecoder {
+    private emit;
+    private options;
+    private carry;
+    private pasting;
+    private pasteBuffer;
+    private escapeTimer;
+    constructor(emit: (event: InputEvent) => void, options?: DecoderOptions);
+    /** Feed raw input. Emits zero or more events. */
+    feed(chunk: string): void;
+    private clearEscapeTimer;
+    /** Consume one event's worth of bytes. Returns how many were used. */
+    private step;
+    private stepPlain;
+    private stepPaste;
+    /** `ESC O P` - the application-cursor form of F1..F4 and the arrows. */
+    private stepSs3;
+    private stepCsi;
+    /** Drop any half-read sequence. After releasing the terminal. */
+    reset(): void;
+}
+export declare function createDecoder(emit: (event: InputEvent) => void, options?: DecoderOptions): InputDecoder;
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAwB,MAAM,cAAc,CAAC;AAiErE,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,YAAY;IAOrB,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IAPjB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,WAAW,CAA8C;gBAGvD,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACjC,OAAO,GAAE,cAAmB;IAGtC,iDAAiD;IACjD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAqBzB,OAAO,CAAC,gBAAgB;IAOxB,sEAAsE;IACtE,OAAO,CAAC,IAAI;IAyDZ,OAAO,CAAC,SAAS;IA8CjB,OAAO,CAAC,SAAS;IAkBjB,wEAAwE;IACxE,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,OAAO;IA8Ff,iEAAiE;IACjE,KAAK,IAAI,IAAI;CAMd;AA4CD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,YAAY,CAEd"}