vt100.js 0.1.0 → 0.1.2

package/README.md

@@ -2,29 +2,22 @@
 
 Pure TypeScript VT100 terminal emulator. Zero dependencies, headless, fast.
 
+Part of the [vterm](https://github.com/beorn/vterm) monorepo.
+
 ## Features
 
-- Full VT100/ANSI escape sequence parsing
-- SGR attributes (bold, italic, underline, colors, etc.)
-- 16-color, 256-color, and 24-bit truecolor support
-- Cursor movement, save/restore (DECSC/DECRC)
-- Screen modes (alternate screen, auto-wrap, origin mode, etc.)
+- Strict DEC VT100 (1978) emulation — monochrome display
+- SGR attributes: bold, underline (boolean), blink, inverse
+- Cursor movement (CUP, CUU, CUD, CUF, CUB, CHA, CNL, CPL, HVP, VPA)
+- Cursor save/restore (DECSC/DECRC)
+- Erase display/line (ED/EL)
 - Scroll regions (DECSTBM) with content preservation
+- Scroll up/down (SU/SD)
 - Scrollback buffer with configurable limit
-- Insert/delete characters and lines
-- Wide character support (CJK, emoji)
-- Zero dependencies -- works in Bun, Node.js, and browsers
-
-## Comparison
-
-| Package | Screen State | SGR Colors | Scrollback | Wide Chars | Zero Deps | Size |
-|---------|:---:|:---:|:---:|:---:|:---:|:---:|
-| **vt100.js** | yes | 16/256/true | yes | yes | yes | ~30KB |
-| `@xterm/headless` | yes | 16/256/true | yes | yes | no | ~500KB |
-| `node-pty` + xterm | yes | 16/256/true | yes | yes | no | native build |
-| `ansi-parser` | no | parse only | no | no | yes | ~5KB |
-| `terminal-kit` | yes | 16/256/true | no | partial | no | ~2MB |
-| `blessed` / `neo-blessed` | yes | 16/256 | no | no | no | ~1MB |
+- Screen modes (auto-wrap, origin mode, cursor visibility)
+- DEC special graphics charset
+- DA1/DSR/CPR device responses
+- Zero dependencies — works in Bun, Node.js, and browsers
 
 ## Install
 
@@ -40,91 +33,60 @@ import { createVt100Screen } from "vt100.js"
 const screen = createVt100Screen({ cols: 80, rows: 24 })
 screen.process(new TextEncoder().encode("Hello, \x1b[1mBold\x1b[0m World!"))
 
-// Read cell state
-const cell = screen.getCell(0, 0)
-console.log(cell.char)  // "H"
-
-// Read text
-console.log(screen.getText())  // "Hello, Bold World!"
-
-// Check cursor position
-const pos = screen.getCursorPosition()
-console.log(pos)  // { x: 18, y: 0 }
+console.log(screen.getText()) // "Hello, Bold World!"
+console.log(screen.getCell(0, 7).bold) // true
+console.log(screen.getCursorPosition()) // { x: 18, y: 0 }
 ```
 
 ## API
 
 ### `createVt100Screen(options)`
 
-Create a new screen instance.
-
-```typescript
-const screen = createVt100Screen({
-  cols: 80,          // terminal width
-  rows: 24,          // terminal height
-  scrollbackLimit: 1000  // max scrollback lines (default: 1000)
-})
-```
+| Option            | Type     | Default  | Description          |
+| ----------------- | -------- | -------- | -------------------- |
+| `cols`            | `number` | required | Terminal width       |
+| `rows`            | `number` | required | Terminal height      |
+| `scrollbackLimit` | `number` | `1000`   | Max scrollback lines |
 
 ### Screen methods
 
-| Method | Description |
-|--------|-------------|
-| `process(data: Uint8Array)` | Feed raw terminal data |
-| `getText()` | Get all text (scrollback + screen) |
-| `getTextRange(startRow, startCol, endRow, endCol)` | Get text in a range |
-| `getLine(row)` | Get cells for a row |
-| `getCell(row, col)` | Get a single cell (char, fg, bg, bold, etc.) |
-| `getCursorPosition()` | Get cursor `{ x, y }` |
-| `getCursorVisible()` | Check cursor visibility |
-| `getMode(mode)` | Check terminal mode (`altScreen`, `bracketedPaste`, etc.) |
-| `getTitle()` | Get window title (set via OSC 0/2) |
-| `getScrollbackLength()` | Number of scrollback lines |
-| `getViewportOffset()` | Current viewport scroll offset |
-| `scrollViewport(delta)` | Scroll viewport by delta lines |
-| `resize(cols, rows)` | Resize the terminal |
-| `reset()` | Reset to initial state |
+| Method                         | Description                        |
+| ------------------------------ | ---------------------------------- |
+| `process(data: Uint8Array)`    | Feed raw terminal data             |
+| `getText()`                    | Get all text (scrollback + screen) |
+| `getTextRange(sr, sc, er, ec)` | Get text in a range                |
+| `getLine(row)`                 | Get cells for a row                |
+| `getCell(row, col)`            | Get a single cell                  |
+| `getCursorPosition()`          | Get cursor `{ x, y }`              |
+| `getCursorVisible()`           | Check cursor visibility            |
+| `getMode(mode)`                | Check terminal mode                |
+| `getTitle()`                   | Get window title                   |
+| `getScrollbackLength()`        | Number of scrollback lines         |
+| `getViewportOffset()`          | Current viewport scroll offset     |
+| `scrollViewport(delta)`        | Scroll viewport                    |
+| `resize(cols, rows)`           | Resize terminal                    |
+| `reset()`                      | Reset to initial state             |
 
 ### Cell properties
 
 ```typescript
 interface ScreenCell {
-  char: string           // character content
-  fg: CellColor | null   // foreground color { r, g, b }
-  bg: CellColor | null   // background color { r, g, b }
+  char: string
+  fg: CellColor | null // always null (VT100 is monochrome)
+  bg: CellColor | null // always null (VT100 is monochrome)
   bold: boolean
-  faint: boolean
-  italic: boolean
-  underline: UnderlineStyle  // "none" | "single" | "double" | "curly" | "dotted" | "dashed"
-  strikethrough: boolean
+  underline: boolean
+  blink: boolean
   inverse: boolean
   hidden: boolean
-  wide: boolean          // true for CJK/emoji double-width chars
 }
 ```
 
-### Terminal modes
-
-Queryable via `screen.getMode(mode)`:
-
-- `altScreen` -- alternate screen buffer
-- `bracketedPaste` -- bracketed paste mode
-- `mouseTracking` -- mouse tracking
-- `autoWrap` -- auto-wrap at right margin (default: on)
-- `applicationCursor` -- application cursor keys
-- `applicationKeypad` -- application keypad mode
-- `originMode` -- origin mode
-- `insertMode` -- insert mode
-- `reverseVideo` -- reverse video
-- `focusTracking` -- focus tracking
-- `cursorVisible` -- cursor visibility
-
-## Ecosystem
+## See also
 
-- [Termless](https://termless.dev) -- headless terminal testing (uses vt100.js as its default backend)
-- [Terminfo.dev](https://terminfo.dev) -- terminal feature support tables
-- [Silvery](https://silvery.dev) -- React TUI framework
-- [@termless/vt100](https://github.com/beorn/termless) -- Termless backend wrapper for vt100.js
+- [vterm.js](../vterm/) — full-featured modern emulator (100% terminfo.dev coverage)
+- [Termless](https://termless.dev) — headless terminal testing
+- [Terminfo.dev](https://terminfo.dev) — terminal feature support tables
 
 ## License
 

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+//#region src/screen.d.ts
+/**
+ * Pure TypeScript VT100 terminal emulator.
+ *
+ * Strict DEC VT100 (1978) implementation: monochrome display, cursor movement,
+ * scroll regions, auto-wrap, origin mode, DEC special graphics charset.
+ * SGR supports bold, underline, blink, and reverse — NO colors (VT100 is
+ * monochrome). No insert mode, no insert/delete chars/lines — those are
+ * VT102/VT220 features.
+ *
+ * Zero dependencies. For colors and VT220 features, use vt220.js.
+ * For truecolor, 256 colors, and wide chars, use vterm.js.
+ */
+interface CellColor {
+  r: number;
+  g: number;
+  b: number;
+}
+interface ScreenCell {
+  char: string;
+  fg: CellColor | null;
+  bg: CellColor | null;
+  bold: boolean;
+  underline: boolean;
+  blink: boolean;
+  inverse: boolean;
+  hidden: boolean;
+}
+interface ScreenOptions {
+  cols: number;
+  rows: number;
+  scrollbackLimit?: number;
+  /** Callback for DA1/DSR responses — write these back to the PTY */
+  onResponse?: (data: string) => void;
+}
+interface Screen {
+  readonly cols: number;
+  readonly rows: number;
+  process(data: Uint8Array): void;
+  resize(cols: number, rows: number): void;
+  reset(): void;
+  getCell(row: number, col: number): ScreenCell;
+  getLine(row: number): ScreenCell[];
+  getText(): string;
+  getTextRange(startRow: number, startCol: number, endRow: number, endCol: number): string;
+  getCursorPosition(): {
+    x: number;
+    y: number;
+  };
+  getCursorVisible(): boolean;
+  getTitle(): string;
+  getMode(mode: string): boolean;
+  getScrollbackLength(): number;
+  getViewportOffset(): number;
+  scrollViewport(delta: number): void;
+}
+declare function createScreen(opts: ScreenOptions): Screen;
+//#endregion
+export { type CellColor, type ScreenCell, type Screen as Vt100Screen, type ScreenOptions as Vt100ScreenOptions, createScreen as createVt100Screen };