{"_id":"@ank1015/agents-tui","_rev":"3-8f5f4b7a3b818c4ac657850e295b8d80","name":"@ank1015/agents-tui","dist-tags":{"latest":"0.0.22"},"versions":{"0.0.2":{"name":"@ank1015/agents-tui","version":"0.0.2","keywords":["tui","terminal","cli","ui","terminal-ui","differential-rendering","interactive"],"author":{"name":"ank1015"},"license":"MIT","_id":"@ank1015/agents-tui@0.0.2","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"homepage":"https://github.com/ank1015/agents-tui#readme","bugs":{"url":"https://github.com/ank1015/agents-tui/issues"},"dist":{"shasum":"6d4cbe2949cfcd07f55b891d5e9ff5d5a203736d","tarball":"https://registry.npmjs.org/@ank1015/agents-tui/-/agents-tui-0.0.2.tgz","fileCount":71,"integrity":"sha512-ZZG7xYJN5w7pqegg0FSJtBCDdodfLOeOQva6mTNQYhChhZNfDSxyOJLIUbCPcMl8AXPDPrquOALVzELYl0B9/Q==","signatures":[{"sig":"MEUCIQDxP7AF+obmgCVn3bPRcAYyBxpvXd238VbqxFgliiELogIgBZx72NQKiaDw/jXryYcPcNJMSBegQNzD2GhLB4U1Vts=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":378133},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"e34ec97e9252325a1bec98ebc69a385857710ddd","scripts":{"dev":"tsc --watch","test":"vitest --run","build":"tsc","check":"biome check --write . && tsc --noEmit","clean":"rm -rf dist","start":"node dist/index.js"},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"repository":{"url":"git+https://github.com/ank1015/agents-tui.git","type":"git"},"_npmVersion":"11.5.1","description":"Terminal User Interface library with differential rendering","directories":{},"_nodeVersion":"24.6.0","dependencies":{"chalk":"^5.5.0","marked":"^15.0.12","mime-types":"^3.0.1","@xterm/xterm":"^5.5.0","string-width":"^8.1.0","@xterm/headless":"^5.5.0","@types/mime-types":"^2.1.4"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.14","@types/node":"^25.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agents-tui_0.0.2_1766575827925_0.1940754954947339","host":"s3://npm-registry-packages-npm-production"}},"0.0.21":{"name":"@ank1015/agents-tui","version":"0.0.21","keywords":["tui","terminal","cli","ui","terminal-ui","differential-rendering","interactive"],"author":{"name":"ank1015"},"license":"MIT","_id":"@ank1015/agents-tui@0.0.21","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"homepage":"https://github.com/ank1015/agents-tui#readme","bugs":{"url":"https://github.com/ank1015/agents-tui/issues"},"dist":{"shasum":"0d3919d9b9463dac8adda1db19a744cfa16fc02f","tarball":"https://registry.npmjs.org/@ank1015/agents-tui/-/agents-tui-0.0.21.tgz","fileCount":71,"integrity":"sha512-DXk69zn6pSBWFWwM9gUR1/kHX+yROOPUSEVwfZVwJiuKQYWbXNs86sX5cWC4wBYVEG8+foHetVVVxlmRmr+dgQ==","signatures":[{"sig":"MEUCIEcXociIfnCGdFMAy2k8JWc6nFPlhEHww3OQGd2GkNEvAiEA2u2wZe2Yav8phkkj3x1fkyFwgkL9pbzWXY5PZ0uc/bw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":378959},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"3f466cf13572acd32891dffca667cee2966316ff","scripts":{"dev":"tsc --watch","test":"vitest --run","build":"tsc","check":"biome check --write . && tsc --noEmit","clean":"rm -rf dist","start":"node dist/index.js"},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"repository":{"url":"git+https://github.com/ank1015/agents-tui.git","type":"git"},"_npmVersion":"11.5.1","description":"Terminal User Interface library with differential rendering","directories":{},"_nodeVersion":"24.6.0","dependencies":{"chalk":"^5.5.0","marked":"^15.0.12","mime-types":"^3.0.1","@xterm/xterm":"^5.5.0","string-width":"^8.1.0","@xterm/headless":"^5.5.0","@types/mime-types":"^2.1.4"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.14","@types/node":"^25.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agents-tui_0.0.21_1766660900862_0.014046392840622257","host":"s3://npm-registry-packages-npm-production"}},"0.0.22":{"name":"@ank1015/agents-tui","version":"0.0.22","description":"Terminal User Interface library with differential rendering","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","clean":"rm -rf dist","check":"biome check --write . && tsc --noEmit","test":"vitest --run"},"keywords":["tui","terminal","cli","ui","terminal-ui","differential-rendering","interactive"],"repository":{"type":"git","url":"git+https://github.com/ank1015/agents-tui.git"},"bugs":{"url":"https://github.com/ank1015/agents-tui/issues"},"homepage":"https://github.com/ank1015/agents-tui#readme","author":{"name":"ank1015"},"license":"MIT","dependencies":{"@types/mime-types":"^2.1.4","@xterm/headless":"^5.5.0","chalk":"^5.5.0","marked":"^15.0.12","mime-types":"^3.0.1","string-width":"^8.1.0","@xterm/xterm":"^5.5.0"},"devDependencies":{"@types/node":"^25.0.0","vitest":"^4.0.14"},"gitHead":"fc2314ef1b3f332a67eeae8e077797a264c24bc3","_id":"@ank1015/agents-tui@0.0.22","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-sby77IMVZZ7HlestdRMDA5ygP8YTDwIdyolq/6DrLjusamdBarbwPYUaK/J7EUD9obU45Gl1AKsuO4eW1jw3SA==","shasum":"5802d03d87561971fa7bc5928f4ed7c6536c61bb","tarball":"https://registry.npmjs.org/@ank1015/agents-tui/-/agents-tui-0.0.22.tgz","fileCount":83,"unpackedSize":452770,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC5FMOjUBpcTMPoRXD6OvVnspDKEItEEKjE2QUN+4GxzgIhAIm9/+G7br2w6ffdX26PAvLesHfpb1HjvSJW4wS1VisP"}]},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"directories":{},"maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agents-tui_0.0.22_1768211836479_0.2138317680849955"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-24T11:30:27.839Z","modified":"2026-01-12T09:57:16.821Z","0.0.2":"2025-12-24T11:30:28.076Z","0.0.21":"2025-12-25T11:08:21.007Z","0.0.22":"2026-01-12T09:57:16.607Z"},"bugs":{"url":"https://github.com/ank1015/agents-tui/issues"},"author":{"name":"ank1015"},"license":"MIT","homepage":"https://github.com/ank1015/agents-tui#readme","keywords":["tui","terminal","cli","ui","terminal-ui","differential-rendering","interactive"],"repository":{"type":"git","url":"git+https://github.com/ank1015/agents-tui.git"},"description":"Terminal User Interface library with differential rendering","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"readme":"# @ank1015/agents-tui\n\nMinimal terminal UI framework with differential rendering and synchronized output for flicker-free interactive CLI applications. Inspired by @mariozechner/pi-tui\n\n## Features\n\n- **Differential Rendering**: Three-strategy rendering system that only updates what changed\n- **Synchronized Output**: Uses CSI 2026 for atomic screen updates (no flicker)\n- **Bracketed Paste Mode**: Handles large pastes correctly with markers for >10 line pastes\n- **Component-based**: Simple Component interface with render() method\n- **Built-in Components**: Text, Input, Editor, Markdown, Loader, SelectList, Spacer\n- **Autocomplete Support**: File paths and slash commands\n\n## Quick Start\n\n```typescript\nimport { TUI, Text, Editor, ProcessTerminal } from \"@ank1015/agents-tui\";\n\n// Create terminal\nconst terminal = new ProcessTerminal();\n\n// Create TUI\nconst tui = new TUI(terminal);\n\n// Add components\ntui.addChild(new Text(\"Welcome to my app!\"));\n\nconst editor = new Editor();\neditor.onSubmit = (text) => {\n\tconsole.log(\"Submitted:\", text);\n\ttui.addChild(new Text(`You said: ${text}`));\n};\ntui.addChild(editor);\n\n// Start\ntui.start();\n```\n\n## Core API\n\n### TUI\n\nMain container that manages components and rendering.\n\n```typescript\nconst tui = new TUI(terminal);\ntui.addChild(component);\ntui.removeChild(component);\ntui.start();\ntui.stop();\ntui.requestRender(); // Request a re-render\n```\n\n### Component Interface\n\nAll components implement:\n\n```typescript\ninterface Component {\n\trender(width: number): string[];\n\thandleInput?(data: string): void;\n}\n```\n\n## Built-in Components\n\n### Container\n\nGroups child components.\n\n```typescript\nconst container = new Container();\ncontainer.addChild(component);\ncontainer.removeChild(component);\n```\n\n### Text\n\nDisplays multi-line text with word wrapping and padding.\n\n```typescript\nconst text = new Text(\"Hello World\", paddingX, paddingY); // defaults: 1, 1\ntext.setText(\"Updated text\");\n```\n\n### Input\n\nSingle-line text input with horizontal scrolling.\n\n```typescript\nconst input = new Input();\ninput.onSubmit = (value) => console.log(value);\ninput.setValue(\"initial\");\n```\n\n**Key Bindings:**\n- `Enter` - Submit\n- `Ctrl+A` / `Ctrl+E` - Line start/end\n- `Ctrl+W` or `Option+Backspace` - Delete word backwards\n- `Ctrl+U` - Delete to start of line\n- `Ctrl+K` - Delete to end of line\n- Arrow keys, Backspace, Delete work as expected\n\n### Editor\n\nMulti-line text editor with autocomplete, file completion, and paste handling.\n\n```typescript\nconst editor = new Editor();\neditor.onSubmit = (text) => console.log(text);\neditor.onChange = (text) => console.log(\"Changed:\", text);\neditor.disableSubmit = true; // Disable submit temporarily\neditor.setAutocompleteProvider(provider);\n```\n\n**Features:**\n- Multi-line editing with word wrap\n- Slash command autocomplete (type `/`)\n- File path autocomplete (press `Tab`)\n- Large paste handling (>10 lines creates `[paste #1 +50 lines]` marker)\n- Horizontal lines above/below editor\n- Fake cursor rendering (hidden real cursor)\n\n**Key Bindings:**\n- `Enter` - Submit\n- `Shift+Enter`, `Ctrl+Enter`, or `Alt+Enter` - New line (terminal-dependent, Alt+Enter most reliable)\n- `Tab` - Autocomplete\n- `Ctrl+K` - Delete line\n- `Ctrl+A` / `Ctrl+E` - Line start/end\n- Arrow keys, Backspace, Delete work as expected\n\n### Markdown\n\nRenders markdown with syntax highlighting and optional background colors.\n\n```typescript\nconst md = new Markdown(\n\t\"# Hello\\n\\nSome **bold** text\",\n\tbgColor,           // optional: \"bgRed\", \"bgBlue\", etc.\n\tfgColor,           // optional: \"white\", \"cyan\", etc.\n\tcustomBgRgb,       // optional: { r: 52, g: 53, b: 65 }\n\tpaddingX,          // optional: default 1\n\tpaddingY           // optional: default 1\n);\nmd.setText(\"Updated markdown\");\n```\n\n**Features:**\n- Headings, bold, italic, code blocks, lists, links, blockquotes\n- Syntax highlighting with chalk\n- Optional background colors (including custom RGB)\n- Padding support\n- Render caching for performance\n\n### Loader\n\nAnimated loading spinner.\n\n```typescript\nconst loader = new Loader(tui, \"Loading...\");\nloader.start();\nloader.stop();\n```\n\n### SelectList\n\nInteractive selection list with keyboard navigation.\n\n```typescript\nconst list = new SelectList([\n\t{ value: \"opt1\", label: \"Option 1\", description: \"First option\" },\n\t{ value: \"opt2\", label: \"Option 2\", description: \"Second option\" },\n], 5); // maxVisible\n\nlist.onSelect = (item) => console.log(\"Selected:\", item);\nlist.onCancel = () => console.log(\"Cancelled\");\nlist.setFilter(\"opt\"); // Filter items\n```\n\n**Controls:**\n- Arrow keys: Navigate\n- Enter or Tab: Select\n- Escape: Cancel\n\n### Spacer\n\nEmpty lines for vertical spacing.\n\n```typescript\nconst spacer = new Spacer(2); // 2 empty lines (default: 1)\n```\n\n## Autocomplete\n\n### CombinedAutocompleteProvider\n\nSupports both slash commands and file paths.\n\n```typescript\nimport { CombinedAutocompleteProvider } from \"@ank1015/agents-tui\";\n\nconst provider = new CombinedAutocompleteProvider(\n\t[\n\t\t{ name: \"help\", description: \"Show help\" },\n\t\t{ name: \"clear\", description: \"Clear screen\" },\n\t\t{ name: \"delete\", description: \"Delete last message\" },\n\t],\n\tprocess.cwd() // base path for file completion\n);\n\neditor.setAutocompleteProvider(provider);\n```\n\n**Features:**\n- Type `/` to see slash commands\n- Press `Tab` for file path completion\n- Works with `~/`, `./`, `../`, and `@` prefix\n- Filters to attachable files for `@` prefix\n\n## Differential Rendering\n\nThe TUI uses three rendering strategies:\n\n1. **First Render**: Output all lines without clearing scrollback\n2. **Width Changed or Change Above Viewport**: Clear screen and full re-render\n3. **Normal Update**: Move cursor to first changed line, clear to end, render changed lines\n\nAll updates are wrapped in **synchronized output** (`\\x1b[?2026h` ... `\\x1b[?2026l`) for atomic, flicker-free rendering.\n\n## Terminal Interface\n\nThe TUI works with any object implementing the `Terminal` interface:\n\n```typescript\ninterface Terminal {\n\tstart(onInput: (data: string) => void, onResize: () => void): void;\n\tstop(): void;\n\twrite(data: string): void;\n\tget columns(): number;\n\tget rows(): number;\n\tmoveBy(lines: number): void;\n\thideCursor(): void;\n\tshowCursor(): void;\n\tclearLine(): void;\n\tclearFromCursor(): void;\n\tclearScreen(): void;\n}\n```\n\n**Built-in implementations:**\n- `ProcessTerminal` - Uses `process.stdin/stdout`\n- `VirtualTerminal` - For testing (uses `@xterm/headless`)\n\n## Example\n\nSee `test/chat-simple.ts` for a complete chat interface example with:\n- Markdown messages with custom background colors\n- Loading spinner during responses\n- Editor with autocomplete and slash commands\n- Spacers between messages\n\nRun it:\n```bash\nnpx tsx test/chat-simple.ts\n```\n\n## Development\n\n```bash\n# Install dependencies (from monorepo root)\nnpm install\n\n# Run type checking\nnpm run check\n\n# Run the demo\nnpx tsx test/chat-simple.ts\n```\n","readmeFilename":"README.md"}