@textui/terminal 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,8 @@
 # @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.
+[![npm](https://img.shields.io/npm/v/@textui/terminal?label=%40textui%2Fterminal)](https://www.npmjs.com/package/@textui/terminal) [![license](https://img.shields.io/npm/l/@textui/terminal)](https://github.com/softov/textui/blob/main/LICENSE)
+
+What [`@textui/core`](https://www.npmjs.com/package/@textui/core) needs to reach an actual terminal: adapters, capability detection, ANSI writing and input decoding.
 
 ```bash
 npm install @textui/terminal
@@ -17,40 +18,27 @@ 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.
+`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.
+`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:
+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.
+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.
+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.
+`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:
+`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(), {
@@ -59,25 +47,26 @@ const svg = bufferToSvg(app.buffer(), {
 });
 ```
 
-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.
+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.
+`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.
+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.
+No dependencies beyond [`@textui/core`](https://www.npmjs.com/package/@textui/core). Uses `process` for stdio and signals, and no other Node API. Node 22+ and Bun.
 
 ## Documentation
 
 <https://softov.github.io/textui/>
+
+<!-- family -->
+
+---
+
+Part of **[TextUI](https://github.com/softov/textui)** - [documentation](https://softov.github.io/textui/) - [getting started](https://softov.github.io/textui/getting-started.html)
+
+[`@textui/kit`](https://www.npmjs.com/package/@textui/kit) one install · [`@textui/core`](https://www.npmjs.com/package/@textui/core) the runtime · [`@textui/widgets`](https://www.npmjs.com/package/@textui/widgets) the catalog · **`@textui/terminal`** adapters and input · [`@textui/testing`](https://www.npmjs.com/package/@textui/testing) the harness · [`@textui/cli`](https://www.npmjs.com/package/@textui/cli) the CLI

package/dist/ansi.d.ts

@@ -23,6 +23,8 @@ 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. */
+/** DECSCUSR 0: back to whatever the terminal was configured for. */
+export declare const cursorShapeReset = "\u001B[0 q";
 export declare const cursorShape: (shape: "block" | "underline" | "bar", blinking?: boolean) => string;
 export declare const eraseLine = "\u001B[2K";
 export declare const eraseLineRight = "\u001B[0K";

package/dist/ansi.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../src/ansi.ts"],"names":[],"mappings":"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"}

package/dist/ansi.js

@@ -24,6 +24,8 @@ 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. */
+/** DECSCUSR 0: back to whatever the terminal was configured for. */
+export const cursorShapeReset = `${CSI}0 q`;
 export const cursorShape = (shape, blinking = true) => {
     const base = shape === 'block' ? 1 : shape === 'underline' ? 3 : 5;
     return `${CSI}${blinking ? base : base + 1} q`;

package/dist/capabilities.d.ts.map

@@ -1 +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"}
+{"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,CAgE9E;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

@@ -101,7 +101,25 @@ export function detectCapabilities(input) {
         paste: true,
         // tmux rewrites OSC 8, and Apple Terminal ignores it.
         hyperlinks: modern && !mux && program !== 'Apple_Terminal',
-        clipboard: modern || mux,
+        /*
+         * OSC 52, and on for anything that is not known to mangle it.
+         *
+         * This used to require a recognised terminal, which switched it off in
+         * precisely the situation it exists for. Over ssh none of the variables
+         * that name a terminal survive the hop - `TERM_PROGRAM`, `KITTY_WINDOW_ID`
+         * and `WT_SESSION` are all set by the terminal on the machine you are
+         * sitting at, not the one the program is running on - so a remote session
+         * saw a bare `xterm-256color` and refused to copy. Reaching the clipboard
+         * of a machine the program is not running on is the entire reason OSC 52
+         * was specified.
+         *
+         * Assuming it works is safe in a way that assuming most sequences work is
+         * not: a terminal that does not implement OSC 52 ignores the whole string
+         * rather than printing part of it, because an OSC runs to its terminator.
+         * The one that does not is `screen`, which needs the payload wrapped in
+         * its own passthrough and shows it as text otherwise.
+         */
+        clipboard: !(env.TERM ?? '').startsWith('screen'),
         altScreen: true,
         cursor: true,
         // Synchronized output is safe when supported and harmless when not, but

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export * as ansi from './ansi.js';
 export { Writer, createWriter } from './writer.js';
 export { captureBuffer } from './capture.js';
 export type { CaptureOptions } from './capture.js';
+export { renderStill } from './still.js';
+export type { Still, StillOptions } from './still.js';
 export { bufferToSvg } from './svg.js';
 export type { SvgOptions } from './svg.js';
 export { detectCapabilities, detectColorDepth, detectUnicode, applyOverrides, describeEnvironment, } from './capabilities.js';

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,YAAY,CAAC;AACzC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,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

@@ -1,6 +1,7 @@
 export * as ansi from './ansi.js';
 export { Writer, createWriter } from './writer.js';
 export { captureBuffer } from './capture.js';
+export { renderStill } from './still.js';
 export { bufferToSvg } from './svg.js';
 export { detectCapabilities, detectColorDepth, detectUnicode, applyOverrides, describeEnvironment, } from './capabilities.js';
 export { InputDecoder, createDecoder } from './input.js';

package/dist/input.d.ts.map

@@ -1 +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"}
+{"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;AAgDD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,YAAY,CAEd"}

package/dist/input.js

@@ -333,6 +333,10 @@ function decodeSgrMouse(body, final) {
         x: col - 1,
         y: row - 1,
         ctrl, alt, shift,
+        // Stamped on arrival, because nothing downstream can tell a double click
+        // from two clicks without knowing when each one landed. The wire says
+        // press and release and nothing else.
+        at: Date.now(),
         handled: false,
     };
     if (wheel) {

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import type { AcquiredState, CapabilityOverrides, Disposable, InputEvent, Size, TerminalAdapter, TerminalCapabilities, TerminalSessionOptions } from '@textui/core';
+import type { AcquiredState, CapabilityOverrides, CursorStyle, Disposable, InputEvent, Size, TerminalAdapter, TerminalCapabilities, TerminalSessionOptions } from '@textui/core';
 /**
  * The Node TTY adapter.
  *
@@ -91,6 +91,7 @@ export declare class NodeTerminalAdapter implements TerminalAdapter {
     onResize(fn: (size: Size) => void): Disposable;
     writeClipboard(text: string): void;
     setTitle(title: string): void;
+    setCursorShape(shape: CursorStyle): void;
     private installExitHandlers;
     private removeExitHandlers;
     dispose(): void;

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/node.js

@@ -5,7 +5,7 @@ import { createDecoder } from './input.js';
 const NOTHING_ACQUIRED = {
     altScreen: false, mouse: false, wheel: false, focusEvents: false,
     paste: false, cursorHidden: false, enhancedKeys: false, rawMode: false,
-    titleSet: false,
+    titleSet: false, cursorShaped: false,
 };
 export class NodeTerminalAdapter {
     options;
@@ -147,6 +147,8 @@ export class NodeTerminalAdapter {
             out.push(ansi.altScreenLeave);
         if (state.cursorHidden)
             out.push(ansi.cursorShow);
+        if (state.cursorShaped)
+            out.push(ansi.cursorShapeReset);
         out.push(ansi.reset);
         try {
             this.stdout.write(out.join(''));
@@ -199,6 +201,14 @@ export class NodeTerminalAdapter {
             return;
         this.stdout.write(ansi.setTitle(title));
     }
+    setCursorShape(shape) {
+        // No session means nothing to put back, and nothing that would put it
+        // back - so a shape set outside one is a shape left on the user's shell.
+        if (!this.caps.cursor || !this.state)
+            return;
+        this.stdout.write(ansi.cursorShape(shape));
+        this.state.cursorShaped = true;
+    }
     installExitHandlers() {
         this.exitHandler = () => this.release();
         process.on('exit', this.exitHandler);

package/dist/still.d.ts

@@ -0,0 +1,71 @@
+import type { CapabilityOverrides, CellBuffer, CreateAppOptions, TextUIApp } from '@textui/core';
+import type { CaptureOptions } from './capture.js';
+/**
+ * One frame of an application, as text.
+ *
+ * The same application, not a second rendering path: it is mounted against a
+ * terminal that is a size and nothing else, rendered until it stops changing,
+ * and every cell it painted is what comes back. Which is what a program does
+ * when its output is a pipe rather than a screen - there is no frame after
+ * this one to correct it, so it has to be the finished picture.
+ *
+ * Every example in this repository had written this out by hand, and all of
+ * them ended the same way: a sleep loop of four milliseconds times a number
+ * somebody had tried until the picture looked right. Eight, mostly - four in
+ * one, twelve in another - for the same eight lines of setup either side. The
+ * number was the tell. Nobody knew it, a small one silently writes a
+ * half-drawn frame, and `TextUIApp.settled` is the answer they were all
+ * approximating.
+ */
+export interface StillOptions extends Omit<CreateAppOptions, 'terminal' | 'session'> {
+    /** Columns. The terminal is only a size, so this is the whole of it. */
+    width?: number;
+    height?: number;
+    /** What the terminal should claim to be able to do. */
+    capabilities?: CapabilityOverrides;
+    /**
+     * Drive it before the frame is taken.
+     *
+     * A still of an application in its opening state is the least interesting
+     * one. This is where a screen is pushed, a message sent, or a scripted host
+     * pumped to the point worth photographing - and it may be async, because
+     * most of those are.
+     */
+    before?(app: TextUIApp): void | Promise<void>;
+    /**
+     * The frame is drawn and the application is still alive.
+     *
+     * For what a string cannot carry and `stop` would take away: the buffer, to
+     * crop it to the rows that were used, and the theme, whose two colours are
+     * the honest background for a picture of *this* screen rather than the
+     * exporter's guess. It runs before the capture, so a buffer changed here is
+     * the buffer that comes back as `text`.
+     */
+    after?(app: TextUIApp): void | Promise<void>;
+    /** Plain text or SGR, and at what depth. Defaults to what the terminal claims. */
+    capture?: CaptureOptions;
+    /** Settle passes before giving up. See `TextUIApp.settled`. */
+    settleLimit?: number;
+}
+export interface Still {
+    /** Every cell it painted, rows separated by newlines. */
+    text: string;
+    /**
+     * The cells themselves, for anything text cannot carry - `bufferToSvg`, a
+     * pixel diff, an assertion about one cell's colour. Valid after the
+     * application has stopped: nothing writes to it again.
+     */
+    buffer: CellBuffer;
+    /**
+     * Whether it went quiet, or the limit ran out first.
+     *
+     * An application that animates settles between its frames, so this is
+     * `true` for one of those and the picture is a photograph of something
+     * moving. `false` means the passes never stopped producing work - a render
+     * loop that does not converge - and the frame was taken anyway, because a
+     * still is better evidence of that than nothing is.
+     */
+    settled: boolean;
+}
+export declare function renderStill(options?: StillOptions): Promise<Still>;
+//# sourceMappingURL=still.d.ts.map

package/dist/still.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"still.d.ts","sourceRoot":"","sources":["../src/still.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAC7D,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC;IAClF,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,kFAAkF;IAClF,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;;;OAQG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,KAAK,CAAC,CAgC5E"}

package/dist/still.js

@@ -0,0 +1,29 @@
+import { WRITER_KEY, createApp } from '@textui/core';
+import { createVirtualTerminal } from './virtual.js';
+import { createWriter } from './writer.js';
+import { captureBuffer } from './capture.js';
+export async function renderStill(options = {}) {
+    const { width = 80, height = 24, capabilities, before, after, capture, settleLimit, ...app } = options;
+    const terminal = createVirtualTerminal({
+        width,
+        height,
+        ...(capabilities ? { capabilities } : {}),
+    });
+    const created = createApp({ ...app, terminal });
+    // The writer is provided even though the buffer is what is read: a virtual
+    // terminal records what was written to it, and a still that quietly stopped
+    // producing that would break anything reading the bytes rather than the
+    // cells.
+    created.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+    await created.start();
+    await before?.(created);
+    const settled = await created.settled(settleLimit === undefined ? {} : { limit: settleLimit });
+    // Even when it did not settle: the limit means "stop waiting", not "give up
+    // on the frame", and a still of a moving thing is still a still.
+    created.flush();
+    await after?.(created);
+    const text = captureBuffer(created.buffer(), terminal.capabilities(), capture ?? {});
+    const buffer = created.buffer();
+    await created.stop();
+    return { text, buffer, settled };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textui/terminal",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Terminal adapters, capability detection, ANSI writing and input decoding for TextUI",
   "keywords": [
     "terminal",
@@ -48,15 +48,15 @@
       "import": "./dist/virtual.js"
     }
   },
-  "dependencies": {
-    "@textui/core": "^0.1.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run"
+  },
+  "dependencies": {
+    "@textui/core": "^0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
-}
+}

package/src/ansi.ts

@@ -26,6 +26,9 @@ export const cursorBack = (n = 1): string => `${CSI}${n}D`;
 export const cursorColumn = (x: number): string => `${CSI}${x + 1}G`;
 
 /** Cursor shapes, for a text field that wants a bar rather than a block. */
+/** DECSCUSR 0: back to whatever the terminal was configured for. */
+export const cursorShapeReset = `${CSI}0 q`;
+
 export const cursorShape = (
   shape: 'block' | 'underline' | 'bar',
   blinking = true,

package/src/capabilities.ts

@@ -106,7 +106,25 @@ export function detectCapabilities(input: DetectionInput): TerminalCapabilities
     paste: true,
     // tmux rewrites OSC 8, and Apple Terminal ignores it.
     hyperlinks: modern && !mux && program !== 'Apple_Terminal',
-    clipboard: modern || mux,
+    /*
+     * OSC 52, and on for anything that is not known to mangle it.
+     *
+     * This used to require a recognised terminal, which switched it off in
+     * precisely the situation it exists for. Over ssh none of the variables
+     * that name a terminal survive the hop - `TERM_PROGRAM`, `KITTY_WINDOW_ID`
+     * and `WT_SESSION` are all set by the terminal on the machine you are
+     * sitting at, not the one the program is running on - so a remote session
+     * saw a bare `xterm-256color` and refused to copy. Reaching the clipboard
+     * of a machine the program is not running on is the entire reason OSC 52
+     * was specified.
+     *
+     * Assuming it works is safe in a way that assuming most sequences work is
+     * not: a terminal that does not implement OSC 52 ignores the whole string
+     * rather than printing part of it, because an OSC runs to its terminator.
+     * The one that does not is `screen`, which needs the payload wrapped in
+     * its own passthrough and shows it as text otherwise.
+     */
+    clipboard: !(env.TERM ?? '').startsWith('screen'),
     altScreen: true,
     cursor: true,
     // Synchronized output is safe when supported and harmless when not, but

package/src/index.ts

@@ -2,6 +2,8 @@ export * as ansi from './ansi.js';
 export { Writer, createWriter } from './writer.js';
 export { captureBuffer } from './capture.js';
 export type { CaptureOptions } from './capture.js';
+export { renderStill } from './still.js';
+export type { Still, StillOptions } from './still.js';
 export { bufferToSvg } from './svg.js';
 export type { SvgOptions } from './svg.js';
 export {

package/src/input.ts

@@ -362,6 +362,10 @@ function decodeSgrMouse(body: string, final: string): MouseEvent | null {
     x: col - 1,
     y: row - 1,
     ctrl, alt, shift,
+    // Stamped on arrival, because nothing downstream can tell a double click
+    // from two clicks without knowing when each one landed. The wire says
+    // press and release and nothing else.
+    at: Date.now(),
     handled: false,
   };
 

package/src/node.ts

@@ -1,7 +1,4 @@
-import type {
-  AcquiredState, CapabilityOverrides, Disposable, InputEvent, Size,
-  TerminalAdapter, TerminalCapabilities, TerminalSessionOptions,
-} from '@textui/core';
+import type { AcquiredState, CapabilityOverrides, CursorStyle, Disposable, InputEvent, Size, TerminalAdapter, TerminalCapabilities, TerminalSessionOptions } from '@textui/core';
 import { toDisposable } from '@textui/core';
 import * as ansi from './ansi.js';
 import { applyOverrides, detectCapabilities, describeEnvironment } from './capabilities.js';
@@ -71,7 +68,7 @@ export interface NodeAdapterOptions {
 const NOTHING_ACQUIRED: AcquiredState = {
   altScreen: false, mouse: false, wheel: false, focusEvents: false,
   paste: false, cursorHidden: false, enhancedKeys: false, rawMode: false,
-  titleSet: false,
+  titleSet: false, cursorShaped: false,
 };
 
 export class NodeTerminalAdapter implements TerminalAdapter {
@@ -235,6 +232,7 @@ export class NodeTerminalAdapter implements TerminalAdapter {
     if (state.mouse) out.push(state.wheel ? ansi.mouseOff : ansi.mouseButtonsOff);
     if (state.altScreen) out.push(ansi.altScreenLeave);
     if (state.cursorHidden) out.push(ansi.cursorShow);
+    if (state.cursorShaped) out.push(ansi.cursorShapeReset);
     out.push(ansi.reset);
 
     try {
@@ -291,6 +289,14 @@ export class NodeTerminalAdapter implements TerminalAdapter {
     this.stdout.write(ansi.setTitle(title));
   }
 
+  setCursorShape(shape: CursorStyle): void {
+    // No session means nothing to put back, and nothing that would put it
+    // back - so a shape set outside one is a shape left on the user's shell.
+    if (!this.caps.cursor || !this.state) return;
+    this.stdout.write(ansi.cursorShape(shape));
+    this.state.cursorShaped = true;
+  }
+
   private installExitHandlers(): void {
     this.exitHandler = () => this.release();
     process.on('exit', this.exitHandler);

package/src/still.ts

@@ -0,0 +1,111 @@
+import type {
+  CapabilityOverrides, CellBuffer, CreateAppOptions, TextUIApp,
+} from '@textui/core';
+import { WRITER_KEY, createApp } from '@textui/core';
+import { createVirtualTerminal } from './virtual.js';
+import { createWriter } from './writer.js';
+import { captureBuffer } from './capture.js';
+import type { CaptureOptions } from './capture.js';
+
+/**
+ * One frame of an application, as text.
+ *
+ * The same application, not a second rendering path: it is mounted against a
+ * terminal that is a size and nothing else, rendered until it stops changing,
+ * and every cell it painted is what comes back. Which is what a program does
+ * when its output is a pipe rather than a screen - there is no frame after
+ * this one to correct it, so it has to be the finished picture.
+ *
+ * Every example in this repository had written this out by hand, and all of
+ * them ended the same way: a sleep loop of four milliseconds times a number
+ * somebody had tried until the picture looked right. Eight, mostly - four in
+ * one, twelve in another - for the same eight lines of setup either side. The
+ * number was the tell. Nobody knew it, a small one silently writes a
+ * half-drawn frame, and `TextUIApp.settled` is the answer they were all
+ * approximating.
+ */
+export interface StillOptions extends Omit<CreateAppOptions, 'terminal' | 'session'> {
+  /** Columns. The terminal is only a size, so this is the whole of it. */
+  width?: number;
+  height?: number;
+  /** What the terminal should claim to be able to do. */
+  capabilities?: CapabilityOverrides;
+  /**
+   * Drive it before the frame is taken.
+   *
+   * A still of an application in its opening state is the least interesting
+   * one. This is where a screen is pushed, a message sent, or a scripted host
+   * pumped to the point worth photographing - and it may be async, because
+   * most of those are.
+   */
+  before?(app: TextUIApp): void | Promise<void>;
+  /**
+   * The frame is drawn and the application is still alive.
+   *
+   * For what a string cannot carry and `stop` would take away: the buffer, to
+   * crop it to the rows that were used, and the theme, whose two colours are
+   * the honest background for a picture of *this* screen rather than the
+   * exporter's guess. It runs before the capture, so a buffer changed here is
+   * the buffer that comes back as `text`.
+   */
+  after?(app: TextUIApp): void | Promise<void>;
+  /** Plain text or SGR, and at what depth. Defaults to what the terminal claims. */
+  capture?: CaptureOptions;
+  /** Settle passes before giving up. See `TextUIApp.settled`. */
+  settleLimit?: number;
+}
+
+export interface Still {
+  /** Every cell it painted, rows separated by newlines. */
+  text: string;
+  /**
+   * The cells themselves, for anything text cannot carry - `bufferToSvg`, a
+   * pixel diff, an assertion about one cell's colour. Valid after the
+   * application has stopped: nothing writes to it again.
+   */
+  buffer: CellBuffer;
+  /**
+   * Whether it went quiet, or the limit ran out first.
+   *
+   * An application that animates settles between its frames, so this is
+   * `true` for one of those and the picture is a photograph of something
+   * moving. `false` means the passes never stopped producing work - a render
+   * loop that does not converge - and the frame was taken anyway, because a
+   * still is better evidence of that than nothing is.
+   */
+  settled: boolean;
+}
+
+export async function renderStill(options: StillOptions = {}): Promise<Still> {
+  const {
+    width = 80, height = 24, capabilities, before, after, capture, settleLimit, ...app
+  } = options;
+
+  const terminal = createVirtualTerminal({
+    width,
+    height,
+    ...(capabilities ? { capabilities } : {}),
+  });
+
+  const created = createApp({ ...app, terminal });
+  // The writer is provided even though the buffer is what is read: a virtual
+  // terminal records what was written to it, and a still that quietly stopped
+  // producing that would break anything reading the bytes rather than the
+  // cells.
+  created.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+
+  await created.start();
+  await before?.(created);
+
+  const settled = await created.settled(settleLimit === undefined ? {} : { limit: settleLimit });
+  // Even when it did not settle: the limit means "stop waiting", not "give up
+  // on the frame", and a still of a moving thing is still a still.
+  created.flush();
+  await after?.(created);
+
+  const text = captureBuffer(created.buffer(), terminal.capabilities(), capture ?? {});
+  const buffer = created.buffer();
+  await created.stop();
+
+  return { text, buffer, settled };
+}