@tokentop/ttop 0.2.2

package/src/tui/driver/index.ts

@@ -0,0 +1,53 @@
+export {
+  createDriver,
+  type Driver,
+  type DriverOptions,
+  type CaptureResult,
+  type WaitOptions,
+  type StableOptions,
+  type KeyModifiers,
+} from './driver.ts';
+
+export {
+  diffFrames,
+  highlightDiff,
+  createCharDiff,
+  type DiffResult,
+  type LineChange,
+  type DiffOptions,
+} from './diff.ts';
+
+export {
+  assertSnapshot,
+  listGoldenFiles,
+  deleteGoldenFile,
+  getGoldenFile,
+  type AssertResult,
+  type AssertOptions,
+  type GoldenFile,
+  type GoldenFileInfo,
+} from './assertions.ts';
+
+export {
+  createRecorder,
+  replayRecording,
+  saveRecording,
+  loadRecording,
+  listRecordings,
+  deleteRecording,
+  type Recorder,
+  type Recording,
+  type RecordedCommand,
+  type RecorderOptions,
+  type ReplayOptions,
+  type ReplayResult,
+} from './recorder.ts';
+
+export {
+  createCoverageTracker,
+  detectViewFromFrame,
+  formatCoverageReport,
+  type CoverageTracker,
+  type CoverageReport,
+  type ViewVisit,
+} from './coverage.ts';

package/src/tui/driver/recorder.ts

