@visulima/ansi 4.0.0-alpha.8 → 4.0.0

package/dist/background.d.ts

@@ -0,0 +1,72 @@
+/**
+* Returns a sequence that sets the terminal's default foreground (text) color.
+*
+* The color may be any string the terminal understands for `OSC 10`, such as an
+* X11 color name (`"red"`), a hex value (`"#ff0000"`), or an `XParseColor`
+* string (`"rgb:ff/00/00"`, `"rgba:ff/00/00/ff"`).
+*
+* Sequence: `OSC 10 ; color BEL`
+* @param color The color to set the foreground to.
+* @returns The `OSC 10` escape sequence.
+* @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands}
+*/
+declare const setForegroundColor: (color: string) => string;
+/**
+* Sequence that queries the terminal's current default foreground color.
+*
+* Sequence: `OSC 10 ; ? BEL`
+*/
+declare const requestForegroundColor: string;
+/**
+* Sequence that resets the terminal's default foreground color to its default.
+*
+* Sequence: `OSC 110 BEL`
+*/
+declare const resetForegroundColor: string;
+/**
+* Returns a sequence that sets the terminal's default background color.
+*
+* The color may be any string the terminal understands for `OSC 11` (X11 color
+* name, hex value, or `XParseColor` string).
+*
+* Sequence: `OSC 11 ; color BEL`
+* @param color The color to set the background to.
+* @returns The `OSC 11` escape sequence.
+*/
+declare const setBackgroundColor: (color: string) => string;
+/**
+* Sequence that queries the terminal's current default background color.
+*
+* Sequence: `OSC 11 ; ? BEL`
+*/
+declare const requestBackgroundColor: string;
+/**
+* Sequence that resets the terminal's default background color to its default.
+*
+* Sequence: `OSC 111 BEL`
+*/
+declare const resetBackgroundColor: string;
+/**
+* Returns a sequence that sets the terminal's cursor color.
+*
+* The color may be any string the terminal understands for `OSC 12` (X11 color
+* name, hex value, or `XParseColor` string).
+*
+* Sequence: `OSC 12 ; color BEL`
+* @param color The color to set the cursor to.
+* @returns The `OSC 12` escape sequence.
+*/
+declare const setCursorColor: (color: string) => string;
+/**
+* Sequence that queries the terminal's current cursor color.
+*
+* Sequence: `OSC 12 ; ? BEL`
+*/
+declare const requestCursorColor: string;
+/**
+* Sequence that resets the terminal's cursor color to its default.
+*
+* Sequence: `OSC 112 BEL`
+*/
+declare const resetCursorColor: string;
+export { requestBackgroundColor, requestCursorColor, requestForegroundColor, resetBackgroundColor, resetCursorColor, resetForegroundColor, setBackgroundColor, setCursorColor, setForegroundColor };

package/dist/background.js

@@ -0,0 +1 @@
+import{OSC as r,BEL as o,stripOscTerminators as e}from"./constants.js";const t=$=>`${r}10;${e($)}${o}`,C=`${r}10;?${o}`,u=`${r}110${o}`,l=$=>`${r}11;${e($)}${o}`,n=`${r}11;?${o}`,d=`${r}111${o}`,g=$=>`${r}12;${e($)}${o}`,c=`${r}12;?${o}`,a=`${r}112${o}`;export{n as requestBackgroundColor,c as requestCursorColor,C as requestForegroundColor,d as resetBackgroundColor,a as resetCursorColor,u as resetForegroundColor,l as setBackgroundColor,g as setCursorColor,t as setForegroundColor};

package/dist/charset.d.ts

