@vibecheckai/cli 3.2.0 → 3.2.2

package/bin/runners/lib/terminal-ui.js

@@ -1,34 +1,28 @@
 /**
- * Terminal UI - Premium CLI Components
- * 
- * Reusable across all vibecheck commands:
- * - Advanced spinners with phases
- * - Multi-line progress displays
- * - Score visualizations
- * - Tables and cards
- * - Color utilities
- * 
- * Zero dependencies - pure ANSI escape codes
+ * Terminal UI - The Vibecheck Design System
+ * * Centralizes all visual primitives to ensure "World Class" consistency.
+ * * features:
+ * - Global Grid: 76 chars width
+ * - Border Style: Double Outer / Single Inner
+ * - Components: Spinners, Progress Bars, Tables, Headers
  */
 
+import process from 'process';
+
 // ═══════════════════════════════════════════════════════════════════════════════
-// ANSI ESCAPE CODES
+// 1. CORE CONSTANTS & ANSI
 // ═══════════════════════════════════════════════════════════════════════════════
 
-const ESC = '\x1b';
+export const WIDTH = 76;
 
-const ansi = {
-  // Text styles
+const ESC = '\x1b';
+export const ansi = {
   reset: `${ESC}[0m`,
   bold: `${ESC}[1m`,
   dim: `${ESC}[2m`,
   italic: `${ESC}[3m`,
   underline: `${ESC}[4m`,
-  inverse: `${ESC}[7m`,
-  strikethrough: `${ESC}[9m`,
-  
-  // Standard colors
-  black: `${ESC}[30m`,
+  // Colors
   red: `${ESC}[31m`,
   green: `${ESC}[32m`,
   yellow: `${ESC}[33m`,
@@ -36,818 +30,242 @@ const ansi = {
   magenta: `${ESC}[35m`,
   cyan: `${ESC}[36m`,
   white: `${ESC}[37m`,
-  
-  // Bright colors
   gray: `${ESC}[90m`,
-  brightRed: `${ESC}[91m`,
-  brightGreen: `${ESC}[92m`,
-  brightYellow: `${ESC}[93m`,
-  brightBlue: `${ESC}[94m`,
-  brightMagenta: `${ESC}[95m`,
-  brightCyan: `${ESC}[96m`,
-  brightWhite: `${ESC}[97m`,
-  
-  // Background colors
-  bgBlack: `${ESC}[40m`,
+  // Backgrounds
   bgRed: `${ESC}[41m`,
   bgGreen: `${ESC}[42m`,
   bgYellow: `${ESC}[43m`,
   bgBlue: `${ESC}[44m`,
   bgMagenta: `${ESC}[45m`,
   bgCyan: `${ESC}[46m`,
-  bgWhite: `${ESC}[47m`,
-  
-  // Cursor control
+  // Cursor
   hideCursor: `${ESC}[?25l`,
   showCursor: `${ESC}[?25h`,
-  saveCursor: `${ESC}[s`,
-  restoreCursor: `${ESC}[u`,
   clearLine: `${ESC}[2K`,
-  clearScreen: `${ESC}[2J`,
   cursorUp: (n = 1) => `${ESC}[${n}A`,
-  cursorDown: (n = 1) => `${ESC}[${n}B`,
-  cursorRight: (n = 1) => `${ESC}[${n}C`,
-  cursorLeft: (n = 1) => `${ESC}[${n}D`,
-  cursorTo: (x, y) => `${ESC}[${y};${x}H`,
-  
-  // 24-bit color (truecolor)
-  rgb: (r, g, b) => `${ESC}[38;2;${r};${g};${b}m`,
-  bgRgb: (r, g, b) => `${ESC}[48;2;${r};${g};${b}m`,
-};
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// COLOR PALETTE - Electric Blue Theme
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const colors = {
-  // Primary brand colors
-  primary: ansi.rgb(99, 102, 241),      // Indigo
-  secondary: ansi.rgb(139, 92, 246),    // Purple
-  accent: ansi.rgb(6, 182, 212),        // Cyan
-  
-  // Semantic colors
-  success: ansi.rgb(16, 185, 129),      // Emerald
-  warning: ansi.rgb(245, 158, 11),      // Amber
-  error: ansi.rgb(239, 68, 68),         // Red
-  info: ansi.rgb(59, 130, 246),         // Blue
-  
-  // Severity colors
-  critical: ansi.rgb(220, 38, 38),      // Red-600
-  high: ansi.rgb(234, 88, 12),          // Orange-600
-  medium: ansi.rgb(202, 138, 4),        // Yellow-600
-  low: ansi.rgb(37, 99, 235),           // Blue-600
-  
-  // Gradient stops
-  gradient: {
-    cyan: ansi.rgb(0, 255, 255),
-    blue: ansi.rgb(100, 149, 237),
-    purple: ansi.rgb(138, 43, 226),
-    pink: ansi.rgb(236, 72, 153),
-    orange: ansi.rgb(251, 146, 60),
-  },
-  
-  // Background variants
-  bg: {
-    success: ansi.bgRgb(16, 185, 129),
-    warning: ansi.bgRgb(245, 158, 11),
-    error: ansi.bgRgb(220, 38, 38),
-    info: ansi.bgRgb(59, 130, 246),
-    muted: ansi.bgRgb(39, 39, 42),
-  },
 };
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// BOX DRAWING CHARACTERS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const box = {
-  // Rounded corners
-  topLeft: '╭',
-  topRight: '╮',
-  bottomLeft: '╰',
-  bottomRight: '╯',
-  horizontal: '─',
-  vertical: '│',
-  
-  // Sharp corners
-  sharpTopLeft: '┌',
-  sharpTopRight: '┐',
-  sharpBottomLeft: '└',
-  sharpBottomRight: '┘',
-  
-  // Double lines
-  doubleHorizontal: '═',
-  doubleVertical: '║',
-  doubleTopLeft: '╔',
-  doubleTopRight: '╗',
-  doubleBottomLeft: '╚',
-  doubleBottomRight: '╝',
-  
-  // Connectors
-  teeRight: '├',
-  teeLeft: '┤',
-  teeDown: '┬',
-  teeUp: '┴',
-  cross: '┼',
-  
-  // Block elements
-  fullBlock: '█',
-  lightShade: '░',
-  mediumShade: '▒',
-  darkShade: '▓',
-  upperHalf: '▀',
-  lowerHalf: '▄',
-  leftHalf: '▌',
-  rightHalf: '▐',
+// Semantic Palette
+export const style = {
+  success: (t: string) => `${ansi.green}${t}${ansi.reset}`,
+  error: (t: string) => `${ansi.red}${t}${ansi.reset}`,
+  warning: (t: string) => `${ansi.yellow}${t}${ansi.reset}`,
+  info: (t: string) => `${ansi.cyan}${t}${ansi.reset}`,
+  subtle: (t: string) => `${ansi.gray}${t}${ansi.reset}`,
+  highlight: (t: string) => `${ansi.bold}${ansi.white}${t}${ansi.reset}`,
+  label: (t: string) => `${ansi.blue}${t}${ansi.reset}`,
+  // Backgrounds for badges
+  bgSuccess: (t: string) => `${ansi.bgGreen}${ansi.bold}${ansi.white} ${t} ${ansi.reset}`,
+  bgError: (t: string) => `${ansi.bgRed}${ansi.bold}${ansi.white} ${t} ${ansi.reset}`,
+  bgWarn: (t: string) => `${ansi.bgYellow}${ansi.bold}${ansi.white} ${t} ${ansi.reset}`,
 };
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// ICONS & SYMBOLS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const icons = {
-  // Status
+export const icons = {
   success: '✓',
   error: '✗',
   warning: '⚠',
   info: 'ℹ',
-  question: '?',
-  
-  // Arrows
-  arrowRight: '→',
-  arrowLeft: '←',
-  arrowUp: '↑',
-  arrowDown: '↓',
-  arrowBoth: '↔',
-  
-  // Pointers
-  pointer: '❯',
-  pointerSmall: '›',
   bullet: '•',
-  dot: '·',
-  
-  // Misc
-  star: '★',
-  heart: '♥',
-  lightning: '⚡',
-  fire: '🔥',
-  rocket: '🚀',
-  check: '☑',
+  pointer: '❯',
+  arrowRight: '→',
+  line: '─',
   radioOn: '◉',
   radioOff: '○',
-  
-  // Severity badges
-  critical: '🚨',
-  high: '🔴',
-  medium: '🟡',
-  low: '🔵',
+  lock: '🔒',
 };
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// SPINNER - Advanced Multi-Phase Spinner
+// 2. LAYOUT PRIMITIVES (The "Grid")
 // ═══════════════════════════════════════════════════════════════════════════════
 
-const SPINNER_FRAMES = {
-  dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
-  line: ['|', '/', '-', '\\'],
-  arc: ['◜', '◠', '◝', '◞', '◡', '◟'],
-  circle: ['◐', '◓', '◑', '◒'],
-  bounce: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'],
-  pulse: ['█', '▓', '▒', '░', '▒', '▓'],
+export const BOX = {
+  // Outer Frame (Double)
+  tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║',
+  trT: '╠', tlT: '╣',
+  // Inner Dividers (Single)
+  ltl: '┌', ltr: '┐', lbl: '└', lbr: '┘', lh: '─', lv: '│',
+  lt: '┬', lb: '┴', lx: '┼', ltrT: '├', ltlT: '┤'
 };
 
-class Spinner {
-  constructor(options = {}) {
-    this.frames = SPINNER_FRAMES[options.type || 'dots'];
-    this.interval = options.interval || 80;
-    this.stream = options.stream || process.stdout;
-    this.color = options.color || colors.primary;
-    this.frameIndex = 0;
-    this.timer = null;
-    this.text = '';
-    this.phases = [];
-    this.currentPhase = 0;
-    this.lines = 1;
-  }
-  
-  start(text) {
-    this.text = text;
-    this.stream.write(ansi.hideCursor);
-    this._render();
-    this.timer = setInterval(() => this._render(), this.interval);
-    return this;
-  }
-  
-  update(text) {
-    this.text = text;
-    return this;
-  }
-  
-  setPhases(phases) {
-    this.phases = phases;
-    this.currentPhase = 0;
-    return this;
-  }
-  
-  nextPhase() {
-    if (this.currentPhase < this.phases.length - 1) {
-      this.currentPhase++;
-      this.text = this.phases[this.currentPhase];
-    }
-    return this;
-  }
-  
-  succeed(text) {
-    this._stop();
-    this._clear();
-    const msg = text || this.text;
-    this.stream.write(`  ${colors.success}${icons.success}${ansi.reset} ${msg}\n`);
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  fail(text) {
-    this._stop();
-    this._clear();
-    const msg = text || this.text;
-    this.stream.write(`  ${colors.error}${icons.error}${ansi.reset} ${msg}\n`);
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  warn(text) {
-    this._stop();
-    this._clear();
-    const msg = text || this.text;
-    this.stream.write(`  ${colors.warning}${icons.warning}${ansi.reset} ${msg}\n`);
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  info(text) {
-    this._stop();
-    this._clear();
-    const msg = text || this.text;
-    this.stream.write(`  ${colors.info}${icons.info}${ansi.reset} ${msg}\n`);
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  stop() {
-    this._stop();
-    this._clear();
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  _render() {
-    const frame = this.frames[this.frameIndex];
-    this.frameIndex = (this.frameIndex + 1) % this.frames.length;
-    
-    this._clear();
-    
-    let output = `  ${this.color}${frame}${ansi.reset} ${this.text}`;
-    
-    // Add phase indicator if phases are set
-    if (this.phases.length > 0) {
-      const phaseIndicator = this.phases.map((_, i) => 
-        i < this.currentPhase ? `${colors.success}●${ansi.reset}` :
-        i === this.currentPhase ? `${this.color}●${ansi.reset}` :
-        `${ansi.dim}○${ansi.reset}`
-      ).join(' ');
-      output += `  ${ansi.dim}[${ansi.reset}${phaseIndicator}${ansi.dim}]${ansi.reset}`;
-    }
-    
-    this.stream.write(`\r${output}`);
-  }
-  
-  _stop() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-  }
-  
-  _clear() {
-    this.stream.write(`\r${ansi.clearLine}`);
-  }
+/**
+ * Centers text within the standard width, accounting for ANSI codes
+ */
+export function padCenter(str: string, width: number = WIDTH - 2): string {
+  const visibleLen = str.replace(/\u001b\[\d+m/g, '').length;
+  const padding = Math.max(0, width - visibleLen);
+  const left = Math.floor(padding / 2);
+  return ' '.repeat(left) + str + ' '.repeat(padding - left);
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// PROGRESS BAR
-// ═══════════════════════════════════════════════════════════════════════════════
-
-class ProgressBar {
-  constructor(options = {}) {
-    this.total = options.total || 100;
-    this.width = options.width || 40;
-    this.complete = options.complete || '█';
-    this.incomplete = options.incomplete || '░';
-    this.stream = options.stream || process.stdout;
-    this.current = 0;
-    this.startTime = Date.now();
-  }
-  
-  update(current, label = '') {
-    this.current = current;
-    const percent = Math.min(100, Math.round((current / this.total) * 100));
-    const filled = Math.round((percent / 100) * this.width);
-    const empty = this.width - filled;
-    
-    const color = percent >= 80 ? colors.success : percent >= 50 ? colors.warning : colors.error;
-    const bar = `${color}${this.complete.repeat(filled)}${ansi.dim}${this.incomplete.repeat(empty)}${ansi.reset}`;
-    
-    const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
-    const eta = current > 0 ? (((this.total - current) / current) * (Date.now() - this.startTime) / 1000).toFixed(1) : '?';
-    
-    this.stream.write(`\r${ansi.clearLine}  ${bar} ${ansi.bold}${percent}%${ansi.reset} ${ansi.dim}${label} (${elapsed}s / ~${eta}s)${ansi.reset}`);
-  }
-  
-  complete(label = 'Complete') {
-    this.update(this.total, label);
-    this.stream.write('\n');
-  }
+/**
+ * Pads text to the right, accounting for ANSI codes
+ */
+export function padRight(str: string, len: number): string {
+  const visibleLen = str.replace(/\u001b\[\d+m/g, '').length;
+  const truncated = visibleLen > len ? str.substring(0, len - 3) + '...' : str;
+  const finalLen = truncated.replace(/\u001b\[\d+m/g, '').length;
+  return truncated + ' '.repeat(Math.max(0, len - finalLen));
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// MULTI-LINE PROGRESS - Phase-Based Progress Display
-// ═══════════════════════════════════════════════════════════════════════════════
-
-class PhaseProgress {
-  constructor(phases, options = {}) {
-    this.phases = phases.map(p => ({
-      name: p.name || p,
-      status: 'pending', // pending, running, success, error, skipped
-      message: '',
-      duration: null,
-    }));
-    this.currentPhase = -1;
-    this.stream = options.stream || process.stdout;
-    this.startTime = null;
-    this.phaseStartTime = null;
-    this.spinner = new Spinner({ color: colors.primary });
-  }
-  
-  start() {
-    this.startTime = Date.now();
-    this.stream.write(ansi.hideCursor);
-    this._render();
-    return this;
-  }
-  
-  startPhase(index, message = '') {
-    if (this.currentPhase >= 0 && this.phases[this.currentPhase].status === 'running') {
-      this.phases[this.currentPhase].status = 'success';
-      this.phases[this.currentPhase].duration = Date.now() - this.phaseStartTime;
-    }
-    
-    this.currentPhase = index;
-    this.phaseStartTime = Date.now();
-    this.phases[index].status = 'running';
-    this.phases[index].message = message;
-    this._render();
-    return this;
-  }
-  
-  updatePhase(message) {
-    if (this.currentPhase >= 0) {
-      this.phases[this.currentPhase].message = message;
-      this._render();
-    }
-    return this;
-  }
-  
-  succeedPhase(message = '') {
-    if (this.currentPhase >= 0) {
-      this.phases[this.currentPhase].status = 'success';
-      this.phases[this.currentPhase].duration = Date.now() - this.phaseStartTime;
-      if (message) this.phases[this.currentPhase].message = message;
-      this._render();
-    }
-    return this;
-  }
-  
-  failPhase(message = '') {
-    if (this.currentPhase >= 0) {
-      this.phases[this.currentPhase].status = 'error';
-      this.phases[this.currentPhase].duration = Date.now() - this.phaseStartTime;
-      if (message) this.phases[this.currentPhase].message = message;
-      this._render();
-    }
-    return this;
-  }
-  
-  skipPhase(message = 'Skipped') {
-    if (this.currentPhase >= 0) {
-      this.phases[this.currentPhase].status = 'skipped';
-      this.phases[this.currentPhase].message = message;
-      this._render();
-    }
-    return this;
-  }
-  
-  finish() {
-    if (this.currentPhase >= 0 && this.phases[this.currentPhase].status === 'running') {
-      this.phases[this.currentPhase].status = 'success';
-      this.phases[this.currentPhase].duration = Date.now() - this.phaseStartTime;
-    }
-    this._render();
-    this.stream.write(ansi.showCursor);
-    return this;
-  }
-  
-  _render() {
-    // Move cursor up to clear previous render
-    if (this._rendered) {
-      this.stream.write(ansi.cursorUp(this.phases.length + 1));
-    }
-    this._rendered = true;
-    
-    const totalDuration = Date.now() - this.startTime;
-    
-    for (const phase of this.phases) {
-      this.stream.write(ansi.clearLine);
-      
-      let statusIcon, statusColor;
-      switch (phase.status) {
-        case 'success':
-          statusIcon = icons.success;
-          statusColor = colors.success;
-          break;
-        case 'error':
-          statusIcon = icons.error;
-          statusColor = colors.error;
-          break;
-        case 'running':
-          statusIcon = this.spinner.frames[this.spinner.frameIndex];
-          statusColor = colors.primary;
-          this.spinner.frameIndex = (this.spinner.frameIndex + 1) % this.spinner.frames.length;
-          break;
-        case 'skipped':
-          statusIcon = '○';
-          statusColor = ansi.dim;
-          break;
-        default:
-          statusIcon = '○';
-          statusColor = ansi.dim;
-      }
-      
-      const duration = phase.duration ? `${ansi.dim}${phase.duration}ms${ansi.reset}` : '';
-      const message = phase.message ? `${ansi.dim}${phase.message}${ansi.reset}` : '';
-      
-      this.stream.write(`  ${statusColor}${statusIcon}${ansi.reset} ${phase.name.padEnd(25)} ${duration.padEnd(15)} ${message}\n`);
-    }
-    
-    // Total line
-    this.stream.write(ansi.clearLine);
-    this.stream.write(`  ${ansi.dim}${'─'.repeat(60)}${ansi.reset}\n`);
-    
-    // Keep spinner running for active phase
-    if (this.phases.some(p => p.status === 'running')) {
-      setTimeout(() => this._render(), 80);
-    }
-  }
+/**
+ * Truncates text with ellipsis
+ */
+export function truncate(str: string, len: number): string {
+  if (!str) return '';
+  const clean = str.replace(/\u001b\[\d+m/g, '');
+  if (clean.length <= len) return str;
+  return clean.substring(0, len - 3) + '...';
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// SCORE DISPLAY - Animated Score Card
+// 3. COMPONENT: SPINNER
 // ═══════════════════════════════════════════════════════════════════════════════
 
-function getScoreColor(score) {
-  if (score >= 90) return colors.success;
-  if (score >= 70) return colors.warning;
-  if (score >= 50) return ansi.rgb(251, 146, 60);
-  return colors.error;
-}
-
-function getGrade(score) {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
-}
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
-function renderScoreCard(score, options = {}) {
-  const {
-    verdict = score >= 80 ? 'SHIP' : score >= 60 ? 'WARN' : 'BLOCK',
-    findings = { critical: 0, high: 0, medium: 0, low: 0 },
-    duration = null,
-    cached = false,
-  } = options;
-  
-  const scoreColor = getScoreColor(score);
-  const grade = getGrade(score);
-  const gradeColor = scoreColor;
-  
-  const verdictConfig = {
-    SHIP: { bg: colors.bg.success, text: '  ✓ SHIP  ', desc: 'Ready to ship' },
-    WARN: { bg: colors.bg.warning, text: '  ⚠ WARN  ', desc: 'Review before shipping' },
-    BLOCK: { bg: colors.bg.error, text: '  ✗ BLOCK ', desc: 'Fix issues before shipping' },
-    PASS: { bg: colors.bg.success, text: '  ✓ PASS  ', desc: 'All checks passed' },
-    FAIL: { bg: colors.bg.error, text: '  ✗ FAIL  ', desc: 'Checks failed' },
-  };
-  const v = verdictConfig[verdict] || verdictConfig.WARN;
-  
-  // Build progress bar
-  const barWidth = 40;
-  const filled = Math.round((score / 100) * barWidth);
-  const bar = `${scoreColor}${'█'.repeat(filled)}${ansi.dim}${'░'.repeat(barWidth - filled)}${ansi.reset}`;
-  
-  const lines = [];
-  lines.push('');
-  lines.push(`  ${ansi.dim}${box.topLeft}${'─'.repeat(66)}${box.topRight}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  
-  // Score + Grade row
-  const scoreStr = String(score).padStart(3);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}    ${ansi.dim}SCORE${ansi.reset}  ${scoreColor}${ansi.bold}${scoreStr}${ansi.reset}${ansi.dim}/100${ansi.reset}        ${ansi.dim}GRADE${ansi.reset}  ${gradeColor}${ansi.bold}${grade}${ansi.reset}        ${cached ? `${ansi.dim}(cached)${ansi.reset}` : ''}      ${ansi.dim}${box.vertical}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  
-  // Progress bar
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}    ${bar}                  ${ansi.dim}${box.vertical}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  
-  // Verdict badge
-  const verdictPad = ' '.repeat(Math.max(0, 23 - v.text.length));
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(20)}${v.bg}${ansi.bold}${v.text}${ansi.reset}${verdictPad}${ansi.dim}${v.desc}${ansi.reset}  ${ansi.dim}${box.vertical}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
+export class Spinner {
+  private timer: NodeJS.Timeout | null = null;
+  private frameIndex = 0;
   
-  // Findings summary
-  const criticalStr = `${colors.critical}${findings.critical || 0}${ansi.reset} critical`;
-  const highStr = `${colors.high}${findings.high || 0}${ansi.reset} high`;
-  const mediumStr = `${colors.medium}${findings.medium || 0}${ansi.reset} medium`;
-  const lowStr = `${colors.low}${findings.low || 0}${ansi.reset} low`;
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}    ${criticalStr}  ${ansi.dim}│${ansi.reset}  ${highStr}  ${ansi.dim}│${ansi.reset}  ${mediumStr}  ${ansi.dim}│${ansi.reset}  ${lowStr}       ${ansi.dim}${box.vertical}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  
-  // Duration if provided
-  if (duration) {
-    const durationStr = typeof duration === 'number' ? `${duration}ms` : duration;
-    lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}    ${ansi.dim}Completed in ${durationStr}${ansi.reset}${' '.repeat(Math.max(0, 46 - durationStr.length))}${ansi.dim}${box.vertical}${ansi.reset}`);
-    lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${' '.repeat(66)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  }
-  
-  lines.push(`  ${ansi.dim}${box.bottomLeft}${'─'.repeat(66)}${box.bottomRight}${ansi.reset}`);
-  lines.push('');
-  
-  return lines.join('\n');
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// FINDINGS LIST - Premium Findings Display
-// ═══════════════════════════════════════════════════════════════════════════════
+  constructor(public text: string = '', private colorStr = ansi.cyan) {}
 
-function renderFindingsList(findings, options = {}) {
-  const { maxItems = 10, showCode = false, groupBySeverity = true } = options;
-  
-  if (!findings || findings.length === 0) {
-    return `\n  ${colors.success}${icons.success}${ansi.reset} ${ansi.bold}No issues found${ansi.reset}\n`;
-  }
-  
-  const lines = [];
-  
-  if (groupBySeverity) {
-    const groups = {
-      critical: findings.filter(f => f.severity === 'critical' || f.severity === 'BLOCK'),
-      high: findings.filter(f => f.severity === 'high'),
-      medium: findings.filter(f => f.severity === 'medium' || f.severity === 'WARN' || f.severity === 'warning'),
-      low: findings.filter(f => f.severity === 'low' || f.severity === 'INFO' || f.severity === 'info'),
-    };
-    
-    for (const [severity, items] of Object.entries(groups)) {
-      if (items.length === 0) continue;
-      
-      const color = colors[severity] || ansi.dim;
-      const icon = icons[severity] || icons.bullet;
-      
-      lines.push('');
-      lines.push(`  ${color}${ansi.bold}${severity.toUpperCase()} (${items.length})${ansi.reset}`);
-      lines.push(`  ${ansi.dim}${'─'.repeat(40)}${ansi.reset}`);
-      
-      for (const finding of items.slice(0, Math.ceil(maxItems / 4))) {
-        lines.push(...renderFinding(finding, { showCode, color }));
-      }
-      
-      if (items.length > Math.ceil(maxItems / 4)) {
-        lines.push(`  ${ansi.dim}  ... and ${items.length - Math.ceil(maxItems / 4)} more ${severity} findings${ansi.reset}`);
-      }
-    }
-  } else {
-    for (const finding of findings.slice(0, maxItems)) {
-      lines.push(...renderFinding(finding, { showCode }));
-    }
-    
-    if (findings.length > maxItems) {
-      lines.push('');
-      lines.push(`  ${ansi.dim}... and ${findings.length - maxItems} more findings${ansi.reset}`);
-    }
+  start(text?: string) {
+    if (text) this.text = text;
+    process.stdout.write(ansi.hideCursor);
+    this.timer = setInterval(() => {
+      const frame = SPINNER_FRAMES[this.frameIndex];
+      this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES.length;
+      process.stdout.write(`\r ${this.colorStr}${frame}${ansi.reset} ${this.text}`);
+    }, 80);
+    return this;
   }
-  
-  return lines.join('\n');
-}
 
-function renderFinding(finding, options = {}) {
-  const { showCode = false, color = ansi.dim } = options;
-  const lines = [];
-  
-  const severityColor = {
-    critical: colors.critical,
-    BLOCK: colors.critical,
-    high: colors.high,
-    medium: colors.medium,
-    WARN: colors.medium,
-    warning: colors.medium,
-    low: colors.low,
-    INFO: colors.low,
-    info: colors.low,
-  }[finding.severity] || ansi.dim;
-  
-  const title = finding.title || finding.message || 'Unknown issue';
-  lines.push(`  ${severityColor}${icons.pointer}${ansi.reset} ${ansi.bold}${truncate(title, 60)}${ansi.reset}`);
-  
-  if (finding.file) {
-    const fileStr = finding.file + (finding.line ? `:${finding.line}` : '');
-    lines.push(`    ${ansi.dim}${truncate(fileStr, 55)}${ansi.reset}`);
-  }
-  
-  if (finding.fix || finding.fixSuggestion) {
-    lines.push(`    ${colors.success}${icons.arrowRight}${ansi.reset} ${ansi.dim}${truncate(finding.fix || finding.fixSuggestion, 50)}${ansi.reset}`);
-  }
-  
-  if (showCode && finding.codeSnippet) {
-    lines.push(`    ${ansi.dim}┌──────────────────────────────────────${ansi.reset}`);
-    for (const line of finding.codeSnippet.split('\n').slice(0, 3)) {
-      lines.push(`    ${ansi.dim}│${ansi.reset} ${truncate(line, 50)}`);
+  stop(symbol = icons.success, color = ansi.green, finalMsg?: string) {
+    if (this.timer) clearInterval(this.timer);
+    process.stdout.write(`\r${ansi.clearLine}`);
+    if (finalMsg !== null) { // Pass null to clear completely
+      const msg = finalMsg || this.text;
+      console.log(` ${color}${symbol}${ansi.reset} ${msg}`);
     }
-    lines.push(`    ${ansi.dim}└──────────────────────────────────────${ansi.reset}`);
+    process.stdout.write(ansi.showCursor);
+    return this;
   }
-  
-  lines.push('');
-  return lines;
-}
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// TABLE RENDERING
-// ═══════════════════════════════════════════════════════════════════════════════
-
-function renderTable(headers, rows, options = {}) {
-  const { padding = 2, headerColor = colors.primary } = options;
-  
-  // Calculate column widths
-  const colWidths = headers.map((h, i) => {
-    const maxData = Math.max(...rows.map(r => stripAnsi(String(r[i] || '')).length));
-    return Math.max(stripAnsi(h).length, maxData) + padding;
-  });
-  
-  const lines = [];
-  const totalWidth = colWidths.reduce((a, b) => a + b, 0) + colWidths.length + 1;
-  
-  // Header
-  lines.push(`  ${ansi.dim}${box.topLeft}${'─'.repeat(totalWidth - 2)}${box.topRight}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${headers.map((h, i) => `${headerColor}${ansi.bold}${h.padEnd(colWidths[i])}${ansi.reset}`).join(`${ansi.dim}│${ansi.reset}`)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  lines.push(`  ${ansi.dim}${box.teeRight}${'─'.repeat(totalWidth - 2)}${box.teeLeft}${ansi.reset}`);
-  
-  // Rows
-  for (const row of rows) {
-    const cells = row.map((cell, i) => {
-      const str = String(cell || '');
-      const visibleLen = stripAnsi(str).length;
-      return str + ' '.repeat(Math.max(0, colWidths[i] - visibleLen));
-    });
-    lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}${cells.join(`${ansi.dim}│${ansi.reset}`)}${ansi.dim}${box.vertical}${ansi.reset}`);
-  }
-  
-  lines.push(`  ${ansi.dim}${box.bottomLeft}${'─'.repeat(totalWidth - 2)}${box.bottomRight}${ansi.reset}`);
-  
-  return lines.join('\n');
+  succeed(text?: string) { return this.stop(icons.success, ansi.green, text); }
+  fail(text?: string) { return this.stop(icons.error, ansi.red, text); }
+  warn(text?: string) { return this.stop(icons.warning, ansi.yellow, text); }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// SECTION HEADERS
+// 4. COMPONENT: PROGRESS BAR
 // ═══════════════════════════════════════════════════════════════════════════════
 
-function renderSection(title, icon = '◆') {
-  return `\n  ${colors.accent}${icon}${ansi.reset} ${ansi.bold}${title}${ansi.reset}\n  ${ansi.dim}${'─'.repeat(60)}${ansi.reset}`;
-}
-
-function renderDivider(char = '─', width = 60) {
-  return `  ${ansi.dim}${char.repeat(width)}${ansi.reset}`;
+export function renderProgressBar(percentage: number, width = 20, color = ansi.green): string {
+  const filled = Math.round((percentage / 100) * width);
+  return `${color}${'█'.repeat(filled)}${ansi.gray}${'░'.repeat(width - filled)}${ansi.reset}`;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// UTILITY FUNCTIONS
+// 5. STANDARD RENDERERS (The "Look")
 // ═══════════════════════════════════════════════════════════════════════════════
 
-function truncate(str, len) {
-  if (!str) return '';
-  str = String(str);
-  const visible = stripAnsi(str);
-  if (visible.length <= len) return str;
-  return str.slice(0, len - 3) + '...';
-}
-
-function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*m/g, '');
-}
+/**
+ * Renders the Standard Double-Border Header with Logo
+ */
+export function renderScreenHeader(
+  logoAscii: string, 
+  title: string, 
+  logoColor: (t: string) => string = (t) => t,
+  context?: { label: string, value: string }
+) {
+  const lines: string[] = [];
+  
+  // Top Frame
+  lines.push(ansi.gray + BOX.tl + BOX.h.repeat(WIDTH - 2) + BOX.tr + ansi.reset);
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+
+  // Logo Processing
+  logoAscii.trim().split('\n').forEach(line => {
+    const cleanLine = line.replace(/\r/g, ''); 
+    const maxLen = Math.max(...logoAscii.split('\n').map(l => l.length));
+    const padding = ' '.repeat(Math.floor((WIDTH - 2 - maxLen) / 2));
+    const rightPad = ' '.repeat(WIDTH - 2 - padding.length - cleanLine.length);
+    
+    lines.push(ansi.gray + BOX.v + ansi.reset + padding + logoColor(cleanLine) + rightPad + ansi.gray + BOX.v + ansi.reset);
+  });
 
-function formatNumber(num) {
-  return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-}
+  // Title
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  lines.push(ansi.gray + BOX.v + ansi.reset + padCenter(ansi.bold + ansi.white + title + ansi.reset, WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  
+  // Context Bar (Optional)
+  if (context) {
+    lines.push(ansi.gray + BOX.trT + BOX.h.repeat(WIDTH - 2) + BOX.tlT + ansi.reset);
+    const ctxStr = `${ansi.gray}${context.label}: ${ansi.reset}${ansi.cyan}${context.value}${ansi.reset}`;
+    lines.push(ansi.gray + BOX.v + ansi.reset + padCenter(ctxStr, WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+    lines.push(ansi.gray + BOX.trT + BOX.h.repeat(WIDTH - 2) + BOX.tlT + ansi.reset);
+  } else {
+    lines.push(ansi.gray + BOX.trT + BOX.h.repeat(WIDTH - 2) + BOX.tlT + ansi.reset);
+  }
 
-function formatDuration(ms) {
-  if (ms < 1000) return `${ms}ms`;
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  return `${Math.floor(ms / 60000)}m ${Math.round((ms % 60000) / 1000)}s`;
+  console.log(lines.join('\n'));
 }
 
-function formatBytes(bytes) {
-  if (bytes === 0) return '0 B';
-  const k = 1024;
-  const sizes = ['B', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+/**
+ * Renders the Standard Footer
+ */
+export function renderScreenFooter() {
+  console.log(ansi.gray + BOX.bl + BOX.h.repeat(WIDTH - 2) + BOX.br + ansi.reset);
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// BANNER GENERATOR
-// ═══════════════════════════════════════════════════════════════════════════════
-
-function renderBanner(name = 'VIBECHECK', subtitle = '') {
-  const gradient = [
-    ansi.rgb(0, 200, 255),
-    ansi.rgb(30, 180, 255),
-    ansi.rgb(60, 160, 255),
-    ansi.rgb(90, 140, 255),
-    ansi.rgb(120, 120, 255),
-    ansi.rgb(150, 100, 255),
-  ];
-  
-  const asciiArt = {
-    V: ['██╗   ██╗', '██║   ██║', '██║   ██║', '╚██╗ ██╔╝', ' ╚████╔╝ ', '  ╚═══╝  '],
-    I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
-    B: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██████╔╝', '╚═════╝ '],
-    E: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '███████╗', '╚══════╝'],
-    C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
-    H: ['██╗  ██╗', '██║  ██║', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
-    K: ['██╗  ██╗', '██║ ██╔╝', '█████╔╝ ', '██╔═██╗ ', '██║  ██╗', '╚═╝  ╚═╝'],
-  };
-  
-  const lines = [];
-  lines.push('');
-  
-  for (let row = 0; row < 6; row++) {
-    let line = '  ';
-    for (const char of name) {
-      if (asciiArt[char]) {
-        line += asciiArt[char][row];
-      }
-    }
-    lines.push(`${gradient[row]}${line}${ansi.reset}`);
-  }
-  
-  if (subtitle) {
-    lines.push('');
-    lines.push(`  ${ansi.dim}${box.topLeft}${'─'.repeat(subtitle.length + 4)}${box.topRight}${ansi.reset}`);
-    lines.push(`  ${ansi.dim}${box.vertical}${ansi.reset}  ${subtitle}  ${ansi.dim}${box.vertical}${ansi.reset}`);
-    lines.push(`  ${ansi.dim}${box.bottomLeft}${'─'.repeat(subtitle.length + 4)}${box.bottomRight}${ansi.reset}`);
+/**
+ * Renders a Standard Verdict/Telemetry Table
+ */
+export function renderVerdictTable(
+  stats: { duration: number, heap: number, files?: number },
+  score: number,
+  findings: any[]
+) {
+  const lines: string[] = [];
+
+  // Telemetry Row
+  const heapMB = Math.round(stats.heap / 1024 / 1024);
+  const statsStr = `📡 TELEMETRY  │ ⏱  ${stats.duration}ms  │ 📂 ${stats.files || '?'} Files  │ 📦 ${heapMB}MB`;
+  lines.push(ansi.gray + BOX.v + ansi.reset + padCenter(statsStr, WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  lines.push(ansi.gray + BOX.trT + BOX.h.repeat(WIDTH - 2) + BOX.tlT + ansi.reset);
+
+  // Score Row
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  const bar = renderProgressBar(score, 20);
+  lines.push(ansi.gray + BOX.v + ansi.reset + padCenter(`HEALTH SCORE    [${bar}] ${score} / 100`, WIDTH + 18) + ansi.gray + BOX.v + ansi.reset);
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+
+  if (findings.length > 0) {
+    // Table Header
+    const C1=10, C2=13, C3=41;
+    const tTop = `  ${BOX.ltl}${BOX.lh.repeat(C1)}${BOX.lt}${BOX.lh.repeat(C2)}${BOX.lt}${BOX.lh.repeat(C3)}${BOX.ltr}  `;
+    const header = `  ${BOX.lv}${padRight(' SEVERITY', C1)}${BOX.lv}${padRight(' TYPE', C2)}${BOX.lv}${padRight(' FINDING', C3)}${BOX.lv}  `;
+    const tBot = `  ${BOX.lbl}${BOX.lh.repeat(C1)}${BOX.lb}${BOX.lh.repeat(C2)}${BOX.lb}${BOX.lh.repeat(C3)}${BOX.lbr}  `;
+
+    lines.push(ansi.gray + BOX.v + ansi.reset + ansi.gray + tTop + ansi.reset + ansi.gray + BOX.v + ansi.reset);
+    lines.push(ansi.gray + BOX.v + ansi.reset + ansi.bold + header + ansi.reset + ansi.gray + BOX.v + ansi.reset);
+    
+    // Rows
+    findings.slice(0, 5).forEach(f => {
+      let sev = style.subtle(' INFO    ');
+      if (f.severity === 'critical' || f.severity === 'BLOCK') sev = style.error('🛑 CRIT  ');
+      else if (f.severity === 'high' || f.severity === 'WARN') sev = style.warning('🟡 WARN  ');
+      
+      const row = `  ${ansi.gray}${BOX.lv}${ansi.reset}${sev}${ansi.gray}${BOX.lv}${ansi.reset}${padRight(' '+(f.category||'General'), C2)}${ansi.gray}${BOX.lv}${ansi.reset}${padRight(' '+(f.message||f.title), C3)}${ansi.gray}${BOX.lv}${ansi.reset}  `;
+      lines.push(ansi.gray + BOX.v + ansi.reset + row + ansi.gray + BOX.v + ansi.reset);
+    });
+    
+    lines.push(ansi.gray + BOX.v + ansi.reset + ansi.gray + tBot + ansi.reset + ansi.gray + BOX.v + ansi.reset);
+  } else {
+    lines.push(ansi.gray + BOX.v + ansi.reset + padCenter(style.success('✅  NO ISSUES FOUND'), WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
   }
-  
-  lines.push('');
-  return lines.join('\n');
-}
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXPORTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-module.exports = {
-  // ANSI codes
-  ansi,
-  colors,
-  box,
-  icons,
-  
-  // Components
-  Spinner,
-  ProgressBar,
-  PhaseProgress,
-  
-  // Renderers
-  renderScoreCard,
-  renderFindingsList,
-  renderFinding,
-  renderTable,
-  renderSection,
-  renderDivider,
-  renderBanner,
-  
-  // Utilities
-  truncate,
-  stripAnsi,
-  formatNumber,
-  formatDuration,
-  formatBytes,
-  getScoreColor,
-  getGrade,
-};
+  lines.push(ansi.gray + BOX.v + ansi.reset + ' '.repeat(WIDTH - 2) + ansi.gray + BOX.v + ansi.reset);
+  console.log(lines.join('\n'));
+}