@visulima/ansi 3.0.3 → 3.0.4

package/dist/mouse.d.ts

@@ -1,4 +1,31 @@
-declare const MouseButton: {
+/**
+ * Defines codes for various mouse buttons and actions.
+ * These are based on X11 button codes and common terminal mouse reporting extensions.
+ * @property {number} LEFT - Left mouse button (typically button 1).
+ * @property {number} MIDDLE - Middle mouse button (typically button 2).
+ * @property {number} RIGHT - Right mouse button (typically button 3).
+ * @property {number} NONE - Represents no specific button, often used for release events in some protocols.
+ * @property {number} RELEASE - Alias for `NONE`, used to signify a button release event.
+ * @property {number} BUTTON_1 - Alias for `LEFT`.
+ * @property {number} BUTTON_2 - Alias for `MIDDLE`.
+ * @property {number} BUTTON_3 - Alias for `RIGHT`.
+ * @property {number} WHEEL_UP - Mouse wheel scrolled upwards (typically button 4).
+ * @property {number} WHEEL_DOWN - Mouse wheel scrolled downwards (typically button 5).
+ * @property {number} WHEEL_LEFT - Mouse wheel scrolled leftwards (typically button 6, less common).
+ * @property {number} WHEEL_RIGHT - Mouse wheel scrolled rightwards (typically button 7, less common).
+ * @property {number} BACKWARD - Auxiliary button, often browser "Back" (typically button 8).
+ * @property {number} FORWARD - Auxiliary button, often browser "Forward" (typically button 9).
+ * @property {number} BUTTON_4 - Alias for `WHEEL_UP`.
+ * @property {number} BUTTON_5 - Alias for `WHEEL_DOWN`.
+ * @property {number} BUTTON_6 - Alias for `WHEEL_LEFT`.
+ * @property {number} BUTTON_7 - Alias for `WHEEL_RIGHT`.
+ * @property {number} BUTTON_8 - Alias for `BACKWARD`.
+ * @property {number} BUTTON_9 - Alias for `FORWARD`.
+ * @property {number} BUTTON_10 - Auxiliary button 10.
+ * @property {number} BUTTON_11 - Auxiliary button 11.
+ * @enum {number}
+ */
+export declare const MouseButton: {
     readonly BACKWARD: 8;
     readonly BUTTON_1: 1;
     readonly BUTTON_2: 2;
@@ -22,27 +49,182 @@ declare const MouseButton: {
     readonly WHEEL_RIGHT: 7;
     readonly WHEEL_UP: 4;
 };
-type MouseButtonType = (typeof MouseButton)[keyof typeof MouseButton];
-interface MouseModifiers {
+export type MouseButtonType = (typeof MouseButton)[keyof typeof MouseButton];
+/**
+ * Interface representing modifier keys (Shift, Alt, Ctrl) that might be active during a mouse event.
+ * @property {boolean} [alt] - `true` if the Alt (or Meta) key was pressed, `false` or `undefined` otherwise.
+ * @property {boolean} [ctrl] - `true` if the Control key was pressed, `false` or `undefined` otherwise.
+ * @property {boolean} [shift] - `true` if the Shift key was pressed, `false` or `undefined` otherwise.
+ */
+export interface MouseModifiers {
     alt?: boolean;
     ctrl?: boolean;
     shift?: boolean;
 }
-declare const encodeMouseButtonByte: (button: MouseButtonType, motion: boolean, modifiers?: MouseModifiers) => number;
-declare const mouseX10Sequence: (callback: number, x: number, y: number) => string;
-declare const mouseSgrSequence: (callback: number, x: number, y: number, isRelease: boolean) => string;
-declare const enableX10Mouse: string;
-declare const disableX10Mouse: string;
-declare const enableNormalMouse: string;
-declare const disableNormalMouse: string;
-declare const enableButtonEventMouse: string;
-declare const disableButtonEventMouse: string;
-declare const enableAnyEventMouse: string;
-declare const disableAnyEventMouse: string;
-declare const enableSgrMouse: string;
-declare const disableSgrMouse: string;
-declare const enableFocusTracking: string;
-declare const disableFocusTracking: string;
-
-export { MouseButton, disableAnyEventMouse, disableButtonEventMouse, disableFocusTracking, disableNormalMouse, disableSgrMouse, disableX10Mouse, enableAnyEventMouse, enableButtonEventMouse, enableFocusTracking, enableNormalMouse, enableSgrMouse, enableX10Mouse, encodeMouseButtonByte, mouseSgrSequence, mouseX10Sequence };
-export type { MouseButtonType, MouseModifiers };
+/**
+ * Encodes a mouse button, motion status, and modifiers into a single byte (Cb)
+ * for use in X10 and SGR mouse tracking protocols.
+ *
+ * The encoded byte combines button information, whether it's a motion event,
+ * and the state of Shift, Alt, and Ctrl keys.
+ * @param button The {@link MouseButtonType} representing the button pressed or wheel action.
+ * @param motion `true` if this is a motion event, `false` otherwise.
+ * @param modifiers An optional {@link MouseModifiers} object indicating active modifier keys.
+ * @returns The encoded byte (Cb). Returns `0xFF` (255) if the provided `button` is invalid or not recognized.
+ * @example
+ * ```typescript
+ * import { encodeMouseButtonByte, MouseButton, MouseModifiers } from \'@visulima/ansi/mouse\';
+ *
+ * // Left button press, no motion, no modifiers
+ * const cb1 = encodeMouseButtonByte(MouseButton.LEFT, false);
+ * console.log(cb1); // Output: 0
+ *
+ * // Middle button press, with motion, Shift key held
+ * const cb2 = encodeMouseButtonByte(MouseButton.MIDDLE, true, { shift: true });
+ * console.log(cb2); // Output: 37 (Middle=1 + Shift=4 + Motion=32)
+ *
+ * // Wheel up, no motion, Alt and Ctrl held
+ * const cb3 = encodeMouseButtonByte(MouseButton.WHEEL_UP, false, { alt: true, ctrl: true });
+ * console.log(cb3); // Output: 88 (WheelUp=0 + WheelFlag=64 + Alt=8 + Ctrl=16)
+ *
+ * // Release event
+ * const cb4 = encodeMouseButtonByte(MouseButton.RELEASE, false);
+ * console.log(cb4); // Output: 3
+ * ```
+ */
+export declare const encodeMouseButtonByte: (button: MouseButtonType, motion: boolean, modifiers?: MouseModifiers) => number;
+/**
+ * Generates an X10 mouse tracking escape sequence.
+ * Format: `CSI M Cb Cx Cy`
+ * Where `Cb`, `Cx`, `Cy` are characters derived by adding {@link X10_MOUSE_OFFSET} (32) to the
+ * encoded button byte, 1-based X coordinate, and 1-based Y coordinate, respectively.
+ *
+ * This is an older mouse reporting protocol, primarily reporting button presses.
+ * @param callback The encoded button byte, typically from {@link encodeMouseButtonByte}.
+ * @param x The 0-indexed X coordinate of the mouse event.
+ * @param y The 0-indexed Y coordinate of the mouse event.
+ * @returns The X10 mouse sequence string. Returns an empty string if `cb` is `0xFF` (invalid).
+ * @example
+ * ```typescript
+ * import { mouseX10Sequence, encodeMouseButtonByte, MouseButton } from \'@visulima/ansi/mouse\';
+ *
+ * const cb = encodeMouseButtonByte(MouseButton.LEFT, false);
+ * const seq = mouseX10Sequence(cb, 10, 20); // Coordinates are 0-indexed
+ * // Result: "\u001b[M!+5" (Cb=0 -> char 32, Cx=11 -> char 43, Cy=21 -> char 53)
+ * console.log(seq);
+ * ```
+ */
+export declare const mouseX10Sequence: (callback: number, x: number, y: number) => string;
+/**
+ * Generates an SGR (Select Graphic Rendition) style mouse tracking escape sequence.
+ * This is a more modern and robust mouse reporting format.
+ *
+ * Format for press/motion: `CSI < Cb ; Px ; Py M`
+ * Format for release: `CSI < Cb ; Px ; Py m`
+ *
+ * `Cb` is the encoded button byte (see {@link encodeMouseButtonByte}).
+ * `Px` and `Py` are 1-based X and Y coordinates.
+ * @param callback The encoded button byte from {@link encodeMouseButtonByte}.
+ * @param x The 0-indexed X coordinate of the mouse event.
+ * @param y The 0-indexed Y coordinate of the mouse event.
+ * @param isRelease `true` if this is a button release event (sequence ends with `m`),
+ * `false` for press or motion events (sequence ends with `M`).
+ * @returns The SGR mouse sequence string. Returns an empty string if `cb` is `0xFF` (invalid).
+ * @example
+ * ```typescript
+ * import { mouseSgrSequence, encodeMouseButtonByte, MouseButton } from \'@visulima/ansi/mouse\';
+ *
+ * // Left button press at (10, 20)
+ * const cbPress = encodeMouseButtonByte(MouseButton.LEFT, false);
+ * const seqPress = mouseSgrSequence(cbPress, 10, 20, false);
+ * console.log(seqPress); // Output: "\u001b[<0;11;21M"
+ *
+ * // Left button release at (10, 20)
+ * const cbRelease = encodeMouseButtonByte(MouseButton.RELEASE, false); // Or use original button with isRelease=true
+ * const seqRelease = mouseSgrSequence(cbPress, 10, 20, true); // cbPress (0) is fine for release with SGR if button info isn't needed for release
+ * console.log(seqRelease); // Output: "\u001b[<0;11;21m"
+ * // If using explicit release button code from encodeMouseButtonByte:
+ * const cbExplicitRelease = encodeMouseButtonByte(MouseButton.RELEASE, false);
+ * const seqExplicitRelease = mouseSgrSequence(cbExplicitRelease, 10, 20, true);
+ * console.log(seqExplicitRelease); // Output: "\u001b[<3;11;21m"
+ *
+ * // Motion with middle button and Shift key at (5,5)
+ * const cbMotion = encodeMouseButtonByte(MouseButton.MIDDLE, true, { shift: true });
+ * const seqMotion = mouseSgrSequence(cbMotion, 5, 5, false);
+ * console.log(seqMotion); // Output: "\u001b[<37;6;6M"
+ * ```
+ */
+export declare const mouseSgrSequence: (callback: number, x: number, y: number, isRelease: boolean) => string;
+/**
+ * Enables X10 compatibility mouse reporting (DECSET 9).
+ * This is an older protocol that typically reports only button press events.
+ * The format is `CSI M Cb Cx Cy`.
+ * @see {@link disableX10Mouse}
+ * @see {@link mouseX10Sequence}
+ */
+export declare const enableX10Mouse: string;
+/**
+ * Disables X10 compatibility mouse reporting (DECRST 9).
+ * @see {@link enableX10Mouse}
+ */
+export declare const disableX10Mouse: string;
+/**
+ * Enables Normal Tracking mode, also known as VT200 mouse reporting (DECSET 1000).
+ * Reports button press and release events.
+ * Uses X10-style coordinate encoding if SGR mode is not also active.
+ * @see {@link disableNormalMouse}
+ */
+export declare const enableNormalMouse: string;
+/**
+ * Disables Normal Tracking mode / VT200 mouse reporting (DECRST 1000).
+ * @see {@link enableNormalMouse}
+ */
+export declare const disableNormalMouse: string;
+/**
+ * Enables Button-Event tracking mouse reporting (DECSET 1002).
+ * Reports press, release, and mouse motion when a button is held down.
+ * @see {@link disableButtonEventMouse}
+ */
+export declare const enableButtonEventMouse: string;
+/**
+ * Disables Button-Event tracking mouse reporting (DECRST 1002).
+ * @see {@link enableButtonEventMouse}
+ */
+export declare const disableButtonEventMouse: string;
+/**
+ * Enables Any-Event mouse reporting (DECSET 1003).
+ * Reports press, release, and all mouse motion (including hover when no buttons are pressed).
+ * This is the most comprehensive mouse motion tracking mode (excluding pixel-level reporting).
+ * @see {@link disableAnyEventMouse}
+ */
+export declare const enableAnyEventMouse: string;
+/**
+ * Disables Any-Event mouse reporting (DECRST 1003).
+ * @see {@link enableAnyEventMouse}
+ */
+export declare const disableAnyEventMouse: string;
+/**
+ * Enables SGR (Select Graphic Rendition) Extended mouse reporting (DECSET 1006).
+ * Event data is sent in a more robust format: `CSI < Cb ; Px ; Py M` (press) or `m` (release).
+ * This mode is generally preferred for new applications due to its clarity and ability
+ * to handle coordinates larger than 95 without ambiguity with UTF-8 characters.
+ * @see {@link disableSgrMouse}
+ * @see {@link mouseSgrSequence}
+ */
+export declare const enableSgrMouse: string;
+/**
+ * Disables SGR Extended mouse reporting (DECRST 1006).
+ * @see {@link enableSgrMouse}
+ */
+export declare const disableSgrMouse: string;
+/**
+ * Enables FocusIn/FocusOut event reporting (DECSET 1004).
+ * The terminal will send `CSI I` when it gains focus and `CSI O` when it loses focus.
+ * @see {@link disableFocusTracking}
+ */
+export declare const enableFocusTracking: string;
+/**
+ * Disables FocusIn/FocusOut event reporting (DECRST 1004).
+ * @see {@link enableFocusTracking}
+ */
+export declare const disableFocusTracking: string;

package/dist/passthrough.d.ts

@@ -1,6 +1,77 @@
-declare const SCREEN_MAX_LEN_DEFAULT: number;
-declare const SCREEN_TYPICAL_LIMIT: number;
-declare const screenPassthrough: (sequence: string, limit?: number) => string;
-declare const tmuxPassthrough: (sequence: string) => string;
-
-export { SCREEN_MAX_LEN_DEFAULT, SCREEN_TYPICAL_LIMIT, screenPassthrough, tmuxPassthrough };
+/**
+ * Default value for the `limit` parameter in {@link screenPassthrough}, indicating no chunking.
+ * When this value is used (or any value <= 0), the passthrough sequence is not split into smaller chunks.
+ */
+export declare const SCREEN_MAX_LEN_DEFAULT: number;
+/**
+ * A typical limit for string sequences in GNU Screen (e.g., 768 bytes).
+ * This constant can be used as a practical value for the `limit` parameter in {@link screenPassthrough}
+ * to avoid issues with Screen's internal buffers, though the function itself defaults to no limit.
+ * It's provided for informational purposes and as a suggested practical chunking limit.
+ */
+export declare const SCREEN_TYPICAL_LIMIT: number;
+/**
+ * Wraps a given ANSI escape sequence in a DCS (Device Control String) passthrough sequence
+ * specifically for GNU Screen. This allows raw escape sequences to be sent to the
+ * terminal emulator that is hosting Screen, bypassing Screen's own interpretation.
+ *
+ * The basic format is: `DCS <data> ST` (where `DCS` is `ESC P` and `ST` is `ESC \`).
+ *
+ * GNU Screen has limitations on the length of string sequences it can handle (often around 768 bytes).
+ * This function can optionally chunk the input `sequence` into smaller parts, each wrapped
+ * in its own `DCS...ST` sequence, to work around this limitation.
+ * @param sequence The ANSI escape sequence string to be wrapped.
+ * @param limit The maximum length for each chunk of the `sequence` before it's wrapped.
+ * If `0` or a negative number, the sequence is not chunked. Defaults to {@link SCREEN_MAX_LEN_DEFAULT} (0).
+ * Consider using {@link SCREEN_TYPICAL_LIMIT} (768) for practical chunking with Screen.
+ * @returns The wrapped string, possibly chunked into multiple `DCS...ST` sequences if `limit` is positive and the `sequence` exceeds it.
+ * @see {@link https://www.gnu.org/software/screen/manual/screen.html#String-Escapes} GNU Screen Manual - String Escapes.
+ * @example
+ * ```typescript
+ * import { screenPassthrough, SCREEN_TYPICAL_LIMIT } from \'@visulima/ansi/passthrough\';
+ * import { cursorShow, cursorHide } from \'@visulima/ansi/cursor\';
+ *
+ * const longSequence = cursorHide + "Some very long output..." + cursorShow;
+ *
+ * // No chunking (default behavior if sequence is short enough or limit is 0)
+ * const passthrough1 = screenPassthrough(cursorHide);
+ * console.log(JSON.stringify(passthrough1)); // "\u001bP?25l\u001b\\"
+ *
+ * // With chunking, assuming SCREEN_TYPICAL_LIMIT is small for demonstration
+ * const limitedPassthrough = screenPassthrough(longSequence, 10); // Hypothetical small limit
+ * // Example output if longSequence was "0123456789abcde" and limit 10:
+ * // "\u001bP0123456789\u001b\\\u001bPabcde\u001b\\"
+ * console.log(JSON.stringify(limitedPassthrough));
+ * ```
+ */
+export declare const screenPassthrough: (sequence: string, limit?: number) => string;
+/**
+ * Wraps a given ANSI escape sequence in a special DCS (Device Control String) passthrough sequence
+ * designed for tmux (Terminal Multiplexer). This allows raw escape sequences to be sent to the
+ * terminal emulator hosting tmux, bypassing tmux's own interpretation.
+ *
+ * The format is: `DCS tmux ; <escaped-data> ST`
+ * (where `DCS` is `ESC P`, and `ST` is `ESC \`).
+ *
+ * The `<escaped-data>` is the original `sequence` with all occurrences of the ESC character (`\u001B`)
+ * doubled (i.e., `ESC` becomes `ESC ESC`).
+ *
+ * **Note:** For this to work, the tmux option `allow-passthrough` must be enabled (`on`) in the tmux configuration.
+ * By default, it might be off.
+ * @param sequence The ANSI escape sequence string to be wrapped and properly escaped for tmux.
+ * @returns The wrapped and escaped string suitable for tmux passthrough.
+ * @see {@link https://github.com/tmux/tmux/wiki/FAQ#what-is-the-passthrough-escape-sequence-and-how-do-i-use-it} Tmux FAQ on Passthrough.
+ * @example
+ * ```typescript
+ * import { tmuxPassthrough } from \'@visulima/ansi/passthrough\';
+ * import { cursorShow } from \'@visulima/ansi/cursor\';
+ *
+ * const originalSequence = cursorShow; // e.g., "\u001b[?25h"
+ * const passthrough = tmuxPassthrough(originalSequence);
+ *
+ * // Expected: "\u001bPtmux;\u001b\u001b[?25h\u001b\\"
+ * // (ESC P tmux ; ESC ESC [ ? 2 5 h ESC \)
+ * console.log(JSON.stringify(passthrough));
+ * ```
+ */
+export declare const tmuxPassthrough: (sequence: string) => string;

package/dist/progress.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resets the progress bar to its default state (hidden).
+ *
+ * Sequence: `OSC 9 ; 4 ; 0 BEL`
+ * @see {@link https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences}
+ */
+export declare const resetProgressBar: string;
+/**
+ * Returns a sequence for setting the progress bar to a specific percentage (0-100) in the "default" state.
+ *
+ * Sequence: `OSC 9 ; 4 ; 1 ; Percentage BEL`
+ * @param percentage The progress percentage (0-100, clamped automatically)
+ * @returns The progress bar sequence
+ * @see {@link https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences}
+ */
+export declare const setProgressBar: (percentage: number) => string;
+/**
+ * Returns a sequence for setting the progress bar to a specific percentage (0-100) in the "Error" state.
+ *
+ * Sequence: `OSC 9 ; 4 ; 2 ; Percentage BEL`
+ * @param percentage The progress percentage (0-100, clamped automatically)
+ * @returns The error progress bar sequence
+ * @see {@link https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences}
+ */
+export declare const setErrorProgressBar: (percentage: number) => string;
+/**
+ * Sets the progress bar to the indeterminate state.
+ *
+ * Sequence: `OSC 9 ; 4 ; 3 BEL`
+ * @see {@link https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences}
+ */
+export declare const setIndeterminateProgressBar: string;
+/**
+ * Returns a sequence for setting the progress bar to a specific percentage (0-100) in the "Warning" state.
+ *
+ * Sequence: `OSC 9 ; 4 ; 4 ; Percentage BEL`
+ * @param percentage The progress percentage (0-100, clamped automatically)
+ * @returns The warning progress bar sequence
+ * @see {@link https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences}
+ */
+export declare const setWarningProgressBar: (percentage: number) => string;

package/dist/reset.d.ts

@@ -1,4 +1,26 @@
-declare const RESET_INITIAL_STATE: string;
-declare const RIS: string;
-
-export { RESET_INITIAL_STATE, RIS };
+/**
+ * The ANSI escape sequence for Reset Initial State (RIS).
+ * This command attempts to reset the terminal to its power-up state or initial configuration.
+ * The exact behavior can vary between terminal emulators, but it typically includes:
+ * - Resetting graphic rendition (SGR parameters) to default.
+ * - Clearing the screen.
+ * - Moving the cursor to the top-left (home position).
+ * - Resetting character sets.
+ * - Resetting tab stops.
+ * - Resetting modes (like DECAWM, DECOM) to their defaults.
+ *
+ * Sequence: `ESC c`
+ *
+ * This is a more comprehensive reset than `CSI 0 m` (which only resets SGR) or `CSI 2 J` (which only clears the screen).
+ * It is often referred to as a "hard reset".
+ * @see {@link https://vt100.net/docs/vt510-rm/RIS.html VT510 RIS Documentation}
+ * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Reset} Xterm Control Sequences - Reset
+ */
+export declare const RESET_INITIAL_STATE: string;
+/**
+ * Alias for {@link RESET_INITIAL_STATE} (Reset Initial State).
+ *
+ * Provides a shorter name for the RIS sequence `ESC c`.
+ * @see {@link RESET_INITIAL_STATE}
+ */
+export declare const RIS: string;

package/dist/screen.d.ts

@@ -1,11 +1,234 @@
-declare const insertLine: (count?: number) => string;
-declare const deleteLine: (count?: number) => string;
-declare const setTopBottomMargins: (top?: number | null, bottom?: number | null) => string;
-declare const setLeftRightMargins: (left?: number | null, right?: number | null) => string;
-declare const insertCharacter: (count?: number) => string;
-declare const deleteCharacter: (count?: number) => string;
-declare const clearTabStop: (mode?: 0 | 3) => string;
-declare const requestPresentationStateReport: (mode: 0 | 1 | 2) => string;
-declare const repeatPreviousCharacter: (count?: number) => string;
-
-export { clearTabStop, deleteCharacter, deleteLine, insertCharacter, insertLine, repeatPreviousCharacter, requestPresentationStateReport, setLeftRightMargins, setTopBottomMargins };
+/**
+ * Inserts a specified number of blank lines at the current cursor position.
+ * (IL - Insert Line)
+ *
+ * Existing lines from the cursor position to the bottom margin are moved downwards.
+ * Lines moved past the bottom margin are lost. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to inserting one line.
+ *
+ * Sequence: `CSI Pn L`
+ * - `Pn`: Number of lines to insert (default: 1).
+ * @param count The number of blank lines to insert. Defaults to 1.
+ * @returns The ANSI escape sequence for inserting lines.
+ * @see {@link https://vt100.net/docs/vt510-rm/IL.html VT510 IL Documentation}
+ * @example
+ * ```typescript
+ * import { insertLine } from \'@visulima/ansi/screen\';
+ *
+ * // Insert 1 line (default)
+ * process.stdout.write(insertLine()); // CSI L
+ *
+ * // Insert 5 lines
+ * process.stdout.write(insertLine(5)); // CSI 5L
+ * ```
+ */
+export declare const insertLine: (count?: number) => string;
+/**
+ * Deletes a specified number of lines starting from the line with the cursor.
+ * (DL - Delete Line)
+ *
+ * Lines below the deleted ones are moved upwards. Blank lines are added at the bottom
+ * of the scrolling region to fill the gap. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to deleting one line.
+ *
+ * Sequence: `CSI Pn M`
+ * - `Pn`: Number of lines to delete (default: 1).
+ * @param count The number of lines to delete. Defaults to 1.
+ * @returns The ANSI escape sequence for deleting lines.
+ * @see {@link https://vt100.net/docs/vt510-rm/DL.html VT510 DL Documentation}
+ * @example
+ * ```typescript
+ * import { deleteLine } from \'@visulima/ansi/screen\';
+ *
+ * // Delete 1 line (default)
+ * process.stdout.write(deleteLine()); // CSI M
+ *
+ * // Delete 3 lines
+ * process.stdout.write(deleteLine(3)); // CSI 3M
+ * ```
+ */
+export declare const deleteLine: (count?: number) => string;
+/**
+ * Sets the top and bottom margins, defining the scrolling region.
+ * (DECSTBM - Set Top and Bottom Margins)
+ *
+ * Cursor movement is typically confined to this region, especially when Origin Mode (DECOM) is active.
+ * If parameters are omitted or invalid (e.g., `0`, `null`, `undefined`), they usually default to the
+ * screen's current extents (e.g., line 1 for top, last line for bottom).
+ *
+ * Sequence: `CSI Pt ; Pb r`
+ * - `Pt`: Line number for the top margin (1-indexed). Default: 1.
+ * - `Pb`: Line number for the bottom margin (1-indexed). Default: screen height.
+ * @param top The line number for the top margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted, implying default.
+ * @param bottom The line number for the bottom margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted, implying default.
+ * @returns The ANSI escape sequence for DECSTBM.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSTBM.html VT510 DECSTBM Documentation}
+ * @example
+ * ```typescript
+ * import { setTopBottomMargins } from \'@visulima/ansi/screen\';
+ *
+ * // Set scrolling region from line 5 to 20
+ * process.stdout.write(setTopBottomMargins(5, 20)); // CSI 5;20r
+ *
+ * // Reset to default margins (full screen)
+ * process.stdout.write(setTopBottomMargins()); // CSI ;r
+ * ```
+ */
+export declare const setTopBottomMargins: (top?: number | null, bottom?: number | null) => string;
+/**
+ * Sets the left and right margins for the page or screen, defining horizontal boundaries.
+ * (DECSLRM - Set Left and Right Margins)
+ *
+ * This command is common on VT420+ terminals and xterm.
+ * If parameters are omitted or invalid, they usually default to the screen's current extents
+ * (e.g., column 1 for left, last column for right).
+ *
+ * Sequence: `CSI Pl ; Pr s`
+ * - `Pl`: Column number for the left margin (1-indexed). Default: 1.
+ * - `Pr`: Column number for the right margin (1-indexed). Default: screen width.
+ *
+ * Note: The final character 's' should not be confused with save cursor sequences.
+ * @param left The column number for the left margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted.
+ * @param right The column number for the right margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted.
+ * @returns The ANSI escape sequence for DECSLRM.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSLRM.html VT510 DECSLRM Documentation}
+ * @example
+ * ```typescript
+ * import { setLeftRightMargins } from \'@visulima/ansi/screen\';
+ *
+ * // Set left margin to 10, right margin to 70
+ * process.stdout.write(setLeftRightMargins(10, 70)); // CSI 10;70s
+ *
+ * // Reset to default margins (full width)
+ * process.stdout.write(setLeftRightMargins());      // CSI ;s
+ * ```
+ */
+export declare const setLeftRightMargins: (left?: number | null, right?: number | null) => string;
+/**
+ * Inserts a specified number of blank characters at the current cursor position.
+ * (ICH - Insert CHaracter)
+ *
+ * Existing characters from the cursor position to the right margin are shifted to the right.
+ * Characters shifted past the right margin are lost. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to inserting one character.
+ *
+ * Sequence: `CSI Pn @`
+ * - `Pn`: Number of blank characters to insert (default: 1).
+ * @param count The number of blank characters to insert. Defaults to 1.
+ * @returns The ANSI escape sequence for inserting characters.
+ * @see {@link https://vt100.net/docs/vt510-rm/ICH.html VT510 ICH Documentation}
+ * @example
+ * ```typescript
+ * import { insertCharacter } from \'@visulima/ansi/screen\';
+ *
+ * // Insert 1 character (default)
+ * process.stdout.write(insertCharacter()); // CSI @
+ *
+ * // Insert 10 characters
+ * process.stdout.write(insertCharacter(10)); // CSI 10@
+ * ```
+ */
+export declare const insertCharacter: (count?: number) => string;
+/**
+ * Deletes a specified number of characters starting from the current cursor position.
+ * (DCH - Delete CHaracter)
+ *
+ * Remaining characters on the line (to the right of the cursor) are shifted to the left.
+ * Character attributes move with the characters. Blank characters with default attributes
+ * are inserted at the right margin. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to deleting one character.
+ *
+ * Sequence: `CSI Pn P`
+ * - `Pn`: Number of characters to delete (default: 1).
+ * @param count The number of characters to delete. Defaults to 1.
+ * @returns The ANSI escape sequence for deleting characters.
+ * @see {@link https://vt100.net/docs/vt510-rm/DCH.html VT510 DCH Documentation}
+ * @example
+ * ```typescript
+ * import { deleteCharacter } from \'@visulima/ansi/screen\';
+ *
+ * // Delete 1 character (default)
+ * process.stdout.write(deleteCharacter()); // CSI P
+ *
+ * // Delete 5 characters
+ * process.stdout.write(deleteCharacter(5)); // CSI 5P
+ * ```
+ */
+export declare const deleteCharacter: (count?: number) => string;
+/**
+ * Clears horizontal tab stops.
+ * (TBC - Tabulation Clear)
+ *
+ * Sequence: `CSI Ps g`
+ * - `Ps = 0` (or omitted): Clear horizontal tab stop at the current column (default).
+ * - `Ps = 3`: Clear all horizontal tab stops in the current line (or all lines, terminal-dependent).
+ * @param mode Specifies which tab stops to clear:
+ * - `0`: Clear tab stop at the current cursor column (default).
+ * - `3`: Clear all horizontal tab stops.
+ * @returns The ANSI escape sequence for clearing tab stops.
+ * @see {@link https://vt100.net/docs/vt510-rm/TBC.html VT510 TBC Documentation}
+ * @example
+ * ```typescript
+ * import { clearTabStop } from \'@visulima/ansi/screen\';
+ *
+ * // Clear tab stop at current column
+ * process.stdout.write(clearTabStop(0)); // CSI 0g
+ * process.stdout.write(clearTabStop());  // CSI 0g (default)
+ *
+ * // Clear all tab stops
+ * process.stdout.write(clearTabStop(3)); // CSI 3g
+ * ```
+ */
+export declare const clearTabStop: (mode?: 0 | 3) => string;
+/**
+ * Requests a report of the terminal's presentation state.
+ * (DECRQPSR - Request Presentation State Report)
+ *
+ * The terminal responds with a corresponding report sequence (e.g., DECTPSSR, DECSGRSR, DECCPSR).
+ * This is useful for querying current SGR settings, color palette, etc.
+ *
+ * Sequence: `CSI Ps $ u`
+ * - `Ps = 0`: Report Text Presentation State (DECTPSSR) - font, decoration, etc.
+ * - `Ps = 1`: Report SGR State (DECSGRSR) - current graphic rendition attributes.
+ * - `Ps = 2`: Report Color Palette State (DECCPSR) - color table contents.
+ * @param mode Specifies the type of presentation state report requested:
+ * - `0`: Text Presentation State (DECTPSSR).
+ * - `1`: SGR State (DECSGRSR).
+ * - `2`: Color Palette State (DECCPSR).
+ * @returns The ANSI escape sequence to request the presentation state report.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECRQPSR.html VT510 DECRQPSR Documentation}
+ * @example
+ * ```typescript
+ * import { requestPresentationStateReport } from \'@visulima/ansi/screen\';
+ *
+ * // Request SGR state
+ * process.stdout.write(requestPresentationStateReport(1)); // CSI 1$u
+ * ```
+ */
+export declare const requestPresentationStateReport: (mode: 0 | 1 | 2) => string;
+/**
+ * Repeats the preceding graphic character a specified number of times.
+ * (REP - Repeat Previous Character)
+ *
+ * The character repeated is the last non-control character that was processed by the terminal.
+ * If the parameter `count` is 0 or 1, it defaults to repeating one time (i.e., printing it again).
+ *
+ * Sequence: `CSI Pn b`
+ * - `Pn`: Number of times to repeat the character (default: 1).
+ * @param count The number of times to repeat the preceding graphic character. Defaults to 1.
+ * @returns The ANSI escape sequence for repeating the previous character.
+ * @see {@link https://vt100.net/docs/vt510-rm/REP.html VT510 REP Documentation (though REP is less common or behavior varies)}
+ * @example
+ * ```typescript
+ * import { repeatPreviousCharacter } from \'@visulima/ansi/screen\';
+ *
+ * process.stdout.write("A");
+ * // Repeat 'A' 5 times
+ * process.stdout.write(repeatPreviousCharacter(5)); // Output: AAAAA (total 6 'A's)
+ *
+ * process.stdout.write("B");
+ * // Repeat 'B' 1 time (default)
+ * process.stdout.write(repeatPreviousCharacter()); // Output: BB (total 2 'B's)
+ * ```
+ */
+export declare const repeatPreviousCharacter: (count?: number) => string;