@@ -0,0 +1,52 @@
+/**
+* Returns a Select Character Set (SCS) sequence that designates `charset` into
+* one of the G0–G3 character-set slots.
+*
+* `gset` is one of the designator characters (see {@link G0}, {@link G1},
+* {@link G2}, {@link G3} for 94-character sets, or `"-"`, `"."`, `"/"` for the
+* 96-character G1–G3 slots). `charset` selects the final character of the set,
+* e.g. {@link USASCII} (`"B"`), {@link DEC_SPECIAL_GRAPHICS} (`"0"`) or
+* {@link UNITED_KINGDOM} (`"A"`).
+*
+* Sequence: `ESC gset charset`
+* @param gset The G-set designator character.
+* @param charset The final character identifying the character set.
+* @returns The SCS escape sequence.
+* @see {@link https://vt100.net/docs/vt510-rm/SCS.html}
+*/
+declare const selectCharacterSet: (gset: string, charset: string) => string;
+/** Alias for {@link selectCharacterSet} (Select Character Set). */
+declare const SCS: typeof selectCharacterSet;
+/** G0 designator for a 94-character set. */
+declare const G0: string;
+/** G1 designator for a 94-character set. */
+declare const G1: string;
+/** G2 designator for a 94-character set. */
+declare const G2: string;
+/** G3 designator for a 94-character set. */
+declare const G3: string;
+/** DEC Special Character and Line Drawing Set (final character `0`). */
+declare const DEC_SPECIAL_GRAPHICS: string;
+/** United Kingdom character set (final character `A`). */
+declare const UNITED_KINGDOM: string;
+/** United States (USASCII) character set (final character `B`). */
+declare const USASCII: string;
+/** Locking Shift 0 (LS0 / SI): invoke G0 into GL. Sequence: `SI` (`\u000F`). */
+declare const LS0: string;
+/** Alias for {@link LS0} (Shift In). */
+declare const SI: string;
+/** Locking Shift 1 (LS1 / SO): invoke G1 into GL. Sequence: `SO` (`\u000E`). */
+declare const LS1: string;
+/** Alias for {@link LS1} (Shift Out). */
+declare const SO: string;
+/** Locking Shift 1 Right (LS1R): invoke G1 into GR. Sequence: `ESC ~`. */
+declare const LS1R: string;
+/** Locking Shift 2 (LS2): invoke G2 into GL. Sequence: `ESC n`. */
+declare const LS2: string;
+/** Locking Shift 2 Right (LS2R): invoke G2 into GR. Sequence: `ESC }`. */
+declare const LS2R: string;
+/** Locking Shift 3 (LS3): invoke G3 into GL. Sequence: `ESC o`. */
+declare const LS3: string;
+/** Locking Shift 3 Right (LS3R): invoke G3 into GR. Sequence: `ESC |`. */
+declare const LS3R: string;
+export { DEC_SPECIAL_GRAPHICS, G0, G1, G2, G3, LS0, LS1, LS1R, LS2, LS2R, LS3, LS3R, SCS, SI, SO, UNITED_KINGDOM, USASCII, selectCharacterSet };

package/dist/charset.js

@@ -0,0 +1 @@
+import{ESC as S}from"./constants.js";const C=(L,$)=>`${S}${L}${$}`,e=C,o="(",r=")",A="*",E="+",R="0",c="A",D="B",I="",_=I,t="",a=t,m=`${S}~`,n=`${S}n`,p=`${S}}`,s=`${S}o`,N=`${S}|`;export{R as DEC_SPECIAL_GRAPHICS,o as G0,r as G1,A as G2,E as G3,I as LS0,t as LS1,m as LS1R,n as LS2,p as LS2R,s as LS3,N as LS3R,e as SCS,_ as SI,a as SO,c as UNITED_KINGDOM,D as USASCII,C as selectCharacterSet};

package/dist/clear.d.ts

