@visulima/ansi 3.0.3 → 3.0.5

package/dist/erase.d.ts

@@ -1,23 +1,206 @@
-declare enum EraseDisplayMode {
+/**
+ * Defines the modes for erasing parts of the display using the ED (Erase in Display) sequence.
+ * The ED sequence is `CSI Ps J`, where `Ps` is one of these mode values.
+ * @see {@link eraseDisplay} for the function that generates ED sequences.
+ * @see {@link https://vt100.net/docs/vt510-rm/ED.html} VT510 Erase in Display (ED) documentation.
+ * @enum {number}
+ */
+export declare enum EraseDisplayMode {
+    /**
+     * Clears the entire screen. The cursor position usually does not change, but this can be
+     * terminal-dependent. Some terminals might move the cursor to the home position (top-left).
+     * This corresponds to `Ps=2` in `CSI Ps J`.
+     * Sequence: `CSI 2J`.
+     */
     EntireScreen = 2,
+    /**
+     * Clears the entire screen and, on supported terminals (like XTerm and derivatives),
+     * also deletes all lines saved in the scrollback buffer.
+     * This corresponds to `Ps=3` in `CSI Ps J` (an XTerm extension, widely adopted).
+     * Sequence: `CSI 3J`.
+     * @remarks This mode is particularly useful for a more complete "reset" of the terminal view.
+     */
     EntireScreenAndScrollback = 3,
+    /**
+     * Clears from the beginning of the screen to the current cursor position (inclusive).
+     * This corresponds to `Ps=1` in `CSI Ps J`.
+     * Sequence: `CSI 1J`.
+     */
     ToBeginning = 1,
+    /**
+     * Clears from the current cursor position to the end of the screen (inclusive).
+     * If the cursor is at the top-left, this clears the entire screen.
+     * This corresponds to `Ps=0` (or `Ps` omitted) in `CSI Ps J`.
+     * Sequence: `CSI J` or `CSI 0J`.
+     */
     ToEnd = 0
 }
-declare const eraseDisplay: (mode: EraseDisplayMode | 0 | 1 | 2 | 3) => string;
-declare enum EraseLineMode {
+/**
+ * Generates an ANSI escape sequence to erase parts of the display (ED - Erase in Display).
+ * The specific sequence is `CSI <mode>J`, where `<mode>` is a parameter from {@link EraseDisplayMode}.
+ *
+ * - If `mode` is `EraseDisplayMode.ToEnd` (or `0`), the sequence can be shortened to `CSI J`.
+ * - The function validates the input `mode`. If an invalid number is provided, it defaults to `EraseDisplayMode.ToEnd`.
+ * @param mode The erase mode, specified as a value from `EraseDisplayMode` or its corresponding number (0, 1, 2, 3).
+ * @returns The ANSI escape sequence string for erasing in display.
+ * @example
+ * ```typescript
+ * import { eraseDisplay, EraseDisplayMode } from '@visulima/ansi/erase';
+ *
+ * // Erase from cursor to end of screen
+ * process.stdout.write(eraseDisplay(EraseDisplayMode.ToEnd)); // or eraseDisplay(0)
+ *
+ * // Erase entire screen
+ * process.stdout.write(eraseDisplay(EraseDisplayMode.EntireScreen)); // or eraseDisplay(2)
+ *
+ * // Erase entire screen and scrollback buffer
+ * process.stdout.write(eraseDisplay(EraseDisplayMode.EntireScreenAndScrollback)); // or eraseDisplay(3)
+ * ```
+ * @see {@link EraseDisplayMode}
+ * @see {@link https://vt100.net/docs/vt510-rm/ED.html} VT510 Erase in Display (ED) documentation.
+ */
+export declare const eraseDisplay: (mode: EraseDisplayMode | 0 | 1 | 2 | 3) => string;
+/**
+ * Defines the modes for erasing parts of the current line using the EL (Erase in Line) sequence.
+ * The EL sequence is `CSI Ps K`, where `Ps` is one of these mode values.
+ * The cursor position is NOT affected by EL sequences.
+ * @see {@link eraseInLine} for the function that generates EL sequences.
+ * @see {@link https://vt100.net/docs/vt510-rm/EL.html} VT510 Erase in Line (EL) documentation.
+ * @enum {number}
+ */
+export declare enum EraseLineMode {
+    /**
+     * Clears the entire current line.
+     * This corresponds to `Ps=2` in `CSI Ps K`.
+     * Sequence: `CSI 2K`.
+     */
     EntireLine = 2,
+    /**
+     * Clears from the beginning of the line to the current cursor position (inclusive).
+     * This corresponds to `Ps=1` in `CSI Ps K`.
+     * Sequence: `CSI 1K`.
+     */
     ToBeginning = 1,
+    /**
+     * Clears from the current cursor position to the end of the line (inclusive).
+     * This corresponds to `Ps=0` (or `Ps` omitted) in `CSI Ps K`.
+     * Sequence: `CSI K` or `CSI 0K`.
+     */
     ToEnd = 0
 }
-declare const eraseInLine: (mode: EraseLineMode | 0 | 1 | 2) => string;
-declare const eraseDown: string;
-declare const eraseLine: string;
-declare const eraseLineEnd: string;
-declare const eraseLineStart: string;
-declare const eraseLines: (count: number) => string;
-declare const eraseScreen: string;
-declare const eraseUp: string;
-declare const eraseScreenAndScrollback: string;
-
-export { EraseDisplayMode, EraseLineMode, eraseDisplay, eraseDown, eraseInLine, eraseLine, eraseLineEnd, eraseLineStart, eraseLines, eraseScreen, eraseScreenAndScrollback, eraseUp };
+/**
+ * Generates an ANSI escape sequence to erase parts of the current line (EL - Erase in Line).
+ * The specific sequence is `CSI <mode>K`, where `<mode>` is a parameter from {@link EraseLineMode}.
+ * The cursor position is NOT changed by this sequence.
+ *
+ * - If `mode` is `EraseLineMode.ToEnd` (or `0`), the sequence can be shortened to `CSI K`.
+ * - The function validates the input `mode`. If an invalid number is provided, it defaults to `EraseLineMode.ToEnd`.
+ * @param mode The erase mode, specified as a value from `EraseLineMode` or its corresponding number (0, 1, 2).
+ * @returns The ANSI escape sequence string for erasing in line.
+ * @example
+ * ```typescript
+ * import { eraseInLine, EraseLineMode } from '@visulima/ansi/erase';
+ *
+ * // Erase from cursor to end of line
+ * process.stdout.write(eraseInLine(EraseLineMode.ToEnd)); // or eraseInLine(0)
+ *
+ * // Erase entire current line
+ * process.stdout.write(eraseInLine(EraseLineMode.EntireLine)); // or eraseInLine(2)
+ * ```
+ * @see {@link EraseLineMode}
+ * @see {@link https://vt100.net/docs/vt510-rm/EL.html} VT510 Erase in Line (EL) documentation.
+ */
+export declare const eraseInLine: (mode: EraseLineMode | 0 | 1 | 2) => string;
+/**
+ * Erases the screen from the current cursor position down to the bottom of the screen (inclusive).
+ * This is a convenience constant for `eraseDisplay(EraseDisplayMode.ToEnd)`.
+ * Sequence: `CSI J` (or `CSI 0J`).
+ * @returns The ANSI escape sequence `CSI J`.
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.ToEnd}
+ */
+export declare const eraseDown: string;
+/**
+ * Erases the entire current line. The cursor position does not change.
+ * This is a convenience constant for `eraseInLine(EraseLineMode.EntireLine)`.
+ * Sequence: `CSI 2K`.
+ * @returns The ANSI escape sequence `CSI 2K`.
+ * @see {@link eraseInLine}
+ * @see {@link EraseLineMode.EntireLine}
+ */
+export declare const eraseLine: string;
+/**
+ * Erases from the current cursor position to the end of the current line (inclusive).
+ * The cursor position does not change.
+ * This is a convenience constant for `eraseInLine(EraseLineMode.ToEnd)`.
+ * Sequence: `CSI K` (or `CSI 0K`).
+ * @returns The ANSI escape sequence `CSI K`.
+ * @see {@link eraseInLine}
+ * @see {@link EraseLineMode.ToEnd}
+ */
+export declare const eraseLineEnd: string;
+/**
+ * Erases from the current cursor position to the beginning of the current line (inclusive).
+ * The cursor position does not change.
+ * This is a convenience constant for `eraseInLine(EraseLineMode.ToBeginning)`.
+ * Sequence: `CSI 1K`.
+ * @returns The ANSI escape sequence `CSI 1K`.
+ * @see {@link eraseInLine}
+ * @see {@link EraseLineMode.ToBeginning}
+ */
+export declare const eraseLineStart: string;
+/**
+ * Erases a specified number of lines, starting from the current line and moving upwards,
+ * then moves the cursor to the beginning of the topmost erased line (which becomes the new current line).
+ *
+ * This is a custom helper function, not a single standard ANSI/VT sequence. It combines
+ * multiple sequences: {@link eraseLine} to clear each line, {@link cursorUp} to move to the line above,
+ * and finally {@link cursorToColumn1} to position the cursor at the start of the resulting current line.
+ * @param count The total number of lines to erase. This includes the current line and `count-1` lines above it.
+ * If `count` is 0 or negative, an empty string is returned (no operation).
+ * @returns A string of concatenated ANSI escape sequences to perform the operation.
+ * @example
+ * ```typescript
+ * import { eraseLines } from '@visulima/ansi/erase';
+ *
+ * // To erase the current line and the 2 lines above it (total 3 lines):
+ * process.stdout.write(eraseLines(3));
+ * // Conceptual sequence of operations:
+ * // 1. Erase current line
+ * // 2. Cursor up
+ * // 3. Erase current line (which was the line above the original)
+ * // 4. Cursor up
+ * // 5. Erase current line (which was two lines above the original)
+ * // 6. Cursor to column 1 (on this topmost erased line)
+ * ```
+ */
+export declare const eraseLines: (count: number) => string;
+/**
+ * Erases the entire screen. The cursor position usually does not change, though this can be terminal-dependent.
+ * This is a convenience constant for `eraseDisplay(EraseDisplayMode.EntireScreen)`.
+ * Sequence: `CSI 2J`.
+ * @returns The ANSI escape sequence `CSI 2J`.
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.EntireScreen}
+ */
+export declare const eraseScreen: string;
+/**
+ * Erases the screen from the current cursor position up to the top of the screen (inclusive).
+ * This is a convenience constant for `eraseDisplay(EraseDisplayMode.ToBeginning)`.
+ * Sequence: `CSI 1J`.
+ * @returns The ANSI escape sequence `CSI 1J`.
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.ToBeginning}
+ */
+export declare const eraseUp: string;
+/**
+ * Erases the entire screen and, on supported terminals (like XTerm and derivatives),
+ * also deletes all lines saved in the scrollback buffer.
+ * This is a convenience constant for `eraseDisplay(EraseDisplayMode.EntireScreenAndScrollback)`.
+ * Sequence: `CSI 3J` (an XTerm extension, widely adopted).
+ * @returns The ANSI escape sequence `CSI 3J`.
+ * @remarks This mode is particularly useful for a more complete "reset" of the terminal view.
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.EntireScreenAndScrollback}
+ */
+export declare const eraseScreenAndScrollback: string;

package/dist/helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks if the current environment is a browser-like environment.
+ * It specifically checks for the presence of `globalThis.window.document`.
+ */
+/**
+ * Indicates whether the code is running inside Apple's Terminal.app.
+ * This is true if not in a browser and the `TERM_PROGRAM` environment variable is "Apple_Terminal".
+ */
+export declare const isTerminalApp: boolean;
+/**
+ * Indicates whether the current platform is Windows.
+ * This is true if not in a browser and `process.platform` is "win32".
+ */
+export declare const isWindows: boolean;

package/dist/hyperlink.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Creates a clickable hyperlink in the terminal.
+ *
+ * This function constructs an ANSI escape sequence that, when printed to a compatible terminal,
+ * renders as a clickable link. The link's visible text and its target URL are specified
+ * by the `text` and `url` parameters, respectively.
+ *
+ * For information on terminal support for hyperlinks, see this
+ * [Gist by Egmont Kob](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda).
+ * To programmatically check for hyperlink support in the current environment,
+ * consider using a library like [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks).
+ * @param text The visible text of the link.
+ * @param url The URL the link should point to.
+ * @returns A string representing the ANSI escape sequence for the hyperlink.
+ * @example
+ * ```typescript
+ * import { hyperlink } from "@visulima/ansi/hyperlink"; // Adjust import path as needed
+ *
+ * const aLink = hyperlink("Visulima", "https://www.visulima.com");
+ * console.log(`Visit ${aLink} for more information.`);
+ * // In a supported terminal, this will output:
+ * // Visit Visulima for more information. (where "Visulima" is a clickable link)
+ * ```
+ * @see {@link https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda} for supported terminals.
+ */
 declare const hyperlink: (text: string, url: string) => string;
-
-export { hyperlink as default };
+export default hyperlink;

package/dist/image.d.ts

@@ -1,11 +1,73 @@
-import { LiteralUnion } from 'type-fest';
-
-interface ImageOptions {
+import type { LiteralUnion } from "type-fest";
+/**
+ * Options for controlling the display of an inline image in iTerm2.
+ */
+export interface ImageOptions {
+    /**
+     * The display height of the image. It can be specified as:
+     * - A number: Interpreted as the number of character cells (e.g., `10`).
+     * - A string with `px`: Interpreted as pixels (e.g., `"100px"`).
+     * - A string with `%`: Interpreted as a percentage of the terminal session's height (e.g., `"50%"`).
+     * - The string `"auto"`: The image's inherent height will be used, or the terminal will decide.
+     */
     readonly height?: LiteralUnion<"auto", number | string>;
+    /**
+     * Controls whether the image's aspect ratio is preserved when scaling.
+     * - If `true` (default), the aspect ratio is preserved.
+     * - If `false`, the image may be stretched to fit the specified width and height.
+     * Corresponds to the `preserveAspectRatio` argument in the iTerm2 sequence (`1` for true, `0` for false).
+     * @default true
+     */
     readonly preserveAspectRatio?: boolean;
+    /**
+     * The display width of the image. It can be specified as:
+     * - A number: Interpreted as the number of character cells (e.g., `20`).
+     * - A string with `px`: Interpreted as pixels (e.g., `"200px"`).
+     * - A string with `%`: Interpreted as a percentage of the terminal session's width (e.g., `"75%"`).
+     * - The string `"auto"`: The image's inherent width will be used, or the terminal will decide.
+     */
     readonly width?: LiteralUnion<"auto", number | string>;
 }
-declare const image: (data: Uint8Array, options?: ImageOptions) => string;
-
-export { image };
-export type { ImageOptions };
+/**
+ * Generates an ANSI escape sequence for displaying an image inline, primarily for iTerm2.
+ *
+ * This function constructs a proprietary iTerm2 escape sequence (`OSC 1337 ; File = [arguments] : &lt;base64_data> BEL`)
+ * that allows raw image data to be displayed directly in the terminal.
+ * @param data The raw image data as a `Uint8Array`. This data will be Base64 encoded.
+ * @param options Optional parameters to control how the image is displayed (e.g., width, height, aspect ratio).
+ * See {@link ImageOptions}.
+ * @returns A string containing the ANSI escape sequence for displaying the image in iTerm2.
+ * Returns an empty string if `data` is null or undefined, though TypeScript should prevent this.
+ * @example
+ * ```typescript
+ * import { image } from '@visulima/ansi/image'; // Adjust import path
+ * import { promises as fs } from 'fs';
+ *
+ * async function displayImage() {
+ *   try {
+ *     const imageData = await fs.readFile('path/to/your/image.png');
+ *     const imageSequence = image(new Uint8Array(imageData), {
+ *       width: 50, // 50 character cells wide
+ *       height: "auto",
+ *       preserveAspectRatio: true,
+ *     });
+ *     console.log(imageSequence);
+ *   } catch (error) {
+ *     console.error("Error reading or displaying image:", error);
+ *   }
+ * }
+ *
+ * displayImage();
+ * ```
+ * @remarks
+ * - This sequence is specific to iTerm2 and may not work in other terminal emulators.
+ * - For Node.js environments, `Buffer.from(data).toString("base64")` is used for Base64 encoding.
+ * In browser environments, a polyfill or an alternative method for Base64 encoding `Uint8Array` would be necessary
+ * if `Buffer` is not available (e.g., `btoa(String.fromCharCode(...data))` after careful handling of binary data).
+ * - The `name` parameter (for filename) is not directly supported by this simplified helper but is part of the
+ * full iTerm2 inline image protocol. For more advanced features, consider using the more detailed iTerm2 sequence
+ * builders in `iterm2/` files.
+ * @see {@link https://iterm2.com/documentation-images.html} iTerm2 Inline Images Protocol.
+ * @see {@link ImageOptions}
+ */
+export declare const image: (data: Uint8Array, options?: ImageOptions) => string;

package/dist/index.d.ts

@@ -1,30 +1,36 @@
-export { ALT_SCREEN_OFF, ALT_SCREEN_ON, alternativeScreenOff, alternativeScreenOn } from './alternative-screen.js';
-export { clearLineAndHomeCursor, clearScreenAndHomeCursor, clearScreenFromTopLeft, resetTerminal } from './clear.js';
-export { CURSOR_BACKWARD_1, CURSOR_DOWN_1, CURSOR_FORWARD_1, CURSOR_UP_1, CursorStyle, REQUEST_CURSOR_POSITION, REQUEST_EXTENDED_CURSOR_POSITION, RESTORE_CURSOR_DEC, SAVE_CURSOR_DEC, cursorBackward, cursorBackwardTab, cursorDown, cursorForward, cursorHide, cursorHorizontalAbsolute, cursorHorizontalForwardTab, cursorLeft, cursorMove, cursorNextLine, cursorPosition, cursorPreviousLine, cursorRestore, cursorSave, cursorShow, cursorTo, cursorToColumn1, cursorUp, cursorVerticalAbsolute, eraseCharacter, setCursorStyle } from './cursor.js';
-export { EraseDisplayMode, EraseLineMode, eraseDisplay, eraseDown, eraseInLine, eraseLine, eraseLineEnd, eraseLineStart, eraseLines, eraseScreen, eraseScreenAndScrollback, eraseUp } from './erase.js';
-export { default as hyperlink } from './hyperlink.js';
-export { ImageOptions, image } from './image.js';
-export { IITerm2Payload, IT2_AUTO, ITerm2File, ITerm2FileEnd, ITerm2FilePart, ITerm2FileProperties, ITerm2MultipartFileStart, iTerm2, it2Cells, it2Percent, it2Pixels } from './iterm2.js';
-export { AnsiMode, BDSM, BiDirectionalSupportMode, BracketedPasteMode, DECRPM, DECRQM, DecMode, DisableModifiersMode, IRM, InBandResizeMode, InsertReplaceMode, KAM, KeyboardActionMode, LNM, LightDarkMode, LineFeedNewLineMode, LocalEchoMode, Mode, ModeSetting, OriginMode, RM, RequestBiDirectionalSupportMode, RequestInBandResizeMode, RequestInsertReplaceMode, RequestKeyboardActionMode, RequestLineFeedNewLineMode, RequestLocalEchoMode, RequestSendReceiveMode, RequestUnicodeCoreMode, ResetBiDirectionalSupportMode, ResetInBandResizeMode, ResetInsertReplaceMode, ResetKeyboardActionMode, ResetLineFeedNewLineMode, ResetLocalEchoMode, ResetSendReceiveMode, ResetUnicodeCoreMode, SGRMouseMode, SM, SRM, SendFocusEventsMode, SendReceiveMode, SetBiDirectionalSupportMode, SetInBandResizeMode, SetInsertReplaceMode, SetKeyboardActionMode, SetLineFeedNewLineMode, SetLocalEchoMode, SetSendReceiveMode, SetUnicodeCoreMode, TextCursorEnableMode, UnicodeCoreMode, createAnsiMode, createDecMode, isModeNotRecognized, isModePermanentlyReset, isModePermanentlySet, isModeReset, isModeSet, reportMode, requestMode, resetMode, setMode } from './mode.js';
-export { MouseButton, MouseButtonType, MouseModifiers, disableAnyEventMouse, disableButtonEventMouse, disableFocusTracking, disableNormalMouse, disableSgrMouse, disableX10Mouse, enableAnyEventMouse, enableButtonEventMouse, enableFocusTracking, enableNormalMouse, enableSgrMouse, enableX10Mouse, encodeMouseButtonByte, mouseSgrSequence, mouseX10Sequence } from './mouse.js';
-export { SCREEN_MAX_LEN_DEFAULT, SCREEN_TYPICAL_LIMIT, screenPassthrough, tmuxPassthrough } from './passthrough.js';
-export { RESET_INITIAL_STATE, RIS } from './reset.js';
-export { clearTabStop, deleteCharacter, deleteLine, insertCharacter, insertLine, repeatPreviousCharacter, requestPresentationStateReport, setLeftRightMargins, setTopBottomMargins } from './screen.js';
-export { SCROLL_DOWN_1, SCROLL_UP_1, scrollDown, scrollUp } from './scroll.js';
-export { AnsiStatusReport, CPR, DA1, DA2, DA3, DECXCPR, DSR, DSR_KeyboardLanguageDEC, DSR_PrinterStatusDEC, DSR_TerminalStatus, DSR_UDKStatusDEC, DecStatusReport, LightDarkReport, RequestLightDarkReport, RequestNameVersion, StatusReport, XTVERSION, createAnsiStatusReport, createDecStatusReport, cursorPositionReport, deviceStatusReport, extendedCursorPositionReport, reportKeyboardLanguageDEC, reportPrimaryDeviceAttributes, reportPrinterNoPaperDEC, reportPrinterNotReadyDEC, reportPrinterReadyDEC, reportSecondaryDeviceAttributes, reportTerminalNotOK, reportTerminalOK, reportTertiaryDeviceAttributes, reportUDKLockedDEC, reportUDKUnlockedDEC, requestCursorPositionReport, requestExtendedCursorPositionReport, requestKeyboardLanguageDEC, requestPrimaryDeviceAttributes, requestPrimaryDeviceAttributesParam0, requestPrinterStatusDEC, requestSecondaryDeviceAttributes, requestSecondaryDeviceAttributesParam0, requestTerminalStatus, requestTertiaryDeviceAttributes, requestTertiaryDeviceAttributesParam0, requestUDKStatusDEC } from './status.js';
-export { default as strip } from './strip.js';
-export { XTGETTCAP, requestTermcap, requestTerminfo } from './termcap.js';
-export { decsin, decswt, setIconName, setIconNameAndWindowTitle, setIconNameAndWindowTitleWithST, setIconNameWithST, setWindowTitle, setWindowTitleWithST } from './title.js';
-export { XTWINOPS, XTermWindowOp, deiconifyWindow, iconifyWindow, lowerWindow, maximizeWindow, moveWindow, raiseWindow, refreshWindow, reportWindowPosition, reportWindowState, requestCellSizePixels, requestTextAreaSizeChars, requestTextAreaSizePixels, resizeTextAreaChars, resizeTextAreaPixels, restoreMaximizedWindow, setPageSizeLines, xtermWindowOp } from './window-ops.js';
-export { XTMODKEYS, XTQMODKEYS, keyModifierOptions, queryKeyModifierOptions, queryModifyOtherKeys, resetKeyModifierOptions, resetModifyOtherKeys, setKeyModifierOptions, setModifyOtherKeys1, setModifyOtherKeys2 } from './xterm.js';
-import 'type-fest';
-
-declare const resetProgressBar: string;
-declare const setProgressBar: (percentage: number) => string;
-declare const setErrorProgressBar: (percentage: number) => string;
-declare const setIndeterminateProgressBar: string;
-declare const setWarningProgressBar: (percentage: number) => string;
-
-declare const beep = "\u0007";
-
-export { beep, resetProgressBar, setErrorProgressBar, setIndeterminateProgressBar, setProgressBar, setWarningProgressBar };
+/**
+ * Output a beeping sound.
+ */
+export declare const beep = "\u0007";
+export { ALT_SCREEN_OFF, ALT_SCREEN_ON, alternativeScreenOff, alternativeScreenOn } from "./alternative-screen.d.ts";
+export { clearLineAndHomeCursor, clearScreenAndHomeCursor, clearScreenFromTopLeft, resetTerminal } from "./clear.d.ts";
+export type { CursorStyle } from "./cursor.d.ts";
+export { CURSOR_BACKWARD_1, CURSOR_DOWN_1, CURSOR_FORWARD_1, CURSOR_UP_1, cursorBackward, cursorBackwardTab, cursorDown, cursorForward, cursorHide, cursorHorizontalAbsolute, cursorHorizontalForwardTab, cursorLeft, cursorMove, cursorNextLine, cursorPosition, cursorPreviousLine, cursorRestore, // Function
+cursorSave, // Function
+cursorShow, cursorTo, cursorToColumn1, cursorUp, cursorVerticalAbsolute, eraseCharacter, REQUEST_CURSOR_POSITION, REQUEST_EXTENDED_CURSOR_POSITION, RESTORE_CURSOR_DEC, // Constant for ESC 8
+SAVE_CURSOR_DEC, // Constant for ESC 7
+setCursorStyle, } from "./cursor.d.ts";
+export type { EraseDisplayMode, EraseLineMode } from "./erase.d.ts";
+export { eraseDisplay, eraseDown, eraseInLine, eraseLine, eraseLineEnd, eraseLines, eraseLineStart, eraseScreen, eraseScreenAndScrollback, eraseUp, } from "./erase.d.ts";
+export { default as hyperlink } from "./hyperlink.d.ts";
+export type { ImageOptions } from "./image.d.ts";
+export { image } from "./image.d.ts";
+export type { IITerm2Payload, ITerm2FileProperties } from "./iterm2.d.ts";
+export { IT2_AUTO, it2Cells, it2Percent, it2Pixels, iTerm2, ITerm2File, ITerm2FileEnd, ITerm2FilePart, ITerm2MultipartFileStart } from "./iterm2.d.ts";
+export type { AnsiMode, DecMode, Mode, ModeSetting } from "./mode.d.ts";
+export { BDSM, BiDirectionalSupportMode, BracketedPasteMode, createAnsiMode, createDecMode, DECRPM, DECRQM, DisableModifiersMode, InBandResizeMode, InsertReplaceMode, IRM, isModeNotRecognized, isModePermanentlyReset, isModePermanentlySet, isModeReset, isModeSet, KAM, KeyboardActionMode, LightDarkMode, LineFeedNewLineMode, LNM, LocalEchoMode, OriginMode, reportMode, RequestBiDirectionalSupportMode, RequestInBandResizeMode, RequestInsertReplaceMode, RequestKeyboardActionMode, RequestLineFeedNewLineMode, RequestLocalEchoMode, requestMode, RequestSendReceiveMode, RequestUnicodeCoreMode, ResetBiDirectionalSupportMode, ResetInBandResizeMode, ResetInsertReplaceMode, ResetKeyboardActionMode, ResetLineFeedNewLineMode, ResetLocalEchoMode, resetMode, ResetSendReceiveMode, ResetUnicodeCoreMode, RM, SendFocusEventsMode, SendReceiveMode, SetBiDirectionalSupportMode, SetInBandResizeMode, SetInsertReplaceMode, SetKeyboardActionMode, SetLineFeedNewLineMode, SetLocalEchoMode, setMode, SetSendReceiveMode, SetUnicodeCoreMode, SGRMouseMode, SM, SRM, TextCursorEnableMode, UnicodeCoreMode, } from "./mode.d.ts";
+export type { MouseButtonType, MouseModifiers } from "./mouse.d.ts";
+export { disableAnyEventMouse, disableButtonEventMouse, disableFocusTracking, disableNormalMouse, disableSgrMouse, disableX10Mouse, enableAnyEventMouse, enableButtonEventMouse, enableFocusTracking, enableNormalMouse, enableSgrMouse, enableX10Mouse, encodeMouseButtonByte, MouseButton, mouseSgrSequence, mouseX10Sequence, } from "./mouse.d.ts";
+export { SCREEN_MAX_LEN_DEFAULT, SCREEN_TYPICAL_LIMIT, screenPassthrough, tmuxPassthrough } from "./passthrough.d.ts";
+export { resetProgressBar, setErrorProgressBar, setIndeterminateProgressBar, setProgressBar, setWarningProgressBar } from "./progress.d.ts";
+export { RESET_INITIAL_STATE, RIS } from "./reset.d.ts";
+export { clearTabStop, deleteCharacter, deleteLine, insertCharacter, insertLine, repeatPreviousCharacter, requestPresentationStateReport, setLeftRightMargins, setTopBottomMargins, } from "./screen.d.ts";
+export { SCROLL_DOWN_1, SCROLL_UP_1, scrollDown, scrollUp } from "./scroll.d.ts";
+export type { AnsiStatusReport, DecStatusReport, StatusReport } from "./status.d.ts";
+export { CPR, createAnsiStatusReport, createDecStatusReport, cursorPositionReport, DA1, DA2, DA3, DECXCPR, deviceStatusReport, DSR, DSR_KeyboardLanguageDEC, DSR_PrinterStatusDEC, DSR_TerminalStatus, DSR_UDKStatusDEC, extendedCursorPositionReport, LightDarkReport, reportKeyboardLanguageDEC, reportPrimaryDeviceAttributes, reportPrinterNoPaperDEC, reportPrinterNotReadyDEC, reportPrinterReadyDEC, reportSecondaryDeviceAttributes, reportTerminalNotOK, reportTerminalOK, reportTertiaryDeviceAttributes, reportUDKLockedDEC, reportUDKUnlockedDEC, requestCursorPositionReport, requestExtendedCursorPositionReport, requestKeyboardLanguageDEC, RequestLightDarkReport, RequestNameVersion, requestPrimaryDeviceAttributes, requestPrimaryDeviceAttributesParam0, requestPrinterStatusDEC, requestSecondaryDeviceAttributes, requestSecondaryDeviceAttributesParam0, requestTerminalStatus, requestTertiaryDeviceAttributes, requestTertiaryDeviceAttributesParam0, requestUDKStatusDEC, XTVERSION, } from "./status.d.ts";
+export { default as strip } from "./strip.d.ts";
+export { requestTermcap, requestTerminfo, XTGETTCAP } from "./termcap.d.ts";
+export { decsin, decswt, setIconName, setIconNameAndWindowTitle, setIconNameAndWindowTitleWithST, setIconNameWithST, setWindowTitle, setWindowTitleWithST, } from "./title.d.ts";
+export type { XTermWindowOp } from "./window-ops.d.ts";
+export { deiconifyWindow, iconifyWindow, lowerWindow, maximizeWindow, moveWindow, raiseWindow, refreshWindow, reportWindowPosition, reportWindowState, requestCellSizePixels, requestTextAreaSizeChars, requestTextAreaSizePixels, resizeTextAreaChars, resizeTextAreaPixels, restoreMaximizedWindow, setPageSizeLines, xtermWindowOp, XTWINOPS, } from "./window-ops.d.ts";
+export { keyModifierOptions, queryKeyModifierOptions, queryModifyOtherKeys, resetKeyModifierOptions, resetModifyOtherKeys, setKeyModifierOptions, setModifyOtherKeys1, setModifyOtherKeys2, XTMODKEYS, XTQMODKEYS, } from "./xterm.d.ts";

package/dist/iterm2/iterm2-properties.d.ts

@@ -0,0 +1,135 @@
+import type { LiteralUnion } from "type-fest";
+/**
+ * Represents the special string value `'auto'` used for iTerm2 image or file dimensions.
+ * When `'auto'` is used for width or height, the terminal (iTerm2) determines the appropriate dimension
+ * based on the image's inherent size or other context.
+ * @example `width: IT2_AUTO`
+ */
+export declare const IT2_AUTO: string;
+/**
+ * Formats a number as a string representing a dimension in character cells for iTerm2.
+ * iTerm2 interprets plain numbers for width/height as character cell counts.
+ * @param n The number of character cells.
+ * @returns A string representation of the number (e.g., `10` becomes `"10"`).
+ * @example
+ * ```typescript
+ * const widthInCells = it2Cells(20); // "20"
+ * const sequence = `File=width=${widthInCells}`;
+ * ```
+ */
+export declare const it2Cells: (n: number) => string;
+/**
+ * Formats a number as a string representing a dimension in pixels for iTerm2.
+ * Appends `px` to the number.
+ * @param n The number of pixels.
+ * @returns A string representing the dimension in pixels (e.g., `100` becomes `"100px"`).
+ * @example
+ * ```typescript
+ * const heightInPixels = it2Pixels(150);
+ * const sequence = `File=height=${heightInPixels}`;
+ * ```
+ */
+export declare const it2Pixels: (n: number) => string;
+/**
+ * Formats a number as a string representing a dimension as a percentage for iTerm2.
+ * Appends `%` to the number.
+ * @param n The percentage value (e.g., `50` for 50%).
+ * @returns A string representing the dimension as a percentage (e.g., `50` becomes `"50%"`).
+ * @example
+ * ```typescript
+ * const widthAsPercentage = it2Percent(75);
+ * const sequence = `File=width=${widthAsPercentage}`;
+ * ```
+ */
+export declare const it2Percent: (n: number) => string;
+/**
+ * Defines the interface for any iTerm2 OSC 1337 payload object.
+ *
+ * An OSC 1337 sequence has the general form: `OSC 1337 ; <payload_string> BEL`.
+ * Objects implementing this interface are responsible for generating that `<payload_string>`
+ * via their `toString()` method. This allows for a structured way to build various iTerm2 commands.
+ * @see {@link iTerm2} function which consumes objects of this type.
+ */
+export interface IITerm2Payload {
+    /**
+     * Converts the payload object into its specific string representation required for an iTerm2 OSC 1337 command.
+     * For example, for a file transfer, this might return `"File=name=...;size=...:content..."`.
+     * @returns The string payload part of the OSC 1337 sequence.
+     */
+    toString: () => string;
+}
+/**
+ * Defines the properties for an iTerm2 file transfer or inline image display command (`File=...`).
+ * These correspond to the key-value pairs used within the `File=` argument of the OSC 1337 sequence.
+ * @see {@link https://iterm2.com/documentation-escape-codes.html} iTerm2 Escape Codes (search for `File=`)
+ * @see {@link https://iterm2.com/documentation-images.html} iTerm2 Inline Images Protocol
+ */
+export interface ITerm2FileProperties {
+    /**
+     * The Base64 encoded content of the file or image.
+     * This is typically used when `inline=1` is set for images, or for transferring small files directly
+     * within the escape sequence. For larger files, multipart transfer is recommended.
+     * @remarks The `ITerm2File` class can handle the Base64 encoding of `Uint8Array` data automatically.
+     */
+    content?: string;
+    /**
+     * If `true`, instructs the terminal not to move the cursor after displaying an inline image.
+     * Corresponds to `doNotMoveCursor=1` in the sequence.
+     * This is a WezTerm extension, also supported by iTerm2 beta/nightly builds as of some versions.
+     * @default false (cursor behavior is default terminal behavior)
+     */
+    doNotMoveCursor?: boolean;
+    /**
+     * The display height of the image or file placeholder.
+     * Can be:
+     * - A number (interpreted as character cells, e.g., `10`).
+     * - A string with units: `"Npx"` (N pixels), `"N%"` (N percent of session height).
+     * - The string {@link IT2_AUTO} (`"auto"`) for automatic sizing.
+     * Use helper functions like {@link it2Cells}, {@link it2Pixels}, {@link it2Percent} for formatting if needed.
+     * @example `10`, `"100px"`, `"50%"`, `IT2_AUTO`
+     */
+    height?: LiteralUnion<typeof IT2_AUTO, number | string>;
+    /**
+     * Controls aspect ratio preservation for inline images.
+     * - If `true` (or omitted), the aspect ratio *is* preserved (`preserveAspectRatio=1`, which is the default iTerm2 behavior if the param is absent).
+     * - If `false`, the aspect ratio is *not* preserved, and the image may stretch (`preserveAspectRatio=0`).
+     * @remarks Note the slight inversion: this property `ignoreAspectRatio: true` means `preserveAspectRatio=0` in the sequence.
+     * The default iTerm2 behavior *is* to preserve aspect ratio if the `preserveAspectRatio` parameter is not given.
+     * So, to *not* preserve, you set this to true to *add* `preserveAspectRatio=0`.
+     * If you want to preserve (default), you can omit this or set it to `false`.
+     * @default false (meaning aspect ratio is preserved by iTerm2 default unless overridden)
+     */
+    ignoreAspectRatio?: boolean;
+    /**
+     * If `true`, the file (typically an image) should be displayed inline in the terminal.
+     * Corresponds to `inline=1` in the sequence.
+     * If `false` or omitted, iTerm2 might prompt for download or handle based on file type.
+     * @default false
+     */
+    inline?: boolean;
+    /**
+     * The name of the file. This is displayed in UI elements (like a download prompt or image info)
+     * and used as the default filename if downloaded.
+     * The name **must be Base64 encoded** if it contains special characters (like `;`, `=`, or non-ASCII characters)
+     * to ensure correct parsing of the escape sequence by iTerm2.
+     * The `ITerm2File` and `ITerm2MultipartFileStart` classes generally expect the name to be pre-encoded if necessary.
+     * @example `"bXlmaWxlLnR4dA=="` (Base64 for "myfile.txt")
+     */
+    name?: string;
+    /**
+     * The size of the file in bytes. This is used by iTerm2 for progress indication during downloads
+     * or to inform inline display mechanisms.
+     * JavaScript `number` type is generally sufficient for typical file sizes (up to `Number.MAX_SAFE_INTEGER`).
+     */
+    size?: number;
+    /**
+     * The display width of the image or file placeholder.
+     * Can be:
+     * - A number (interpreted as character cells, e.g., `20`).
+     * - A string with units: `"Npx"` (N pixels), `"N%"` (N percent of session width).
+     * - The string {@link IT2_AUTO} (`"auto"`) for automatic sizing.
+     * Use helper functions like {@link it2Cells}, {@link it2Pixels}, {@link it2Percent} for formatting if needed.
+     * @example `20`, `"200px"`, `"75%"`, `IT2_AUTO`
+     */
+    width?: LiteralUnion<typeof IT2_AUTO, number | string>;
+}