@butlerw/vellum 0.1.0

package/src/tui/utils/heightEstimator.ts

@@ -0,0 +1,198 @@
+/**
+ * Height Estimation Utilities (T002)
+ *
+ * Functions for estimating rendered line heights of text and messages.
+ * Used by virtualization and adaptive rendering systems.
+ *
+ * CRITICAL: Height estimates MUST be UPPER BOUNDS (never under-estimate).
+ * Under-estimation causes terminal overflow and UI "sinking" bugs.
+ *
+ * @module tui/utils/heightEstimator
+ */
+
+import stringWidth from "string-width";
+import type { Message } from "../context/MessagesContext.js";
+
+// =============================================================================
+// Constants - Upper Bound Safety Margins
+// =============================================================================
+
+/**
+ * Safety margin added to all height estimates to prevent overflow.
+ * Accounts for borders, padding, and rendering variations.
+ */
+export const HEIGHT_SAFETY_MARGIN = 2;
+
+/**
+ * Upper bound lines per tool call.
+ * Tool calls render as inline status indicators (Gemini-style):
+ * - Status icon + tool name + optional error = typically 1-2 lines
+ * Previous value of 10 was too conservative for inline rendering.
+ */
+export const TOOL_CALL_UPPER_BOUND = 3;
+
+/**
+ * Upper bound lines per tool call when a diff preview is shown.
+ * Accounts for status line + margin + MaxSizedBox diff preview (12 lines).
+ */
+export const TOOL_CALL_DIFF_UPPER_BOUND = 14;
+
+/**
+ * Upper bound for thinking block header and chrome.
+ * Includes collapsible header, borders, and internal padding.
+ */
+export const THINKING_HEADER_UPPER_BOUND = 4;
+
+/**
+ * Default estimated item height for virtualization.
+ * Used when no specific estimate is available.
+ * Increased from 4 to prevent overflow from under-estimation.
+ */
+export const DEFAULT_ESTIMATED_ITEM_HEIGHT = 12;
+
+/**
+ * Minimum message height (header + minimal content + margin).
+ */
+export const MIN_MESSAGE_HEIGHT = 4;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface DiffMetadata {
+  readonly diff: string;
+  readonly additions: number;
+  readonly deletions: number;
+}
+
+type ToolCallInfo = NonNullable<Message["toolCalls"]>[number];
+
+/**
+ * Options for message height estimation.
+ */
+export interface HeightEstimatorOptions {
+  /** Terminal width for line wrapping calculation */
+  readonly width: number;
+  /** Whether to include tool calls in height calculation (default: true) */
+  readonly includeToolCalls?: boolean;
+  /** Padding to subtract from width for content area (default: 4) */
+  readonly contentPadding?: number;
+  /** Padding to subtract for thinking blocks (default: 6) */
+  readonly thinkingPadding?: number;
+}
+
+// =============================================================================
+// Functions
+// =============================================================================
+
+function isDiffMetadata(value: unknown): value is DiffMetadata {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.diff === "string" &&
+    typeof obj.additions === "number" &&
+    typeof obj.deletions === "number"
+  );
+}
+
+function getDiffMetadata(result: unknown): DiffMetadata | null {
+  if (isDiffMetadata(result)) {
+    return result;
+  }
+  if (!result || typeof result !== "object") {
+    return null;
+  }
+  const diffMeta = (result as Record<string, unknown>).diffMeta;
+  return isDiffMetadata(diffMeta) ? diffMeta : null;
+}
+
+function getToolCallUpperBound(toolCall: ToolCallInfo): number {
+  const diffMeta = getDiffMetadata(toolCall.result);
+  const hasDiffContent =
+    toolCall.status === "completed" &&
+    diffMeta !== null &&
+    diffMeta.diff.trim() !== "" &&
+    diffMeta.diff !== "(no changes)";
+  return hasDiffContent ? TOOL_CALL_DIFF_UPPER_BOUND : TOOL_CALL_UPPER_BOUND;
+}
+
+/**
+ * Estimate the number of lines a text will occupy when wrapped.
+ * Uses string-width for accurate CJK/Emoji/ANSI handling.
+ *
+ * @param text - The text to measure
+ * @param width - The available terminal width
+ * @returns Estimated number of lines after wrapping
+ */
+export function estimateWrappedLineCount(text: string, width: number): number {
+  const safeWidth = Math.max(1, width);
+  if (!text) {
+    return 1;
+  }
+
+  let total = 0;
+  const lines = text.split("\n");
+  for (const line of lines) {
+    // Use string-width for accurate display width calculation
+    // This correctly handles CJK characters (2 cells), Emoji, and ANSI escape codes
+    const lineWidth = stringWidth(line);
+    if (lineWidth === 0) {
+      total += 1;
+      continue;
+    }
+    total += Math.max(1, Math.ceil(lineWidth / safeWidth));
+  }
+  return total;
+}
+
+/**
+ * Estimate a message height in lines for virtualized scrolling and layout.
+ * Uses UPPER BOUND estimation to prevent terminal overflow.
+ *
+ * @param message - The message to measure
+ * @param options - Height estimation options
+ * @returns Estimated height in lines (conservative upper bound)
+ */
+export function estimateMessageHeight(message: Message, options: HeightEstimatorOptions): number {
+  const { width, includeToolCalls = true, contentPadding = 4, thinkingPadding = 6 } = options;
+
+  // Use 2 lines for header (role + timestamp) to account for wrapping
+  const headerLines = 2;
+  // Margin between messages
+  const marginLines = 2;
+  const contentWidth = Math.max(10, width - contentPadding);
+  const thinkingWidth = Math.max(10, width - thinkingPadding);
+  const toolCalls = message.toolCalls ?? [];
+
+  // Tool group messages have special handling
+  if (message.role === "tool_group") {
+    const toolLines = toolCalls.reduce((sum, call) => sum + getToolCallUpperBound(call), 0);
+    // Each tool in a group can expand to multiple lines
+    return Math.max(MIN_MESSAGE_HEIGHT, toolLines) + marginLines;
+  }
+
+  const content = message.content || (message.isStreaming ? "" : "(empty)");
+  let lines = headerLines;
+
+  lines += estimateWrappedLineCount(content, contentWidth);
+
+  // Add thinking block lines if present (with upper bound for chrome)
+  if (message.thinking && message.thinking.length > 0) {
+    lines += THINKING_HEADER_UPPER_BOUND; // Collapsible header + borders
+    lines += estimateWrappedLineCount(message.thinking, thinkingWidth);
+  }
+
+  // Add tool call lines if enabled and present (UPPER BOUND per tool)
+  if (includeToolCalls && toolCalls.length > 0) {
+    lines += 1; // separator before tool calls (margin already counted)
+    lines += toolCalls.reduce((sum, call) => sum + getToolCallUpperBound(call), 0);
+  }
+
+  // FIX: Simplified height calculation to avoid double-counting margins
+  // Previous version added marginLines (2) + HEIGHT_SAFETY_MARGIN (2) = 4 extra lines
+  // which caused over-estimation and blank spaces in virtualized list
+  // Now we only add a single safety buffer
+  return Math.max(MIN_MESSAGE_HEIGHT, lines + HEIGHT_SAFETY_MARGIN);
+}

