@visulima/ansi 1.0.18 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## @visulima/ansi [1.1.0](https://github.com/visulima/visulima/compare/@visulima/ansi@1.0.18...@visulima/ansi@1.1.0) (2025-05-30)
+
+### Features
+
+* **ansi:** introduces a significant number of changes, including refactoring of exports, renaming of functions for clarity and consistency ([d80d2db](https://github.com/visulima/visulima/commit/d80d2dba2580e208cbf21f60d27bfb4e95417281))
+
+### Bug Fixes
+
+* **ansi:** improved readme, added all files as export ([a70ad00](https://github.com/visulima/visulima/commit/a70ad0026e05552b4c56b0be355bf439a40c3c3e))
+* **ansi:** update dependencies ([85478c4](https://github.com/visulima/visulima/commit/85478c4614b3fe78ee80e090b36829bc64f6e4c1))
+
+### Miscellaneous Chores
+
+* updated dev dependencies ([2433ed5](https://github.com/visulima/visulima/commit/2433ed5fb662e0303c37edee8ddc21b46c21263f))
+
+
+### Dependencies
+
+* **@visulima/colorize:** upgraded to 1.4.22
+* **@visulima/path:** upgraded to 1.3.6
+
 ## @visulima/ansi [1.0.18](https://github.com/visulima/visulima/compare/@visulima/ansi@1.0.17...@visulima/ansi@1.0.18) (2025-03-07)
 
 ### Bug Fixes

package/LICENSE.md

@@ -122,11 +122,14 @@ Repository: https://github.com/tapjs/signal-exit.git
 <!-- TYPE_DEPENDENCIES -->
 
 # Licenses of bundled types
+
 The published @visulima/ansi artifact additionally contains code with the following licenses:
 MIT, (MIT OR CC0-1.0)
 
 # Bundled types:
+
 ## restore-cursor
+
 License: MIT
 By: Sindre Sorhus
 Repository: sindresorhus/restore-cursor
@@ -141,9 +144,10 @@ Repository: sindresorhus/restore-cursor
 >
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
----------------------------------------
+---
 
 ## type-fest
+
 License: (MIT OR CC0-1.0)
 By: Sindre Sorhus
 Repository: sindresorhus/type-fest
@@ -188,86 +192,84 @@ Repository: sindresorhus/type-fest
 > Work and the meaning and intended legal effect of CC0 on those rights.
 >
 > 1. Copyright and Related Rights. A Work made available under CC0 may be
-> protected by copyright and related or neighboring rights ("Copyright and
-> Related Rights"). Copyright and Related Rights include, but are not
-> limited to, the following:
+>    protected by copyright and related or neighboring rights ("Copyright and
+>    Related Rights"). Copyright and Related Rights include, but are not
+>    limited to, the following:
 >
->   i. the right to reproduce, adapt, distribute, perform, display,
->      communicate, and translate a Work;
->  ii. moral rights retained by the original author(s) and/or performer(s);
+> i. the right to reproduce, adapt, distribute, perform, display,
+> communicate, and translate a Work;
+> ii. moral rights retained by the original author(s) and/or performer(s);
 > iii. publicity and privacy rights pertaining to a person's image or
->      likeness depicted in a Work;
->  iv. rights protecting against unfair competition in regards to a Work,
->      subject to the limitations in paragraph 4(a), below;
->   v. rights protecting the extraction, dissemination, use and reuse of data
->      in a Work;
->  vi. database rights (such as those arising under Directive 96/9/EC of the
->      European Parliament and of the Council of 11 March 1996 on the legal
->      protection of databases, and under any national implementation
->      thereof, including any amended or successor version of such
->      directive); and
+> likeness depicted in a Work;
+> iv. rights protecting against unfair competition in regards to a Work,
+> subject to the limitations in paragraph 4(a), below;
+> v. rights protecting the extraction, dissemination, use and reuse of data
+> in a Work;
+> vi. database rights (such as those arising under Directive 96/9/EC of the
+> European Parliament and of the Council of 11 March 1996 on the legal
+> protection of databases, and under any national implementation
+> thereof, including any amended or successor version of such
+> directive); and
 > vii. other similar, equivalent or corresponding rights throughout the
->      world based on applicable law or treaty, and any national
->      implementations thereof.
+> world based on applicable law or treaty, and any national
+> implementations thereof.
 >
 > 2. Waiver. To the greatest extent permitted by, but not in contravention
-> of, applicable law, Affirmer hereby overtly, fully, permanently,
-> irrevocably and unconditionally waives, abandons, and surrenders all of
-> Affirmer's Copyright and Related Rights and associated claims and causes
-> of action, whether now known or unknown (including existing as well as
-> future claims and causes of action), in the Work (i) in all territories
-> worldwide, (ii) for the maximum duration provided by applicable law or
-> treaty (including future time extensions), (iii) in any current or future
-> medium and for any number of copies, and (iv) for any purpose whatsoever,
-> including without limitation commercial, advertising or promotional
-> purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
-> member of the public at large and to the detriment of Affirmer's heirs and
-> successors, fully intending that such Waiver shall not be subject to
-> revocation, rescission, cancellation, termination, or any other legal or
-> equitable action to disrupt the quiet enjoyment of the Work by the public
-> as contemplated by Affirmer's express Statement of Purpose.
->
+>    of, applicable law, Affirmer hereby overtly, fully, permanently,
+>    irrevocably and unconditionally waives, abandons, and surrenders all of
+>    Affirmer's Copyright and Related Rights and associated claims and causes
+>    of action, whether now known or unknown (including existing as well as
+>    future claims and causes of action), in the Work (i) in all territories
+>    worldwide, (ii) for the maximum duration provided by applicable law or
+>    treaty (including future time extensions), (iii) in any current or future
+>    medium and for any number of copies, and (iv) for any purpose whatsoever,
+>    including without limitation commercial, advertising or promotional
+>    purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+>    member of the public at large and to the detriment of Affirmer's heirs and
+>    successors, fully intending that such Waiver shall not be subject to
+>    revocation, rescission, cancellation, termination, or any other legal or
+>    equitable action to disrupt the quiet enjoyment of the Work by the public
+>    as contemplated by Affirmer's express Statement of Purpose.
 > 3. Public License Fallback. Should any part of the Waiver for any reason
-> be judged legally invalid or ineffective under applicable law, then the
-> Waiver shall be preserved to the maximum extent permitted taking into
-> account Affirmer's express Statement of Purpose. In addition, to the
-> extent the Waiver is so judged Affirmer hereby grants to each affected
-> person a royalty-free, non transferable, non sublicensable, non exclusive,
-> irrevocable and unconditional license to exercise Affirmer's Copyright and
-> Related Rights in the Work (i) in all territories worldwide, (ii) for the
-> maximum duration provided by applicable law or treaty (including future
-> time extensions), (iii) in any current or future medium and for any number
-> of copies, and (iv) for any purpose whatsoever, including without
-> limitation commercial, advertising or promotional purposes (the
-> "License"). The License shall be deemed effective as of the date CC0 was
-> applied by Affirmer to the Work. Should any part of the License for any
-> reason be judged legally invalid or ineffective under applicable law, such
-> partial invalidity or ineffectiveness shall not invalidate the remainder
-> of the License, and in such case Affirmer hereby affirms that he or she
-> will not (i) exercise any of his or her remaining Copyright and Related
-> Rights in the Work or (ii) assert any associated claims and causes of
-> action with respect to the Work, in either case contrary to Affirmer's
-> express Statement of Purpose.
->
+>    be judged legally invalid or ineffective under applicable law, then the
+>    Waiver shall be preserved to the maximum extent permitted taking into
+>    account Affirmer's express Statement of Purpose. In addition, to the
+>    extent the Waiver is so judged Affirmer hereby grants to each affected
+>    person a royalty-free, non transferable, non sublicensable, non exclusive,
+>    irrevocable and unconditional license to exercise Affirmer's Copyright and
+>    Related Rights in the Work (i) in all territories worldwide, (ii) for the
+>    maximum duration provided by applicable law or treaty (including future
+>    time extensions), (iii) in any current or future medium and for any number
+>    of copies, and (iv) for any purpose whatsoever, including without
+>    limitation commercial, advertising or promotional purposes (the
+>    "License"). The License shall be deemed effective as of the date CC0 was
+>    applied by Affirmer to the Work. Should any part of the License for any
+>    reason be judged legally invalid or ineffective under applicable law, such
+>    partial invalidity or ineffectiveness shall not invalidate the remainder
+>    of the License, and in such case Affirmer hereby affirms that he or she
+>    will not (i) exercise any of his or her remaining Copyright and Related
+>    Rights in the Work or (ii) assert any associated claims and causes of
+>    action with respect to the Work, in either case contrary to Affirmer's
+>    express Statement of Purpose.
 > 4. Limitations and Disclaimers.
 >
->  a. No trademark or patent rights held by Affirmer are waived, abandoned,
->     surrendered, licensed or otherwise affected by this document.
->  b. Affirmer offers the Work as-is and makes no representations or
->     warranties of any kind concerning the Work, express, implied,
->     statutory or otherwise, including without limitation warranties of
->     title, merchantability, fitness for a particular purpose, non
->     infringement, or the absence of latent or other defects, accuracy, or
->     the present or absence of errors, whether or not discoverable, all to
->     the greatest extent permissible under applicable law.
->  c. Affirmer disclaims responsibility for clearing rights of other persons
->     that may apply to the Work or any use thereof, including without
->     limitation any person's Copyright and Related Rights in the Work.
->     Further, Affirmer disclaims responsibility for obtaining any necessary
->     consents, permissions or other rights required for any use of the
->     Work.
->  d. Affirmer understands and acknowledges that Creative Commons is not a
->     party to this document and has no duty or obligation with respect to
->     this CC0 or use of the Work.
+> a. No trademark or patent rights held by Affirmer are waived, abandoned,
+> surrendered, licensed or otherwise affected by this document.
+> b. Affirmer offers the Work as-is and makes no representations or
+> warranties of any kind concerning the Work, express, implied,
+> statutory or otherwise, including without limitation warranties of
+> title, merchantability, fitness for a particular purpose, non
+> infringement, or the absence of latent or other defects, accuracy, or
+> the present or absence of errors, whether or not discoverable, all to
+> the greatest extent permissible under applicable law.
+> c. Affirmer disclaims responsibility for clearing rights of other persons
+> that may apply to the Work or any use thereof, including without
+> limitation any person's Copyright and Related Rights in the Work.
+> Further, Affirmer disclaims responsibility for obtaining any necessary
+> consents, permissions or other rights required for any use of the
+> Work.
+> d. Affirmer understands and acknowledges that Creative Commons is not a
+> party to this document and has no duty or obligation with respect to
+> this CC0 or use of the Work.
 
 <!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -39,6 +39,19 @@ yarn add @visulima/ansi
 pnpm add @visulima/ansi
 ```
 
+## Features
+
+*   **Comprehensive Cursor Control:** Functions for precise cursor positioning, movement, visibility, and style.
+*   **Screen Manipulation:** Clear parts of the screen or the entire screen, manage alternative screen buffers, and control scrolling.
+*   **Text Erasure:** Erase characters, lines, or parts of lines.
+*   **iTerm2 Integration:** Support for iTerm2 specific features like image display.
+*   **Terminal Mode Management:** Control various terminal modes like line feed, local echo, and mouse events.
+*   **Mouse Event Handling:** Enable and disable different types of mouse tracking.
+*   **Window and Title Control:** Manipulate window titles, icons, and basic window operations (maximize, minimize, etc. for supported terminals).
+*   **Status Reporting:** Request and report various terminal statuses.
+*   **Hyperlinks:** Create clickable hyperlinks in the terminal.
+*   **Utility Functions:** Includes functions to strip ANSI codes and passthrough sequences for tmux.
+
 ## Usage
 
 ```js
@@ -65,6 +78,326 @@ const { cursorUp, cursorLeft } = require("@visulima/ansi");
 // etc, as above...
 ```
 
+**More Examples:**
+
+**Cursor Manipulation**
+
+```javascript
+import { cursorTo, cursorUp, eraseLine } from "@visulima/ansi";
+
+// Move cursor to column 10, row 5
+process.stdout.write(cursorTo(10, 5));
+
+// Move cursor up 3 lines
+process.stdout.write(cursorUp(3));
+
+// Erase the current line
+process.stdout.write(eraseLine);
+```
+
+**Screen Clearing**
+
+```javascript
+import { clearScreen, eraseDown } from "@visulima/ansi";
+
+// Clear the entire screen
+process.stdout.write(clearScreen);
+
+// Clear from cursor to end of screen
+process.stdout.write(eraseDown);
+```
+
+**Text Styling (with other libraries)**
+
+While `@visulima/ansi` focuses on terminal control, you can combine it with libraries like `chalk` for text styling:
+
+```javascript
+import { cursorTo } from "@visulima/ansi";
+import chalk from "chalk";
+
+process.stdout.write(cursorTo(0,0));
+process.stdout.write(chalk.blue("This is a blue message at the top left!"));
+```
+
+## API
+
+This package exports the following functions and constants. For a detailed list of all exports, see the `src/index.ts` file.
+
+**General**
+
+*   `beep`
+
+**Alternative Screen** (from `alternative-screen.ts`)
+
+*   `ALT_SCREEN_OFF`
+*   `ALT_SCREEN_ON`
+*   `alternativeScreenOff`
+*   `alternativeScreenOn`
+
+**Clear** (from `clear.ts`)
+
+*   `clearLineAndHomeCursor`
+*   `clearScreenAndHomeCursor`
+*   `clearScreenFromTopLeft`
+*   `resetTerminal`
+
+**Cursor** (from `cursor.ts`)
+
+*   `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`
+*   `cursorSave`
+*   `cursorShow`
+*   `cursorTo`
+*   `cursorToColumn1`
+*   `cursorUp`
+*   `cursorVerticalAbsolute`
+*   `eraseCharacter` (Note: Also related to erase)
+*   `REQUEST_CURSOR_POSITION`
+*   `REQUEST_EXTENDED_CURSOR_POSITION`
+*   `RESTORE_CURSOR_DEC`
+*   `SAVE_CURSOR_DEC`
+*   `setCursorStyle`
+
+**Erase** (from `erase.ts`)
+
+*   `eraseDisplay`
+*   `eraseDown`
+*   `eraseInLine`
+*   `eraseLine`
+*   `eraseLineEnd`
+*   `eraseLines`
+*   `eraseLineStart`
+*   `eraseScreen`
+*   `eraseScreenAndScrollback`
+*   `eraseUp`
+
+**Hyperlink** (from `hyperlink.ts`)
+
+*   `hyperlink`
+
+**Image** (from `image.ts`)
+
+*   `image`
+
+**iTerm2 Integration** (from `iterm2.ts` and `iterm2/`)
+
+*   `IT2_AUTO`
+*   `it2Cells`
+*   `it2Percent`
+*   `it2Pixels`
+*   `iTerm2`
+*   `ITerm2File`
+*   `ITerm2FileEnd`
+*   `ITerm2FilePart`
+*   `ITerm2MultipartFileStart`
+
+**Mode** (from `mode.ts`)
+
+*   `BDSM`
+*   `BiDirectionalSupportMode`
+*   `createAnsiMode`
+*   `createDecMode`
+*   `DECRPM`
+*   `DECRQM`
+*   `InsertReplaceMode`
+*   `IRM`
+*   `isModeNotRecognized`
+*   `isModePermanentlyReset`
+*   `isModePermanentlySet`
+*   `isModeReset`
+*   `isModeSet`
+*   `KAM`
+*   `KeyboardActionMode`
+*   `LineFeedNewLineMode`
+*   `LNM`
+*   `LocalEchoMode`
+*   `reportMode`
+*   `RequestBiDirectionalSupportMode`
+*   `RequestInsertReplaceMode`
+*   `RequestKeyboardActionMode`
+*   `RequestLineFeedNewLineMode`
+*   `RequestLocalEchoMode`
+*   `requestMode`
+*   `RequestSendReceiveMode`
+*   `ResetBiDirectionalSupportMode`
+*   `ResetInsertReplaceMode`
+*   `ResetKeyboardActionMode`
+*   `ResetLineFeedNewLineMode`
+*   `ResetLocalEchoMode`
+*   `resetMode`
+*   `ResetSendReceiveMode`
+*   `RM`
+*   `SendReceiveMode`
+*   `SetBiDirectionalSupportMode`
+*   `SetInsertReplaceMode`
+*   `SetKeyboardActionMode`
+*   `SetLineFeedNewLineMode`
+*   `SetLocalEchoMode`
+*   `setMode`
+*   `SetSendReceiveMode`
+*   `SM`
+*   `SRM`
+
+**Mouse** (from `mouse.ts`)
+
+*   `disableAnyEventMouse`
+*   `disableButtonEventMouse`
+*   `disableFocusTracking`
+*   `disableNormalMouse`
+*   `disableSgrMouse`
+*   `disableX10Mouse`
+*   `enableAnyEventMouse`
+*   `enableButtonEventMouse`
+*   `enableFocusTracking`
+*   `enableNormalMouse`
+*   `enableSgrMouse`
+*   `enableX10Mouse`
+*   `encodeMouseButtonByte`
+*   `MouseButton`
+*   `mouseSgrSequence`
+*   `mouseX10Sequence`
+
+**Passthrough** (from `passthrough.ts`)
+
+*   `SCREEN_MAX_LEN_DEFAULT`
+*   `SCREEN_TYPICAL_LIMIT`
+*   `screenPassthrough`
+*   `tmuxPassthrough`
+
+**Reset** (from `reset.ts`)
+
+*   `RESET_INITIAL_STATE`
+*   `RIS`
+
+**Screen** (from `screen.ts`)
+
+*   `clearTabStop`
+*   `deleteCharacter`
+*   `deleteLine`
+*   `insertCharacter`
+*   `insertLine`
+*   `repeatPreviousCharacter`
+*   `requestPresentationStateReport`
+*   `setLeftRightMargins`
+*   `setTopBottomMargins`
+
+**Scroll** (from `scroll.ts`)
+
+*   `SCROLL_DOWN_1`
+*   `SCROLL_UP_1`
+*   `scrollDown`
+*   `scrollUp`
+
+**Status** (from `status.ts`)
+
+*   `CPR`
+*   `createAnsiStatusReport`
+*   `createDecStatusReport`
+*   `cursorPositionReport`
+*   `DA1`
+*   `DA2`
+*   `DA3`
+*   `DECXCPR`
+*   `deviceStatusReport`
+*   `DSR`
+*   `DSR_KeyboardLanguageDEC`
+*   `DSR_PrinterStatusDEC`
+*   `DSR_TerminalStatus`
+*   `DSR_UDKStatusDEC`
+*   `extendedCursorPositionReport`
+*   `reportKeyboardLanguageDEC`
+*   `reportPrimaryDeviceAttributes`
+*   `reportPrinterNoPaperDEC`
+*   `reportPrinterNotReadyDEC`
+*   `reportPrinterReadyDEC`
+*   `reportSecondaryDeviceAttributes`
+*   `reportTerminalNotOK`
+*   `reportTerminalOK`
+*   `reportTertiaryDeviceAttributes`
+*   `reportUDKLockedDEC`
+*   `reportUDKUnlockedDEC`
+*   `requestCursorPositionReport`
+*   `requestExtendedCursorPositionReport`
+*   `requestKeyboardLanguageDEC`
+*   `RequestNameVersion`
+*   `requestPrimaryDeviceAttributes`
+*   `requestPrimaryDeviceAttributesParam0`
+*   `requestPrinterStatusDEC`
+*   `requestSecondaryDeviceAttributes`
+*   `requestSecondaryDeviceAttributesParam0`
+*   `requestTerminalStatus`
+*   `requestTertiaryDeviceAttributes`
+*   `requestTertiaryDeviceAttributesParam0`
+*   `requestUDKStatusDEC`
+*   `XTVERSION`
+
+**Strip** (from `strip.ts`)
+
+*   `strip`
+
+**Termcap/Terminfo** (from `termcap.ts`)
+
+*   `requestTermcap`
+*   `requestTerminfo`
+*   `XTGETTCAP`
+
+**Title** (from `title.ts`)
+
+*   `decsin`
+*   `decswt`
+*   `setIconName`
+*   `setIconNameAndWindowTitle`
+*   `setIconNameAndWindowTitleWithST`
+*   `setIconNameWithST`
+*   `setWindowTitle`
+*   `setWindowTitleWithST`
+
+**Window Operations** (from `window-ops.ts`)
+
+*   `deiconifyWindow`
+*   `iconifyWindow`
+*   `lowerWindow`
+*   `maximizeWindow`
+*   `moveWindow`
+*   `raiseWindow`
+*   `refreshWindow`
+*   `reportWindowPosition`
+*   `reportWindowState`
+*   `requestCellSizePixels`
+*   `requestFullScreen`
+*   `requestTextAreaSizeChars`
+*   `requestTextAreaSizePixels`
+*   `requestWindowPosition`
+*   `requestWindowSizeChars`
+*   `requestWindowSizePixels`
+*   `resizeTextAreaChars`
+*   `resizeTextAreaPixels`
+*   `restoreWindow`
+*   `XTWINOPS`
+
+**XTerm** (from `xterm.ts`)
+
+*   `xtermBell`
+*   `xtermManipulateWindow`
+*   `xtermReport`
+*   `xtermRequest`
+*   `xtermSet`
+
 ## Related
 
 - [ansi-escapes](https://github.com/sindresorhus/ansi-escapes) - ANSI escape codes for manipulating the terminal
@@ -73,8 +406,8 @@ const { cursorUp, cursorLeft } = require("@visulima/ansi");
 
 ## Supported Node.js Versions
 
-Libraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).
-Here’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
+Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).
+Here's [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
 
 ## Contributing
 

package/dist/alternative-screen.cjs

@@ -2,10 +2,16 @@
 
 Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
 
-const constants = require('./packem_shared/constants-D8u2npjW.cjs');
+const constants = require('./packem_shared/constants-BK26O-46.cjs');
 
-const alternativeScreenEnter = constants.ESC + "?1049h";
-const alternativeScreenExit = constants.ESC + "?1049l";
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const ALT_SCREEN_ON = `${constants.CSI}?1049h`;
+const ALT_SCREEN_OFF = `${constants.CSI}?1049l`;
+const alternativeScreenOn = /* @__PURE__ */ __name(() => ALT_SCREEN_ON, "alternativeScreenOn");
+const alternativeScreenOff = /* @__PURE__ */ __name(() => ALT_SCREEN_OFF, "alternativeScreenOff");
 
-exports.alternativeScreenEnter = alternativeScreenEnter;
-exports.alternativeScreenExit = alternativeScreenExit;
+exports.ALT_SCREEN_OFF = ALT_SCREEN_OFF;
+exports.ALT_SCREEN_ON = ALT_SCREEN_ON;
+exports.alternativeScreenOff = alternativeScreenOff;
+exports.alternativeScreenOn = alternativeScreenOn;

package/dist/alternative-screen.d.cts

@@ -1,4 +1,74 @@
-declare const alternativeScreenEnter: string;
-declare const alternativeScreenExit: string;
-
-export { alternativeScreenEnter, alternativeScreenExit };
+/**
+ * ANSI escape sequence to enable the alternative screen buffer.
+ *
+ * This sequence (`CSI ?1049h`) instructs the terminal to switch to the alternative screen buffer.
+ * This is a common practice for full-screen terminal applications (e.g., vim, less, htop)
+ * to provide a separate screen area for their interface, leaving the original shell content
+ * undisturbed and restoring it upon exit.
+ * When this mode is activated, the original screen content is typically saved by the terminal,
+ * and a blank screen is presented. Operations then occur on this alternative buffer.
+ *
+ * The specific behavior (like whether the screen is cleared on switch) can sometimes vary
+ * slightly between terminal emulators. `?1049h` generally includes saving the cursor position
+ * along with the screen content and clearing the alternative screen.
+ * It is closely related to mode `?47h`, which also switches to an alternative buffer but might
+ * have different semantics regarding screen clearing and cursor saving.
+ * Mode `?1049h` is generally preferred for a more robust alternative screen experience.
+ * @see {@link ALT_SCREEN_OFF} for the sequence to disable the alternative screen buffer.
+ * @see {@link alternativeScreenOn} for a function that returns this sequence.
+ * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-The-Alternate-Screen-Buffer} Xterm Control Sequences documentation.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSLPP.html} (related DEC modes, though 1049 is more common for this behavior).
+ */
+export declare const ALT_SCREEN_ON: string;
+/**
+ * ANSI escape sequence to disable the alternative screen buffer.
+ *
+ * This sequence (`CSI ?1049l`) instructs the terminal to switch back from the alternative
+ * screen buffer to the main screen buffer. When this occurs, the terminal typically
+ * restores the screen content and cursor position that were saved when the alternative
+ * buffer was activated by {@link ALT_SCREEN_ON}.
+ *
+ * This is used when a full-screen application exits, allowing the user to return to their
+ * previous shell session seamlessly.
+ * @see {@link ALT_SCREEN_ON} for the sequence to enable the alternative screen buffer.
+ * @see {@link alternativeScreenOff} for a function that returns this sequence.
+ */
+export declare const ALT_SCREEN_OFF: string;
+/**
+ * Returns the ANSI escape sequence to enable the alternative screen buffer.
+ *
+ * This function is a convenience wrapper around the {@link ALT_SCREEN_ON} constant.
+ * It provides a more descriptive way to obtain the sequence for enabling the
+ * alternative screen, often used at the initialization phase of a full-screen
+ * terminal application.
+ * @returns The ANSI escape sequence (`CSI ?1049h`) for enabling the alternative screen buffer.
+ * @example
+ * ```typescript
+ * import { alternativeScreenOn } from '@visulima/ansi/alternative-screen';
+ *
+ * process.stdout.write(alternativeScreenOn());
+ * // Terminal switches to the alternative screen buffer.
+ * ```
+ * @see {@link ALT_SCREEN_ON}
+ * @see {@link alternativeScreenOff}
+ */
+export declare const alternativeScreenOn: () => string;
+/**
+ * Returns the ANSI escape sequence to disable the alternative screen buffer.
+ *
+ * This function is a convenience wrapper around the {@link ALT_SCREEN_OFF} constant.
+ * It provides a more descriptive way to obtain the sequence for disabling the
+ * alternative screen, typically used when a full-screen terminal application is exiting
+ * to restore the user's original terminal state.
+ * @returns The ANSI escape sequence (`CSI ?1049l`) for disabling the alternative screen buffer.
+ * @example
+ * ```typescript
+ * import { alternativeScreenOff } from '@visulima/ansi/alternative-screen';
+ *
+ * process.stdout.write(alternativeScreenOff());
+ * // Terminal switches back to the main screen buffer, restoring previous content.
+ * ```
+ * @see {@link ALT_SCREEN_OFF}
+ * @see {@link alternativeScreenOn}
+ */
+export declare const alternativeScreenOff: () => string;