Terminal Viewer

A production-ready React component library for displaying live terminal sessions in pentesting and security operations.

Features

• ✨ High Performance: Handles 100k+ lines at 60fps with virtualization
• 🎨 ANSI Color Support: Full support for 16/256/RGB color modes
• 🚀 Real-time Streaming: WebSocket integration with auto-reconnect and exponential backoff
• 🔍 Search with Highlighting: Fast, debounced search with character-level match highlighting
• 🎭 11 Beautiful Themes: Dracula, Cyberpunk, Matrix, Monokai, Nord, Solarized Dark, Gruvbox Dark, One Dark, Tokyo Night, Catppuccin Mocha, Ayu Dark
• 🎮 Interactive Demo: Built-in command generator with realistic pentest scenarios
• ⌨️ Keyboard Shortcuts: Ctrl+F (search), Ctrl+L (clear), Ctrl+End (scroll bottom)
• 📘 TypeScript First: Fully typed with strict mode enabled

Installation

npm install @yourorg/terminal-viewer

Quick Start

import { useRef, useEffect } from 'react';
import { TerminalViewer, TerminalViewerHandle } from '@yourorg/terminal-viewer';

function App() {
  const terminalRef = useRef<TerminalViewerHandle>(null);

  useEffect(() => {
    // Add some terminal output
    terminalRef.current?.addContent(`
\\x1b[1;32m=== System Scan ===\\x1b[0m
\\x1b[36mScanning network...\\x1b[0m
\\x1b[32m[+]\\x1b[0m Found open port 22/tcp
\\x1b[31m[-]\\x1b[0m Port 23/tcp closed
\\x1b[1;32m[✓] Scan complete!\\x1b[0m
    `);
  }, []);

  return (
    <TerminalViewer
      ref={terminalRef}
      width={900}
      height={600}
      onLineClick={(line, index) => {
        console.log('Clicked:', line.raw);
      }}
    />
  );
}

API Reference

TerminalViewer Component

Main component for displaying terminal output.

Props:

• width?: number - Width in pixels (default: 800)
• height?: number - Height in pixels (default: 600)
• maxLines?: number - Maximum lines to store (default: 100000)
• theme?: TerminalTheme - Custom theme override
• searchMatches?: SearchMatch[] - Search matches for highlighting
• currentMatchIndex?: number - Index of current search match
• queryLength?: number - Length of search query
• onLineClick?: (line: TerminalLine, index: number) => void - Line click handler

Ref Methods:

• addContent(text: string) - Add terminal output
• clear() - Clear all content
• scrollToLine(index: number) - Scroll to specific line
• scrollToBottom() - Scroll to bottom
• getBuffer() - Get buffer reference for search integration

Hooks

useTerminalBuffer

Manages the circular buffer for terminal lines.

const { addContent, clear, lineCount, stats } = useTerminalBuffer({
  maxLines: 100000
});

useTerminalTheme

Manages theme state and provides color utilities.

const { theme, themeName, setTheme, availableThemes } = useTerminalTheme('dracula');

Available themes: dracula, cyberpunk, matrix, monokai, nord, solarized-dark, gruvbox-dark, one-dark, tokyo-night, catppuccin-mocha, ayu-dark

useTerminalSearch

Provides search functionality across terminal buffer with match highlighting.

const {
  query,
  setQuery,
  matches,
  goToNext,
  goToPrevious,
  currentMatchIndex,
  totalMatches,
  isSearching
} = useTerminalSearch({ bufferRef, debounceMs: 150 });

useTerminalWebSocket

Manages WebSocket connection for real-time terminal streaming.

const {
  status,
  error,
  connect,
  disconnect,
  send,
  messagesReceived
} = useTerminalWebSocket({
  url: 'ws://localhost:3001/session/demo',
  onData: (data) => terminalRef.current?.addContent(data),
  onClear: () => terminalRef.current?.clear(),
  reconnect: true
});

ANSI Color Support

The parser supports:

• Basic colors (30-37, 40-47): Standard 8 colors
• Bright colors (90-97, 100-107): Bright variants
• 256-color mode (38;5;n, 48;5;n): Extended palette
• RGB mode (38;2;r;g;b, 48;2;r;g;b): True color
• Text styles: Bold, dim, italic, underline, strikethrough, blink

Architecture

src/
├── components/       # React components
│   ├── TerminalLine.tsx
│   └── TerminalViewer.tsx
├── hooks/           # Custom React hooks
│   ├── useTerminalBuffer.ts
│   ├── useTerminalTheme.ts
│   └── useTerminalSearch.ts
├── lib/             # Core logic (non-React)
│   ├── CircularBuffer.ts
│   ├── ANSIParser.ts
│   └── themes.ts
├── types/           # TypeScript definitions
│   └── index.ts
└── utils/           # Helper functions
    ├── generateId.ts
    └── parseTerminalLine.ts

Development Status

✅ Completed

• Phase 1: Project setup (Git, Vite, React, TypeScript)
• Phase 2: Core data structures (CircularBuffer, TypeScript interfaces)
• Phase 3: ANSI parser with full SGR code support
• Phase 4: React hooks (buffer, theme, search)
• Phase 5: Components (TerminalLine, TerminalViewer)
• Phase 6: WebSocket integration for real-time streaming with auto-reconnect
• Phase 7: Search UI with character-level highlighting and match navigation
• Phase 8: Storybook documentation, 11 themes, interactive demo

Tests: All passing ✅
TypeScript: Strict mode enabled ✅

🚧 Future Enhancements

• Collaborative Annotations: Add notes, findings, and questions to specific lines
• Export Functionality: Save terminal output to file
• Line Numbers: Toggle line number display

Showcase & Demo

The project includes a fully interactive demo showcasing all features:

# Start the development server
npm run dev

# In another terminal, start the WebSocket mock server (optional)
npm run mock-server

The demo includes:

• Interactive Command Generator: Generate realistic pentest commands (nmap, nikto, sqlmap, dirb, etc.)
• WebSocket Toggle: Switch between local generation and WebSocket server
• Real-time Stats: Commands generated, lines added, generation rate
• Speed Control: Adjustable generation speed (500-3000ms)
• Scenario Selector: Choose from different command scenarios
• Search Highlighting: Try searching for "port", "scan", or any term
• Theme Switcher: Switch between 11 beautiful themes
• Keyboard Shortcuts: Use Ctrl+F to search, Ctrl+L to clear

Development

# Install dependencies
npm install

# Run dev server
npm run dev

# Run WebSocket mock server (for testing WebSocket features)
npm run mock-server

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

# Type check
npm run typecheck

# Build for production
npm run build

# Storybook (component documentation)
npm run storybook

Performance

• Handles 100,000+ lines smoothly at 60fps
• Virtual scrolling with react-window
• O(1) buffer operations with circular buffer
• Debounced search (150ms) for responsiveness
• Memoized components to prevent unnecessary re-renders
• Character-level search highlighting with efficient segment splitting
• WebSocket auto-reconnect with exponential backoff

License

MIT

Contributing

Contributions welcome! This is a work in progress.

Built with ❤️ for pentesting and security operations.