{"_id":"@b0xs/termbox","name":"@b0xs/termbox","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@b0xs/termbox","version":"1.0.0","type":"module","description":"Production-ready Terminal Viewer component for live pentesting sessions with ANSI color support, WebSocket streaming, and multiple themes","author":{"name":"Oscar Valdez","email":"ozipi.nomad@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ozipi/termbox.git"},"keywords":["terminal","viewer","ansi","websocket","pentesting","security","react","typescript","virtualization","terminal-emulator"],"main":"./dist/index.js","module":"./dist/index.esm.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.esm.js","require":"./dist/index.js","types":"./dist/index.d.ts"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"dev":"vite","build":"vite build","build:types":"tsc --emitDeclarationOnly --outDir dist","prepublishOnly":"npm run build","lint":"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0","preview":"vite preview","test":"vitest","test:ui":"vitest --ui","test:coverage":"vitest --coverage","typecheck":"tsc --noEmit","storybook":"storybook dev -p 6006","build-storybook":"storybook build","mock-server":"cd mock-server && npm start"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0"},"dependencies":{"react-window":"^1.8.10"},"devDependencies":{"@storybook/addon-essentials":"^8.6.14","@storybook/addon-interactions":"^8.6.14","@storybook/addon-links":"^8.6.14","@storybook/blocks":"^8.6.14","@storybook/react":"^8.6.14","@storybook/react-vite":"^8.6.14","@storybook/test":"^8.6.14","@testing-library/jest-dom":"^6.4.2","@testing-library/react":"^14.2.2","@testing-library/user-event":"^14.5.2","@types/react":"^18.2.66","@types/react-dom":"^18.2.22","@types/react-window":"^1.8.8","@typescript-eslint/eslint-plugin":"^7.2.0","@typescript-eslint/parser":"^7.2.0","@vitejs/plugin-react":"^4.2.1","@vitest/ui":"^1.4.0","eslint":"^8.57.0","eslint-plugin-react-hooks":"^4.6.0","eslint-plugin-react-refresh":"^0.4.6","jsdom":"^24.0.0","react":"^18.2.0","react-dom":"^18.2.0","storybook":"^8.6.14","terser":"^5.44.1","typescript":"^5.2.2","vite":"^5.2.0","vite-plugin-dts":"^4.5.4","vitest":"^1.4.0"},"_id":"@b0xs/termbox@1.0.0","gitHead":"a250fff2500088e6436d0496127c56dfffb47a4f","bugs":{"url":"https://github.com/ozipi/termbox/issues"},"homepage":"https://github.com/ozipi/termbox#readme","_nodeVersion":"20.11.0","_npmVersion":"10.2.4","dist":{"integrity":"sha512-HDvSKcSVzSmZ8kYuu2Me1OweY2a/qvZiB7Wqwi9UH/4w9oCYt9NOa1dj4AT/ESeoNauCyyk+02LMaH4b3764uQ==","shasum":"f422304361a664e78b6aa8defff43e4ee8fb824d","tarball":"https://registry.npmjs.org/@b0xs/termbox/-/termbox-1.0.0.tgz","fileCount":26,"unpackedSize":509829,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEnc7wYmIqjAId7nF/vr5q+vJQWhikR9ff/Wipf3FosNAiBxQ1bLt2RSaDIEDOjUSsDCHXVnyXEv1Jh5ZJgSS8opQg=="}]},"_npmUser":{"name":"ozipi","email":"ozipi.nomad@gmail.com"},"directories":{},"maintainers":[{"name":"ozipi","email":"ozipi.nomad@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/termbox_1.0.0_1764889141252_0.586196313030023"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-04T22:59:01.198Z","1.0.0":"2025-12-04T22:59:01.443Z","modified":"2025-12-04T22:59:01.756Z"},"maintainers":[{"name":"ozipi","email":"ozipi.nomad@gmail.com"}],"description":"Production-ready Terminal Viewer component for live pentesting sessions with ANSI color support, WebSocket streaming, and multiple themes","homepage":"https://github.com/ozipi/termbox#readme","keywords":["terminal","viewer","ansi","websocket","pentesting","security","react","typescript","virtualization","terminal-emulator"],"repository":{"type":"git","url":"git+https://github.com/ozipi/termbox.git"},"author":{"name":"Oscar Valdez","email":"ozipi.nomad@gmail.com"},"bugs":{"url":"https://github.com/ozipi/termbox/issues"},"license":"MIT","readme":"# Terminal Viewer\n\nA production-ready React component library for displaying live terminal sessions in pentesting and security operations.\n\n## Features\n\n- ✨ **High Performance**: Handles 100k+ lines at 60fps with virtualization\n- 🎨 **ANSI Color Support**: Full support for 16/256/RGB color modes\n- 🚀 **Real-time Streaming**: WebSocket integration with auto-reconnect and exponential backoff\n- 🔍 **Search with Highlighting**: Fast, debounced search with character-level match highlighting\n- 🎭 **11 Beautiful Themes**: Dracula, Cyberpunk, Matrix, Monokai, Nord, Solarized Dark, Gruvbox Dark, One Dark, Tokyo Night, Catppuccin Mocha, Ayu Dark\n- 🎮 **Interactive Demo**: Built-in command generator with realistic pentest scenarios\n- ⌨️ **Keyboard Shortcuts**: Ctrl+F (search), Ctrl+L (clear), Ctrl+End (scroll bottom)\n- 📘 **TypeScript First**: Fully typed with strict mode enabled\n\n## Installation\n\n```bash\nnpm install @yourorg/terminal-viewer\n```\n\n## Quick Start\n\n```tsx\nimport { useRef, useEffect } from 'react';\nimport { TerminalViewer, TerminalViewerHandle } from '@yourorg/terminal-viewer';\n\nfunction App() {\n  const terminalRef = useRef<TerminalViewerHandle>(null);\n\n  useEffect(() => {\n    // Add some terminal output\n    terminalRef.current?.addContent(`\n\\\\x1b[1;32m=== System Scan ===\\\\x1b[0m\n\\\\x1b[36mScanning network...\\\\x1b[0m\n\\\\x1b[32m[+]\\\\x1b[0m Found open port 22/tcp\n\\\\x1b[31m[-]\\\\x1b[0m Port 23/tcp closed\n\\\\x1b[1;32m[✓] Scan complete!\\\\x1b[0m\n    `);\n  }, []);\n\n  return (\n    <TerminalViewer\n      ref={terminalRef}\n      width={900}\n      height={600}\n      onLineClick={(line, index) => {\n        console.log('Clicked:', line.raw);\n      }}\n    />\n  );\n}\n```\n\n## API Reference\n\n### TerminalViewer Component\n\nMain component for displaying terminal output.\n\n**Props:**\n- `width?: number` - Width in pixels (default: 800)\n- `height?: number` - Height in pixels (default: 600)\n- `maxLines?: number` - Maximum lines to store (default: 100000)\n- `theme?: TerminalTheme` - Custom theme override\n- `searchMatches?: SearchMatch[]` - Search matches for highlighting\n- `currentMatchIndex?: number` - Index of current search match\n- `queryLength?: number` - Length of search query\n- `onLineClick?: (line: TerminalLine, index: number) => void` - Line click handler\n\n**Ref Methods:**\n- `addContent(text: string)` - Add terminal output\n- `clear()` - Clear all content\n- `scrollToLine(index: number)` - Scroll to specific line\n- `scrollToBottom()` - Scroll to bottom\n- `getBuffer()` - Get buffer reference for search integration\n\n### Hooks\n\n#### useTerminalBuffer\n\nManages the circular buffer for terminal lines.\n\n```tsx\nconst { addContent, clear, lineCount, stats } = useTerminalBuffer({\n  maxLines: 100000\n});\n```\n\n#### useTerminalTheme\n\nManages theme state and provides color utilities.\n\n```tsx\nconst { theme, themeName, setTheme, availableThemes } = useTerminalTheme('dracula');\n```\n\n**Available themes:** `dracula`, `cyberpunk`, `matrix`, `monokai`, `nord`, `solarized-dark`, `gruvbox-dark`, `one-dark`, `tokyo-night`, `catppuccin-mocha`, `ayu-dark`\n\n#### useTerminalSearch\n\nProvides search functionality across terminal buffer with match highlighting.\n\n```tsx\nconst {\n  query,\n  setQuery,\n  matches,\n  goToNext,\n  goToPrevious,\n  currentMatchIndex,\n  totalMatches,\n  isSearching\n} = useTerminalSearch({ bufferRef, debounceMs: 150 });\n```\n\n#### useTerminalWebSocket\n\nManages WebSocket connection for real-time terminal streaming.\n\n```tsx\nconst {\n  status,\n  error,\n  connect,\n  disconnect,\n  send,\n  messagesReceived\n} = useTerminalWebSocket({\n  url: 'ws://localhost:3001/session/demo',\n  onData: (data) => terminalRef.current?.addContent(data),\n  onClear: () => terminalRef.current?.clear(),\n  reconnect: true\n});\n```\n\n## ANSI Color Support\n\nThe parser supports:\n- **Basic colors** (30-37, 40-47): Standard 8 colors\n- **Bright colors** (90-97, 100-107): Bright variants\n- **256-color mode** (38;5;n, 48;5;n): Extended palette\n- **RGB mode** (38;2;r;g;b, 48;2;r;g;b): True color\n- **Text styles**: Bold, dim, italic, underline, strikethrough, blink\n\n## Architecture\n\n```\nsrc/\n├── components/       # React components\n│   ├── TerminalLine.tsx\n│   └── TerminalViewer.tsx\n├── hooks/           # Custom React hooks\n│   ├── useTerminalBuffer.ts\n│   ├── useTerminalTheme.ts\n│   └── useTerminalSearch.ts\n├── lib/             # Core logic (non-React)\n│   ├── CircularBuffer.ts\n│   ├── ANSIParser.ts\n│   └── themes.ts\n├── types/           # TypeScript definitions\n│   └── index.ts\n└── utils/           # Helper functions\n    ├── generateId.ts\n    └── parseTerminalLine.ts\n```\n\n## Development Status\n\n### ✅ Completed\n\n- **Phase 1**: Project setup (Git, Vite, React, TypeScript)\n- **Phase 2**: Core data structures (CircularBuffer, TypeScript interfaces)\n- **Phase 3**: ANSI parser with full SGR code support\n- **Phase 4**: React hooks (buffer, theme, search)\n- **Phase 5**: Components (TerminalLine, TerminalViewer)\n- **Phase 6**: WebSocket integration for real-time streaming with auto-reconnect\n- **Phase 7**: Search UI with character-level highlighting and match navigation\n- **Phase 8**: Storybook documentation, 11 themes, interactive demo\n\n**Tests**: All passing ✅  \n**TypeScript**: Strict mode enabled ✅\n\n### 🚧 Future Enhancements\n\n- **Collaborative Annotations**: Add notes, findings, and questions to specific lines\n- **Export Functionality**: Save terminal output to file\n- **Line Numbers**: Toggle line number display\n\n## Showcase & Demo\n\nThe project includes a fully interactive demo showcasing all features:\n\n```bash\n# Start the development server\nnpm run dev\n\n# In another terminal, start the WebSocket mock server (optional)\nnpm run mock-server\n```\n\nThe demo includes:\n- **Interactive Command Generator**: Generate realistic pentest commands (nmap, nikto, sqlmap, dirb, etc.)\n- **WebSocket Toggle**: Switch between local generation and WebSocket server\n- **Real-time Stats**: Commands generated, lines added, generation rate\n- **Speed Control**: Adjustable generation speed (500-3000ms)\n- **Scenario Selector**: Choose from different command scenarios\n- **Search Highlighting**: Try searching for \"port\", \"scan\", or any term\n- **Theme Switcher**: Switch between 11 beautiful themes\n- **Keyboard Shortcuts**: Use Ctrl+F to search, Ctrl+L to clear\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run dev server\nnpm run dev\n\n# Run WebSocket mock server (for testing WebSocket features)\nnpm run mock-server\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm test -- --watch\n\n# Type check\nnpm run typecheck\n\n# Build for production\nnpm run build\n\n# Storybook (component documentation)\nnpm run storybook\n```\n\n## Performance\n\n- Handles **100,000+ lines** smoothly at 60fps\n- **Virtual scrolling** with react-window\n- **O(1)** buffer operations with circular buffer\n- **Debounced search** (150ms) for responsiveness\n- **Memoized components** to prevent unnecessary re-renders\n- **Character-level search highlighting** with efficient segment splitting\n- **WebSocket auto-reconnect** with exponential backoff\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! This is a work in progress.\n\n---\n\nBuilt with ❤️ for pentesting and security operations.\n","readmeFilename":"README.md","_rev":"1-e2ab71503203c232599f63b3d57b49c8"}