Advanced Terminal Features

/**
 * Create a clickable link in the terminal
 * @param text - The text to display as the link
 * @param url - The URL to link to
 * @returns ANSI escape sequence with embedded hyperlink
 */
function link(text: string, url: string): string;

import { link } from 'ansi-escapes';

// Create a basic hyperlink
console.log(link('Visit our website', 'https://example.com'));

// Link with descriptive text
console.log(`Documentation: ${link('API Reference', 'https://api.example.com/docs')}`);

// Multiple links in output
console.log(`Resources: ${link('Docs', 'https://docs.example.com')} | ${link('GitHub', 'https://github.com/user/repo')}`);

/**
 * Display an image in the terminal
 * @param data - Image data as Uint8Array (usually from fs.readFile)
 * @param options - Optional display options
 * @returns ANSI escape sequence for image display
 */
function image(data: Uint8Array, options?: ImageOptions): string;

interface ImageOptions {
  /** Image width - number (character cells), string with unit, or 'auto' */
  width?: 'auto' | number | string;
  /** Image height - number (character cells), string with unit, or 'auto' */  
  height?: 'auto' | number | string;
  /** Whether to preserve aspect ratio (default: true) */
  preserveAspectRatio?: boolean;
}

import { image } from 'ansi-escapes';
import { readFileSync } from 'fs';

// Display image at original size
const imageData = readFileSync('./logo.png');
console.log(image(imageData));

// Display with specific width
console.log(image(imageData, { width: 50 }));

// Display with pixel dimensions
console.log(image(imageData, { width: '300px', height: '200px' }));

// Display with percentage of terminal size
console.log(image(imageData, { width: '50%', preserveAspectRatio: false }));

const iTerm: {
  /**
   * Inform iTerm2 of the current directory for semantic history
   * @param cwd - Current directory path (default: process.cwd())
   * @returns ANSI escape sequence for directory notification
   */
  setCwd(cwd?: string): string;

  /**
   * Create an iTerm2 annotation
   * @param message - The message to display in the annotation
   * @param options - Optional positioning and display options
   * @returns ANSI escape sequence for annotation
   */
  annotation(message: string, options?: AnnotationOptions): string;
};

interface AnnotationOptions {
  /** Number of columns to annotate (default: remainder of line) */
  length?: number;
  /** Starting X coordinate (must be used with y and length) */
  x?: number;
  /** Starting Y coordinate (must be used with x and length) */
  y?: number;
  /** Create hidden annotation (shown via "Show Annotations" command) */
  isHidden?: boolean;
}

import { iTerm } from 'ansi-escapes';
import { chdir, cwd } from 'process';

// Notify iTerm2 of current directory
process.stdout.write(iTerm.setCwd());

// Notify after changing directories
chdir('/path/to/project');
process.stdout.write(iTerm.setCwd('/path/to/project'));

// Use in shell-like applications
function changeDirectory(newPath) {
  chdir(newPath);
  process.stdout.write(iTerm.setCwd(newPath));
  console.log(`Changed to: ${newPath}`);
}

import { iTerm } from 'ansi-escapes';

// Basic annotation
console.log('Build completed');
process.stdout.write(iTerm.annotation('Build took 2.3s'));

// Positional annotation
process.stdout.write(iTerm.annotation('Error here', {
  x: 10,
  y: 5,
  length: 20
}));

// Hidden annotation (visible via Show Annotations command)
process.stdout.write(iTerm.annotation('Debug info', { isHidden: true }));

import ansiEscapes from 'ansi-escapes';
import { Terminal } from 'xterm';

const terminal = new Terminal();

// Links work in xterm.js with hyperlink addon
terminal.write(ansiEscapes.link('Click me', 'https://example.com'));

// Images require iTerm2-compatible terminal emulator
// Most browser-based terminals don't support image display