@butlerw/vellum 0.1.0

package/src/tui/utils/text-width.ts

@@ -0,0 +1,225 @@
+/**
+ * Text Width Utilities
+ *
+ * Visual width calculation and manipulation utilities for terminal text.
+ * Handles CJK characters, emojis, and ANSI escape sequences correctly.
+ *
+ * @module tui/utils/text-width
+ */
+
+import stringWidth from "string-width";
+import wrapAnsi from "wrap-ansi";
+
+/**
+ * Text alignment options for padding.
+ */
+export type TextAlign = "left" | "center" | "right";
+
+/**
+ * Get the visual width of text in terminal columns.
+ *
+ * This accounts for:
+ * - CJK characters (width 2)
+ * - Emojis (width 2)
+ * - ANSI escape sequences (width 0)
+ * - Zero-width characters
+ *
+ * @param text - Text to measure
+ * @returns Visual width in terminal columns
+ *
+ * @example
+ * ```ts
+ * getVisualWidth("hello") // 5
+ * getVisualWidth("你好") // 4 (2 chars × 2 width)
+ * getVisualWidth("👋") // 2
+ * getVisualWidth("\x1b[31mred\x1b[0m") // 3 (ANSI codes have 0 width)
+ * ```
+ */
+export function getVisualWidth(text: string): number {
+  return stringWidth(text);
+}
+
+/**
+ * Truncate text to fit within a maximum visual width.
+ *
+ * Adds ellipsis if truncation is needed. Handles ANSI codes correctly,
+ * ensuring escape sequences are properly closed.
+ *
+ * @param text - Text to truncate
+ * @param maxWidth - Maximum visual width
+ * @param ellipsis - Ellipsis string (default: "…")
+ * @returns Truncated text with ellipsis if needed
+ *
+ * @example
+ * ```ts
+ * truncateToWidth("Hello World", 8) // "Hello W…"
+ * truncateToWidth("Short", 10) // "Short"
+ * truncateToWidth("你好世界", 5) // "你好…"
+ * ```
+ */
+export function truncateToWidth(text: string, maxWidth: number, ellipsis = "…"): string {
+  const textWidth = getVisualWidth(text);
+
+  if (textWidth <= maxWidth) {
+    return text;
+  }
+
+  const ellipsisWidth = getVisualWidth(ellipsis);
+  const targetWidth = maxWidth - ellipsisWidth;
+
+  if (targetWidth <= 0) {
+    return ellipsis.slice(0, maxWidth);
+  }
+
+  // Build truncated string character by character
+  let result = "";
+  let currentWidth = 0;
+
+  for (const char of text) {
+    const charWidth = getVisualWidth(char);
+    if (currentWidth + charWidth > targetWidth) {
+      break;
+    }
+    result += char;
+    currentWidth += charWidth;
+  }
+
+  return result + ellipsis;
+}
+
+/**
+ * Pad text to a specific visual width with alignment.
+ *
+ * @param text - Text to pad
+ * @param width - Target visual width
+ * @param align - Alignment: "left", "center", or "right"
+ * @param padChar - Character to use for padding (default: space)
+ * @returns Padded text
+ *
+ * @example
+ * ```ts
+ * padToWidth("Hi", 10, "left")   // "Hi        "
+ * padToWidth("Hi", 10, "right")  // "        Hi"
+ * padToWidth("Hi", 10, "center") // "    Hi    "
+ * padToWidth("你好", 8, "center") // "  你好  "
+ * ```
+ */
+export function padToWidth(
+  text: string,
+  width: number,
+  align: TextAlign = "left",
+  padChar = " "
+): string {
+  const textWidth = getVisualWidth(text);
+  const padCharWidth = getVisualWidth(padChar);
+
+  if (textWidth >= width) {
+    return text;
+  }
+
+  const totalPadding = width - textWidth;
+  const padCount = Math.floor(totalPadding / padCharWidth);
+
+  switch (align) {
+    case "right": {
+      return padChar.repeat(padCount) + text;
+    }
+    case "center": {
+      const leftPad = Math.floor(padCount / 2);
+      const rightPad = padCount - leftPad;
+      return padChar.repeat(leftPad) + text + padChar.repeat(rightPad);
+    }
+    default: {
+      // "left" alignment (default)
+      return text + padChar.repeat(padCount);
+    }
+  }
+}
+
+/**
+ * Wrap text at visual width boundaries.
+ *
+ * Uses wrap-ansi for proper handling of ANSI codes and
+ * word boundaries. Preserves ANSI styling across lines.
+ *
+ * @param text - Text to wrap
+ * @param width - Maximum line width
+ * @param options - Wrapping options
+ * @returns Wrapped text with newlines
+ *
+ * @example
+ * ```ts
+ * wrapToWidth("This is a long line that needs wrapping", 20)
+ * // "This is a long line\nthat needs wrapping"
+ *
+ * wrapToWidth("LongWordThatCantBreak", 10, { hard: true })
+ * // "LongWordTh\natCantBrea\nk"
+ * ```
+ */
+export function wrapToWidth(
+  text: string,
+  width: number,
+  options: {
+    /** Hard wrap long words (default: false) */
+    hard?: boolean;
+    /** Trim whitespace at line ends (default: true) */
+    trim?: boolean;
+    /** Preserve leading whitespace (default: false) */
+    wordWrap?: boolean;
+  } = {}
+): string {
+  const { hard = false, trim = true, wordWrap = true } = options;
+
+  return wrapAnsi(text, width, {
+    hard,
+    trim,
+    wordWrap,
+  });
+}
+
+/**
+ * Split text into lines respecting visual width.
+ *
+ * Similar to wrapToWidth but returns an array of lines
+ * instead of a single string with newlines.
+ *
+ * @param text - Text to split
+ * @param width - Maximum line width
+ * @param options - Wrapping options
+ * @returns Array of lines
+ *
+ * @example
+ * ```ts
+ * splitLines("Hello World", 6)
+ * // ["Hello", "World"]
+ * ```
+ */
+export function splitLines(
+  text: string,
+  width: number,
+  options: Parameters<typeof wrapToWidth>[2] = {}
+): string[] {
+  return wrapToWidth(text, width, options).split("\n");
+}
+
+/**
+ * Calculate the number of lines text will occupy at a given width.
+ *
+ * @param text - Text to measure
+ * @param width - Available width
+ * @param options - Wrapping options
+ * @returns Number of lines
+ *
+ * @example
+ * ```ts
+ * countLines("Hello World", 6) // 2
+ * countLines("Hi", 10) // 1
+ * ```
+ */
+export function countLines(
+  text: string,
+  width: number,
+  options: Parameters<typeof wrapToWidth>[2] = {}
+): number {
+  return splitLines(text, width, options).length;
+}

