novac 2.0.1 → 2.2.0

package/novac/kits/kitansi/kitdef.js

@@ -0,0 +1,1402 @@
+'use strict';
+
+// ============================================================
+//  kitansi.js  —  Full ANSI escape sequence kit
+//  Every sequence. Every control. Every color system.
+//  module.exports = { kitdef: { ...all exports } }
+// ============================================================
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 1: CORE ESCAPE PRIMITIVES
+// ────────────────────────────────────────────────────────────
+
+const ESC  = '\x1b';       // Escape character
+const CSI  = '\x1b[';      // Control Sequence Introducer
+const OSC  = '\x1b]';      // Operating System Command
+const DCS  = '\x1bP';      // Device Control String
+const ST   = '\x1b\\';     // String Terminator
+const BEL  = '\x07';       // Bell character (alt ST for OSC)
+const SS3  = '\x1bO';      // Single Shift Three
+const PM   = '\x1b^';      // Privacy Message
+const APC  = '\x1b_';      // Application Program Command
+
+/**
+ * Raw CSI sequence builder.
+ * @param {string} code
+ * @returns {string}
+ */
+function csi(code) { return CSI + code; }
+
+/**
+ * Raw OSC sequence builder.
+ * @param {string} code
+ * @returns {string}
+ */
+function osc(code) { return OSC + code + BEL; }
+
+/**
+ * Raw OSC sequence with ST terminator instead of BEL.
+ */
+function oscST(code) { return OSC + code + ST; }
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 2: SGR — SELECT GRAPHIC RENDITION (styles/colors)
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Build a CSI SGR sequence from numeric codes.
+ * @param {...number} codes
+ * @returns {string}
+ */
+function sgr(...codes) { return CSI + codes.join(';') + 'm'; }
+
+// ── Reset ────────────────────────────────────────────────────
+
+const RESET         = sgr(0);    // Reset all attributes
+const RESET_FG      = sgr(39);   // Default foreground color
+const RESET_BG      = sgr(49);   // Default background color
+const RESET_UNDER   = sgr(59);   // Default underline color
+
+// ── Text style codes ─────────────────────────────────────────
+
+const Style = {
+  RESET:          sgr(0),
+  BOLD:           sgr(1),
+  DIM:            sgr(2),
+  ITALIC:         sgr(3),
+  UNDERLINE:      sgr(4),
+  BLINK:          sgr(5),       // Slow blink (<150/min)
+  BLINK_FAST:     sgr(6),       // Rapid blink (≥150/min, limited support)
+  INVERSE:        sgr(7),       // Swap fg/bg
+  HIDDEN:         sgr(8),       // Invisible (conceal)
+  STRIKE:         sgr(9),       // Strikethrough
+  FONT_DEFAULT:   sgr(10),      // Primary font
+  FONT_ALT_1:     sgr(11),
+  FONT_ALT_2:     sgr(12),
+  FONT_ALT_3:     sgr(13),
+  FONT_ALT_4:     sgr(14),
+  FONT_ALT_5:     sgr(15),
+  FONT_ALT_6:     sgr(16),
+  FONT_ALT_7:     sgr(17),
+  FONT_ALT_8:     sgr(18),
+  FONT_ALT_9:     sgr(19),
+  FRAKTUR:        sgr(20),      // Gothic / Fraktur (rare)
+  BOLD_OFF:       sgr(21),      // Bold off (or double underline)
+  NORMAL:         sgr(22),      // Normal intensity (bold+dim off)
+  ITALIC_OFF:     sgr(23),
+  UNDERLINE_OFF:  sgr(24),
+  BLINK_OFF:      sgr(25),
+  PROPORTIONAL:   sgr(26),      // Proportional spacing (rare)
+  INVERSE_OFF:    sgr(27),
+  REVEAL:         sgr(28),      // Conceal off
+  STRIKE_OFF:     sgr(29),
+  // 30-37: standard fg (see Color)
+  // 38: extended fg
+  // 39: default fg
+  // 40-47: standard bg (see Color)
+  // 48: extended bg
+  // 49: default bg
+  PROPORTIONAL_OFF: sgr(50),
+  FRAMED:         sgr(51),
+  ENCIRCLED:      sgr(52),
+  OVERLINE:       sgr(53),
+  FRAMED_OFF:     sgr(54),      // Framed + encircled off
+  OVERLINE_OFF:   sgr(55),
+  // 58: underline color (extended)
+  // 59: default underline color
+  SUPERSCRIPT:    sgr(73),      // Rare; mintty etc.
+  SUBSCRIPT:      sgr(74),
+  SUPERSCRIPT_OFF:sgr(75),
+  DOUBLE_UNDERLINE: sgr(21),    // In some terminals = double underline
+};
+
+// ── Standard 16 colors ───────────────────────────────────────
+
+const Color = {
+  // Foreground
+  FG_BLACK:          sgr(30),
+  FG_RED:            sgr(31),
+  FG_GREEN:          sgr(32),
+  FG_YELLOW:         sgr(33),
+  FG_BLUE:           sgr(34),
+  FG_MAGENTA:        sgr(35),
+  FG_CYAN:           sgr(36),
+  FG_WHITE:          sgr(37),
+  FG_DEFAULT:        sgr(39),
+  FG_BRIGHT_BLACK:   sgr(90),   // "Gray" / dark gray
+  FG_BRIGHT_RED:     sgr(91),
+  FG_BRIGHT_GREEN:   sgr(92),
+  FG_BRIGHT_YELLOW:  sgr(93),
+  FG_BRIGHT_BLUE:    sgr(94),
+  FG_BRIGHT_MAGENTA: sgr(95),
+  FG_BRIGHT_CYAN:    sgr(96),
+  FG_BRIGHT_WHITE:   sgr(97),
+
+  // Background
+  BG_BLACK:          sgr(40),
+  BG_RED:            sgr(41),
+  BG_GREEN:          sgr(42),
+  BG_YELLOW:         sgr(43),
+  BG_BLUE:           sgr(44),
+  BG_MAGENTA:        sgr(45),
+  BG_CYAN:           sgr(46),
+  BG_WHITE:          sgr(47),
+  BG_DEFAULT:        sgr(49),
+  BG_BRIGHT_BLACK:   sgr(100),
+  BG_BRIGHT_RED:     sgr(101),
+  BG_BRIGHT_GREEN:   sgr(102),
+  BG_BRIGHT_YELLOW:  sgr(103),
+  BG_BRIGHT_BLUE:    sgr(104),
+  BG_BRIGHT_MAGENTA: sgr(105),
+  BG_BRIGHT_CYAN:    sgr(106),
+  BG_BRIGHT_WHITE:   sgr(107),
+};
+
+// ── 256-color ─────────────────────────────────────────────────
+
+/**
+ * Set foreground to a 256-color palette entry (0–255).
+ * @param {number} n
+ * @returns {string}
+ */
+function fg256(n) { return sgr(38, 5, n); }
+
+/**
+ * Set background to a 256-color palette entry (0–255).
+ * @param {number} n
+ * @returns {string}
+ */
+function bg256(n) { return sgr(48, 5, n); }
+
+/**
+ * Set underline color to a 256-color palette entry.
+ * @param {number} n
+ * @returns {string}
+ */
+function ul256(n) { return sgr(58, 5, n); }
+
+// ── True color (24-bit RGB) ───────────────────────────────────
+
+/**
+ * Set foreground to an RGB true color.
+ * @param {number} r  0–255
+ * @param {number} g  0–255
+ * @param {number} b  0–255
+ * @returns {string}
+ */
+function fgRGB(r, g, b) { return sgr(38, 2, r, g, b); }
+
+/**
+ * Set background to an RGB true color.
+ */
+function bgRGB(r, g, b) { return sgr(48, 2, r, g, b); }
+
+/**
+ * Set underline color to an RGB true color.
+ */
+function ulRGB(r, g, b) { return sgr(58, 2, r, g, b); }
+
+/**
+ * Parse a hex color string (#RGB or #RRGGBB) to [r, g, b].
+ * @param {string} hex
+ * @returns {[number, number, number]}
+ */
+function _hexToRGB(hex) {
+  hex = hex.replace('#', '');
+  if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+  return [
+    parseInt(hex.slice(0, 2), 16),
+    parseInt(hex.slice(2, 4), 16),
+    parseInt(hex.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Set foreground to a hex color.
+ * @param {string} hex  '#RRGGBB' or '#RGB'
+ * @returns {string}
+ */
+function fgHex(hex) { return fgRGB(..._hexToRGB(hex)); }
+
+/**
+ * Set background to a hex color.
+ */
+function bgHex(hex) { return bgRGB(..._hexToRGB(hex)); }
+
+/**
+ * Set underline color to a hex color.
+ */
+function ulHex(hex) { return ulRGB(..._hexToRGB(hex)); }
+
+// ── Underline style (kitty / VTE extension) ──────────────────
+
+const UnderlineStyle = {
+  OFF:     sgr(4, 0),    // No underline
+  SINGLE:  sgr(4, 1),    // Single underline (or just sgr(4))
+  DOUBLE:  sgr(4, 2),    // Double underline
+  CURLY:   sgr(4, 3),    // Curly / wavy underline
+  DOTTED:  sgr(4, 4),    // Dotted underline
+  DASHED:  sgr(4, 5),    // Dashed underline
+};
+
+// ── Composite: wrap a string with open/close SGR codes ────────
+
+/**
+ * Wrap a string with one or more SGR open codes, closing with RESET.
+ * @param {string} str
+ * @param {...number} codes  SGR numeric codes
+ * @returns {string}
+ */
+function wrap(str, ...codes) {
+  return sgr(...codes) + str + RESET;
+}
+
+/**
+ * Wrap a string with explicit open and close SGR sequences.
+ * @param {string} str
+ * @param {string} open   - full escape sequence to prepend
+ * @param {string} close  - full escape sequence to append
+ * @returns {string}
+ */
+function wrapRaw(str, open, close) {
+  return open + str + close;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 3: CURSOR CONTROL
+// ────────────────────────────────────────────────────────────
+
+const Cursor = {
+  // ── Absolute positioning ─────────────────────────────────
+
+  /** Move cursor to row, col (1-based). */
+  to:            (row, col) => csi(`${row};${col}H`),
+  /** Alias: CUP — Cursor Position. */
+  pos:           (row, col) => csi(`${row};${col}H`),
+  /** Move to column (1-based). */
+  toCol:         (col)      => csi(`${col}G`),
+  /** Move to row (1-based). */
+  toRow:         (row)      => csi(`${row}d`),
+
+  // ── Relative movement ────────────────────────────────────
+
+  /** Move up N lines. */
+  up:            (n = 1)    => csi(`${n}A`),
+  /** Move down N lines. */
+  down:          (n = 1)    => csi(`${n}B`),
+  /** Move right N columns. */
+  right:         (n = 1)    => csi(`${n}C`),
+  /** Move left N columns. */
+  left:          (n = 1)    => csi(`${n}D`),
+  /** Move down N lines, to column 1 (CNL). */
+  nextLine:      (n = 1)    => csi(`${n}E`),
+  /** Move up N lines, to column 1 (CPL). */
+  prevLine:      (n = 1)    => csi(`${n}F`),
+
+  // ── Save / Restore ───────────────────────────────────────
+
+  /** Save cursor position (ANSI/VT100). */
+  save:          ESC + '7',
+  /** Restore cursor position (ANSI/VT100). */
+  restore:       ESC + '8',
+  /** Save cursor position (CSI variant). */
+  saveCSI:       csi('s'),
+  /** Restore cursor position (CSI variant). */
+  restoreCSI:    csi('u'),
+  /** Save cursor + attrs (DECSC). */
+  saveDEC:       ESC + '7',
+  /** Restore cursor + attrs (DECRC). */
+  restoreDEC:    ESC + '8',
+
+  // ── Visibility ───────────────────────────────────────────
+
+  /** Hide cursor. */
+  hide:          csi('?25l'),
+  /** Show cursor. */
+  show:          csi('?25h'),
+
+  // ── Style (DECSCUSR) ─────────────────────────────────────
+
+  /** Cursor styles via DECSCUSR. */
+  style: {
+    DEFAULT:          csi('0 q'),
+    BLOCK_BLINK:      csi('1 q'),
+    BLOCK_STEADY:     csi('2 q'),
+    UNDERLINE_BLINK:  csi('3 q'),
+    UNDERLINE_STEADY: csi('4 q'),
+    BAR_BLINK:        csi('5 q'),
+    BAR_STEADY:       csi('6 q'),
+  },
+
+  // ── Blinking ─────────────────────────────────────────────
+
+  /** Enable cursor blinking. */
+  blinkOn:       csi('?12h'),
+  /** Disable cursor blinking. */
+  blinkOff:      csi('?12l'),
+
+  // ── Report ───────────────────────────────────────────────
+
+  /** Request cursor position report (CPR). Terminal replies with ESC[row;colR. */
+  report:        csi('6n'),
+  /** Request extended cursor position (DECXCPR). */
+  reportExt:     csi('?6n'),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 4: SCREEN / LINE ERASING
+// ────────────────────────────────────────────────────────────
+
+const Erase = {
+  // ── Display ──────────────────────────────────────────────
+
+  /** Erase from cursor to end of screen (ED 0). */
+  toEndOfScreen:      csi('0J'),
+  /** Erase from start of screen to cursor (ED 1). */
+  toStartOfScreen:    csi('1J'),
+  /** Erase entire screen (ED 2). */
+  screen:             csi('2J'),
+  /** Erase entire screen + scrollback buffer (ED 3, xterm). */
+  screenAndScrollback:csi('3J'),
+
+  // ── Line ─────────────────────────────────────────────────
+
+  /** Erase from cursor to end of line (EL 0). */
+  toEndOfLine:        csi('0K'),
+  /** Erase from start of line to cursor (EL 1). */
+  toStartOfLine:      csi('1K'),
+  /** Erase entire current line (EL 2). */
+  line:               csi('2K'),
+
+  // ── Characters ───────────────────────────────────────────
+
+  /** Erase N characters at cursor position (ECH). */
+  chars:       (n = 1)   => csi(`${n}X`),
+  /** Delete N characters from cursor (DCH, shifts left). */
+  deleteChars: (n = 1)   => csi(`${n}P`),
+  /** Delete N lines from cursor (DL, shifts up). */
+  deleteLines: (n = 1)   => csi(`${n}M`),
+
+  // ── Insert ───────────────────────────────────────────────
+
+  /** Insert N blank characters at cursor (ICH, shifts right). */
+  insertChars: (n = 1)   => csi(`${n}@`),
+  /** Insert N blank lines at cursor (IL, shifts down). */
+  insertLines: (n = 1)   => csi(`${n}L`),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 5: SCROLLING
+// ────────────────────────────────────────────────────────────
+
+const Scroll = {
+  /** Scroll up N lines (SU — new lines at bottom). */
+  up:     (n = 1) => csi(`${n}S`),
+  /** Scroll down N lines (SD — new lines at top). */
+  down:   (n = 1) => csi(`${n}T`),
+  /** Set scrolling region top/bottom rows (DECSTBM, 1-based). */
+  region: (top, bottom) => csi(`${top};${bottom}r`),
+  /** Reset scrolling region to full screen. */
+  resetRegion: csi('r'),
+  /** Enable smooth (slow) scroll. */
+  smoothOn:  csi('?4h'),
+  /** Disable smooth scroll (jump scroll). */
+  smoothOff: csi('?4l'),
+  /** Save scrolling region. */
+  save:      ESC + '7',
+  /** Restore scrolling region. */
+  restore:   ESC + '8',
+  /** Pan down (DECBI — Back Index). */
+  panDown:   ESC + '6',
+  /** Pan up (DECFI — Forward Index). */
+  panUp:     ESC + '9',
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 6: SCREEN MODES & ALTERNATE BUFFER
+// ────────────────────────────────────────────────────────────
+
+const Screen = {
+  // ── Alternate screen buffer ──────────────────────────────
+
+  /** Enter alternate screen buffer (xterm). */
+  altOn:          csi('?1049h'),
+  /** Leave alternate screen buffer. */
+  altOff:         csi('?1049l'),
+  /** Enter alternate screen (simple, no save/restore). */
+  altSimpleOn:    csi('?47h'),
+  /** Leave alternate screen (simple). */
+  altSimpleOff:   csi('?47l'),
+
+  // ── Screen modes ─────────────────────────────────────────
+
+  /** 40×25 monochrome (text). */
+  mode40x25Mono:  csi('=0h'),
+  /** 40×25 color. */
+  mode40x25Color: csi('=1h'),
+  /** 80×25 monochrome. */
+  mode80x25Mono:  csi('=2h'),
+  /** 80×25 color. */
+  mode80x25Color: csi('=3h'),
+  /** 320×200 4-color. */
+  mode320x200_4:  csi('=4h'),
+  /** 320×200 monochrome. */
+  mode320x200Mono:csi('=5h'),
+  /** 320×200 color (mode 13h). */
+  mode320x200_256:csi('=13h'),
+  /** 640×200 monochrome. */
+  mode640x200Mono:csi('=6h'),
+  /** 640×200 color. */
+  mode640x200Color:csi('=14h'),
+  /** Line wrap on. */
+  wrapOn:         csi('?7h'),
+  /** Line wrap off. */
+  wrapOff:        csi('?7l'),
+  /** Reverse video (light background). */
+  reverseOn:      csi('?5h'),
+  /** Normal video. */
+  reverseOff:     csi('?5l'),
+  /** Enable bracketed paste mode. */
+  bracketedPasteOn:  csi('?2004h'),
+  /** Disable bracketed paste mode. */
+  bracketedPasteOff: csi('?2004l'),
+  /** Enable focus reporting. */
+  focusReportOn:  csi('?1004h'),
+  /** Disable focus reporting. */
+  focusReportOff: csi('?1004l'),
+
+  // ── Resize ────────────────────────────────────────────────
+
+  /** Resize terminal to cols×rows (xterm CSI 8 ; rows ; cols t). */
+  resize: (rows, cols) => csi(`8;${rows};${cols}t`),
+  /** Maximize window. */
+  maximize:       csi('9;1t'),
+  /** Restore window size. */
+  restoreSize:    csi('9;0t'),
+  /** Raise window to front. */
+  raise:          csi('5t'),
+  /** Lower window. */
+  lower:          csi('6t'),
+  /** Refresh / repaint window. */
+  repaint:        csi('7t'),
+  /** Report terminal size in chars (CSI 18 t). */
+  reportSize:     csi('18t'),
+  /** Report screen size in chars (CSI 19 t). */
+  reportScreenSize: csi('19t'),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 7: MOUSE REPORTING
+// ────────────────────────────────────────────────────────────
+
+const Mouse = {
+  // ── Basic mouse ──────────────────────────────────────────
+
+  /** Enable X10 mouse (button press only). */
+  x10On:              csi('?9h'),
+  x10Off:             csi('?9l'),
+
+  /** Enable normal (VT200) mouse reporting (press+release). */
+  normalOn:           csi('?1000h'),
+  normalOff:          csi('?1000l'),
+
+  /** Enable mouse highlight tracking. */
+  highlightOn:        csi('?1001h'),
+  highlightOff:       csi('?1001l'),
+
+  /** Enable button-event mouse reporting. */
+  buttonOn:           csi('?1002h'),
+  buttonOff:          csi('?1002l'),
+
+  /** Enable any-event mouse reporting (motion too). */
+  anyOn:              csi('?1003h'),
+  anyOff:             csi('?1003l'),
+
+  // ── Extended encoding ────────────────────────────────────
+
+  /** UTF-8 extended mouse mode (xterm). */
+  utf8On:             csi('?1005h'),
+  utf8Off:            csi('?1005l'),
+
+  /** SGR extended mouse mode (recommended; supports >223 cols). */
+  sgrOn:              csi('?1006h'),
+  sgrOff:             csi('?1006l'),
+
+  /** URXVT extended mouse mode. */
+  urxvtOn:            csi('?1015h'),
+  urxvtOff:           csi('?1015l'),
+
+  /** SGR pixel-based mouse reporting (xterm 379+). */
+  sgrPixelOn:         csi('?1016h'),
+  sgrPixelOff:        csi('?1016l'),
+
+  // ── Convenience combos ───────────────────────────────────
+
+  /** Enable full mouse (any-event + SGR encoding). */
+  enableFull:         csi('?1003h') + csi('?1006h'),
+  /** Disable full mouse. */
+  disableFull:        csi('?1003l') + csi('?1006l'),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 8: WINDOW / TITLE (OSC)
+// ────────────────────────────────────────────────────────────
+
+const Window = {
+  /**
+   * Set window title.
+   * @param {string} title
+   * @returns {string}
+   */
+  title:     (title)  => osc(`0;${title}`),
+  /**
+   * Set icon name only.
+   */
+  iconName:  (name)   => osc(`1;${name}`),
+  /**
+   * Set both icon name and window title.
+   */
+  titleAndIcon: (title) => osc(`0;${title}`),
+  /**
+   * Set terminal tab color (iTerm2 / some terminals). Hex e.g. 'ff0000'.
+   */
+  tabColor:  (hex)    => osc(`6;1;bg;red;brightness;${parseInt(hex.slice(0,2),16)}`),
+  /**
+   * iTerm2: set current directory.
+   */
+  currentDir:(path)   => osc(`7;file://localhost${path}`),
+  /**
+   * iTerm2: set mark (shell integration).
+   */
+  mark:               osc('133;A'),
+  /**
+   * iTerm2: start of command output.
+   */
+  cmdStart:           osc('133;C'),
+  /**
+   * iTerm2: end of command output.
+   */
+  cmdEnd:   (code=0)  => osc(`133;D;${code}`),
+  /**
+   * Hyperlink (OSC 8). Opens url, closes with empty url.
+   * @param {string} url
+   * @param {string} text
+   * @returns {string}
+   */
+  hyperlink: (url, text) => osc(`8;;${url}`) + ST + text + osc('8;;') + ST,
+  /**
+   * Notify (libnotify via OSC 777, supported by some terminals).
+   */
+  notify: (title, body) => osc(`777;notify;${title};${body}`),
+  /**
+   * Set clipboard contents (OSC 52).
+   * @param {string} data  - base64-encoded string
+   * @param {'c'|'p'|'s'} [buf='c'] - c=clipboard, p=primary, s=secondary
+   */
+  clipboard: (data, buf = 'c') => osc(`52;${buf};${data}`),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 9: DEVICE CONTROL / TERMINAL QUERIES
+// ────────────────────────────────────────────────────────────
+
+const Device = {
+  /** Device Attributes (DA1) — request terminal ID. */
+  queryDA1:           csi('c'),
+  /** Secondary Device Attributes (DA2). */
+  queryDA2:           csi('>c'),
+  /** Tertiary Device Attributes (DA3). */
+  queryDA3:           csi('=c'),
+  /** Status report (DSR) — reports cursor position. */
+  statusReport:       csi('5n'),
+  /** DECID — identify terminal. */
+  identify:           ESC + 'Z',
+  /** Request DEC private mode (DECRQM). */
+  queryMode: (mode)   => csi(`?${mode}$p`),
+  /** Soft terminal reset (DECSTR). */
+  softReset:          csi('!p'),
+  /** Hard terminal reset (RIS). */
+  hardReset:          ESC + 'c',
+  /** Invoke character set G0 (SI). */
+  charSetG0:          '\x0F',
+  /** Invoke character set G1 (SO). */
+  charSetG1:          '\x0E',
+  /** Designate G0 as US ASCII. */
+  g0ASCII:            ESC + '(B',
+  /** Designate G0 as DEC special graphics. */
+  g0DEC:              ESC + '(0',
+  /** Conformance Level. */
+  conformLevel1:      csi('61"p'),
+  conformLevel2:      csi('62"p'),
+  conformLevel3:      csi('63"p'),
+  conformLevel4:      csi('64"p'),
+  /** XTVERSION — request terminal version string. */
+  queryVersion:       csi('>0q'),
+  /** XTSMGRAPHICS — sixel / ReGIS graphics queries. */
+  querySixel:         csi('?1;1;0S'),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 10: SPECIAL / MISC SEQUENCES
+// ────────────────────────────────────────────────────────────
+
+const Special = {
+  /** Bell (BEL). */
+  bell:             BEL,
+  /** Backspace. */
+  backspace:        '\x08',
+  /** Horizontal tab. */
+  tab:              '\x09',
+  /** Line feed. */
+  lf:               '\x0A',
+  /** Vertical tab. */
+  vt:               '\x0B',
+  /** Form feed / new page. */
+  ff:               '\x0C',
+  /** Carriage return. */
+  cr:               '\x0D',
+  /** Return to home position (no erase). */
+  home:             csi('H'),
+  /** Next line (NEL). */
+  nextLine:         ESC + 'E',
+  /** Index (IND) — move down one line. */
+  index:            ESC + 'D',
+  /** Reverse index (RI) — move up one line. */
+  reverseIndex:     ESC + 'M',
+  /** Tab set at current column (HTS). */
+  tabSet:           ESC + 'H',
+  /** Tab clear at current column (TBC 0). */
+  tabClear:         csi('0g'),
+  /** Tab clear all (TBC 3). */
+  tabClearAll:      csi('3g'),
+  /** Tab forward N (CHT). */
+  tabForward:  (n=1) => csi(`${n}I`),
+  /** Tab backward N (CBT). */
+  tabBackward: (n=1) => csi(`${n}Z`),
+  /** Lock keyboard (DECLL). */
+  lockKbd:          csi('0q'),
+  /** Unlock keyboard. */
+  unlockKbd:        csi('2q'),
+  /** Application Keypad Mode. */
+  keypadApp:        ESC + '=',
+  /** Numeric Keypad Mode. */
+  keypadNum:        ESC + '>',
+  /** Application Cursor Keys (DECCKM). */
+  cursorKeysApp:    csi('?1h'),
+  /** Normal Cursor Keys. */
+  cursorKeysNormal: csi('?1l'),
+  /** Enable auto-repeat. */
+  autoRepeatOn:     csi('?8h'),
+  /** Disable auto-repeat. */
+  autoRepeatOff:    csi('?8l'),
+  /** Set insert mode (IRM). */
+  insertModeOn:     csi('4h'),
+  /** Set replace mode. */
+  insertModeOff:    csi('4l'),
+  /** Enable local echo. */
+  echoOn:           csi('12l'),
+  /** Disable local echo. */
+  echoOff:          csi('12h'),
+  /** DEC Origin Mode on (DECOM). */
+  originModeOn:     csi('?6h'),
+  /** DEC Origin Mode off. */
+  originModeOff:    csi('?6l'),
+  /** Column 132 mode on (DECCOLM). */
+  col132On:         csi('?3h'),
+  /** Column 80 mode. */
+  col80On:          csi('?3l'),
+  /** Enable 80/132 column switching (DECCOLM allowed). */
+  colSwitchOn:      csi('?40h'),
+  colSwitchOff:     csi('?40l'),
+  /** Left/right margin mode (DECLRMM). */
+  lrMarginOn:       csi('?69h'),
+  lrMarginOff:      csi('?69l'),
+  /** Set left and right margins (DECSLRM). */
+  setLRMargins: (l, r) => csi(`${l};${r}s`),
+  /** Print screen. */
+  printScreen:      csi('i'),
+  /** Print line. */
+  printLine:        csi('1i'),
+  /** Enter print controller mode. */
+  printCtrlOn:      csi('5i'),
+  /** Exit print controller mode. */
+  printCtrlOff:     csi('4i'),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 11: SIXEL GRAPHICS (DCS)
+// ────────────────────────────────────────────────────────────
+
+const Sixel = {
+  /**
+   * Begin a sixel data stream.
+   * @param {number} [aspectRatio=0]   - 0=1:1 pixels, 2=2:1 etc.
+   * @param {number} [background=0]    - 0=bg stays, 1=bg clears to first color
+   * @param {number} [gridSize=0]      - 0=use terminal default
+   * @returns {string}
+   */
+  begin: (aspectRatio = 0, background = 0, gridSize = 0) =>
+    `${DCS}${aspectRatio};${background};${gridSize}q`,
+
+  /** End sixel data stream. */
+  end: ST,
+
+  /** Wrap raw sixel data in a DCS container. */
+  wrap: (data, aspectRatio = 0, background = 0) =>
+    `${DCS}${aspectRatio};${background};0q${data}${ST}`,
+
+  /**
+   * Set sixel color register (# n ; 2 ; r ; g ; b for RGB, # n ; 1 ; h ; l ; s for HLS).
+   * @param {number} reg   - register index 0–255
+   * @param {number} r     - red 0–100
+   * @param {number} g     - green 0–100
+   * @param {number} b     - blue 0–100
+   */
+  colorRGB: (reg, r, g, b) => `#${reg};2;${r};${g};${b}`,
+
+  /**
+   * Set sixel color register (HLS).
+   * @param {number} reg
+   * @param {number} h   hue 0–360
+   * @param {number} l   lightness 0–100
+   * @param {number} s   saturation 0–100
+   */
+  colorHLS: (reg, h, l, s) => `#${reg};1;${h};${l};${s}`,
+
+  /** Use a defined color register for following sixel data. */
+  useColor: (reg) => `#${reg}`,
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 12: KITTY GRAPHICS PROTOCOL (APC)
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Build a kitty graphics protocol APC payload.
+ * @param {object} keys   - key=value control pairs
+ * @param {string} [payload='']
+ * @returns {string}
+ */
+function kittyGfx(keys, payload = '') {
+  const ctrl = Object.entries(keys).map(([k, v]) => `${k}=${v}`).join(',');
+  return `${APC}G${ctrl};${payload}${ST}`;
+}
+
+const KittyGfx = {
+  /**
+   * Transmit image data (chunked base64).
+   * @param {string} b64data  - base64 payload chunk
+   * @param {object} [opts]
+   * @param {'png'|'rgb'|'rgba'|'jpg'} [opts.format='png']
+   * @param {number} [opts.width]
+   * @param {number} [opts.height]
+   * @param {number} [opts.id]        - image id
+   * @param {0|1} [opts.more=0]       - 1 if more chunks follow
+   */
+  transmit: (b64data, opts = {}) => {
+    const keys = { a: 't', f: opts.format === 'rgb' ? 24 : opts.format === 'rgba' ? 32 : opts.format === 'jpg' ? 100 : 100, t: 'd' };
+    if (opts.width)  keys.s = opts.width;
+    if (opts.height) keys.v = opts.height;
+    if (opts.id)     keys.i = opts.id;
+    if (opts.more)   keys.m = opts.more;
+    return kittyGfx(keys, b64data);
+  },
+
+  /**
+   * Display a previously transmitted image.
+   * @param {number} id
+   * @param {object} [opts]
+   * @param {number} [opts.x]      - display column
+   * @param {number} [opts.y]      - display row
+   * @param {number} [opts.cols]   - display columns
+   * @param {number} [opts.rows]   - display rows
+   */
+  display: (id, opts = {}) => {
+    const keys = { a: 'p', i: id };
+    if (opts.x    !== undefined) keys.X = opts.x;
+    if (opts.y    !== undefined) keys.Y = opts.y;
+    if (opts.cols !== undefined) keys.c = opts.cols;
+    if (opts.rows !== undefined) keys.r = opts.rows;
+    return kittyGfx(keys);
+  },
+
+  /** Delete image by id. */
+  delete: (id) => kittyGfx({ a: 'd', d: 'i', i: id }),
+
+  /** Delete all images. */
+  deleteAll: kittyGfx({ a: 'd', d: 'a' }),
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 13: ITERM2 / WEZTERM INLINE IMAGES (OSC 1337)
+// ────────────────────────────────────────────────────────────
+
+const InlineImage = {
+  /**
+   * Display an inline image (iTerm2 / WezTerm protocol, OSC 1337).
+   * @param {string} b64data  - base64-encoded image data
+   * @param {object} [opts]
+   * @param {string} [opts.name]
+   * @param {number} [opts.width]   - in chars or pixels (e.g. '100px' or 10)
+   * @param {number} [opts.height]
+   * @param {boolean} [opts.preserveAspect=true]
+   * @param {boolean} [opts.inline=true]
+   */
+  display: (b64data, opts = {}) => {
+    const args = [`size=${b64data.length}`];
+    if (opts.name)   args.push(`name=${Buffer.from ? Buffer.from(opts.name).toString('base64') : btoa(opts.name)}`);
+    if (opts.width)  args.push(`width=${opts.width}`);
+    if (opts.height) args.push(`height=${opts.height}`);
+    args.push(`preserveAspectRatio=${opts.preserveAspect === false ? 0 : 1}`);
+    args.push(`inline=${opts.inline === false ? 0 : 1}`);
+    return `${OSC}1337;File=${args.join(';')}:${b64data}${BEL}`;
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 14: STRIP / MEASURE / DETECT
+// ────────────────────────────────────────────────────────────
+
+/** Regex matching all ANSI escape sequences. */
+const ANSI_RE = /\x1b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|][^\x07\x1b]*(?:\x07|\x1b\\)|[()][AB012]|[NOPX^_][\s\S]*?\x1b\\)/g;
+
+/**
+ * Strip all ANSI escape sequences from a string.
+ * @param {string} str
+ * @returns {string}
+ */
+function strip(str) {
+  return str.replace(ANSI_RE, '');
+}
+
+/**
+ * Measure the visible (printable) length of a string after stripping ANSI.
+ * Accounts for fullwidth Unicode characters (CJK, emoji) as width 2.
+ * @param {string} str
+ * @returns {number}
+ */
+function visibleLength(str) {
+  const s = strip(str);
+  let len = 0;
+  for (const cp of s) {
+    const code = cp.codePointAt(0);
+    // Fullwidth / wide chars: CJK unified, CJK compat, fullwidth forms, emoji blocks
+    if (
+      (code >= 0x1100  && code <= 0x115F)  ||   // Hangul Jamo
+      (code >= 0x2E80  && code <= 0x303E)  ||   // CJK Radicals
+      (code >= 0x3041  && code <= 0x33FF)  ||   // Hiragana, Katakana, CJK compat
+      (code >= 0x3400  && code <= 0x4DBF)  ||   // CJK Extension A
+      (code >= 0x4E00  && code <= 0xA4CF)  ||   // CJK Unified
+      (code >= 0xA960  && code <= 0xA97F)  ||   // Hangul Jamo Extended
+      (code >= 0xAC00  && code <= 0xD7FF)  ||   // Hangul Syllables
+      (code >= 0xF900  && code <= 0xFAFF)  ||   // CJK Compat Ideographs
+      (code >= 0xFE10  && code <= 0xFE19)  ||   // Vertical Forms
+      (code >= 0xFE30  && code <= 0xFE4F)  ||   // CJK Compat Forms
+      (code >= 0xFF01  && code <= 0xFF60)  ||   // Fullwidth ASCII + Halfwidth Katakana
+      (code >= 0xFFE0  && code <= 0xFFE6)  ||   // Fullwidth Signs
+      (code >= 0x1B000 && code <= 0x1B0FF) ||   // Kana Supplement
+      (code >= 0x1F004 && code <= 0x1F0CF) ||   // Mahjong / Playing cards
+      (code >= 0x1F300 && code <= 0x1F9FF) ||   // Misc symbols, Emoji
+      (code >= 0x20000 && code <= 0x2FFFD) ||   // CJK Extension B-F
+      (code >= 0x30000 && code <= 0x3FFFD)       // CJK Extension G
+    ) {
+      len += 2;
+    } else if (code >= 0x0300 && code <= 0x036F) {
+      // Combining diacriticals: zero width
+    } else {
+      len += 1;
+    }
+  }
+  return len;
+}
+
+/**
+ * Detect whether the current environment likely supports ANSI color.
+ * @returns {'truecolor'|'256'|'16'|'none'}
+ */
+function detectColorSupport() {
+  // Browser / non-Node environment
+  if (typeof process === 'undefined') return 'none';
+
+  const env   = process.env || {};
+  const argv  = process.argv || [];
+  const term  = (env.TERM || '').toLowerCase();
+  const cterm = (env.COLORTERM || '').toLowerCase();
+
+  // Explicitly disabled
+  if (env.NO_COLOR !== undefined || env.NODE_DISABLE_COLORS !== undefined) return 'none';
+  if (argv.includes('--no-color') || argv.includes('--color=false')) return 'none';
+
+  // Force flags
+  if (argv.includes('--color=16m') || argv.includes('--color=full')) return 'truecolor';
+  if (argv.includes('--color=256')) return '256';
+  if (argv.includes('--color')) return '16';
+
+  // Truecolor env vars
+  if (cterm === 'truecolor' || cterm === '24bit') return 'truecolor';
+  if (env.TERM_PROGRAM === 'iTerm.app') return 'truecolor';
+  if (env.TERM_PROGRAM === 'hyper') return 'truecolor';
+  if (env.TERM_PROGRAM === 'vscode') return 'truecolor';
+  if (env.WT_SESSION) return 'truecolor';            // Windows Terminal
+  if (env.COLORTERM) return '256';
+
+  // 256 color
+  if (term.includes('256color')) return '256';
+  if (term.includes('256')) return '256';
+
+  // 16 color
+  if (term.includes('color') || term === 'xterm' || term === 'screen' || term === 'linux') return '16';
+
+  // Check if stdout is a TTY
+  if (process.stdout && process.stdout.isTTY) return '16';
+
+  return 'none';
+}
+
+/**
+ * Returns true if the environment supports at least basic color.
+ */
+function hasColor() {
+  return detectColorSupport() !== 'none';
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 15: ANSI PARSER
+// ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} AnsiToken
+ * @property {'text'|'sgr'|'cursor'|'erase'|'osc'|'dcs'|'escape'|'unknown'} type
+ * @property {string} raw       - the raw escape sequence or text chunk
+ * @property {string} [text]    - for type='text', the plain text
+ * @property {number[]} [codes] - for type='sgr', the SGR code list
+ * @property {string} [cmd]     - final byte / command identifier
+ * @property {string} [params]  - raw parameter string
+ * @property {string} [payload] - for OSC/DCS, the payload string
+ * @property {object} [style]   - decoded style object for SGR tokens
+ */
+
+const SGR_NAMES = {
+  0:  'reset',
+  1:  'bold',        2:  'dim',       3:  'italic',
+  4:  'underline',   5:  'blink',     6:  'blink_fast',
+  7:  'inverse',     8:  'hidden',    9:  'strike',
+  21: 'double_underline',
+  22: 'normal',      23: 'italic_off', 24: 'underline_off',
+  25: 'blink_off',   27: 'inverse_off', 28: 'reveal',
+  29: 'strike_off',
+  30: 'fg_black',    31: 'fg_red',    32: 'fg_green',   33: 'fg_yellow',
+  34: 'fg_blue',     35: 'fg_magenta',36: 'fg_cyan',    37: 'fg_white',
+  39: 'fg_default',
+  40: 'bg_black',    41: 'bg_red',    42: 'bg_green',   43: 'bg_yellow',
+  44: 'bg_blue',     45: 'bg_magenta',46: 'bg_cyan',    47: 'bg_white',
+  49: 'bg_default',
+  51: 'framed',      52: 'encircled', 53: 'overline',
+  54: 'framed_off',  55: 'overline_off',
+  90: 'fg_bright_black',  91: 'fg_bright_red',   92: 'fg_bright_green',
+  93: 'fg_bright_yellow', 94: 'fg_bright_blue',  95: 'fg_bright_magenta',
+  96: 'fg_bright_cyan',   97: 'fg_bright_white',
+  100:'bg_bright_black',  101:'bg_bright_red',   102:'bg_bright_green',
+  103:'bg_bright_yellow', 104:'bg_bright_blue',  105:'bg_bright_magenta',
+  106:'bg_bright_cyan',   107:'bg_bright_white',
+};
+
+/**
+ * Decode a list of SGR codes into a human-readable style object.
+ * @param {number[]} codes
+ * @returns {object}
+ */
+function decodeSGR(codes) {
+  const style = {};
+  let i = 0;
+  while (i < codes.length) {
+    const c = codes[i];
+    if ((c === 38 || c === 48 || c === 58) && codes[i+1] === 2) {
+      // RGB color
+      const [r, g, b] = [codes[i+2], codes[i+3], codes[i+4]];
+      const key = c === 38 ? 'fg' : c === 48 ? 'bg' : 'ul';
+      style[key] = { type: 'rgb', r, g, b, hex: `#${[r,g,b].map(v=>v.toString(16).padStart(2,'0')).join('')}` };
+      i += 5;
+    } else if ((c === 38 || c === 48 || c === 58) && codes[i+1] === 5) {
+      const key = c === 38 ? 'fg' : c === 48 ? 'bg' : 'ul';
+      style[key] = { type: '256', index: codes[i+2] };
+      i += 3;
+    } else {
+      if (SGR_NAMES[c]) style[SGR_NAMES[c]] = true;
+      i++;
+    }
+  }
+  return style;
+}
+
+/**
+ * Parse a string containing ANSI escape sequences into an array of tokens.
+ * @param {string} str
+ * @returns {AnsiToken[]}
+ */
+function parse(str) {
+  const tokens = [];
+  // Tokeniser: match escape sequences or text runs
+  const re = /\x1b(?:(\[)([\x30-\x3F]*)([\x20-\x2F]*)([\x40-\x7E])|(])((?:[^\x07\x1b]|\x1b(?!\\))*?)(?:\x07|\x1b\\)|(P)([\s\S]*?)\x1b\\|([@-Z\\-_]))/g;
+  let last = 0;
+
+  for (let m = re.exec(str); m; m = re.exec(str)) {
+    // Text before this match
+    if (m.index > last) tokens.push({ type: 'text', raw: str.slice(last, m.index), text: str.slice(last, m.index) });
+    last = re.lastIndex;
+
+    if (m[1] === '[') {
+      // CSI sequence
+      const params = m[2] || '';
+      const inter  = m[3] || '';
+      const cmd    = m[4];
+      const raw    = m[0];
+      if (cmd === 'm') {
+        // SGR
+        const codes = params === '' ? [0] : params.split(';').map(Number);
+        tokens.push({ type: 'sgr', raw, params, cmd, codes, style: decodeSGR(codes) });
+      } else if ('ABCDEFGH'.includes(cmd)) {
+        tokens.push({ type: 'cursor', raw, params, cmd });
+      } else if ('JK'.includes(cmd)) {
+        tokens.push({ type: 'erase', raw, params, cmd });
+      } else {
+        tokens.push({ type: 'csi', raw, params, inter, cmd });
+      }
+    } else if (m[5] === ']') {
+      // OSC sequence
+      tokens.push({ type: 'osc', raw: m[0], payload: m[6] });
+    } else if (m[7] === 'P') {
+      // DCS sequence
+      tokens.push({ type: 'dcs', raw: m[0], payload: m[8] });
+    } else {
+      // Single ESC + char
+      tokens.push({ type: 'escape', raw: m[0], cmd: m[9] });
+    }
+  }
+
+  // Trailing text
+  if (last < str.length) tokens.push({ type: 'text', raw: str.slice(last), text: str.slice(last) });
+  return tokens;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 16: CHAINABLE ANSI STRING BUILDER
+// ────────────────────────────────────────────────────────────
+
+/**
+ * AnsiString — chainable ANSI-aware string builder.
+ *
+ * Every method returns a new AnsiString (immutable chain).
+ * Call .toString() to get the final escape-code-embedded string.
+ * Call .plain() to get the stripped visible text.
+ *
+ * @example
+ * const s = AnsiString.of('Hello')
+ *   .bold()
+ *   .fgRGB(255, 100, 0)
+ *   .append(' World')
+ *   .underline()
+ *   .toString();
+ */
+class AnsiString {
+  /**
+   * @param {string} [str='']
+   */
+  constructor(str = '') {
+    this._buf = String(str);
+  }
+
+  /** Create a new AnsiString from a value. */
+  static of(str = '') { return new AnsiString(str); }
+
+  /** Get the raw (escape-code-embedded) string. */
+  toString() { return this._buf; }
+  valueOf()  { return this._buf; }
+
+  /** Get the visible plain text (no escape codes). */
+  plain() { return strip(this._buf); }
+
+  /** Visible character width. */
+  width() { return visibleLength(this._buf); }
+
+  _clone(str) { return new AnsiString(str); }
+
+  // ── Append / prepend ────────────────────────────────────
+
+  /** Append raw text or another AnsiString. */
+  append(str)  { return this._clone(this._buf + String(str)); }
+  /** Prepend raw text or another AnsiString. */
+  prepend(str) { return this._clone(String(str) + this._buf); }
+  /** Append a newline. */
+  nl()         { return this._clone(this._buf + '\n'); }
+  /** Append a reset code. */
+  reset()      { return this._clone(this._buf + RESET); }
+
+  // ── SGR style methods ────────────────────────────────────
+
+  /** Apply one or more raw SGR codes to the current content. */
+  _sgr(openCodes, closeCodes) {
+    return this._clone(sgr(...openCodes) + this._buf + sgr(...closeCodes));
+  }
+
+  bold()          { return this._sgr([1],  [22]); }
+  dim()           { return this._sgr([2],  [22]); }
+  italic()        { return this._sgr([3],  [23]); }
+  underline()     { return this._sgr([4],  [24]); }
+  blink()         { return this._sgr([5],  [25]); }
+  blinkFast()     { return this._sgr([6],  [25]); }
+  inverse()       { return this._sgr([7],  [27]); }
+  hidden()        { return this._sgr([8],  [28]); }
+  strike()        { return this._sgr([9],  [29]); }
+  overline()      { return this._sgr([53], [55]); }
+  framed()        { return this._sgr([51], [54]); }
+  encircled()     { return this._sgr([52], [54]); }
+  doubleUnderline() { return this._sgr([21], [24]); }
+  superscript()   { return this._sgr([73], [75]); }
+  subscript()     { return this._sgr([74], [75]); }
+
+  // ── Standard 16 colors ───────────────────────────────────
+
+  black()         { return this._sgr([30], [39]); }
+  red()           { return this._sgr([31], [39]); }
+  green()         { return this._sgr([32], [39]); }
+  yellow()        { return this._sgr([33], [39]); }
+  blue()          { return this._sgr([34], [39]); }
+  magenta()       { return this._sgr([35], [39]); }
+  cyan()          { return this._sgr([36], [39]); }
+  white()         { return this._sgr([37], [39]); }
+  gray()          { return this._sgr([90], [39]); }
+  brightRed()     { return this._sgr([91], [39]); }
+  brightGreen()   { return this._sgr([92], [39]); }
+  brightYellow()  { return this._sgr([93], [39]); }
+  brightBlue()    { return this._sgr([94], [39]); }
+  brightMagenta() { return this._sgr([95], [39]); }
+  brightCyan()    { return this._sgr([96], [39]); }
+  brightWhite()   { return this._sgr([97], [39]); }
+
+  bgBlack()         { return this._sgr([40],  [49]); }
+  bgRed()           { return this._sgr([41],  [49]); }
+  bgGreen()         { return this._sgr([42],  [49]); }
+  bgYellow()        { return this._sgr([43],  [49]); }
+  bgBlue()          { return this._sgr([44],  [49]); }
+  bgMagenta()       { return this._sgr([45],  [49]); }
+  bgCyan()          { return this._sgr([46],  [49]); }
+  bgWhite()         { return this._sgr([47],  [49]); }
+  bgGray()          { return this._sgr([100], [49]); }
+  bgBrightRed()     { return this._sgr([101], [49]); }
+  bgBrightGreen()   { return this._sgr([102], [49]); }
+  bgBrightYellow()  { return this._sgr([103], [49]); }
+  bgBrightBlue()    { return this._sgr([104], [49]); }
+  bgBrightMagenta() { return this._sgr([105], [49]); }
+  bgBrightCyan()    { return this._sgr([106], [49]); }
+  bgBrightWhite()   { return this._sgr([107], [49]); }
+
+  // ── 256 color ────────────────────────────────────────────
+
+  /** Foreground 256-color (0–255). */
+  fg256(n)    { return this._clone(fg256(n)  + this._buf + sgr(39)); }
+  /** Background 256-color (0–255). */
+  bg256(n)    { return this._clone(bg256(n)  + this._buf + sgr(49)); }
+  /** Underline 256-color. */
+  ul256(n)    { return this._clone(ul256(n)  + this._buf + sgr(59)); }
+
+  // ── True color ───────────────────────────────────────────
+
+  /** Foreground RGB. */
+  fgRGB(r, g, b)    { return this._clone(fgRGB(r,g,b) + this._buf + sgr(39)); }
+  /** Background RGB. */
+  bgRGB(r, g, b)    { return this._clone(bgRGB(r,g,b) + this._buf + sgr(49)); }
+  /** Underline RGB. */
+  ulRGB(r, g, b)    { return this._clone(ulRGB(r,g,b) + this._buf + sgr(59)); }
+  /** Foreground hex. */
+  fgHex(hex)        { return this._clone(fgHex(hex)   + this._buf + sgr(39)); }
+  /** Background hex. */
+  bgHex(hex)        { return this._clone(bgHex(hex)   + this._buf + sgr(49)); }
+  /** Underline hex. */
+  ulHex(hex)        { return this._clone(ulHex(hex)   + this._buf + sgr(59)); }
+
+  // ── Gradient (horizontal true-color) ─────────────────────
+
+  /**
+   * Apply a horizontal RGB gradient across the visible characters.
+   * @param {[number,number,number]} from  - start [r,g,b]
+   * @param {[number,number,number]} to    - end [r,g,b]
+   * @param {'fg'|'bg'} [target='fg']
+   */
+  gradient(from, to, target = 'fg') {
+    const plain = this.plain();
+    const len = plain.length || 1;
+    let out = '';
+    for (let i = 0; i < plain.length; i++) {
+      const t = i / (len - 1 || 1);
+      const r = Math.round(from[0] + (to[0] - from[0]) * t);
+      const g = Math.round(from[1] + (to[1] - from[1]) * t);
+      const b = Math.round(from[2] + (to[2] - from[2]) * t);
+      out += (target === 'bg' ? bgRGB(r,g,b) : fgRGB(r,g,b)) + plain[i];
+    }
+    out += RESET;
+    return this._clone(out);
+  }
+
+  // ── Underline style ──────────────────────────────────────
+
+  curlyUnderline()  { return this._clone(UnderlineStyle.CURLY  + this._buf + sgr(24)); }
+  dottedUnderline() { return this._clone(UnderlineStyle.DOTTED + this._buf + sgr(24)); }
+  dashedUnderline() { return this._clone(UnderlineStyle.DASHED + this._buf + sgr(24)); }
+
+  // ── Wrapping helpers ─────────────────────────────────────
+
+  /** Wrap entire current buffer with open/close sequences. */
+  wrap(open, close) { return this._clone(open + this._buf + close); }
+
+  /** Apply an arbitrary transform function to the raw string. */
+  pipe(fn) { return this._clone(fn(this._buf)); }
+
+  /** Strip all ANSI codes. */
+  strip() { return this._clone(strip(this._buf)); }
+
+  /** Pad right to a visible width (ANSI-aware). */
+  padEnd(width, char = ' ') {
+    const vlen = visibleLength(this._buf);
+    if (vlen >= width) return this;
+    return this._clone(this._buf + char.repeat(width - vlen));
+  }
+
+  /** Pad left to a visible width (ANSI-aware). */
+  padStart(width, char = ' ') {
+    const vlen = visibleLength(this._buf);
+    if (vlen >= width) return this;
+    return this._clone(char.repeat(width - vlen) + this._buf);
+  }
+
+  /** Center to a visible width (ANSI-aware). */
+  padCenter(width, char = ' ') {
+    const vlen = visibleLength(this._buf);
+    if (vlen >= width) return this;
+    const total = width - vlen;
+    const left  = Math.floor(total / 2);
+    const right = total - left;
+    return this._clone(char.repeat(left) + this._buf + char.repeat(right));
+  }
+
+  /** Parse the current string into AnsiTokens. */
+  parse() { return parse(this._buf); }
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 17: CONVENIENCE WRAP FUNCTIONS
+// ────────────────────────────────────────────────────────────
+
+// These are standalone functions that mirror the AnsiString methods
+// for use without the class.
+
+const bold          = (s) => sgr(1)  + s + sgr(22);
+const dim           = (s) => sgr(2)  + s + sgr(22);
+const italic        = (s) => sgr(3)  + s + sgr(23);
+const underline     = (s) => sgr(4)  + s + sgr(24);
+const blink         = (s) => sgr(5)  + s + sgr(25);
+const blinkFast     = (s) => sgr(6)  + s + sgr(25);
+const inverse       = (s) => sgr(7)  + s + sgr(27);
+const hidden        = (s) => sgr(8)  + s + sgr(28);
+const strike        = (s) => sgr(9)  + s + sgr(29);
+const overline      = (s) => sgr(53) + s + sgr(55);
+const framed        = (s) => sgr(51) + s + sgr(54);
+
+// FG
+const black         = (s) => sgr(30) + s + sgr(39);
+const red           = (s) => sgr(31) + s + sgr(39);
+const green         = (s) => sgr(32) + s + sgr(39);
+const yellow        = (s) => sgr(33) + s + sgr(39);
+const blue          = (s) => sgr(34) + s + sgr(39);
+const magenta       = (s) => sgr(35) + s + sgr(39);
+const cyan          = (s) => sgr(36) + s + sgr(39);
+const white         = (s) => sgr(37) + s + sgr(39);
+const gray          = (s) => sgr(90) + s + sgr(39);
+const brightRed     = (s) => sgr(91) + s + sgr(39);
+const brightGreen   = (s) => sgr(92) + s + sgr(39);
+const brightYellow  = (s) => sgr(93) + s + sgr(39);
+const brightBlue    = (s) => sgr(94) + s + sgr(39);
+const brightMagenta = (s) => sgr(95) + s + sgr(39);
+const brightCyan    = (s) => sgr(96) + s + sgr(39);
+const brightWhite   = (s) => sgr(97) + s + sgr(39);
+
+// BG
+const bgBlack         = (s) => sgr(40)  + s + sgr(49);
+const bgRed           = (s) => sgr(41)  + s + sgr(49);
+const bgGreen         = (s) => sgr(42)  + s + sgr(49);
+const bgYellow        = (s) => sgr(43)  + s + sgr(49);
+const bgBlue          = (s) => sgr(44)  + s + sgr(49);
+const bgMagenta       = (s) => sgr(45)  + s + sgr(49);
+const bgCyan          = (s) => sgr(46)  + s + sgr(49);
+const bgWhite         = (s) => sgr(47)  + s + sgr(49);
+const bgGray          = (s) => sgr(100) + s + sgr(49);
+const bgBrightRed     = (s) => sgr(101) + s + sgr(49);
+const bgBrightGreen   = (s) => sgr(102) + s + sgr(49);
+const bgBrightYellow  = (s) => sgr(103) + s + sgr(49);
+const bgBrightBlue    = (s) => sgr(104) + s + sgr(49);
+const bgBrightMagenta = (s) => sgr(105) + s + sgr(49);
+const bgBrightCyan    = (s) => sgr(106) + s + sgr(49);
+const bgBrightWhite   = (s) => sgr(107) + s + sgr(49);
+
+/**
+ * Apply a horizontal RGB gradient to a plain string.
+ * @param {string} str
+ * @param {[number,number,number]} from
+ * @param {[number,number,number]} to
+ * @param {'fg'|'bg'} [target='fg']
+ */
+function gradient(str, from, to, target = 'fg') {
+  return AnsiString.of(str).gradient(from, to, target).toString();
+}
+
+// ────────────────────────────────────────────────────────────
+//  EXPORTS
+// ────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    // ── Primitives ──────────────────────────────────
+    ESC, CSI, OSC, DCS, ST, BEL, SS3, PM, APC,
+    csi, osc, oscST, sgr,
+
+    // ── SGR constants ────────────────────────────────
+    RESET, RESET_FG, RESET_BG, RESET_UNDER,
+    Style, Color, UnderlineStyle,
+
+    // ── Color functions ──────────────────────────────
+    fg256, bg256, ul256,
+    fgRGB, bgRGB, ulRGB,
+    fgHex, bgHex, ulHex,
+
+    // ── Wrap helpers ─────────────────────────────────
+    wrap, wrapRaw,
+
+    // ── Standalone style functions ───────────────────
+    bold, dim, italic, underline, blink, blinkFast,
+    inverse, hidden, strike, overline, framed,
+    black, red, green, yellow, blue, magenta, cyan, white, gray,
+    brightRed, brightGreen, brightYellow, brightBlue,
+    brightMagenta, brightCyan, brightWhite,
+    bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta,
+    bgCyan, bgWhite, bgGray, bgBrightRed, bgBrightGreen,
+    bgBrightYellow, bgBrightBlue, bgBrightMagenta,
+    bgBrightCyan, bgBrightWhite,
+    gradient,
+
+    // ── Terminal control ─────────────────────────────
+    Cursor, Erase, Scroll, Screen, Mouse, Window,
+    Device, Special,
+
+    // ── Graphics protocols ───────────────────────────
+    Sixel, KittyGfx, kittyGfx, InlineImage,
+
+    // ── Utilities ────────────────────────────────────
+    strip, visibleLength,
+    detectColorSupport, hasColor,
+    parse, decodeSGR,
+    ANSI_RE,
+
+    // ── Chainable builder ────────────────────────────
+    AnsiString,
+  }
+};