package/src/tui/utils/index.ts

@@ -0,0 +1,91 @@
+/**
+ * TUI Utilities
+ *
+ * Utility functions for the Vellum CLI terminal UI.
+ *
+ * @module tui/utils
+ */
+
+export {
+  disableBracketedPaste,
+  enableBracketedPaste,
+  extractPasteContent,
+  hasPasteEnd,
+  hasPasteStart,
+  PASTE_END,
+  PASTE_START,
+} from "./bracketedPaste.js";
+
+export { CursorManager, type CursorManagerImpl } from "./cursor-manager.js";
+
+export {
+  clearTerminalCapabilitiesCache,
+  createHyperlink,
+  type DetectTerminalOptions,
+  degradeColor,
+  detectTerminal,
+  getSymbol,
+  getTerminalCapabilities,
+  getTerminalName,
+  type TerminalCapabilities,
+  type TerminalType,
+} from "./detectTerminal.js";
+
+export { findLastSafeSplitPoint } from "./findLastSafeSplitPoint.js";
+// Height estimation utilities (T002)
+export {
+  // Constants for upper-bound estimation
+  DEFAULT_ESTIMATED_ITEM_HEIGHT,
+  // Functions
+  estimateMessageHeight,
+  estimateWrappedLineCount,
+  HEIGHT_SAFETY_MARGIN,
+  type HeightEstimatorOptions,
+  MIN_MESSAGE_HEIGHT,
+  THINKING_HEADER_UPPER_BOUND,
+  TOOL_CALL_UPPER_BOUND,
+} from "./heightEstimator.js";
+// Narrow width detection
+export { getNarrowBreakpoint, isNarrowWidth } from "./isNarrowWidth.js";
+// Stdout guard for debugging (T002 Hardening)
+export {
+  disableStdoutGuard,
+  enableStdoutGuard,
+  isStdoutGuardActive,
+} from "./stdoutGuard.js";
+export { isSyncUpdateSupported, syncUpdate } from "./synchronized-update.js";
+// Text width utilities (CJK/emoji aware)
+export {
+  countLines,
+  getVisualWidth,
+  padToWidth,
+  splitLines,
+  type TextAlign,
+  truncateToWidth,
+  wrapToWidth,
+} from "./text-width.js";
+// Text sanitization utilities (Phase 1 - World-Class TUI)
+export {
+  type SanitizeOptions,
+  sanitize,
+  sanitizeAnsi,
+  sanitizeText,
+} from "./textSanitizer.js";
+// Text utilities (T002 Hardening)
+export { hardWrap, truncateToDisplayWidth } from "./textUtils.js";
+// Terminal UI sizing utilities
+export {
+  clamp,
+  DEFAULT_TERMINAL_HEIGHT,
+  DEFAULT_TERMINAL_WIDTH,
+  getContentPadding,
+  getMaxContentWidth,
+  getTerminalHeight,
+  getTerminalSize,
+  getTerminalWidth,
+  lerp,
+  NARROW_CONTENT_RATIO,
+  NARROW_WIDTH_BREAKPOINT,
+  WIDE_CONTENT_RATIO,
+  WIDE_WIDTH_BREAKPOINT,
+} from "./ui-sizing.js";