@@ -0,0 +1,303 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { Driver } from './driver.ts';
+
+export interface RecordedCommand {
+  action: string;
+  params?: Record<string, unknown>;
+  timestamp: number;
+  frameAfter?: string;
+}
+
+export interface Recording {
+  name: string;
+  createdAt: string;
+  width: number;
+  height: number;
+  commands: RecordedCommand[];
+  finalFrame?: string | undefined;
+}
+
+export interface RecorderOptions {
+  captureFrames?: boolean;
+  name?: string;
+}
+
+export interface Recorder {
+  start(): void;
+  stop(): Recording;
+  addCommand(action: string, params?: Record<string, unknown>): void;
+  captureFrame(frame: string): void;
+  isRecording(): boolean;
+  getRecording(): Recording | null;
+}
+
+export function createRecorder(
+  width: number,
+  height: number,
+  options: RecorderOptions = {}
+): Recorder {
+  const { captureFrames = false, name = `recording-${Date.now()}` } = options;
+
+  let recording = false;
+  let commands: RecordedCommand[] = [];
+  let lastFrame: string | undefined;
+  const startTime = Date.now();
+
+  return {
+    start() {
+      recording = true;
+      commands = [];
+      lastFrame = undefined;
+    },
+
+    stop() {
+      recording = false;
+      const result: Recording = {
+        name,
+        createdAt: new Date().toISOString(),
+        width,
+        height,
+        commands,
+        finalFrame: lastFrame,
+      };
+      return result;
+    },
+
+    addCommand(action: string, params?: Record<string, unknown>) {
+      if (!recording) return;
+
+      const cmd: RecordedCommand = {
+        action,
+        timestamp: Date.now() - startTime,
+      };
+
+      if (params && Object.keys(params).length > 0) {
+        cmd.params = params;
+      }
+
+      if (captureFrames && lastFrame) {
+        cmd.frameAfter = lastFrame;
+      }
+
+      commands.push(cmd);
+    },
+
+    captureFrame(frame: string) {
+      if (!recording) return;
+      lastFrame = frame;
+    },
+
+    isRecording() {
+      return recording;
+    },
+
+    getRecording() {
+      if (commands.length === 0) return null;
+      return {
+        name,
+        createdAt: new Date().toISOString(),
+        width,
+        height,
+        commands,
+        finalFrame: lastFrame,
+      };
+    },
+  };
+}
+
+export interface ReplayOptions {
+  speed?: number;
+  stepMode?: boolean;
+  onStep?: (
+    cmd: RecordedCommand,
+    index: number,
+    total: number
+  ) => Promise<void>;
+  onFrame?: (frame: string, cmd: RecordedCommand) => void;
+}
+
+export interface ReplayResult {
+  success: boolean;
+  commandsExecuted: number;
+  totalCommands: number;
+  errors: Array<{ index: number; command: RecordedCommand; error: string }>;
+  finalFrame?: string;
+}
+
+export async function replayRecording(
+  driver: Driver,
+  recording: Recording,
+  options: ReplayOptions = {}
+): Promise<ReplayResult> {
+  const { speed = 1, stepMode = false, onStep, onFrame } = options;
+
+  const result: ReplayResult = {
+    success: true,
+    commandsExecuted: 0,
+    totalCommands: recording.commands.length,
+    errors: [],
+  };
+
+  let lastTimestamp = 0;
+
+  for (let i = 0; i < recording.commands.length; i++) {
+    const cmd = recording.commands[i];
+    if (!cmd) continue;
+
+    if (stepMode && onStep) {
+      await onStep(cmd, i, recording.commands.length);
+    }
+
+    if (!stepMode && speed < Infinity && cmd.timestamp > lastTimestamp) {
+      const delay = (cmd.timestamp - lastTimestamp) / speed;
+      if (delay > 0) {
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    lastTimestamp = cmd.timestamp;
+
+    try {
+      await executeCommand(driver, cmd);
+      result.commandsExecuted++;
+
+      if (onFrame) {
+        const frame = await driver.capture();
+        onFrame(frame, cmd);
+      }
+    } catch (err) {
+      result.success = false;
+      result.errors.push({
+        index: i,
+        command: cmd,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  try {
+    result.finalFrame = await driver.capture();
+  } catch {
+    // Ignore capture errors
+  }
+
+  return result;
+}
+
+async function executeCommand(
+  driver: Driver,
+  cmd: RecordedCommand
+): Promise<void> {
+  const params = cmd.params ?? {};
+
+  switch (cmd.action) {
+    case 'sendKeys':
+      await driver.sendKeys(String(params.keys ?? ''));
+      break;
+
+    case 'pressKey':
+      await driver.pressKey(
+        String(params.key ?? ''),
+        params.modifiers as Record<string, boolean> | undefined
+      );
+      break;
+
+    case 'pressTab':
+      await driver.pressTab();
+      break;
+
+    case 'pressEnter':
+      await driver.pressEnter();
+      break;
+
+    case 'pressEscape':
+      await driver.pressEscape();
+      break;
+
+    case 'pressArrow':
+      await driver.pressArrow(params.direction as 'up' | 'down' | 'left' | 'right');
+      break;
+
+    case 'typeText':
+      await driver.typeText(
+        String(params.text ?? ''),
+        typeof params.delay === 'number' ? params.delay : 0
+      );
+      break;
+
+    case 'resize':
+      await driver.resize(
+        typeof params.cols === 'number' ? params.cols : 100,
+        typeof params.rows === 'number' ? params.rows : 30
+      );
+      break;
+
+    case 'waitForStable':
+      await driver.waitForStable({
+        maxIterations:
+          typeof params.maxIterations === 'number' ? params.maxIterations : 10,
+        intervalMs:
+          typeof params.intervalMs === 'number' ? params.intervalMs : 50,
+      });
+      break;
+
+    case 'waitForText':
+      await driver.waitForText(String(params.text ?? ''), {
+        timeout: typeof params.timeout === 'number' ? params.timeout : 5000,
+      });
+      break;
+
+    default:
+      // Skip unknown commands (launch, close, capture are not replayable)
+      break;
+  }
+}
+
+const DEFAULT_RECORDINGS_DIR = './recordings';
+
+export async function saveRecording(
+  recording: Recording,
+  dir: string = DEFAULT_RECORDINGS_DIR
+): Promise<string> {
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, `${recording.name}.json`);
+  await fs.writeFile(filePath, JSON.stringify(recording, null, 2), 'utf-8');
+  return path.resolve(filePath);
+}
+
+export async function loadRecording(
+  name: string,
+  dir: string = DEFAULT_RECORDINGS_DIR
+): Promise<Recording | null> {
+  const filePath = path.join(dir, `${name}.json`);
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content) as Recording;
+  } catch {
+    return null;
+  }
+}
+
+export async function listRecordings(
+  dir: string = DEFAULT_RECORDINGS_DIR
+): Promise<string[]> {
+  try {
+    const files = await fs.readdir(dir);
+    return files.filter((f) => f.endsWith('.json')).map((f) => f.replace('.json', ''));
+  } catch {
+    return [];
+  }
+}
+
+export async function deleteRecording(
+  name: string,
+  dir: string = DEFAULT_RECORDINGS_DIR
+): Promise<boolean> {
+  const filePath = path.join(dir, `${name}.json`);
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/tui/driver/test-workflow.ts

@@ -0,0 +1,115 @@
+#!/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() {
+  // Use 80x24 to match your terminal
+  const driver = await createDriver({ width: 80, height: 24 });
+  
+  console.log('Launching app...');
+  await driver.launch();
+  await driver.waitForStable();
+  
+  // Step 1: Navigate to Settings (key 5)
+  console.log('Navigating to Settings...');
+  await driver.pressKey('5');
+  await driver.waitForStable();
+  
+  // Step 2: Find and capture Alerts settings
+  // Settings page likely has tabs/sections - need to find Alerts
+  console.log('Looking for Alerts section...');
+  let frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-01-settings');
+  console.log('Saved settings view');
+  
+  // Try navigating within settings to find Alerts (try arrow keys or tab)
+  // First let's see what's on the settings page
+  if (!frame.includes('Alerts') && !frame.includes('alerts')) {
+    // Try pressing tab or arrows to navigate
+    await driver.pressTab();
+    await driver.waitForStable();
+    frame = await driver.capture();
+  }
+  
+  await saveSnapshot(frame, 'workflow-02-alerts-settings');
+  console.log('Saved alerts settings');
+  
+  // Step 3: Navigate back to Dashboard (key 1)
+  console.log('Navigating to Dashboard...');
+  await driver.pressKey('1');
+  await driver.waitForStable();
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-03-dashboard');
+  console.log('Saved dashboard view');
+  
+  // Step 4: Change time scale to 7d
+  // Need to find how to change timescale - likely a dropdown or key
+  console.log('Changing time scale to 7d...');
+  // Try common keys for time scale selection
+  // Check if there's a visible control for this
+  
+  // Try 't' for time or look for other controls
+  await driver.pressKey('t');
+  await driver.waitForStable();
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-04-timescale-menu');
+  
+  // If a menu opened, try to select 7d
+  if (frame.includes('7d') || frame.includes('7 d')) {
+    // Navigate to 7d option
+    await driver.pressArrow('down');
+    await driver.waitForStable();
+    await driver.pressArrow('down');
+    await driver.waitForStable();
+    frame = await driver.capture();
+    await saveSnapshot(frame, 'workflow-05-timescale-selecting');
+    await driver.pressEnter();
+    await driver.waitForStable();
+  }
+  
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-06-after-timescale');
+  console.log('Saved after timescale change');
+  
+  // Step 5: Filter with "opus"
+  console.log('Filtering with "opus"...');
+  // Try '/' for search/filter (common pattern)
+  await driver.pressKey('/');
+  await driver.waitForStable();
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-07-filter-input');
+  
+  // Type "opus"
+  await driver.typeText('opus');
+  await driver.waitForStable();
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-08-filter-opus');
+  
+  // Press enter to apply filter
+  await driver.pressEnter();
+  await driver.waitForStable();
+  
+  // Final result
+  frame = await driver.capture();
+  await saveSnapshot(frame, 'workflow-09-final-result');
+  console.log('Saved final filtered result');
+  
+  await driver.close();
+  
+  console.log('\n✓ Workflow complete! Check ./snapshots/workflow-*.txt');
+}
+
+main().catch((err) => {
+  console.error('Workflow failed:', err);
+  process.exit(1);
+});

package/src/tui/driver/test.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+import { createDriver } from './driver.ts';
+
+async function main() {
+  console.log('Creating driver...');
+  const driver = await createDriver({ width: 100, height: 30 });
+  
+  console.log('Launching app...');
+  await driver.launch();
+  
+  console.log('Waiting for initial render...');
+  await driver.waitForStable();
+  
+  console.log('Capturing initial frame...');
+  const frame1 = await driver.capture();
+  console.log('=== INITIAL FRAME ===');
+  console.log(frame1);
+  console.log('=== END FRAME ===\n');
+  
+  console.log('Pressing "2" to switch to Providers view...');
+  await driver.pressKey('2');
+  await driver.waitForStable();
+  
+  const frame2 = await driver.capture();
+  console.log('=== PROVIDERS VIEW ===');
+  console.log(frame2);
+  console.log('=== END FRAME ===\n');
+  
+  console.log('Pressing "3" to switch to Trends view...');
+  await driver.pressKey('3');
+  await driver.waitForStable();
+  
+  const frame3 = await driver.capture();
+  console.log('=== TRENDS VIEW ===');
+  console.log(frame3);
+  console.log('=== END FRAME ===\n');
+  
+  console.log('Closing driver...');
+  await driver.close();
+  
+  console.log('Done!');
+}
+
+main().catch((err) => {
+  console.error('Test failed:', err);
+  process.exit(1);
+});

package/src/tui/hooks/index.ts

@@ -0,0 +1,20 @@
+export { useEmaActivity } from './useEmaActivity.ts';
+export type { ActivityState, ActivityDebugData, UseActivityRateResult } from './useEmaActivity.ts';
+
+export { useDashboardState } from './useDashboardState.ts';
+export type { DashboardDeltas, UseDashboardStateResult } from './useDashboardState.ts';
+
+export { usePulse, getPulseColor } from './usePulse.ts';
+export type { UsePulseOptions } from './usePulse.ts';
+
+export { useValueFlash, interpolateColor } from './useValueFlash.ts';
+export type { UseValueFlashOptions, UseValueFlashResult } from './useValueFlash.ts';
+
+export { useAnimatedValue, useAnimatedCurrency, useAnimatedTokens, useAnimatedCount, easings } from './useAnimatedValue.ts';
+export type { UseAnimatedValueOptions, EasingFunction } from './useAnimatedValue.ts';
+
+export { useEntranceAnimation, applyEntranceFade } from './useEntranceAnimation.ts';
+export type { UseEntranceAnimationOptions } from './useEntranceAnimation.ts';
+
+export { useExitAnimation } from './useExitAnimation.ts';
+export type { ExitAnimationItem, UseExitAnimationOptions, UseExitAnimationResult } from './useExitAnimation.ts';

package/src/tui/hooks/useAnimatedValue.ts

@@ -0,0 +1,113 @@
+import { useState, useEffect, useRef } from 'react';
+
+export type EasingFunction = (t: number) => number;
+
+export const easings = {
+  linear: (t: number) => t,
+  easeOutQuad: (t: number) => 1 - (1 - t) * (1 - t),
+  easeOutCubic: (t: number) => 1 - Math.pow(1 - t, 3),
+  easeOutExpo: (t: number) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+  easeInOutQuad: (t: number) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+} as const;
+
+export interface UseAnimatedValueOptions {
+  durationMs?: number;
+  easing?: keyof typeof easings | EasingFunction;
+  precision?: number;
+  frameRate?: number;
+}
+
+export function useAnimatedValue(
+  targetValue: number,
+  options: UseAnimatedValueOptions = {}
+): number {
+  const { 
+    durationMs = 300, 
+    easing = 'easeOutQuad',
+    precision = 2,
+    frameRate = 60,
+  } = options;
+
+  const [displayValue, setDisplayValue] = useState(targetValue);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const startValueRef = useRef(targetValue);
+  const startTimeRef = useRef<number>(Date.now());
+  const targetRef = useRef(targetValue);
+
+  const easingFn = typeof easing === 'function' ? easing : easings[easing];
+  const frameInterval = Math.round(1000 / frameRate);
+
+  useEffect(() => {
+    if (targetRef.current === targetValue && displayValue === targetValue) {
+      return;
+    }
+
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+    }
+
+    startValueRef.current = displayValue;
+    startTimeRef.current = Date.now();
+    targetRef.current = targetValue;
+
+    intervalRef.current = setInterval(() => {
+      const elapsed = Date.now() - startTimeRef.current;
+      const progress = Math.min(elapsed / durationMs, 1);
+      const easedProgress = easingFn(progress);
+      
+      const startVal = startValueRef.current;
+      const currentValue = startVal + (targetRef.current - startVal) * easedProgress;
+      const roundedValue = Number(currentValue.toFixed(precision));
+      
+      setDisplayValue(roundedValue);
+
+      if (progress >= 1) {
+        if (intervalRef.current !== null) {
+          clearInterval(intervalRef.current);
+          intervalRef.current = null;
+        }
+        setDisplayValue(targetRef.current);
+      }
+    }, frameInterval);
+
+    return () => {
+      if (intervalRef.current !== null) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    };
+  }, [targetValue, durationMs, easingFn, precision, frameInterval, displayValue]);
+
+  return displayValue;
+}
+
+export function useAnimatedCurrency(
+  targetValue: number,
+  options: Omit<UseAnimatedValueOptions, 'precision'> = {}
+): string {
+  const animatedValue = useAnimatedValue(targetValue, { ...options, precision: 2 });
+  return `$${animatedValue.toFixed(2)}`;
+}
+
+export function useAnimatedTokens(
+  targetValue: number,
+  options: Omit<UseAnimatedValueOptions, 'precision'> = {}
+): string {
+  const animatedValue = useAnimatedValue(targetValue, { ...options, precision: 0 });
+  
+  if (animatedValue >= 1_000_000) {
+    return `${(animatedValue / 1_000_000).toFixed(1)}M`;
+  }
+  if (animatedValue >= 1_000) {
+    return `${(animatedValue / 1_000).toFixed(1)}K`;
+  }
+  return Math.round(animatedValue).toLocaleString();
+}
+
+export function useAnimatedCount(
+  targetValue: number,
+  options: Omit<UseAnimatedValueOptions, 'precision'> = {}
+): string {
+  const animatedValue = useAnimatedValue(targetValue, { ...options, precision: 0 });
+  return Math.round(animatedValue).toLocaleString();
+}