implement screen buffer

- Add ScreenBuffer class with full VT100 support
- Wide character support (CJK, emoji, combining chars)
- Scroll regions (DECSTBM) for vim-like apps
- Terminal modes (origin, insert, autowrap)
- 63 comprehensive tests, all passing (163 assertions)
- Interactive demo for visual testing
- xterm.js-compatible API
- Update AGENTS.md with Task 2 completion and testing guide

Author: sreya

AGENTS.md

@@ -6,23 +6,34 @@ This repository integrates **libghostty-vt** (Ghostty's VT100 parser) with WebAs
 
 ### What's Implemented
 
-**TypeScript Wrapper (618 lines)**
+**Task 1: TypeScript Wrapper (618 lines)** ✅
 - `lib/types.ts` - Type definitions for libghostty-vt C API
 - `lib/ghostty.ts` - `Ghostty`, `SgrParser`, `KeyEncoder` classes
 - Automatic memory management for WASM pointers
-
-**Demo**
-- `examples/sgr-demo.html` - Interactive SGR parser demo
+- Demo: `examples/sgr-demo.html` - Interactive SGR parser demo
+
+**Task 2: Screen Buffer (1,704 lines)** ✅
+- `lib/buffer.ts` - ScreenBuffer class (840 lines)
+  - 2D grid with cursor management
+  - Wide character support (CJK, emoji, combining chars)
+  - Scroll regions (DECSTBM) for vim-like apps
+  - Terminal modes (origin, insert, autowrap)
+  - Scrollback buffer with size limits
+  - xterm.js-compatible API
+- `lib/buffer.test.ts` - 63 comprehensive tests (864 lines)
+  - All passing, 163 assertions
+  - Covers all features and edge cases
+- Demo: `examples/buffer-demo.html` - Interactive buffer testing
 
 ### What's Missing (Your Job)
 
-**Terminal Implementation** - The screen buffer, rendering, and state machine:
-1. Screen buffer (2D array of cells)
+**Terminal Implementation** - Rendering and state machine:
+1. ~~Screen buffer (2D array of cells)~~ ✅ **DONE (Task 2)**
 2. Canvas renderer (draw cells with colors)
 3. VT100 state machine (parse escape sequences, use Ghostty parsers)
 4. Keyboard input handler (use KeyEncoder)
 5. PTY connection (IPC to backend)
-6. Scrollback buffer
+6. ~~Scrollback buffer~~ ✅ **DONE (Task 2)**
 7. Selection/clipboard
 
 ## Building the WASM
@@ -81,7 +92,79 @@ python3 -m http.server 8000
 └──────────────────────────────────────────┘
 ```
 
-## Using the Ghostty API
+## Using the APIs
+
+### ScreenBuffer API (Task 2)
+
+```typescript
+import { ScreenBuffer } from './lib/buffer.ts';
+
+// Create buffer
+const buffer = new ScreenBuffer(80, 24, 1000);
+
+// Write text
+buffer.writeString('Hello, World!');
+buffer.getCursor(); // {x: 13, y: 0, visible: true}
+
+// Wide characters (CJK, emoji)
+buffer.writeChar('中'); // Takes 2 cells
+buffer.getCursor(); // {x: 15, y: 0, ...} - advanced by 2!
+
+// Cursor movement
+buffer.moveCursorTo(10, 5);
+buffer.moveCursorUp(2);
+buffer.saveCursor();
+buffer.restoreCursor();
+
+// Styling
+buffer.setStyle({ 
+  bold: true, 
+  fg: { type: 'palette', index: 1 } // Red
+});
+buffer.writeString('Bold red text');
+buffer.resetStyle();
+
+// Scroll regions (for vim-like apps)
+buffer.setScrollRegion(5, 20); // Lines 5-20 scroll
+buffer.setOriginMode(true);    // Cursor relative to region
+buffer.moveCursorTo(0, 0);     // Goes to line 5 (region top)
+
+// Scrolling
+buffer.scrollUp(1);   // Scroll up 1 line
+buffer.index();       // Move down, scroll if at bottom
+buffer.reverseIndex(); // Move up, scroll if at top
+
+// Erasing
+buffer.eraseInLine(2);    // Clear entire line
+buffer.eraseInDisplay(2); // Clear entire screen
+
+// Line operations
+buffer.insertLines(2);  // Insert 2 blank lines
+buffer.deleteLines(1);  // Delete current line
+
+// Modes
+buffer.setAutoWrap(false); // Disable wrapping
+buffer.setInsertMode(true); // Insert vs replace
+
+// Access data (returns copies)
+const line = buffer.getLine(0);
+const allLines = buffer.getAllLines();
+const scrollback = buffer.getScrollback();
+
+// Dirty tracking for efficient rendering
+if (buffer.isDirty(5)) {
+  renderLine(5);
+}
+buffer.clearDirty();
+
+// xterm.js-compatible properties
+buffer.cursorX;   // Same as getCursor().x
+buffer.cursorY;   // Same as getCursor().y
+buffer.baseY;     // Scrollback length
+buffer.length;    // Total lines (scrollback + rows)
+```
+
+### Ghostty SGR Parser API (Task 1)
 
 ### Parse SGR (Colors/Styles)
 
@@ -307,8 +390,84 @@ console.log(bytes); // Uint8Array([1])
 
 **Estimated time**: 2-4 weeks for MVP terminal
 
+## Testing & Development
+
+### Running Tests
+
+**Run automated tests:**
+```bash
+bun test                    # Run all tests
+bun test lib/buffer.test.ts # Run specific test file
+bun test --watch            # Watch mode
+```
+
+**TypeScript type checking:**
+```bash
+bun run typecheck          # Check types without compiling
+```
+
+### Running Demos
+
+**⚠️ IMPORTANT: Use Vite, not basic HTTP server!**
+
+```bash
+# ✅ CORRECT - Use Vite for TypeScript imports
+bun run dev
+
+# ❌ WRONG - Basic HTTP server can't handle TypeScript
+python3 -m http.server 8000
+```
+
+Then open:
+- Buffer Demo: `http://localhost:8000/examples/buffer-demo.html`
+- SGR Demo: `http://localhost:8000/examples/sgr-demo.html`
+
+### Demo Testing Tips
+
+**Task 2: Screen Buffer Demo**
+
+When testing `buffer-demo.html`:
+
+1. **Check status banner** at top:
+   - ✅ Green "Ready!" = Success
+   - ❌ Red "Error!" = Check console
+
+2. **Open browser console (F12)** to see:
+   ```
+   ✅ ScreenBuffer loaded successfully
+   ✅ Buffer instance created
+   ✅ Buffer demo loaded successfully!
+   ```
+
+3. **Click test scenario buttons** and watch console:
+   ```
+   🧪 Running Test 1: Basic Writing
+   ✅ Test 1 complete
+   ```
+
+4. **Visual checks:**
+   - Blinking green cursor should be visible
+   - Stats update: cursor position, scrollback count
+   - Terminal content appears when clicking buttons
+
+5. **Manual testing in console:**
+   ```javascript
+   // Test buffer API directly
+   buffer.writeString('Hello!')
+   buffer.getCursor()           // {x: 6, y: 0, ...}
+   buffer.writeChar('中')       // Wide char
+   buffer.getCursor()           // x increased by 2!
+   renderBuffer()              // Update display
+   ```
+
+**Critical tests:**
+- **Test 3 (Wide Chars)**: Chinese 中文 should be visibly WIDER than ABC
+- **Test 4 (Scroll Region)**: Headers/footers stay fixed while middle scrolls
+
 ## Troubleshooting
 
+### Build/WASM Issues
+
 **WASM not loading?**
 - Check file exists: `ls -lh ghostty-vt.wasm`
 - Check browser console for fetch errors
@@ -323,3 +482,74 @@ console.log(bytes); // Uint8Array([1])
 - Check WASM exports: `wasm-objdump -x ghostty-vt.wasm | grep export`
 - Check browser console for errors
 - Test with demo: `http://localhost:8000/examples/sgr-demo.html`
+
+### Demo Issues
+
+**"Nothing is rendering in the terminal"**
+- ❌ Using basic HTTP server → **Use `bun run dev` instead!**
+- Refresh browser (Ctrl+Shift+R)
+- Check console for import errors
+- Verify status banner is green
+
+**"Buttons don't work"**
+- Check console (F12) for JavaScript errors
+- Try manual test: `testBasicWriting()` in console
+- Verify functions exist: `window.testBasicWriting` should be `function`
+
+**"Wide characters look wrong"**
+- This is expected with basic HTML rendering
+- Verify in console: cursor advances by 2 for wide chars
+- Proper rendering comes in Task 4 (Canvas Renderer)
+
+**Module import errors**
+- Must use Vite dev server: `bun run dev`
+- Don't use: `python3 -m http.server` or `./run-demo.sh` without Vite
+- Check `package.json` scripts are correct
+
+### Test Failures
+
+**If tests fail:**
+```bash
+# Run specific test file with verbose output
+bun test lib/buffer.test.ts
+
+# Check TypeScript compilation
+bun run typecheck
+
+# Run single test
+bun test -t "test name pattern"
+```
+
+**Common test issues:**
+- Import errors → Check file paths
+- Type errors → Run `bun run typecheck`
+- Assertion failures → Check implementation logic
+
+### Development Workflow
+
+**Best practices for agents:**
+
+1. **Always run tests after changes:**
+   ```bash
+   bun test lib/buffer.test.ts
+   ```
+
+2. **Type check before committing:**
+   ```bash
+   bun run typecheck
+   ```
+
+3. **Test in browser:**
+   ```bash
+   bun run dev
+   # Open http://localhost:8000/examples/buffer-demo.html
+   ```
+
+4. **Debug in console:**
+   - Use `console.log()` liberally
+   - Check browser console (F12) for errors
+   - Test APIs directly: `buffer.writeChar('A')`
+
+5. **Iterate quickly:**
+   - Vite has hot reload - save file, browser auto-updates
+   - Keep console open to catch errors immediately