retroterm 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# retroterm
+
+Terminal-based retro game launcher. A blessed TUI frontend for [retroemu](https://github.com/monteslu/retroemu).
+
+- **ROM browser** — Scans your ROMs directory and organizes by system
+- **Recent games** — Quick access to recently played games
+- **Keyboard navigation** — vim-style controls
+- **Preferences** — Configurable ROMs and saves directories
+
+```
+retroterm
+```
+
+## Installation
+
+```bash
+npm install -g retroterm
+```
+
+This will also install `retroemu` as a dependency.
+
+## Usage
+
+Just run `retroterm` to launch the browser:
+
+```bash
+retroterm
+```
+
+On first run, press `S` to configure your ROMs directory.
+
+### Controls
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Launch selected game |
+| `j` / `k` or arrows | Navigate list |
+| `A` | Show all ROMs |
+| `R` | Show recent games |
+| `S` | Settings |
+| `F5` | Refresh ROM list |
+| `Q` | Quit |
+
+## Configuration
+
+Settings are stored in `~/.config/retroterm/config.json`:
+
+```json
+{
+  "romsDir": "/home/user/roms",
+  "savesDir": "/home/user/.config/retroterm/saves",
+  "recentGames": [],
+  "maxRecent": 10
+}
+```
+
+## Supported Systems
+
+retroterm supports all systems that retroemu supports:
+
+- **Nintendo** — NES, SNES, Game Boy, Game Boy Color, Game Boy Advance
+- **Sega** — Genesis, Master System, Game Gear, SG-1000
+- **Atari** — 2600, 5200, 7800, 800/XL/XE, Lynx
+- **NEC** — TurboGrafx-16 / PC Engine
+- **SNK** — Neo Geo Pocket, Neo Geo Pocket Color
+- **Bandai** — WonderSwan, WonderSwan Color
+- **Other** — ColecoVision, Vectrex, ZX Spectrum, MSX
+
+## Streaming / Remote Play
+
+retroterm can stream games over the network using a custom binary protocol optimized for terminal output.
+
+### Recommended Settings
+
+| Terminal Size | Virtual Resolution | Bandwidth (30 FPS) |
+|---------------|-------------------|-------------------|
+| 60 rows | 160×120 | ~600 KB/s (4.8 Mbps) |
+| 120 rows | 320×240 (PS1 native) | ~2.3 MB/s (18 Mbps) |
+
+### Render Modes
+
+| Mode | Quality | Bandwidth | Best For |
+|------|---------|-----------|----------|
+| `half-block-256` | Chunky pixels | Lowest | Retro games (default) |
+| `block-256` | Smooth shading | Medium | When detail matters |
+| `ascii-256` | Textured | Medium | Aesthetic preference |
+| `braille` | Dot matrix | Tiny | Monochrome games |
+
+### Custom Binary Protocol
+
+Instead of ANSI escape codes (~15 bytes/cell), use raw color indices:
+
+```
+[fg_index][bg_index][fg_index][bg_index]...  (2 bytes/cell)
+```
+
+Decode on client:
+```javascript
+output += `\x1b[38;5;${data[i]};48;5;${data[i+1]}m▀`;
+```
+
+**10x bandwidth reduction** vs standard ANSI output.
+
+### Architecture Options
+
+**Option A: WebRTC P2P** (current)
+- Best latency, works peer-to-peer
+- Requires signaling server for NAT traversal
+
+**Option B: Simple WebSocket relay**
+- Easier to deploy (single server)
+- Works through all firewalls
+- node-datachannel for optional WebRTC upgrade
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [retroemu](https://github.com/monteslu/retroemu) | Terminal emulator engine with libretro WASM cores |
+| [blessed](https://github.com/chjj/blessed) | Terminal UI library |
+| [chafa-wasm](https://github.com/monteslu/chafa-wasm) | Image-to-ANSI conversion (SIMD-optimized fork) |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { Launcher } from '../src/Launcher.js';
+
+const launcher = new Launcher();
+await launcher.start();

package/index.js

@@ -0,0 +1,3 @@
+export { Launcher } from './src/Launcher.js';
+export { RomScanner } from './src/RomScanner.js';
+export { Preferences } from './src/Preferences.js';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "retroterm",
+  "version": "0.1.0",
+  "description": "Terminal-based retro game launcher with ROM browser and box art",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "retroterm": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "index.js"
+  ],
+  "keywords": [
+    "emulator",
+    "retro",
+    "terminal",
+    "launcher",
+    "nes",
+    "snes",
+    "gameboy",
+    "genesis",
+    "blessed",
+    "tui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/monteslu/retroterm.git"
+  },
+  "author": "Luis Montes",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "@monteslu/chafa-wasm": "^0.4.0",
+    "gamepad-node": "^1.3.1",
+    "hsync": "^0.33.0",
+    "retroemu": "^0.1.1",
+    "sharp": "^0.34.5",
+    "yauzl": "^3.2.0"
+  }
+}

package/src/Launcher.js

@@ -0,0 +1,880 @@
+import blessed from 'blessed';
+import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { installNavigatorShim } from 'gamepad-node';
+import { Preferences } from './Preferences.js';
+import { RomScanner } from './RomScanner.js';
+import initChafa from '@monteslu/chafa-wasm';
+import sharp from 'sharp';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ASSETS_DIR = join(__dirname, '..', 'assets', 'systems');
+
+// Chafa constants
+const CHAFA_SYMBOL_TAG_SPACE = 0x1;
+const CHAFA_SYMBOL_TAG_BLOCK = 0x8;
+const CHAFA_CANVAS_MODE_TRUECOLOR = 0;
+
+export class Launcher {
+  constructor() {
+    this.prefs = new Preferences();
+    this.screen = null;
+    this.romList = null;
+    this.statusBar = null;
+    this.controllerBox = null;
+    this.systemArtBox = null;
+    this.chafa = null;
+    this.roms = [];
+    this.sortedRoms = null;
+    this.systems = []; // Available systems
+    this.systemRoms = {}; // ROMs grouped by system
+    this.currentSystemIndex = 0;
+    this._lastSelected = 0;
+    this.currentView = 'system'; // 'system' or 'recent'
+    this.gamepadManager = null;
+    this.gamepadPollInterval = null;
+    this._settingsOpen = false;
+  }
+
+  async start() {
+    // Initialize chafa for image rendering
+    if (!this.chafa) {
+      this.chafa = await initChafa();
+    }
+
+    // Initialize gamepad support
+    this.gamepadManager = installNavigatorShim();
+
+    this.screen = blessed.screen({
+      smartCSR: true,
+      title: 'retroterm',
+      fullUnicode: true,
+    });
+
+    this._createUI();
+    this._loadRoms();
+    this._setupKeys();
+    this._startControllerPolling();
+
+    this.screen.render();
+  }
+
+  _createUI() {
+    // System logo box (horizontal banner)
+    this.systemArtBox = blessed.box({
+      top: 0,
+      left: 0,
+      width: 40,
+      height: 5,
+      tags: true,
+    });
+
+    // System info (right of logo)
+    this.systemTitle = blessed.box({
+      top: 0,
+      left: 40,
+      width: '100%-40',
+      height: 5,
+      tags: true,
+      padding: { left: 1, top: 1 },
+      content: '{bold}{cyan-fg}RETROTERM{/}',
+    });
+
+    // ROM list
+    this.romList = blessed.list({
+      top: 5,
+      left: 0,
+      width: '50%',
+      bottom: 3,
+      border: { type: 'line' },
+      style: {
+        border: { fg: 'blue' },
+        selected: { bg: 'blue', fg: 'white', bold: true },
+        item: { fg: 'white' },
+      },
+      keys: true,
+      vi: true,
+      mouse: true,
+      scrollbar: {
+        ch: ' ',
+        style: { bg: 'blue' },
+      },
+      tags: true,
+    });
+
+    // Info panel (for game details and eventually cover art)
+    this.infoPanel = blessed.box({
+      top: 0,
+      right: 0,
+      width: '50%',
+      bottom: 8,
+      border: { type: 'line' },
+      style: { border: { fg: 'green' } },
+      tags: true,
+      padding: { left: 1, right: 1 },
+      content: '{gray-fg}Select a game{/}',
+    });
+
+    // Controller status
+    this.controllerBox = blessed.box({
+      right: 0,
+      bottom: 3,
+      width: '50%',
+      height: 5,
+      border: { type: 'line' },
+      style: { border: { fg: 'magenta' } },
+      tags: true,
+      padding: { left: 1, right: 1 },
+      content: '{gray-fg}Scanning controllers...{/}',
+    });
+
+    // Status bar
+    this.statusBar = blessed.box({
+      bottom: 0,
+      left: 0,
+      width: '100%',
+      height: 3,
+      border: { type: 'line' },
+      style: { border: { fg: 'gray' } },
+      tags: true,
+      content: ' {bold}A{/} Play  {bold}←→{/} System  {bold}↑↓{/} Browse  {bold}LB/RB{/} Page  {bold}X{/} Recent  {bold}Y{/} Settings  {bold}Q{/} Quit',
+    });
+
+    this.screen.append(this.systemArtBox);
+    this.screen.append(this.systemTitle);
+    this.screen.append(this.romList);
+    this.screen.append(this.infoPanel);
+    this.screen.append(this.controllerBox);
+    this.screen.append(this.statusBar);
+
+    this.romList.focus();
+
+    // Update info panel on selection
+    this.romList.on('select item', (item, index) => {
+      this._lastSelected = index;
+      this._updateInfoPanel(index);
+    });
+  }
+
+  async _loadRoms() {
+    const romsDir = this.prefs.get('romsDir');
+
+    if (!existsSync(romsDir)) {
+      this.romList.setItems(['{yellow-fg}ROMs directory not found{/}', '', `{gray-fg}${romsDir}{/}`, '', '{white-fg}Press S to configure{/}']);
+      this.roms = [];
+      this.screen.render();
+      return;
+    }
+
+    this.romList.setItems(['{cyan-fg}Scanning ROMs...{/}']);
+    this.screen.render();
+
+    const scanner = new RomScanner(romsDir);
+    this.roms = await scanner.scan();
+
+    if (this.roms.length === 0) {
+      this.romList.setItems(['{yellow-fg}No ROMs found{/}', '', `{gray-fg}${romsDir}{/}`, '', '{white-fg}Press S to configure{/}']);
+    } else {
+      this._groupRomsBySystem();
+      this._showCurrentSystem();
+    }
+
+    this.screen.render();
+  }
+
+  _groupRomsBySystem() {
+    // Group by system, then alphabetize within each group
+    this.systemRoms = {};
+    for (const rom of this.roms) {
+      if (!this.systemRoms[rom.system]) {
+        this.systemRoms[rom.system] = [];
+      }
+      this.systemRoms[rom.system].push(rom);
+    }
+
+    // Sort systems alphabetically, sort ROMs within each system
+    this.systems = Object.keys(this.systemRoms).sort();
+    for (const system of this.systems) {
+      this.systemRoms[system].sort((a, b) => a.name.localeCompare(b.name));
+    }
+  }
+
+  _showCurrentSystem() {
+    this.currentView = 'system';
+
+    if (this.systems.length === 0) return;
+
+    const system = this.systems[this.currentSystemIndex];
+    const roms = this.systemRoms[system];
+    this.sortedRoms = roms;
+
+    const items = roms.map(rom => rom.name);
+    this.romList.setItems(items);
+    this.romList.select(0);
+
+    // Update system title
+    this.systemTitle.setContent(
+      `{bold}{yellow-fg}${system}{/}\n` +
+      `{white-fg}${roms.length} games{/}  {gray-fg}[${this.currentSystemIndex + 1}/${this.systems.length}]{/}`
+    );
+
+    // Render system art (async, will update when done)
+    this._renderSystemArt(system);
+
+    this._updateInfoPanel(0);
+    this.screen.render();
+  }
+
+  async _renderSystemArt(system) {
+    const artPath = join(ASSETS_DIR, `${system}.png`);
+    if (!existsSync(artPath) || !this.chafa) {
+      this.systemArtBox.setContent('');
+      return;
+    }
+
+    try {
+      // Decode image with sharp
+      const { data, info } = await sharp(artPath)
+        .raw()
+        .ensureAlpha()
+        .toBuffer({ resolveWithObject: true });
+
+      const chafa = this.chafa;
+
+      // Set up chafa with block characters
+      const symbolMap = chafa._chafa_symbol_map_new();
+      chafa._chafa_symbol_map_add_by_tags(symbolMap, CHAFA_SYMBOL_TAG_SPACE | CHAFA_SYMBOL_TAG_BLOCK);
+
+      const canvasConfig = chafa._chafa_canvas_config_new();
+      chafa._chafa_canvas_config_set_geometry(canvasConfig, 36, 6); // 3 rows with half-blocks
+      chafa._chafa_canvas_config_set_canvas_mode(canvasConfig, CHAFA_CANVAS_MODE_TRUECOLOR);
+      chafa._chafa_canvas_config_set_symbol_map(canvasConfig, symbolMap);
+
+      const canvas = chafa._chafa_canvas_new(canvasConfig);
+
+      // Copy RGBA data to heap
+      const dataPtr = chafa._malloc(data.length);
+      chafa.HEAPU8.set(data, dataPtr);
+
+      // Set canvas contents
+      chafa._chafa_canvas_set_contents_rgba8(canvas, dataPtr, info.width, info.height, info.width * 4);
+      chafa._free(dataPtr);
+
+      // Get ANSI output
+      const gsPtr = chafa._chafa_canvas_build_ansi(canvas);
+      const strPtr = chafa._g_string_free_and_steal(gsPtr);
+      const ansi = chafa.UTF8ToString(strPtr);
+      chafa._free(strPtr);
+
+      // Cleanup
+      chafa._chafa_canvas_unref(canvas);
+      chafa._chafa_canvas_config_unref(canvasConfig);
+      chafa._chafa_symbol_map_unref(symbolMap);
+
+      // Trim any trailing newlines to prevent clipping
+      this.systemArtBox.setContent(ansi.trimEnd());
+      this.screen.render();
+    } catch (err) {
+      this.systemArtBox.setContent('');
+    }
+  }
+
+  _showRecentRoms() {
+    this.currentView = 'recent';
+    const recent = this.prefs.get('recentGames');
+    const recentRoms = recent
+      .map(path => this.roms.find(r => r.path === path))
+      .filter(r => r);
+
+    this.sortedRoms = recentRoms;
+
+    if (recentRoms.length === 0) {
+      this.romList.setItems(['{gray-fg}No recent games{/}']);
+      this.sortedRoms = [];
+    } else {
+      const items = recentRoms.map(rom => `{cyan-fg}[${rom.system}]{/} ${rom.name}`);
+      this.romList.setItems(items);
+    }
+
+    // Update header for recent view
+    this.systemTitle.setContent(
+      `{bold}{magenta-fg}Recent Games{/}\n` +
+      `{white-fg}${recentRoms.length} games{/}`
+    );
+    this.systemArtBox.setContent('');
+
+    this.romList.select(0);
+    this._updateInfoPanel(0);
+    this.screen.render();
+  }
+
+  _updateInfoPanel(index) {
+    const rom = this._getSelectedRom(index);
+    if (!rom) {
+      this.infoPanel.setContent('{gray-fg}Select a game{/}');
+      this.screen.render();
+      return;
+    }
+
+    const lines = [
+      `{bold}{white-fg}${rom.name}{/}`,
+      '',
+      `{cyan-fg}System:{/} ${rom.system}`,
+      `{cyan-fg}File:{/} ${rom.ext}`,
+    ];
+
+    if (rom.zipEntry) {
+      lines.push(`{cyan-fg}In ZIP:{/} ${rom.zipEntry}`);
+    }
+
+    lines.push('', `{gray-fg}${rom.path}{/}`);
+
+    this.infoPanel.setContent(lines.join('\n'));
+    this.screen.render();
+  }
+
+  _getSelectedRom(index) {
+    return this.sortedRoms ? this.sortedRoms[index] : null;
+  }
+
+  _setupKeys() {
+    // Quit
+    this.screen.key(['q', 'C-c'], () => {
+      process.exit(0);
+    });
+
+    // Launch game
+    this.romList.key(['enter'], () => {
+      const index = this.romList.selected;
+      const rom = this._getSelectedRom(index);
+      if (rom) {
+        this._launchGame(rom);
+      }
+    });
+
+    // View toggles
+    this.screen.key(['a'], () => {
+      this._showCurrentSystem();
+    });
+
+    // Left/Right arrow keys for system navigation
+    this.screen.key(['left'], () => {
+      this._navigatePrevSystem();
+    });
+    this.screen.key(['right'], () => {
+      this._navigateNextSystem();
+    });
+
+    this.screen.key(['r'], () => {
+      this._showRecentRoms();
+    });
+
+    // Settings
+    this.screen.key(['s'], () => {
+      this._showSettings();
+    });
+
+    // Refresh
+    this.screen.key(['f5'], () => {
+      this._loadRoms();
+    });
+  }
+
+  _launchGame(rom) {
+    this.prefs.addRecentGame(rom.path);
+
+    // Stop controller polling and clean up
+    this._stopControllerPolling();
+    if (this.gamepadManager && this.gamepadManager.destroy) {
+      try {
+        this.gamepadManager.destroy();
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+
+    // Hide the screen and launch retroemu
+    this.screen.destroy();
+
+    const args = [rom.path];
+    const renderMode = this.prefs.get('renderMode');
+    if (renderMode === 'ascii') {
+      args.push('--ascii');
+    } else if (renderMode === 'braille') {
+      args.push('--braille');
+    } else if (renderMode === 'braille-dither') {
+      args.push('--braille-dither');
+    }
+
+    // Convert 1-10 slider to contrast value (1=0.5, 5=1.0, 10=2.0)
+    const contrastSlider = this.prefs.get('contrast') || 5;
+    const contrastValue = 0.5 + (contrastSlider - 1) * (1.5 / 9);
+    if (contrastValue !== 1.0) {
+      args.push('--contrast', contrastValue.toFixed(2));
+    }
+
+    const retroemuBin = join(__dirname, '..', 'node_modules', '.bin', 'retroemu');
+    const child = spawn(retroemuBin, args, {
+      stdio: 'inherit',
+    });
+
+    child.on('close', () => {
+      // Give SDL time to clean up before reinitializing
+      setTimeout(() => this.start(), 500);
+    });
+  }
+
+  _showSettings() {
+    this._settingsOpen = true;
+    const currentRenderMode = this.prefs.get('renderMode') || 'block';
+
+    const form = blessed.form({
+      parent: this.screen,
+      top: 'center',
+      left: 'center',
+      width: '60%',
+      height: 20,
+      border: { type: 'line' },
+      style: { border: { fg: 'yellow' } },
+      keys: true,
+    });
+
+    blessed.text({
+      parent: form,
+      top: 0,
+      left: 2,
+      content: '{bold}Settings{/}',
+      tags: true,
+    });
+
+    blessed.text({
+      parent: form,
+      top: 2,
+      left: 2,
+      content: 'ROMs Directory:',
+    });
+
+    const romsInput = blessed.textbox({
+      parent: form,
+      top: 3,
+      left: 2,
+      right: 2,
+      height: 3,
+      border: { type: 'line' },
+      style: {
+        border: { fg: 'blue' },
+        focus: { border: { fg: 'green' } },
+      },
+      inputOnFocus: true,
+      value: this.prefs.get('romsDir'),
+    });
+
+    blessed.text({
+      parent: form,
+      top: 7,
+      left: 2,
+      content: 'Render Mode:',
+    });
+
+    const RENDER_MODES = ['block', 'ascii', 'braille', 'braille-dither'];
+    const RENDER_MODE_LABELS = {
+      'block': 'Block characters',
+      'ascii': 'ASCII characters',
+      'braille': 'Braille (B&W)',
+      'braille-dither': 'Braille dithered',
+    };
+
+    const renderModeBox = blessed.box({
+      parent: form,
+      top: 8,
+      left: 2,
+      width: 30,
+      height: 3,
+      border: { type: 'line' },
+      style: {
+        border: { fg: 'blue' },
+        focus: { border: { fg: 'green' } },
+      },
+      tags: true,
+      content: ` ${RENDER_MODE_LABELS[currentRenderMode] || RENDER_MODE_LABELS['block']}`,
+    });
+
+    let selectedRenderMode = currentRenderMode;
+
+    const toggleRenderMode = () => {
+      const idx = RENDER_MODES.indexOf(selectedRenderMode);
+      selectedRenderMode = RENDER_MODES[(idx + 1) % RENDER_MODES.length];
+      renderModeBox.setContent(` ${RENDER_MODE_LABELS[selectedRenderMode]}`);
+      this.screen.render();
+    };
+
+    renderModeBox.on('click', toggleRenderMode);
+
+    // Contrast slider
+    blessed.text({
+      parent: form,
+      top: 11,
+      left: 2,
+      content: 'Contrast:',
+    });
+
+    const currentContrast = this.prefs.get('contrast') || 5;
+    let selectedContrast = currentContrast;
+
+    const renderSlider = (value) => {
+      const filled = '█'.repeat(value);
+      const empty = '░'.repeat(10 - value);
+      return ` ${filled}${empty} ${value}`;
+    };
+
+    const contrastBox = blessed.box({
+      parent: form,
+      top: 12,
+      left: 2,
+      width: 20,
+      height: 3,
+      border: { type: 'line' },
+      style: {
+        border: { fg: 'blue' },
+        focus: { border: { fg: 'green' } },
+      },
+      tags: true,
+      content: renderSlider(selectedContrast),
+    });
+
+    const adjustContrast = (delta) => {
+      selectedContrast = Math.max(1, Math.min(10, selectedContrast + delta));
+      contrastBox.setContent(renderSlider(selectedContrast));
+      this.screen.render();
+    };
+
+    blessed.text({
+      parent: form,
+      top: 15,
+      left: 2,
+      content: '{white-fg}↑↓{/} field  {white-fg}←→{/} adjust  {white-fg}X{/} toggle  {white-fg}A{/} save  {white-fg}B{/} cancel',
+      tags: true,
+    });
+
+    const FIELDS = ['roms', 'render', 'contrast'];
+    let focusedField = 'roms';
+
+    const updateFieldStyles = () => {
+      romsInput.style.border.fg = focusedField === 'roms' ? 'green' : 'blue';
+      renderModeBox.style.border.fg = focusedField === 'render' ? 'green' : 'blue';
+      contrastBox.style.border.fg = focusedField === 'contrast' ? 'green' : 'blue';
+      if (focusedField === 'roms') romsInput.focus();
+      this.screen.render();
+    };
+
+    const focusField = (field) => {
+      focusedField = field;
+      updateFieldStyles();
+    };
+
+    const focusNextField = () => {
+      const idx = FIELDS.indexOf(focusedField);
+      focusField(FIELDS[(idx + 1) % FIELDS.length]);
+    };
+
+    const focusPrevField = () => {
+      const idx = FIELDS.indexOf(focusedField);
+      focusField(FIELDS[(idx - 1 + FIELDS.length) % FIELDS.length]);
+    };
+
+    focusField('roms');
+
+    const closeForm = () => {
+      this._settingsOpen = false;
+      this._settingsState = null;
+      form.destroy();
+      this.romList.focus();
+      this.screen.render();
+    };
+
+    const saveAndClose = () => {
+      const newPath = romsInput.getValue().trim();
+      if (newPath) {
+        this.prefs.set('romsDir', newPath);
+      }
+      this.prefs.set('renderMode', selectedRenderMode);
+      this.prefs.set('contrast', selectedContrast);
+      this._settingsOpen = false;
+      this._settingsState = null;
+      form.destroy();
+      this._loadRoms();
+      this.romList.focus();
+    };
+
+    // Store state for gamepad handling
+    this._settingsState = {
+      focusNextField,
+      focusPrevField,
+      toggleRenderMode,
+      adjustContrast,
+      closeForm,
+      saveAndClose,
+      getFocusedField: () => focusedField,
+    };
+
+    romsInput.key(['escape'], closeForm);
+    romsInput.key(['tab'], focusNextField);
+    romsInput.key(['enter'], saveAndClose);
+
+    form.key(['escape'], closeForm);
+    form.key(['tab'], focusNextField);
+    form.key(['space'], () => {
+      if (focusedField === 'render') toggleRenderMode();
+    });
+    form.key(['left'], () => {
+      if (focusedField === 'contrast') adjustContrast(-1);
+    });
+    form.key(['right'], () => {
+      if (focusedField === 'contrast') adjustContrast(1);
+    });
+    form.key(['enter'], saveAndClose);
+
+    this.screen.render();
+  }
+
+  _navigateUp() {
+    const index = this.romList.selected - 1;
+    if (index >= 0) {
+      this.romList.select(index);
+      this._updateInfoPanel(index);
+      this.screen.render();
+    }
+  }
+
+  _navigateDown() {
+    const index = this.romList.selected + 1;
+    const max = this.sortedRoms ? this.sortedRoms.length : 0;
+    if (index < max) {
+      this.romList.select(index);
+      this._updateInfoPanel(index);
+      this.screen.render();
+    }
+  }
+
+  _navigatePrevSystem() {
+    if (this.currentView !== 'system' || this.systems.length === 0) return;
+
+    this.currentSystemIndex--;
+    if (this.currentSystemIndex < 0) {
+      this.currentSystemIndex = this.systems.length - 1;
+    }
+    this._showCurrentSystem();
+  }
+
+  _navigateNextSystem() {
+    if (this.currentView !== 'system' || this.systems.length === 0) return;
+
+    this.currentSystemIndex++;
+    if (this.currentSystemIndex >= this.systems.length) {
+      this.currentSystemIndex = 0;
+    }
+    this._showCurrentSystem();
+  }
+
+  _startControllerPolling() {
+    // Track previous button states for edge detection
+    this._prevButtons = {};
+    // Track held time for repeat
+    this._holdTime = {};
+    // Wait for all buttons to be released before accepting input (prevents re-launch on resume)
+    this._waitingForRelease = true;
+
+    this.gamepadPollInterval = setInterval(() => {
+      const gamepads = navigator.getGamepads().filter(gp => gp !== null);
+      this._updateControllerStatus(gamepads);
+
+      // Check if we're waiting for buttons to be released
+      if (this._waitingForRelease && gamepads.length > 0) {
+        const gp = gamepads[0];
+        const anyPressed = gp.buttons.some(b => b?.pressed);
+        if (!anyPressed) {
+          this._waitingForRelease = false;
+        }
+        return; // Skip input handling until released
+      }
+
+      this._handleGamepadInput(gamepads);
+    }, 16); // Poll at ~60Hz for responsive input
+  }
+
+  _stopControllerPolling() {
+    if (this.gamepadPollInterval) {
+      clearInterval(this.gamepadPollInterval);
+      this.gamepadPollInterval = null;
+    }
+  }
+
+  _updateControllerStatus(gamepads) {
+    if (gamepads.length === 0) {
+      this.controllerBox.setContent('{gray-fg}No controllers{/}\n{gray-fg}Keyboard: arrows + Enter{/}');
+    } else {
+      const lines = gamepads.slice(0, 2).map((gp, i) => {
+        const name = gp.id.length > 24 ? gp.id.substring(0, 24) + '...' : gp.id;
+        return `{green-fg}P${i + 1}:{/} ${name}`;
+      });
+      if (gamepads.length > 2) {
+        lines.push(`{gray-fg}+${gamepads.length - 2} more{/}`);
+      }
+      this.controllerBox.setContent(lines.join('\n'));
+    }
+    this.screen.render();
+  }
+
+  _handleGamepadInput(gamepads) {
+    if (gamepads.length === 0) return;
+
+    const now = Date.now();
+    const gp = gamepads[0]; // Use first controller for navigation
+    const buttons = gp.buttons;
+    const prev = this._prevButtons;
+    const hold = this._holdTime;
+
+    // Helper: detect button press (edge detection only)
+    const pressed = (idx) => {
+      const isPressed = buttons[idx]?.pressed;
+      const wasPressed = prev[idx];
+      prev[idx] = isPressed;
+      return isPressed && !wasPressed;
+    };
+
+    // Handle settings dialog input separately
+    if (this._settingsOpen && this._settingsState) {
+      const s = this._settingsState;
+
+      // B button = close/cancel
+      if (pressed(1)) {
+        s.closeForm();
+        return;
+      }
+
+      // A button or Start = save
+      if (pressed(0) || pressed(9)) {
+        s.saveAndClose();
+        return;
+      }
+
+      // D-pad up/down = switch fields
+      if (pressed(12)) {
+        s.focusPrevField();
+        return;
+      }
+      if (pressed(13)) {
+        s.focusNextField();
+        return;
+      }
+
+      // D-pad left/right = adjust contrast (when on contrast field)
+      if (s.getFocusedField() === 'contrast') {
+        if (pressed(14)) {
+          s.adjustContrast(-1);
+          return;
+        }
+        if (pressed(15)) {
+          s.adjustContrast(1);
+          return;
+        }
+      }
+
+      // X button = toggle render mode
+      if (pressed(2)) {
+        s.toggleRenderMode();
+        return;
+      }
+
+      return; // Don't process normal navigation while settings open
+    }
+
+    // Helper: detect held with repeat (initial delay 300ms, then repeat every 80ms)
+    const heldWithRepeat = (key, isActive) => {
+      if (isActive) {
+        if (!hold[key]) {
+          hold[key] = now;
+          return true; // First press
+        }
+        const elapsed = now - hold[key];
+        if (elapsed > 300) {
+          // Repeat phase - check if enough time for next repeat
+          const repeatElapsed = (elapsed - 300) % 80;
+          const prevRepeatElapsed = (elapsed - 300 - 16) % 80; // ~16ms ago
+          if (repeatElapsed < prevRepeatElapsed || elapsed - 300 < 16) {
+            return true;
+          }
+        }
+        return false;
+      } else {
+        delete hold[key];
+        return false;
+      }
+    };
+
+    // D-pad navigation (buttons 12-15) or left stick
+    const leftStickY = gp.axes[1] || 0;
+    const leftStickX = gp.axes[0] || 0;
+
+    const upActive = buttons[12]?.pressed || leftStickY < -0.5;
+    const downActive = buttons[13]?.pressed || leftStickY > 0.5;
+    const leftActive = buttons[14]?.pressed || leftStickX < -0.5;
+    const rightActive = buttons[15]?.pressed || leftStickX > 0.5;
+
+    if (heldWithRepeat('up', upActive)) {
+      this._navigateUp();
+    }
+    if (heldWithRepeat('down', downActive)) {
+      this._navigateDown();
+    }
+    if (heldWithRepeat('left', leftActive)) {
+      this._navigatePrevSystem();
+    }
+    if (heldWithRepeat('right', rightActive)) {
+      this._navigateNextSystem();
+    }
+
+    // Shoulder bumpers (buttons 4 and 5) = fast scroll with repeat
+    if (heldWithRepeat('lb', buttons[4]?.pressed)) {
+      for (let i = 0; i < 10; i++) this._navigateUp();
+    }
+    if (heldWithRepeat('rb', buttons[5]?.pressed)) {
+      for (let i = 0; i < 10; i++) this._navigateDown();
+    }
+
+    // A button (south/button 0) = Enter/Select
+    if (pressed(0)) {
+      const index = this.romList.selected;
+      const rom = this._getSelectedRom(index);
+      if (rom) {
+        this._launchGame(rom);
+      }
+    }
+
+    // B button (east/button 1) = Back to system view
+    if (pressed(1)) {
+      this._showCurrentSystem();
+    }
+
+    // X button (west/button 2) = Recent
+    if (pressed(2)) {
+      this._showRecentRoms();
+    }
+
+    // Y button (north/button 3) = Settings
+    if (pressed(3)) {
+      this._showSettings();
+    }
+
+    // Start button (button 9) = Launch
+    if (pressed(9)) {
+      const index = this.romList.selected;
+      const rom = this._getSelectedRom(index);
+      if (rom) {
+        this._launchGame(rom);
+      }
+    }
+  }
+}

package/src/Preferences.js

@@ -0,0 +1,56 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CONFIG_DIR = join(homedir(), '.config', 'retroterm');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+const DEFAULTS = {
+  romsDir: join(homedir(), 'roms'),
+  savesDir: join(homedir(), '.config', 'retroterm', 'saves'),
+  recentGames: [],
+  maxRecent: 10,
+  renderMode: 'block', // 'block', 'ascii', 'braille', 'braille-dither'
+  contrast: 5, // 1-10, where 5 = 1.0 (normal)
+};
+
+export class Preferences {
+  constructor() {
+    this.config = { ...DEFAULTS };
+    this.load();
+  }
+
+  load() {
+    try {
+      const data = readFileSync(CONFIG_FILE, 'utf-8');
+      this.config = { ...DEFAULTS, ...JSON.parse(data) };
+    } catch {
+      // No config file yet, use defaults
+    }
+  }
+
+  save() {
+    try {
+      mkdirSync(CONFIG_DIR, { recursive: true });
+      writeFileSync(CONFIG_FILE, JSON.stringify(this.config, null, 2));
+    } catch (err) {
+      // Ignore save errors
+    }
+  }
+
+  get(key) {
+    return this.config[key];
+  }
+
+  set(key, value) {
+    this.config[key] = value;
+    this.save();
+  }
+
+  addRecentGame(romPath) {
+    const recent = this.config.recentGames.filter(p => p !== romPath);
+    recent.unshift(romPath);
+    this.config.recentGames = recent.slice(0, this.config.maxRecent);
+    this.save();
+  }
+}

package/src/RomScanner.js

@@ -0,0 +1,149 @@
+import { readdirSync, statSync } from 'fs';
+import { join, extname, basename } from 'path';
+import { open } from 'yauzl';
+
+// Supported ROM extensions (from retroemu)
+const ROM_EXTENSIONS = new Set([
+  '.nes', '.fds', '.unf', '.unif',           // NES
+  '.sfc', '.smc',                             // SNES
+  '.gb', '.gbc', '.gba',                      // Game Boy
+  '.md', '.gen', '.smd', '.bin',              // Genesis
+  '.sms', '.gg', '.sg',                       // Master System / Game Gear
+  '.a26', '.a52', '.a78',                     // Atari consoles
+  '.xex', '.atr', '.atx', '.bas', '.car', '.xfd',  // Atari computers
+  '.lnx', '.o',                               // Lynx
+  '.pce', '.cue', '.ccd', '.chd',             // PC Engine
+  '.ngp', '.ngc',                             // Neo Geo Pocket
+  '.ws', '.wsc',                              // WonderSwan
+  '.col',                                     // ColecoVision
+  '.vec',                                     // Vectrex
+  '.tzx', '.z80', '.sna',                     // ZX Spectrum
+  '.mx1', '.mx2', '.rom', '.dsk', '.cas',     // MSX
+  '.iso', '.pbp', '.m3u',                      // PlayStation
+]);
+
+const SYSTEM_NAMES = {
+  '.nes': 'NES', '.fds': 'NES', '.unf': 'NES', '.unif': 'NES',
+  '.sfc': 'SNES', '.smc': 'SNES',
+  '.gb': 'Game Boy', '.gbc': 'Game Boy Color', '.gba': 'Game Boy Advance',
+  '.md': 'Genesis', '.gen': 'Genesis', '.smd': 'Genesis', '.bin': 'Genesis',
+  '.sms': 'Master System', '.gg': 'Game Gear', '.sg': 'SG-1000',
+  '.a26': 'Atari 2600', '.a52': 'Atari 5200', '.a78': 'Atari 7800',
+  '.xex': 'Atari 800', '.atr': 'Atari 800', '.atx': 'Atari 800',
+  '.bas': 'Atari 800', '.car': 'Atari 800', '.xfd': 'Atari 800',
+  '.lnx': 'Lynx', '.o': 'Lynx',
+  '.pce': 'PC Engine', '.cue': 'PC Engine', '.ccd': 'PC Engine', '.chd': 'PC Engine',
+  '.ngp': 'Neo Geo Pocket', '.ngc': 'Neo Geo Pocket Color',
+  '.ws': 'WonderSwan', '.wsc': 'WonderSwan Color',
+  '.col': 'ColecoVision',
+  '.vec': 'Vectrex',
+  '.tzx': 'ZX Spectrum', '.z80': 'ZX Spectrum', '.sna': 'ZX Spectrum',
+  '.mx1': 'MSX', '.mx2': 'MSX', '.rom': 'MSX', '.dsk': 'MSX', '.cas': 'MSX',
+  '.iso': 'PlayStation', '.pbp': 'PlayStation', '.m3u': 'PlayStation',
+  '.zip': 'Archive',
+};
+
+export class RomScanner {
+  constructor(romsDir) {
+    this.romsDir = romsDir;
+  }
+
+  async scan() {
+    const roms = [];
+    await this._scanDir(this.romsDir, roms);
+    return roms.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  async _scanDir(dir, roms, depth = 0) {
+    if (depth > 3) return; // Don't recurse too deep
+
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        if (entry.startsWith('.')) continue;
+
+        const fullPath = join(dir, entry);
+        try {
+          const stat = statSync(fullPath);
+          if (stat.isDirectory()) {
+            await this._scanDir(fullPath, roms, depth + 1);
+          } else if (stat.isFile()) {
+            const ext = extname(entry).toLowerCase();
+            if (ext === '.zip') {
+              // Peek inside ZIP to find ROMs
+              const zipRoms = await this._scanZip(fullPath);
+              roms.push(...zipRoms);
+            } else if (ROM_EXTENSIONS.has(ext)) {
+              roms.push({
+                name: basename(entry, ext),
+                path: fullPath,
+                ext,
+                system: SYSTEM_NAMES[ext] || 'Unknown',
+              });
+            }
+          }
+        } catch {
+          // Skip inaccessible files
+        }
+      }
+    } catch {
+      // Skip inaccessible directories
+    }
+  }
+
+  async _scanZip(zipPath) {
+    const roms = [];
+
+    try {
+      const zipfile = await new Promise((resolve, reject) => {
+        open(zipPath, { lazyEntries: true }, (err, zf) => {
+          if (err) reject(err);
+          else resolve(zf);
+        });
+      });
+
+      const zipName = basename(zipPath, extname(zipPath));
+
+      await new Promise((resolve) => {
+        zipfile.on('entry', (entry) => {
+          const ext = extname(entry.fileName).toLowerCase();
+          if (ROM_EXTENSIONS.has(ext) && !entry.fileName.startsWith('__MACOSX')) {
+            let romName = basename(entry.fileName, ext);
+            // If the inner file has a generic/numeric name, use the zip filename instead
+            if (/^\d+$/.test(romName) || romName.length < 3) {
+              romName = zipName;
+            }
+            roms.push({
+              name: romName,
+              path: zipPath,
+              zipEntry: entry.fileName,
+              ext,
+              system: SYSTEM_NAMES[ext] || 'Unknown',
+            });
+          }
+          zipfile.readEntry();
+        });
+
+        zipfile.on('end', resolve);
+        zipfile.readEntry();
+      });
+
+      zipfile.close();
+    } catch {
+      // Skip unreadable ZIPs
+    }
+
+    return roms;
+  }
+
+  getSystemGroups(roms) {
+    const groups = {};
+    for (const rom of roms) {
+      if (!groups[rom.system]) {
+        groups[rom.system] = [];
+      }
+      groups[rom.system].push(rom);
+    }
+    return groups;
+  }
+}