@puppuccino/ansi

Low-level ANSI escape code utilities for terminal applications.

Installation

npm install @puppuccino/ansi

Or install from GitHub:

npm install github:averagejoeslab/ansi

Features

• Cursor Control - Move, hide, show, save/restore cursor position
• Screen Control - Clear screen, scroll, alternate buffer
• Text Styling (SGR) - Bold, italic, underline, colors, and more
• Color Support - 16 colors, 256 colors, and 24-bit RGB
• String Width - Calculate visible width of strings with ANSI codes
• OSC Sequences - Hyperlinks, window titles, notifications

Usage

Cursor Control

import { cursor } from '@puppuccino/ansi';

// Move cursor
process.stdout.write(cursor.move(10, 5));     // Move to column 10, row 5
process.stdout.write(cursor.up(2));           // Move up 2 lines
process.stdout.write(cursor.down(1));         // Move down 1 line
process.stdout.write(cursor.forward(5));      // Move right 5 columns
process.stdout.write(cursor.back(3));         // Move left 3 columns

// Hide/show cursor
process.stdout.write(cursor.hide);
process.stdout.write(cursor.show);

// Save/restore position
process.stdout.write(cursor.save);
process.stdout.write(cursor.restore);

Screen Control

import { screen } from '@puppuccino/ansi';

// Clear screen
process.stdout.write(screen.clear);           // Clear entire screen
process.stdout.write(screen.clearLine);       // Clear current line
process.stdout.write(screen.clearDown);       // Clear from cursor down

// Alternate buffer (for full-screen apps)
process.stdout.write(screen.altBuffer);       // Enter alternate buffer
process.stdout.write(screen.mainBuffer);      // Return to main buffer

// Scrolling
process.stdout.write(screen.scrollUp(5));     // Scroll up 5 lines
process.stdout.write(screen.scrollDown(3));   // Scroll down 3 lines

Text Styling (SGR)

import { sgr, style } from '@puppuccino/ansi';

// Apply styles
console.log(style.bold('Bold text'));
console.log(style.italic('Italic text'));
console.log(style.underline('Underlined'));
console.log(style.strikethrough('Crossed out'));

// Colors
console.log(style.red('Red text'));
console.log(style.bgBlue('Blue background'));
console.log(style.rgb(255, 128, 0, 'Orange text'));
console.log(style.bgRgb(0, 0, 128, 'Navy background'));

// Combine styles
console.log(style.bold(style.red('Bold red')));

// Using SGR codes directly
import { SGR } from '@puppuccino/ansi';
process.stdout.write(sgr(SGR.bold, SGR.fgRed) + 'Bold Red' + sgr(SGR.reset));

String Width

import { stringWidth, stripAnsi } from '@puppuccino/ansi';

const styled = style.bold('Hello') + ' ' + style.red('World');

// Get visible length (excluding ANSI codes)
console.log(stringWidth(styled));  // 11

// Strip all ANSI codes
console.log(stripAnsi(styled));    // "Hello World"

OSC Sequences

import { osc } from '@puppuccino/ansi';

// Set window title
process.stdout.write(osc.title('My App'));

// Create hyperlink
console.log(osc.link('https://example.com', 'Click here'));

// Desktop notification (terminal support varies)
process.stdout.write(osc.notify('Alert', 'Something happened'));

API Reference

Constants

• CSI - Control Sequence Introducer (\x1b[)
• OSC - Operating System Command (\x1b])
• SGR - Select Graphic Rendition codes

Modules

• cursor - Cursor movement and visibility
• screen - Screen clearing and scrolling
• style - Text styling with SGR codes
• sgr() - Raw SGR sequence generator
• osc - OSC sequence utilities
• stringWidth() - Calculate visible string width
• stripAnsi() - Remove ANSI codes from string

License

MIT