@@ -1,77 +1,78 @@
 /**
- * Moves the cursor to the top-left (0,0 in 0-indexed terms) and erases from the cursor to the end of the screen.
- *
- * This sequence is a combination of:
- * 1. {@link cursorTo}(0, 0): Moves the cursor to the first row, first column.
- * (Equivalent to `CSI 1;1H` as `cursorTo` uses 0-indexed arguments which are converted to 1-indexed for the sequence).
- * 2. {@link eraseDisplay}({@link EraseDisplayMode.ToEnd}): Erases from the cursor position to the end of the screen (`CSI 0J` or `CSI J`).
- *
- * Effective combined sequence: `CSI 1;1H CSI J` (or `CSI 1;1H CSI 0J`).
- * @see {@link cursorTo}
- * @see {@link eraseDisplay}
- * @see {@link EraseDisplayMode.ToEnd}
- */
-export declare const clearScreenFromTopLeft: string;
+* Moves the cursor to the top-left (0,0 in 0-indexed terms) and erases from the cursor to the end of the screen.
+*
+* This sequence is a combination of:
+* 1. {@link cursorTo}(0, 0): Moves the cursor to the first row, first column.
+* (Equivalent to `CSI 1;1H` as `cursorTo` uses 0-indexed arguments which are converted to 1-indexed for the sequence).
+* 2. {@link eraseDisplay}({@link EraseDisplayMode.ToEnd}): Erases from the cursor position to the end of the screen (`CSI 0J` or `CSI J`).
+*
+* Effective combined sequence: `CSI 1;1H CSI J` (or `CSI 1;1H CSI 0J`).
+* @see {@link cursorTo}
+* @see {@link eraseDisplay}
+* @see {@link EraseDisplayMode.ToEnd}
+*/
+declare const clearScreenFromTopLeft: string;
 /**
- * Erases the entire current line and moves the cursor to the beginning of that line (column 1).
- *
- * This sequence is a combination of:
- * 1. {@link eraseInLine}({@link EraseLineMode.EntireLine}): Erases the entire current line (`CSI 2K`).
- * 2. `CSI G`: Moves the cursor to column 1 of the current line (Cursor Horizontal Absolute).
- * Alternatively, a carriage return (`\r`) could achieve a similar cursor move to the start of the line on many systems.
- *
- * Effective combined sequence: `CSI 2K CSI G`.
- * @see {@link eraseInLine}
- * @see {@link EraseLineMode.EntireLine}
- */
-export declare const clearLineAndHomeCursor: string;
+* Erases the entire current line and moves the cursor to the beginning of that line (column 1).
+*
+* This sequence is a combination of:
+* 1. {@link eraseInLine}({@link EraseLineMode.EntireLine}): Erases the entire current line (`CSI 2K`).
+* 2. `CSI G`: Moves the cursor to column 1 of the current line (Cursor Horizontal Absolute).
+* Alternatively, a carriage return (`\r`) could achieve a similar cursor move to the start of the line on many systems.
+*
+* Effective combined sequence: `CSI 2K CSI G`.
+* @see {@link eraseInLine}
+* @see {@link EraseLineMode.EntireLine}
+*/
+declare const clearLineAndHomeCursor: string;
 /**
- * Homes the cursor to the top-left position (row 1, column 1) and erases the entire screen.
- *
- * This sequence is a combination of:
- * 1. `CSI H`: Moves the cursor to the home position (top-left, equivalent to `CSI 1;1H`).
- * 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}): Erases the entire screen (`CSI 2J`).
- *
- * Effective combined sequence: `CSI H CSI 2J`.
- * @remarks This is a very common sequence for clearing the visible terminal window.
- * @see `cursorPosition` from `./cursor` (which `CSI H` relates to)
- * @see {@link eraseDisplay}
- * @see {@link EraseDisplayMode.EntireScreen}
- */
-export declare const clearScreenAndHomeCursor: string;
+* Homes the cursor to the top-left position (row 1, column 1) and erases the entire screen.
+*
+* This sequence is a combination of:
+* 1. `CSI H`: Moves the cursor to the home position (top-left, equivalent to `CSI 1;1H`).
+* 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}): Erases the entire screen (`CSI 2J`).
+*
+* Effective combined sequence: `CSI H CSI 2J`.
+* @remarks This is a very common sequence for clearing the visible terminal window.
+* @see `cursorPosition` from `./cursor` (which `CSI H` relates to)
+* @see {@link eraseDisplay}
+* @see {@link EraseDisplayMode.EntireScreen}
+*/
+declare const clearScreenAndHomeCursor: string;
 /**
- * Clears the entire terminal display, including the scrollback buffer on supported terminals,
- * and attempts to reset the terminal to its initial (or a more pristine) state.
- *
- * This is generally a more comprehensive and forceful clear operation than just erasing the
- * visible screen content (like {@link clearScreenAndHomeCursor}).
- *
- * The exact behavior and sequences used can vary by terminal and operating system:
- *
- * - **On Windows:**
- * It typically uses `CSI 2J` (erase entire screen) followed by `CSI 0f`.
- * `CSI 0f` (or `CSI ;f`, `CSI 0;0f`) is an SGR sequence that also often acts as a cursor home command,
- * though its standardization can be less consistent than `CSI H`.
- * The primary goal is to clear the screen and move the cursor to the top-left.
- *
- * - **On other platforms (e.g., Linux, macOS with XTerm-like terminals):**
- * A more robust combination is used:
- * 1. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}) (`CSI 2J`): Erases the entire visible screen.
- * 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreenAndScrollback}) (`CSI 3J`): Erases the scrollback buffer (XTerm-specific, but widely supported).
- * 3. `CSI H`: Moves the cursor to the home position (top-left).
- * 4. `ESC c` (RIS - Reset to Initial State): This is the most powerful reset sequence. It typically resets the terminal
- * to its power-on state, clearing character sets, SGR attributes, modes, and more.
- * @returns A string containing the ANSI escape sequence(s) for resetting the terminal.
- * @example
- * ```typescript
- * import { resetTerminal } from '@visulima/ansi/clear';
- *
- * process.stdout.write(resetTerminal);
- * // The terminal attempts a full reset.
- * ```
- * @see {@link eraseDisplay}
- * @see {@link EraseDisplayMode.EntireScreen}
- * @see {@link EraseDisplayMode.EntireScreenAndScrollback}
- * @see {@link https://vt100.net/docs/vt510-rm/RIS.html} RIS documentation.
- */
-export declare const resetTerminal: string;
+* Clears the entire terminal display, including the scrollback buffer on supported terminals,
+* and attempts to reset the terminal to its initial (or a more pristine) state.
+*
+* This is generally a more comprehensive and forceful clear operation than just erasing the
+* visible screen content (like {@link clearScreenAndHomeCursor}).
+*
+* The exact behavior and sequences used can vary by terminal and operating system:
+*
+* - **On Windows:**
+* It typically uses `CSI 2J` (erase entire screen) followed by `CSI 0f`.
+* `CSI 0f` (or `CSI ;f`, `CSI 0;0f`) is an SGR sequence that also often acts as a cursor home command,
+* though its standardization can be less consistent than `CSI H`.
+* The primary goal is to clear the screen and move the cursor to the top-left.
+*
+* - **On other platforms (e.g., Linux, macOS with XTerm-like terminals):**
+* A more robust combination is used:
+* 1. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}) (`CSI 2J`): Erases the entire visible screen.
+* 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreenAndScrollback}) (`CSI 3J`): Erases the scrollback buffer (XTerm-specific, but widely supported).
+* 3. `CSI H`: Moves the cursor to the home position (top-left).
+* 4. `ESC c` (RIS - Reset to Initial State): This is the most powerful reset sequence. It typically resets the terminal
+* to its power-on state, clearing character sets, SGR attributes, modes, and more.
+* @returns A string containing the ANSI escape sequence(s) for resetting the terminal.
+* @example
+* ```typescript
+* import { resetTerminal } from '@visulima/ansi/clear';
+*
+* process.stdout.write(resetTerminal);
+* // The terminal attempts a full reset.
+* ```
+* @see {@link eraseDisplay}
+* @see {@link EraseDisplayMode.EntireScreen}
+* @see {@link EraseDisplayMode.EntireScreenAndScrollback}
+* @see {@link https://vt100.net/docs/vt510-rm/RIS.html} RIS documentation.
+*/
+declare const resetTerminal: string;
+export { clearLineAndHomeCursor, clearScreenAndHomeCursor, clearScreenFromTopLeft, resetTerminal };

package/dist/clear.js

@@ -1,10 +1 @@
-import { C as CSI, E as ESC } from './packem_shared/constants-CE7WkXh_.js';
-import { u as cursorTo, A as isWindows } from './packem_shared/cursor-ChpV7cgs.js';
-import { eraseInLine, eraseDisplay, EraseDisplayMode, EraseLineMode } from './erase.js';
-
-const clearScreenFromTopLeft = cursorTo(0, 0) + eraseDisplay(EraseDisplayMode.ToEnd);
-const clearLineAndHomeCursor = `${eraseInLine(EraseLineMode.EntireLine)}${CSI}G`;
-const clearScreenAndHomeCursor = `${CSI}H${eraseDisplay(EraseDisplayMode.EntireScreen)}`;
-const resetTerminal = isWindows ? `${eraseDisplay(EraseDisplayMode.EntireScreen)}${CSI}0f` : `${eraseDisplay(EraseDisplayMode.EntireScreen)}${eraseDisplay(EraseDisplayMode.EntireScreenAndScrollback)}${CSI}H${ESC}c`;
-
-export { clearLineAndHomeCursor, clearScreenAndHomeCursor, clearScreenFromTopLeft, resetTerminal };
+import{CSI as n,ESC as o}from"./constants.js";import{u as i,A as s}from"./packem_shared/cursor-BXG1O_IE.js";import{eraseInLine as c,eraseDisplay as e,EraseDisplayMode as r,EraseLineMode as a}from"./erase.js";const E=i(0,0)+e(r.ToEnd),S=`${c(a.EntireLine)}${n}G`,l=`${n}H${e(r.EntireScreen)}`,d=s?`${e(r.EntireScreen)}${n}0f`:`${e(r.EntireScreen)}${e(r.EntireScreenAndScrollback)}${n}H${o}c`;export{S as clearLineAndHomeCursor,l as clearScreenAndHomeCursor,E as clearScreenFromTopLeft,d as resetTerminal};

package/dist/clipboard.d.ts

@@ -0,0 +1,76 @@
+/**
+* Selection targets for OSC 52 clipboard operations.
+*
+* - `c` is the system clipboard (the common default).
+* - `p` is the primary selection (X11 middle-click paste buffer).
+* - `q` is the secondary selection.
+* - `s` is the "select" selection.
+* - `0` to `7` are numbered cut buffers.
+*
+* Multiple targets may be combined (e.g. `"cp"`) to write the same data to
+* several selections at once.
+* @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html}
+*/
+type ClipboardSelection = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "c" | "p" | "q" | "s" | (string & {});
+/**
+* Writes data to the terminal's clipboard using the OSC 52 escape sequence.
+*
+* Sequence: `OSC 52 ; selection ; base64-data ST`
+*
+* OSC 52 is the only clipboard mechanism that works over SSH/tmux, because the
+* write travels in-band over the terminal stream rather than touching a local
+* clipboard API. The terminal emulator must have clipboard writes enabled
+* (e.g. `set-clipboard` in xterm, `allow-passthrough` plus `set-clipboard` in
+* tmux); many enable it by default.
+* @param data The text to place on the clipboard.
+* @param selection The selection target(s). Defaults to `"c"` (system clipboard).
+* @param terminator The OSC terminator to use. Defaults to {@link BEL}; pass
+* {@link ST} (`ESC backslash`) for terminals that require the canonical String Terminator.
+* @returns The OSC 52 escape sequence.
+* @example
+* ```typescript
+* import { setClipboard } from "@visulima/ansi/clipboard";
+*
+* // Copy a generated token to the user's local clipboard from a remote shell.
+* process.stdout.write(setClipboard("my-secret-token"));
+* ```
+* @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html}
+*/
+declare const setClipboard: (data: string, selection?: ClipboardSelection, terminator?: string) => string;
+/**
+* Requests the current contents of the terminal's clipboard via OSC 52.
+*
+* Sequence: `OSC 52 ; selection ; ? ST`
+*
+* The terminal responds with `OSC 52 ; selection ; base64-data ST` if it
+* permits clipboard reads (frequently disabled for security). Decode the
+* Base64 payload from the response to obtain the clipboard text.
+* @param selection The selection target to query. Defaults to `"c"` (system clipboard).
+* @param terminator The OSC terminator to use. Defaults to {@link BEL}; pass {@link ST} for terminals that require it.
+* @returns The OSC 52 query escape sequence.
+* @example
+* ```typescript
+* import { requestClipboard } from "@visulima/ansi/clipboard";
+*
+* process.stdout.write(requestClipboard());
+* ```
+* @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html}
+*/
+declare const requestClipboard: (selection?: ClipboardSelection, terminator?: string) => string;
+/**
+* Clears the terminal's clipboard for the given selection via OSC 52.
+*
+* Sequence: `OSC 52 ; selection ; ST` (an empty payload clears the selection).
+* @param selection The selection target to clear. Defaults to `"c"` (system clipboard).
+* @param terminator The OSC terminator to use. Defaults to {@link BEL}; pass {@link ST} for terminals that require it.
+* @returns The OSC 52 clear escape sequence.
+* @example
+* ```typescript
+* import { clearClipboard } from "@visulima/ansi/clipboard";
+*
+* process.stdout.write(clearClipboard());
+* ```
+* @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html}
+*/
+declare const clearClipboard: (selection?: ClipboardSelection, terminator?: string) => string;
+export { ClipboardSelection, clearClipboard, requestClipboard, setClipboard };

package/dist/clipboard.js

@@ -0,0 +1 @@
+import{OSC as e,BEL as n}from"./constants.js";const f=r=>{const o=new TextEncoder().encode(r),t=o.toBase64;if(typeof t=="function")return t.call(o);if(typeof btoa=="function"){let i="";for(const c of o)i+=String.fromCodePoint(c);return btoa(i)}const a=globalThis.Buffer;if(a===void 0)throw new Error("No Base64 encoder available: Uint8Array.prototype.toBase64, btoa and Buffer are all missing.");return a.from(o).toString("base64")},l=(r,o="c",t=n)=>`${e}52;${o};${f(r)}${t}`,$=(r="c",o=n)=>`${e}52;${r};?${o}`,b=(r="c",o=n)=>`${e}52;${r};${o}`;export{b as clearClipboard,$ as requestClipboard,l as setClipboard};

package/dist/constants.d.ts

@@ -1,20 +1,28 @@
 /** Escape character (\u001B). */
-export declare const ESC: string;
+declare const ESC: string;
 /** Control Sequence Introducer (ESC [). */
-export declare const CSI: string;
+declare const CSI: string;
 /** Operating System Command (ESC ]). */
-export declare const OSC: string;
+declare const OSC: string;
 /** Bell character (\u0007). Often used to terminate OSC sequences. */
-export declare const BEL: string;
+declare const BEL: string;
 /** Separator used in some ANSI sequences, typically a semicolon. */
-export declare const SEP: string;
+declare const SEP: string;
 /** Device Control String (ESC P). */
-export declare const DCS: string;
+declare const DCS: string;
 /** String Terminator (ESC \\). Used to terminate DCS, SOS, PM, APC sequences. */
-export declare const ST: string;
+declare const ST: string;
 /** Application Program Command (ESC _). */
-export declare const APC: string;
+declare const APC: string;
 /** Start of String (ESC X). */
-export declare const SOS: string;
+declare const SOS: string;
 /** Privacy Message (ESC ^). */
-export declare const PM: string;
+declare const PM: string;
+/**
+* Strips OSC terminators (BEL, ESC) from a caller-supplied value so it cannot
+* inject or prematurely terminate an escape sequence when interpolated into one.
+* @param value The untrusted string to sanitize.
+* @returns `value` with all BEL and ESC characters removed.
+*/
+declare const stripOscTerminators: (value: string) => string;
+export { APC, BEL, CSI, DCS, ESC, OSC, PM, SEP, SOS, ST, stripOscTerminators };

package/dist/constants.js

@@ -0,0 +1 @@
+const B="\x1B",S="\x1B[",r="\x1B]",C="\x07",e=";",s="\x1BP",t="\x1B\\",P="\x1B_",c="\x1BX",l="\x1B^",o=x=>x.replaceAll(/[\u0007\u001B]/g,"");export{P as APC,C as BEL,S as CSI,s as DCS,B as ESC,r as OSC,l as PM,e as SEP,c as SOS,t as ST,o as stripOscTerminators};