@tokentop/ttop 0.2.2

package/src/tui/driver/coverage.ts

@@ -0,0 +1,204 @@
+export interface ViewVisit {
+  view: string;
+  visitedAt: number;
+  duration?: number;
+}
+
+export interface CoverageReport {
+  sessionStart: number;
+  sessionEnd?: number | undefined;
+  viewsVisited: ViewVisit[];
+  uniqueViews: string[];
+  viewCounts: Record<string, number>;
+  totalViewChanges: number;
+  coveragePercentage?: number | undefined;
+}
+
+export interface CoverageTracker {
+  start(): void;
+  stop(): CoverageReport;
+  recordView(view: string): void;
+  getCurrentView(): string | null;
+  getReport(): CoverageReport;
+  isTracking(): boolean;
+}
+
+const KNOWN_VIEWS = [
+  'Dashboard',
+  'Providers',
+  'Trends',
+  'Projects',
+  'Settings',
+];
+
+export function createCoverageTracker(
+  knownViews: string[] = KNOWN_VIEWS
+): CoverageTracker {
+  let tracking = false;
+  let sessionStart = 0;
+  let currentView: string | null = null;
+  let currentViewStart = 0;
+  const viewsVisited: ViewVisit[] = [];
+  const viewCounts: Record<string, number> = {};
+
+  function buildReport(): CoverageReport {
+    const uniqueViews = [...new Set(viewsVisited.map((v) => v.view))];
+    const coveragePercentage =
+      knownViews.length > 0
+        ? (uniqueViews.filter((v) => knownViews.includes(v)).length /
+            knownViews.length) *
+          100
+        : undefined;
+
+    return {
+      sessionStart,
+      sessionEnd: tracking ? undefined : Date.now(),
+      viewsVisited: [...viewsVisited],
+      uniqueViews,
+      viewCounts: { ...viewCounts },
+      totalViewChanges: viewsVisited.length,
+      coveragePercentage,
+    };
+  }
+
+  return {
+    start() {
+      tracking = true;
+      sessionStart = Date.now();
+      currentView = null;
+      currentViewStart = 0;
+      viewsVisited.length = 0;
+      Object.keys(viewCounts).forEach((k) => delete viewCounts[k]);
+    },
+
+    stop() {
+      if (currentView && currentViewStart > 0) {
+        const lastVisit = viewsVisited[viewsVisited.length - 1];
+        if (lastVisit && lastVisit.view === currentView) {
+          lastVisit.duration = Date.now() - currentViewStart;
+        }
+      }
+      tracking = false;
+      return buildReport();
+    },
+
+    recordView(view: string) {
+      if (!tracking) return;
+      if (view === currentView) return;
+
+      const now = Date.now();
+
+      if (currentView && currentViewStart > 0) {
+        const lastVisit = viewsVisited[viewsVisited.length - 1];
+        if (lastVisit && lastVisit.view === currentView) {
+          lastVisit.duration = now - currentViewStart;
+        }
+      }
+
+      currentView = view;
+      currentViewStart = now;
+      viewsVisited.push({ view, visitedAt: now });
+      viewCounts[view] = (viewCounts[view] ?? 0) + 1;
+    },
+
+    getCurrentView() {
+      return currentView;
+    },
+
+    getReport() {
+      return buildReport();
+    },
+
+    isTracking() {
+      return tracking;
+    },
+  };
+}
+
+export function detectViewFromFrame(frame: string): string | null {
+  const lines = frame.split('\n').slice(0, 5);
+  const headerArea = lines.join('\n');
+
+  if (headerArea.includes('[1] Dashboard') && headerArea.includes('│')) {
+    const match = headerArea.match(/\[(\d)\] (\w+)/g);
+    if (match) {
+      for (const m of match) {
+        if (!m.includes('[')) continue;
+        const viewMatch = m.match(/\[(\d)\] (\w+)/);
+        if (viewMatch) {
+          const num = viewMatch[1];
+          const name = viewMatch[2];
+          if (
+            headerArea.includes(`[${num}]`) &&
+            frame.toLowerCase().includes(name?.toLowerCase() ?? '')
+          ) {
+            if (
+              headerArea.includes(`[${num}] ${name}`) &&
+              !headerArea.includes(`│ ${name}`)
+            ) {
+              return name ?? null;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  for (const view of KNOWN_VIEWS) {
+    if (frame.includes(`${view} `) || frame.includes(` ${view}`)) {
+      const viewLower = view.toLowerCase();
+      const frameLower = frame.toLowerCase();
+      if (
+        frameLower.includes(`${viewLower} view`) ||
+        frameLower.includes(`${viewLower}:`) ||
+        (frameLower.includes(viewLower) && lines.some((l) => l.includes(view)))
+      ) {
+        return view;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function formatCoverageReport(report: CoverageReport): string {
+  const lines: string[] = [
+    '╔══════════════════════════════════════════════════════════════════╗',
+    '║ COVERAGE REPORT                                                  ║',
+    '╠══════════════════════════════════════════════════════════════════╣',
+  ];
+
+  const duration = (report.sessionEnd ?? Date.now()) - report.sessionStart;
+  const durationSec = (duration / 1000).toFixed(1);
+
+  lines.push(
+    `║ Session Duration: ${durationSec}s`.padEnd(67) + '║'
+  );
+  lines.push(
+    `║ Views Visited: ${report.uniqueViews.length} unique, ${report.totalViewChanges} total`.padEnd(
+      67
+    ) + '║'
+  );
+
+  if (report.coveragePercentage !== undefined) {
+    lines.push(
+      `║ Coverage: ${report.coveragePercentage.toFixed(0)}%`.padEnd(67) + '║'
+    );
+  }
+
+  lines.push('╠══════════════════════════════════════════════════════════════════╣');
+  lines.push('║ View Breakdown:                                                  ║');
+
+  for (const [view, count] of Object.entries(report.viewCounts).sort(
+    (a, b) => b[1] - a[1]
+  )) {
+    const visits = report.viewsVisited.filter((v) => v.view === view);
+    const totalTime = visits.reduce((sum, v) => sum + (v.duration ?? 0), 0);
+    const timeStr = totalTime > 0 ? ` (${(totalTime / 1000).toFixed(1)}s)` : '';
+    lines.push(`║   ${view}: ${count}x${timeStr}`.padEnd(67) + '║');
+  }
+
+  lines.push('╚══════════════════════════════════════════════════════════════════╝');
+
+  return lines.join('\n');
+}

package/src/tui/driver/demo-snapshot.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+import { createDriver } from './driver.ts';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const SNAPSHOTS_DIR = './snapshots';
+
+async function saveSnapshot(frame: string, name: string): Promise<string> {
+  await fs.mkdir(SNAPSHOTS_DIR, { recursive: true });
+  const filePath = path.join(SNAPSHOTS_DIR, `${name}.txt`);
+  await fs.writeFile(filePath, frame, 'utf-8');
+  return path.resolve(filePath);
+}
+
+async function main() {
+  console.log('Creating driver...');
+  const driver = await createDriver({ width: 100, height: 30 });
+  
+  console.log('Launching app...');
+  await driver.launch();
+  await driver.waitForStable();
+  
+  console.log('Capturing dashboard...');
+  const dashboardFrame = await driver.capture();
+  const dashboardPath = await saveSnapshot(dashboardFrame, '01-dashboard');
+  console.log(`Saved: ${dashboardPath}`);
+  
+  console.log('Switching to Providers view...');
+  await driver.pressKey('2');
+  await driver.waitForStable();
+  const providersFrame = await driver.capture();
+  const providersPath = await saveSnapshot(providersFrame, '02-providers');
+  console.log(`Saved: ${providersPath}`);
+  
+  console.log('Switching to Trends view...');
+  await driver.pressKey('3');
+  await driver.waitForStable();
+  const trendsFrame = await driver.capture();
+  const trendsPath = await saveSnapshot(trendsFrame, '03-trends');
+  console.log(`Saved: ${trendsPath}`);
+  
+  console.log('Switching to Projects view...');
+  await driver.pressKey('4');
+  await driver.waitForStable();
+  const projectsFrame = await driver.capture();
+  const projectsPath = await saveSnapshot(projectsFrame, '04-projects');
+  console.log(`Saved: ${projectsPath}`);
+  
+  console.log('Switching to Settings view...');
+  await driver.pressKey('5');
+  await driver.waitForStable();
+  const settingsFrame = await driver.capture();
+  const settingsPath = await saveSnapshot(settingsFrame, '05-settings');
+  console.log(`Saved: ${settingsPath}`);
+  
+  console.log('Closing driver...');
+  await driver.close();
+  
+  console.log('\n✓ All snapshots saved to ./snapshots/');
+  console.log('  You can view them with: cat snapshots/01-dashboard.txt');
+}
+
+main().catch((err) => {
+  console.error('Demo failed:', err);
+  process.exit(1);
+});

package/src/tui/driver/diff.ts

@@ -0,0 +1,166 @@
+export interface DiffResult {
+  identical: boolean;
+  changedLines: number;
+  totalLines: number;
+  changePercentage: number;
+  additions: LineChange[];
+  deletions: LineChange[];
+  modifications: LineChange[];
+  visualDiff: string;
+}
+
+export interface LineChange {
+  lineNumber: number;
+  content: string;
+  expected?: string;
+}
+
+export interface DiffOptions {
+  ignoreWhitespace?: boolean;
+  contextLines?: number;
+}
+
+export function diffFrames(
+  expected: string,
+  actual: string,
+  options: DiffOptions = {}
+): DiffResult {
+  const { ignoreWhitespace = false, contextLines = 2 } = options;
+
+  const normalize = (s: string) =>
+    ignoreWhitespace ? s.replace(/\s+/g, ' ').trim() : s;
+
+  const expectedLines = expected.split('\n');
+  const actualLines = actual.split('\n');
+
+  const additions: LineChange[] = [];
+  const deletions: LineChange[] = [];
+  const modifications: LineChange[] = [];
+  const diffLines: string[] = [];
+
+  const maxLines = Math.max(expectedLines.length, actualLines.length);
+  const changedLineNumbers = new Set<number>();
+
+  for (let i = 0; i < maxLines; i++) {
+    const expLine = expectedLines[i] ?? '';
+    const actLine = actualLines[i] ?? '';
+    const expNorm = normalize(expLine);
+    const actNorm = normalize(actLine);
+
+    if (expNorm !== actNorm) {
+      changedLineNumbers.add(i);
+
+      if (i >= expectedLines.length) {
+        additions.push({ lineNumber: i + 1, content: actLine });
+      } else if (i >= actualLines.length) {
+        deletions.push({ lineNumber: i + 1, content: expLine });
+      } else {
+        modifications.push({
+          lineNumber: i + 1,
+          content: actLine,
+          expected: expLine,
+        });
+      }
+    }
+  }
+
+  for (let i = 0; i < maxLines; i++) {
+    const expLine = expectedLines[i] ?? '';
+    const actLine = actualLines[i] ?? '';
+
+    const isInContext = Array.from(changedLineNumbers).some(
+      (changed) => Math.abs(changed - i) <= contextLines
+    );
+
+    if (changedLineNumbers.has(i)) {
+      if (i >= expectedLines.length) {
+        diffLines.push(`+ ${String(i + 1).padStart(3)} │ ${actLine}`);
+      } else if (i >= actualLines.length) {
+        diffLines.push(`- ${String(i + 1).padStart(3)} │ ${expLine}`);
+      } else {
+        diffLines.push(`- ${String(i + 1).padStart(3)} │ ${expLine}`);
+        diffLines.push(`+ ${String(i + 1).padStart(3)} │ ${actLine}`);
+      }
+    } else if (isInContext) {
+      diffLines.push(`  ${String(i + 1).padStart(3)} │ ${actLine}`);
+    }
+  }
+
+  const identical = changedLineNumbers.size === 0;
+  const changedLines = changedLineNumbers.size;
+  const totalLines = maxLines;
+  const changePercentage =
+    totalLines > 0 ? (changedLines / totalLines) * 100 : 0;
+
+  return {
+    identical,
+    changedLines,
+    totalLines,
+    changePercentage,
+    additions,
+    deletions,
+    modifications,
+    visualDiff: diffLines.join('\n'),
+  };
+}
+
+export function highlightDiff(
+  expected: string,
+  actual: string,
+  options: DiffOptions = {}
+): string {
+  const result = diffFrames(expected, actual, options);
+
+  if (result.identical) {
+    return '✓ Frames are identical';
+  }
+
+  const lines: string[] = [
+    `╔══════════════════════════════════════════════════════════════════╗`,
+    `║ FRAME DIFF                                                       ║`,
+    `║ Changed: ${result.changedLines}/${result.totalLines} lines (${result.changePercentage.toFixed(1)}%)${' '.repeat(Math.max(0, 24 - result.changePercentage.toFixed(1).length))}║`,
+    `╠══════════════════════════════════════════════════════════════════╣`,
+    `║ - = removed   + = added                                          ║`,
+    `╚══════════════════════════════════════════════════════════════════╝`,
+    '',
+    result.visualDiff,
+  ];
+
+  return lines.join('\n');
+}
+
+export function createCharDiff(expected: string, actual: string): string {
+  const expectedLines = expected.split('\n');
+  const actualLines = actual.split('\n');
+  const maxLines = Math.max(expectedLines.length, actualLines.length);
+
+  const diffLines: string[] = [];
+
+  for (let i = 0; i < maxLines; i++) {
+    const expLine = expectedLines[i] ?? '';
+    const actLine = actualLines[i] ?? '';
+
+    if (expLine === actLine) {
+      continue;
+    }
+
+    const maxLen = Math.max(expLine.length, actLine.length);
+    let markers = '';
+
+    for (let j = 0; j < maxLen; j++) {
+      const expChar = expLine[j] ?? ' ';
+      const actChar = actLine[j] ?? ' ';
+      markers += expChar === actChar ? ' ' : '^';
+    }
+
+    if (markers.trim()) {
+      diffLines.push(`Line ${i + 1}:`);
+      diffLines.push(`  exp: ${expLine}`);
+      diffLines.push(`  act: ${actLine}`);
+      diffLines.push(`       ${markers}`);
+      diffLines.push('');
+    }
+  }
+
+  return diffLines.join('\n');
+}

package/src/tui/driver/driver.ts

@@ -0,0 +1,270 @@
+import { createTestRenderer } from '@opentui/core/testing';
+import { AppContext, createRoot } from '@opentui/react';
+import React from 'react';
+import { act } from 'react';
+import { createAppElement, type CreateAppOptions } from '../createApp.tsx';
+import { TestModeContext } from '../hooks/useSafeRenderer.ts';
+
+export interface DriverOptions {
+  width?: number;
+  height?: number;
+  appOptions?: CreateAppOptions;
+}
+
+export interface CaptureResult {
+  frame: string;
+  width: number;
+  height: number;
+  timestamp: number;
+}
+
+export interface WaitOptions {
+  timeout?: number;
+  interval?: number;
+}
+
+export interface StableOptions {
+  maxIterations?: number;
+  intervalMs?: number;
+  stableFrames?: number;
+}
+
+export interface KeyModifiers {
+  ctrl?: boolean;
+  shift?: boolean;
+  meta?: boolean;
+  option?: boolean;
+}
+
+type TestSetup = Awaited<ReturnType<typeof createTestRenderer>> & {
+  root: ReturnType<typeof createRoot> | null;
+};
+
+export interface Driver {
+  launch(): Promise<void>;
+  close(): Promise<void>;
+  isRunning(): boolean;
+  
+  sendKeys(keys: string): Promise<void>;
+  pressKey(key: string, modifiers?: KeyModifiers): Promise<void>;
+  typeText(text: string, delay?: number): Promise<void>;
+  pressEnter(): Promise<void>;
+  pressEscape(): Promise<void>;
+  pressTab(): Promise<void>;
+  pressArrow(direction: 'up' | 'down' | 'left' | 'right'): Promise<void>;
+  
+  capture(): Promise<string>;
+  captureWithMeta(): Promise<CaptureResult>;
+  
+  waitForText(text: string, options?: WaitOptions): Promise<boolean>;
+  waitForStable(options?: StableOptions): Promise<void>;
+  settle(): Promise<void>;
+  
+  resize(cols: number, rows: number): Promise<void>;
+  getSize(): { width: number; height: number };
+}
+
+export async function createDriver(options: DriverOptions = {}): Promise<Driver> {
+  const width = options.width ?? 100;
+  const height = options.height ?? 30;
+  const appOptions = { 
+    ...options.appOptions, 
+    debug: options.appOptions?.debug ?? false,
+    testMode: true,
+  };
+  
+  let testSetup: TestSetup | null = null;
+  let currentWidth = width;
+  let currentHeight = height;
+
+  const assertRunning = (): TestSetup => {
+    if (!testSetup) {
+      throw new Error('Driver not launched. Call launch() first.');
+    }
+    return testSetup;
+  };
+
+  const driver: Driver = {
+    async launch() {
+      if (testSetup) {
+        throw new Error('Driver already launched. Call close() first.');
+      }
+      
+      (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+      
+      const coreTestSetup = await createTestRenderer({ 
+        width: currentWidth, 
+        height: currentHeight,
+      });
+      
+      const root = createRoot(coreTestSetup.renderer);
+      
+      const appElement = createAppElement(appOptions);
+      
+      const wrappedApp = React.createElement(
+        AppContext.Provider,
+        { 
+          value: { 
+            keyHandler: coreTestSetup.renderer.keyInput, 
+            renderer: coreTestSetup.renderer 
+          } 
+        },
+        React.createElement(
+          TestModeContext.Provider,
+          { value: true },
+          appElement
+        )
+      );
+      
+      act(() => {
+        root.render(wrappedApp);
+      });
+      
+      testSetup = { ...coreTestSetup, root };
+      await testSetup.renderOnce();
+    },
+
+    async close() {
+      if (testSetup) {
+        if (testSetup.root) {
+          act(() => {
+            testSetup!.root!.unmount();
+          });
+        }
+        testSetup.renderer.destroy();
+        testSetup = null;
+        (globalThis as any).IS_REACT_ACT_ENVIRONMENT = false;
+      }
+    },
+
+    isRunning() {
+      return testSetup !== null;
+    },
+
+    async sendKeys(keys: string) {
+      const setup = assertRunning();
+      
+      for (const char of keys) {
+        if (char === '\r' || char === '\n') {
+          setup.mockInput.pressEnter();
+        } else if (char === '\t') {
+          setup.mockInput.pressTab();
+        } else if (char === '\x1b') {
+          setup.mockInput.pressEscape();
+        } else if (char === '\x7f') {
+          setup.mockInput.pressBackspace();
+        } else {
+          setup.mockInput.pressKey(char);
+        }
+      }
+      
+      await this.settle();
+    },
+
+    async pressKey(key: string, modifiers: KeyModifiers = {}) {
+      const setup = assertRunning();
+      setup.mockInput.pressKey(key, modifiers);
+      await this.settle();
+    },
+
+    async typeText(text: string, delay = 0) {
+      const setup = assertRunning();
+      await setup.mockInput.typeText(text, delay);
+      await this.settle();
+    },
+
+    async pressEnter() {
+      const setup = assertRunning();
+      setup.mockInput.pressEnter();
+      await this.settle();
+    },
+
+    async pressEscape() {
+      const setup = assertRunning();
+      setup.mockInput.pressEscape();
+      await this.settle();
+    },
+
+    async pressTab() {
+      const setup = assertRunning();
+      setup.mockInput.pressTab();
+      await this.settle();
+    },
+
+    async pressArrow(direction: 'up' | 'down' | 'left' | 'right') {
+      const setup = assertRunning();
+      setup.mockInput.pressArrow(direction);
+      await this.settle();
+    },
+
+    async capture(): Promise<string> {
+      const setup = assertRunning();
+      await setup.renderOnce();
+      return setup.captureCharFrame();
+    },
+
+    async captureWithMeta(): Promise<CaptureResult> {
+      const frame = await this.capture();
+      return {
+        frame,
+        width: currentWidth,
+        height: currentHeight,
+        timestamp: Date.now(),
+      };
+    },
+
+    async waitForText(text: string, options: WaitOptions = {}): Promise<boolean> {
+      const { timeout = 5000, interval = 50 } = options;
+      const start = Date.now();
+      
+      while (Date.now() - start < timeout) {
+        const frame = await this.capture();
+        if (frame.includes(text)) {
+          return true;
+        }
+        await new Promise(resolve => setTimeout(resolve, interval));
+      }
+      
+      return false;
+    },
+
+    async waitForStable(options: StableOptions = {}): Promise<void> {
+      const { maxIterations = 10, intervalMs = 50, stableFrames = 2 } = options;
+      let lastFrame = '';
+      let stableCount = 0;
+      
+      for (let i = 0; i < maxIterations; i++) {
+        const frame = await this.capture();
+        if (frame === lastFrame) {
+          stableCount++;
+          if (stableCount >= stableFrames) {
+            return;
+          }
+        } else {
+          stableCount = 0;
+        }
+        lastFrame = frame;
+        await new Promise(resolve => setTimeout(resolve, intervalMs));
+      }
+    },
+
+    async settle(): Promise<void> {
+      const setup = assertRunning();
+      await setup.renderOnce();
+    },
+
+    async resize(cols: number, rows: number): Promise<void> {
+      const setup = assertRunning();
+      currentWidth = cols;
+      currentHeight = rows;
+      setup.resize(cols, rows);
+      await this.settle();
+    },
+
+    getSize() {
+      return { width: currentWidth, height: currentHeight };
+    },
+  };
+
+  return driver;
+}