package/src/tui/utils/textSanitizer.ts

@@ -0,0 +1,225 @@
+/**
+ * Text Sanitizer for TUI
+ *
+ * Provides consistent text normalization across all TUI components.
+ * Centralizes sanitization logic previously scattered in TextInput.
+ *
+ * @module tui/utils/textSanitizer
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for text sanitization.
+ */
+export interface SanitizeOptions {
+  /** Convert tabs to spaces (default: 2) */
+  readonly tabWidth?: number;
+  /** Maximum line length before wrap hint (default: 0 = no limit) */
+  readonly maxLineLength?: number;
+  /** Strip ALL ANSI codes (default: false, just sanitize dangerous ones) */
+  readonly stripAllAnsi?: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default tab width in spaces */
+const DEFAULT_TAB_WIDTH = 2;
+
+/**
+ * SGR (Select Graphic Rendition) pattern - safe color/style codes
+ * Format: ESC [ <params> m
+ * Params: 0-109 for colors/styles
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional - matching ANSI SGR sequences
+const SGR_PATTERN = /\x1b\[[\d;]*m/g;
+
+/**
+ * All CSI (Control Sequence Introducer) sequences
+ * Format: ESC [ <params> <final byte>
+ * Final bytes: 0x40-0x7E (@-~)
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional - matching all ANSI CSI sequences
+const CSI_PATTERN = /\x1b\[[\d;?]*[ -/]*[@-~]/g;
+
+/**
+ * OSC (Operating System Command) sequences
+ * Format: ESC ] ... BEL or ESC ] ... ST
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional - matching ANSI OSC sequences
+const OSC_PATTERN = /\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+
+/**
+ * Control characters to strip (except \t=0x09, \n=0x0A, \x1B=ESC for ANSI)
+ * Includes: NUL-HT(0x00-0x08), VT-FF(0x0B-0x0C), SO-SUB(0x0E-0x1A), FS-US(0x1C-0x1F), DEL(0x7F), C1(0x80-0x9F)
+ * Note: ESC(0x1B) is preserved for ANSI sequences
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional - stripping dangerous control characters
+const CONTROL_CHARS_PATTERN = /[\x00-\x08\x0b\x0c\x0e-\x1a\x1c-\x1f\x7f\x80-\x9f]/g;
+
+/**
+ * Standalone ESC characters (not part of a valid sequence)
+ * Matches ESC not followed by [ or ]
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Intentional - matching orphan escape characters
+const ORPHAN_ESC_PATTERN = /\x1b(?![[\]])/g;
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+/**
+ * Sanitize text for safe TUI rendering (without ANSI awareness).
+ *
+ * Performs the following transformations:
+ * 1. CRLF → LF (Windows line endings)
+ * 2. Lone CR → LF (old Mac line endings)
+ * 3. Unicode line/paragraph separators → LF
+ * 4. Remove dangerous control characters (keeps \n, \t, \x1B for ANSI)
+ * 5. Tab → spaces (configurable width)
+ *
+ * @param text - Raw text to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized text safe for rendering
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const clean = sanitizeText("Hello\r\nWorld\t!");
+ * // => "Hello\nWorld  !"
+ *
+ * // Custom tab width
+ * const clean = sanitizeText("A\tB", { tabWidth: 4 });
+ * // => "A    B"
+ * ```
+ */
+export function sanitizeText(text: string, options?: SanitizeOptions): string {
+  const tabWidth = options?.tabWidth ?? DEFAULT_TAB_WIDTH;
+
+  // Step 1-3: Normalize line endings
+  let result = text
+    .replace(/\r\n/g, "\n") // CRLF → LF
+    .replace(/\r/g, "\n") // Lone CR → LF
+    .replace(/\u2028|\u2029/g, "\n"); // Unicode line separators
+
+  // Step 4: Remove dangerous control characters (keep \n=0x0A, \t=0x09, \x1B=ESC)
+  result = result.replace(CONTROL_CHARS_PATTERN, "");
+
+  // Step 5: Convert tabs to spaces
+  if (tabWidth > 0) {
+    const spaces = " ".repeat(tabWidth);
+    result = result.replace(/\t/g, spaces);
+  }
+
+  return result;
+}
+
+/**
+ * Sanitize ANSI codes using an allow-list approach.
+ *
+ * Keeps safe codes:
+ * - SGR (Select Graphic Rendition): Colors and text styles `\x1b[...m`
+ *
+ * Removes dangerous codes:
+ * - Cursor movement: `\x1b[...H`, `\x1b[...A/B/C/D/E/F/G`
+ * - Screen clearing: `\x1b[...J`, `\x1b[...K`
+ * - Scrolling: `\x1b[...S`, `\x1b[...T`
+ * - Other CSI sequences
+ * - OSC sequences (terminal titles, hyperlinks in raw form)
+ *
+ * @param text - Text containing ANSI codes
+ * @param options - Sanitization options
+ * @returns Text with only safe ANSI codes preserved
+ *
+ * @example
+ * ```ts
+ * // Colors preserved
+ * const text = "\x1b[31mRed\x1b[0m";
+ * sanitizeAnsi(text) // => "\x1b[31mRed\x1b[0m"
+ *
+ * // Cursor movement removed
+ * const text = "\x1b[2JCleared\x1b[H";
+ * sanitizeAnsi(text) // => "Cleared"
+ *
+ * // Strip all ANSI
+ * sanitizeAnsi(text, { stripAllAnsi: true }) // => "Cleared"
+ * ```
+ */
+export function sanitizeAnsi(text: string, options?: SanitizeOptions): string {
+  if (options?.stripAllAnsi) {
+    // Remove ALL ANSI sequences
+    return text.replace(CSI_PATTERN, "").replace(OSC_PATTERN, "");
+  }
+
+  // Collect safe SGR sequences and their positions
+  const sgrRegex = new RegExp(SGR_PATTERN.source, "g");
+
+  // Build set of exact positions of safe SGR sequences
+  const safePositions = new Map<number, number>(); // start -> end
+  for (let match = sgrRegex.exec(text); match !== null; match = sgrRegex.exec(text)) {
+    safePositions.set(match.index, match.index + match[0].length);
+  }
+
+  // Remove dangerous CSI sequences (not SGR)
+  let result = "";
+  let lastIndex = 0;
+  const csiRegex = new RegExp(CSI_PATTERN.source, "g");
+
+  for (let match = csiRegex.exec(text); match !== null; match = csiRegex.exec(text)) {
+    const start = match.index;
+    const end = start + match[0].length;
+
+    // Add text before this match
+    result += text.slice(lastIndex, start);
+
+    // Check if this is a safe SGR sequence
+    const isSafe = safePositions.has(start) && safePositions.get(start) === end;
+    if (isSafe) {
+      result += match[0];
+    }
+    // Otherwise, skip (remove) the dangerous sequence
+
+    lastIndex = end;
+  }
+
+  // Add remaining text
+  result += text.slice(lastIndex);
+
+  // Remove OSC sequences (titles, hyperlinks, etc.)
+  result = result.replace(OSC_PATTERN, "");
+
+  return result;
+}
+
+/**
+ * Combined sanitization: text normalization + ANSI filtering.
+ *
+ * This is the recommended function for most use cases.
+ * Applies both `sanitizeAnsi` and `sanitizeText` in sequence.
+ *
+ * @param text - Raw text to sanitize
+ * @param options - Sanitization options
+ * @returns Fully sanitized text safe for TUI rendering
+ *
+ * @example
+ * ```ts
+ * // Combined sanitization
+ * const raw = "Hello\r\nWorld\x1b[2J\x1b[31mRed\x1b[0m\t!";
+ * const clean = sanitize(raw);
+ * // => "Hello\nWorld\x1b[31mRed\x1b[0m  !"
+ * ```
+ */
+export function sanitize(text: string, options?: SanitizeOptions): string {
+  // Step 1: Sanitize ANSI (remove dangerous sequences, keep colors)
+  const ansiClean = sanitizeAnsi(text, options);
+
+  // Step 2: Sanitize text (normalize line endings, remove control chars, convert tabs)
+  const textClean = sanitizeText(ansiClean, options);
+
+  // Step 3: Remove any orphan ESC characters left behind (incomplete sequences)
+  return textClean.replace(ORPHAN_ESC_PATTERN, "");
+}

package/src/tui/utils/textUtils.ts

@@ -0,0 +1,114 @@
+/**
+ * Text Utilities (T002 Hardening)
+ *
+ * Utility functions for text manipulation in the TUI.
+ * Provides hard-wrapping to prevent unpredictable terminal soft-wrapping.
+ *
+ * @module tui/utils/textUtils
+ */
+
+import stringWidth from "string-width";
+
+/**
+ * Hard-wrap text to prevent terminal soft-wrapping.
+ * Forces newlines at column boundaries so terminal doesn't wrap unpredictably.
+ *
+ * Uses string-width for accurate CJK/Emoji/ANSI handling.
+ * This is a simpler implementation that doesn't require wrap-ansi as a direct dependency.
+ *
+ * @param text - The text to wrap
+ * @param columns - Maximum column width
+ * @returns Text with hard line breaks inserted
+ */
+export function hardWrap(text: string, columns: number): string {
+  if (!text || columns <= 0) {
+    return text;
+  }
+
+  const lines = text.split("\n");
+  const wrappedLines: string[] = [];
+
+  for (const line of lines) {
+    if (stringWidth(line) <= columns) {
+      wrappedLines.push(line);
+      continue;
+    }
+
+    // Need to hard-wrap this line
+    let remaining = line;
+    while (remaining.length > 0) {
+      const segment = truncateToWidth(remaining, columns);
+      wrappedLines.push(segment);
+      remaining = remaining.slice(segment.length);
+
+      // Safety: prevent infinite loop if no progress
+      if (segment.length === 0 && remaining.length > 0) {
+        // Force at least one character if we're stuck
+        const firstChar = remaining[0] ?? "";
+        wrappedLines.push(firstChar);
+        remaining = remaining.slice(1);
+      }
+    }
+  }
+
+  return wrappedLines.join("\n");
+}
+
+/**
+ * Truncate a string to fit within a specified display width.
+ * Uses string-width for accurate width calculation.
+ *
+ * @param str - The string to truncate
+ * @param maxWidth - Maximum display width
+ * @returns Truncated string that fits within maxWidth
+ */
+function truncateToWidth(str: string, maxWidth: number): string {
+  if (stringWidth(str) <= maxWidth) {
+    return str;
+  }
+
+  // Binary search for the right length
+  let low = 0;
+  let high = str.length;
+
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const slice = str.slice(0, mid);
+    if (stringWidth(slice) <= maxWidth) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return str.slice(0, low);
+}
+
+/**
+ * Truncate text to fit within a maximum display width with ellipsis.
+ * Uses string-width for accurate CJK/Emoji/ANSI handling.
+ *
+ * @param text - The text to truncate
+ * @param maxWidth - Maximum display width in terminal cells
+ * @param ellipsis - Ellipsis character (default: "…")
+ * @returns Truncated text that fits within maxWidth cells
+ */
+export function truncateToDisplayWidth(
+  text: string,
+  maxWidth: number,
+  ellipsis: string = "…"
+): string {
+  if (!text || maxWidth <= 0) return "";
+
+  const textWidth = stringWidth(text);
+  if (textWidth <= maxWidth) return text;
+
+  const ellipsisWidth = stringWidth(ellipsis);
+  const targetWidth = maxWidth - ellipsisWidth;
+
+  if (targetWidth <= 0) return ellipsis.slice(0, maxWidth);
+
+  // Use existing truncateToWidth for the main content
+  const truncated = truncateToWidth(text, targetWidth);
+  return truncated + ellipsis;
+}