package/src/tui/utils/isNarrowWidth.ts

@@ -0,0 +1,52 @@
+/**
+ * Narrow Width Detection Utility
+ *
+ * Simple utility for detecting narrow terminal widths.
+ * Used for responsive layout decisions throughout the TUI.
+ *
+ * @module tui/utils/isNarrowWidth
+ */
+
+import { getTerminalWidth, NARROW_WIDTH_BREAKPOINT } from "./ui-sizing.js";
+
+/**
+ * Get the narrow width breakpoint constant.
+ *
+ * @returns The narrow width breakpoint (80 columns)
+ *
+ * @example
+ * ```ts
+ * const breakpoint = getNarrowBreakpoint();
+ * console.log(`Narrow mode below ${breakpoint} columns`);
+ * ```
+ */
+export function getNarrowBreakpoint(): number {
+  return NARROW_WIDTH_BREAKPOINT;
+}
+
+/**
+ * Check if the terminal is in narrow width mode.
+ *
+ * Narrow mode is defined as terminal width <= 80 columns.
+ * In narrow mode, UI elements should be more compact and
+ * non-essential elements may be hidden.
+ *
+ * @param width - Terminal width to check (defaults to current terminal)
+ * @returns True if terminal is narrow (<= 80 columns)
+ *
+ * @example
+ * ```ts
+ * if (isNarrowWidth()) {
+ *   // Render compact layout
+ * } else {
+ *   // Render full layout with sidebar
+ * }
+ *
+ * // Or with explicit width
+ * const narrow = isNarrowWidth(60); // true
+ * ```
+ */
+export function isNarrowWidth(width?: number): boolean {
+  const terminalWidth = width ?? getTerminalWidth();
+  return terminalWidth <= NARROW_WIDTH_BREAKPOINT;
+}

package/src/tui/utils/stdoutGuard.ts

