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

``bash
npm install @yourorg/terminal-viewer
`

Quick Start

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

function App() {
const terminalRef = useRef(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 (
ref={terminalRef}
width={900}
height={600}
onLineClick={(line, index) => {
console.log('Clicked:', line.raw);
}}
/>
);
}
`

API Reference

$3

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

$3

#### useTerminalBuffer

Manages the circular buffer for terminal lines.

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

#### useTerminalTheme

Manages theme state and provides color utilities.

`tsx
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.

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

#### useTerminalWebSocket

Manages WebSocket connection for real-time terminal streaming.

`tsx
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

$3

- 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 ✅

$3

- 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:

`bash


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

`bash


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.