@visulima/ansi 1.0.18 → 1.1.0

package/dist/erase.mjs

@@ -1,23 +1,49 @@
-import { C as CSI } from './packem_shared/constants-CqXMfQy0.mjs';
-import { m as cursorUp, e as cursorLeft } from './packem_shared/cursor-CDCWqbC9.mjs';
+import { C as CSI } from './packem_shared/constants-CE7WkXh_.mjs';
+import { u as cursorUp, t as cursorToColumn1 } from './packem_shared/cursor-DhFQcQ9g.mjs';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-const eraseDown = /* @__PURE__ */ __name((count = 1) => `${CSI}J`.repeat(count), "eraseDown");
-const eraseLine = `${CSI}2K`;
-const eraseLineEnd = `${CSI}K`;
-const eraseLineStart = `${CSI}1K`;
+var EraseDisplayMode = /* @__PURE__ */ ((EraseDisplayMode2) => {
+  EraseDisplayMode2[EraseDisplayMode2["EntireScreen"] = 2] = "EntireScreen";
+  EraseDisplayMode2[EraseDisplayMode2["EntireScreenAndScrollback"] = 3] = "EntireScreenAndScrollback";
+  EraseDisplayMode2[EraseDisplayMode2["ToBeginning"] = 1] = "ToBeginning";
+  EraseDisplayMode2[EraseDisplayMode2["ToEnd"] = 0] = "ToEnd";
+  return EraseDisplayMode2;
+})(EraseDisplayMode || {});
+const eraseDisplay = /* @__PURE__ */ __name((mode) => {
+  const validMode = mode >= 0 && mode <= 3 ? mode : 0 /* ToEnd */;
+  return `${CSI + (validMode === 0 /* ToEnd */ ? "" : String(validMode))}J`;
+}, "eraseDisplay");
+var EraseLineMode = /* @__PURE__ */ ((EraseLineMode2) => {
+  EraseLineMode2[EraseLineMode2["EntireLine"] = 2] = "EntireLine";
+  EraseLineMode2[EraseLineMode2["ToBeginning"] = 1] = "ToBeginning";
+  EraseLineMode2[EraseLineMode2["ToEnd"] = 0] = "ToEnd";
+  return EraseLineMode2;
+})(EraseLineMode || {});
+const eraseInLine = /* @__PURE__ */ __name((mode) => {
+  const validMode = mode >= 0 && mode <= 2 ? mode : 0 /* ToEnd */;
+  return `${CSI + (validMode === 0 /* ToEnd */ ? "" : String(validMode))}K`;
+}, "eraseInLine");
+const eraseDown = eraseDisplay(0 /* ToEnd */);
+const eraseLine = eraseInLine(2 /* EntireLine */);
+const eraseLineEnd = eraseInLine(0 /* ToEnd */);
+const eraseLineStart = eraseInLine(1 /* ToBeginning */);
 const eraseLines = /* @__PURE__ */ __name((count) => {
-  let clear = "";
-  for (let index = 0; index < count; index++) {
-    clear += eraseLine + (index < count - 1 ? cursorUp() : "");
+  if (count <= 0) {
+    return "";
   }
-  if (count) {
-    clear += cursorLeft;
+  let clear = "";
+  for (let index = 0; index < count; index += 1) {
+    clear += eraseLine;
+    if (index < count - 1) {
+      clear += cursorUp();
+    }
   }
+  clear += cursorToColumn1;
   return clear;
 }, "eraseLines");
-const eraseScreen = `${CSI}2J`;
-const eraseUp = /* @__PURE__ */ __name((count = 1) => `${CSI}1J`.repeat(count), "eraseUp");
+const eraseScreen = eraseDisplay(2 /* EntireScreen */);
+const eraseUp = eraseDisplay(1 /* ToBeginning */);
+const eraseScreenAndScrollback = eraseDisplay(3 /* EntireScreenAndScrollback */);
 
-export { eraseDown, eraseLine, eraseLineEnd, eraseLineStart, eraseLines, eraseScreen, eraseUp };
+export { EraseDisplayMode, EraseLineMode, eraseDisplay, eraseDown, eraseInLine, eraseLine, eraseLineEnd, eraseLineStart, eraseLines, eraseScreen, eraseScreenAndScrollback, eraseUp };

package/dist/helpers.d.cts

@@ -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/helpers.d.mts

@@ -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/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.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+const constants = require('./packem_shared/constants-BK26O-46.cjs');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const hyperlink = /* @__PURE__ */ __name((text, url) => [constants.OSC, "8", constants.SEP, constants.SEP, url, constants.BEL, text, constants.OSC, "8", constants.SEP, constants.SEP, constants.BEL].join(""), "hyperlink");
+
+module.exports = hyperlink;

package/dist/hyperlink.d.cts

@@ -0,0 +1,29 @@
+/**
+ * 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;

package/dist/hyperlink.d.mts

@@ -0,0 +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 default hyperlink;

package/dist/hyperlink.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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;

package/dist/hyperlink.mjs

@@ -0,0 +1,7 @@
+import { O as OSC, S as SEP, B as BEL } from './packem_shared/constants-CE7WkXh_.mjs';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const hyperlink = /* @__PURE__ */ __name((text, url) => [OSC, "8", SEP, SEP, url, BEL, text, OSC, "8", SEP, SEP, BEL].join(""), "hyperlink");
+
+export { hyperlink as default };

package/dist/image.cjs

@@ -1,21 +1,28 @@
 'use strict';
 
-const constants = require('./packem_shared/constants-D8u2npjW.cjs');
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+const node_buffer = require('node:buffer');
+const constants = require('./packem_shared/constants-BK26O-46.cjs');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 const image = /* @__PURE__ */ __name((data, options = {}) => {
+  if (!data) {
+    return "";
+  }
   let returnValue = `${constants.OSC}1337;File=inline=1`;
-  if (options.width) {
+  if (options.width !== void 0) {
     returnValue += `;width=${options.width}`;
   }
-  if (options.height) {
+  if (options.height !== void 0) {
     returnValue += `;height=${options.height}`;
   }
   if (options.preserveAspectRatio === false) {
     returnValue += ";preserveAspectRatio=0";
   }
-  return returnValue + ":" + Buffer.from(data).toString("base64") + constants.BEL;
+  const base64Data = node_buffer.Buffer.from(data).toString("base64");
+  return `${returnValue}:${base64Data}${constants.BEL}`;
 }, "image");
 
-module.exports = image;
+exports.image = image;

package/dist/image.d.cts

@@ -1,62 +1,73 @@
+import type { LiteralUnion } from "type-fest";
 /**
-Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-
-@category Type
-*/
-type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol
-	| bigint;
-
-declare global {
-	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
-	interface SymbolConstructor {
-		readonly observable: symbol;
-	}
-}
-
-/**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
-
-Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
-
-This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
-
-@example
-```
-import type {LiteralUnion} from 'type-fest';
-
-// Before
-
-type Pet = 'dog' | 'cat' | string;
-
-const pet: Pet = '';
-// Start typing in your TypeScript-enabled IDE.
-// You **will not** get auto-completion for `dog` and `cat` literals.
-
-// After
-
-type Pet2 = LiteralUnion<'dog' | 'cat', string>;
-
-const pet: Pet2 = '';
-// You **will** get auto-completion for `dog` and `cat` literals.
-```
-
-@category Type
-*/
-type LiteralUnion<
-	LiteralType,
-	BaseType extends Primitive,
-> = LiteralType | (BaseType & Record<never, never>);
-
-declare const image: (data: Uint8Array, options?: {
+ * 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>;
-}) => string;
-
-export = image;
+}
+/**
+ * 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/image.d.mts

@@ -1,62 +1,73 @@
+import type { LiteralUnion } from "type-fest";
 /**
-Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-
-@category Type
-*/
-type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol
-	| bigint;
-
-declare global {
-	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
-	interface SymbolConstructor {
-		readonly observable: symbol;
-	}
-}
-
-/**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
-
-Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
-
-This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
-
-@example
-```
-import type {LiteralUnion} from 'type-fest';
-
-// Before
-
-type Pet = 'dog' | 'cat' | string;
-
-const pet: Pet = '';
-// Start typing in your TypeScript-enabled IDE.
-// You **will not** get auto-completion for `dog` and `cat` literals.
-
-// After
-
-type Pet2 = LiteralUnion<'dog' | 'cat', string>;
-
-const pet: Pet2 = '';
-// You **will** get auto-completion for `dog` and `cat` literals.
-```
-
-@category Type
-*/
-type LiteralUnion<
-	LiteralType,
-	BaseType extends Primitive,
-> = LiteralType | (BaseType & Record<never, never>);
-
-declare const image: (data: Uint8Array, options?: {
+ * 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>;
-}) => string;
-
-export { image as default };
+}
+/**
+ * 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/image.d.ts

@@ -1,62 +1,73 @@
+import type { LiteralUnion } from "type-fest";
 /**
-Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-
-@category Type
-*/
-type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol
-	| bigint;
-
-declare global {
-	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
-	interface SymbolConstructor {
-		readonly observable: symbol;
-	}
-}
-
-/**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
-
-Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
-
-This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
-
-@example
-```
-import type {LiteralUnion} from 'type-fest';
-
-// Before
-
-type Pet = 'dog' | 'cat' | string;
-
-const pet: Pet = '';
-// Start typing in your TypeScript-enabled IDE.
-// You **will not** get auto-completion for `dog` and `cat` literals.
-
-// After
-
-type Pet2 = LiteralUnion<'dog' | 'cat', string>;
-
-const pet: Pet2 = '';
-// You **will** get auto-completion for `dog` and `cat` literals.
-```
-
-@category Type
-*/
-type LiteralUnion<
-	LiteralType,
-	BaseType extends Primitive,
-> = LiteralType | (BaseType & Record<never, never>);
-
-declare const image: (data: Uint8Array, options?: {
+ * 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>;
-}) => string;
-
-export = image;
+}
+/**
+ * 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;