@@ -0,0 +1,90 @@
+/**
+ * Stdout Guard Utilities (T002 Hardening)
+ *
+ * Development-time utilities for detecting unexpected stdout writes
+ * that bypass Ink's rendering and could cause terminal overflow.
+ *
+ * IMPORTANT: This is for DEBUGGING ONLY. It must NOT block writes
+ * or break Ink's stdout handling.
+ *
+ * @module tui/utils/stdoutGuard
+ */
+
+// Store the original stdout.write
+let originalStdoutWrite: typeof process.stdout.write | null = null;
+let guardActive = false;
+
+/**
+ * Enable stdout guard for debugging non-Ink writes.
+ *
+ * When enabled (via VELLUM_DEBUG_STDOUT env var), this will log
+ * any writes to stdout that don't appear to come from Ink.
+ *
+ * SAFETY: All writes are allowed through - this only logs warnings.
+ */
+export function enableStdoutGuard(): void {
+  // Only enable in debug mode
+  if (!process.env.VELLUM_DEBUG_STDOUT) {
+    return;
+  }
+
+  if (guardActive) {
+    return; // Already active
+  }
+
+  originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  guardActive = true;
+
+  const guardedWrite = function (
+    this: NodeJS.WriteStream,
+    chunk: string | Uint8Array,
+    encodingOrCallback?: BufferEncoding | ((err?: Error | null) => void),
+    callback?: (err?: Error | null) => void
+  ): boolean {
+    // Try to detect if this is an Ink write by checking the stack
+    const stack = new Error().stack ?? "";
+    const isInkWrite =
+      stack.includes("ink") ||
+      stack.includes("render") ||
+      stack.includes("reconciler") ||
+      stack.includes("yoga");
+
+    if (!isInkWrite) {
+      const chunkStr = typeof chunk === "string" ? chunk : chunk.toString();
+      const preview = chunkStr.substring(0, 80).replace(/\n/g, "\\n");
+      // Log to stderr to avoid recursion
+      process.stderr.write(`[STDOUT GUARD] Non-Ink write detected: "${preview}"\n`);
+    }
+
+    // ALWAYS allow the write through - never block
+    if (originalStdoutWrite) {
+      if (typeof encodingOrCallback === "function") {
+        return originalStdoutWrite(chunk, encodingOrCallback);
+      }
+      return originalStdoutWrite(chunk, encodingOrCallback, callback);
+    }
+    return true;
+  };
+
+  process.stdout.write = guardedWrite as typeof process.stdout.write;
+}
+
+/**
+ * Disable the stdout guard and restore original stdout.write.
+ */
+export function disableStdoutGuard(): void {
+  if (!guardActive || !originalStdoutWrite) {
+    return;
+  }
+
+  process.stdout.write = originalStdoutWrite;
+  originalStdoutWrite = null;
+  guardActive = false;
+}
+
+/**
+ * Check if the stdout guard is currently active.
+ */
+export function isStdoutGuardActive(): boolean {
+  return guardActive;
+}

package/src/tui/utils/synchronized-update.ts

@@ -0,0 +1,70 @@
+/**
+ * Synchronized Update - DEC 2026 protocol
+ *
+ * Prevents terminal flickering by batching output.
+ * Supported in VS Code Terminal 1.85+, iTerm2, Kitty
+ *
+ * @module tui/utils/synchronized-update
+ */
+
+import { getActiveStdout } from "../buffered-stdout.js";
+
+const BEGIN_SYNC = "\x1b[?2026h";
+const END_SYNC = "\x1b[?2026l";
+
+let syncDepth = 0;
+
+/**
+ * Execute a function with synchronized terminal updates.
+ * All output within the callback will be batched and rendered atomically.
+ *
+ * @param fn - The function to execute within synchronized updates
+ * @returns The return value of the function
+ *
+ * @example
+ * ```ts
+ * syncUpdate(() => {
+ *   process.stdout.write('Line 1\n');
+ *   process.stdout.write('Line 2\n');
+ * });
+ * // Both lines rendered atomically without flicker
+ * ```
+ */
+export function syncUpdate<T>(fn: () => T): T {
+  if (syncDepth === 0) {
+    getActiveStdout().write(BEGIN_SYNC);
+  }
+  syncDepth++;
+  try {
+    return fn();
+  } finally {
+    syncDepth--;
+    if (syncDepth === 0) {
+      getActiveStdout().write(END_SYNC);
+    }
+  }
+}
+
+/**
+ * Check if synchronized updates are supported by the current terminal.
+ *
+ * @returns true if DEC 2026 protocol is supported
+ */
+export function isSyncUpdateSupported(): boolean {
+  // VS Code 1.85+, iTerm2, Kitty support DEC 2026
+  const term = process.env.TERM_PROGRAM?.toLowerCase() ?? "";
+  const termVersion = process.env.TERM_PROGRAM_VERSION ?? "";
+
+  if (term === "vscode") {
+    // VS Code 1.85.0 added sync update support
+    const [major = 0] = termVersion.split(".").map(Number);
+    return major >= 1; // Most recent VS Code versions support it
+  }
+
+  if (term === "iterm.app" || term === "kitty") {
+    return true;
+  }
+
+  // Check for explicit support via COLORTERM
+  return process.env.COLORTERM === "truecolor";
+}