@tmustier/pi-nes 0.2.22 → 0.2.23

package/AGENTS.md

@@ -36,6 +36,13 @@ pi-nes/
 
 The emulator uses the [`nes_rust`](https://crates.io/crates/nes_rust) crate (vendored + patched in `native/nes-core/vendor/nes_rust` for SRAM helpers) with [napi-rs](https://napi.rs) bindings.
 
+### Vendored `nes_rust` workflow
+
+- Source of truth is the fork (intended): `https://github.com/tmustier/nes-rust`.
+- Make changes in the fork first, then re-vendor via `scripts/update-vendor-nes-rust.sh`.
+- Update `extensions/nes/native/nes-core/vendor/nes_rust/VENDOR.md` with the fork commit + date + patch summary.
+- Keep TODO inventory in `extensions/nes/native/nes-core/vendor/nes_rust/TODO_INVENTORY.md`.
+
 **API exposed to JavaScript:**
 - `new NativeNes()` - Create emulator instance
 - `setRom(Uint8Array)` - Load ROM data

package/README.md

@@ -106,6 +106,12 @@ Set `"renderer": "text"` if you prefer the ANSI renderer or have display issues.
 - **No audio** — Sound is not currently supported
 - **No save states** — Only battery-backed SRAM saves work
 
+## Vendored Dependencies
+
+- `nes_rust` is vendored under `extensions/nes/native/nes-core/vendor/nes_rust`.
+- Fork: https://github.com/tmustier/nes-rust (upstream: https://github.com/takahirox/nes-rust)
+- Update helper: `scripts/update-vendor-nes-rust.sh`
+
 ---
 
 ## Building from Source

package/TODO_INVENTORY.md

@@ -0,0 +1,116 @@
+# TODO Inventory Review
+
+Scope: `extensions/nes/native/nes-core/vendor/nes_rust` (vendored emulator core). Each TODO reviewed for necessity.
+
+## Action Plan (prioritized)
+
+### P0 — Correctness (act)
+- [ ] APU timing fixes (sample_period, sampling timing, frame sequencer timing, sweep negation, DMC stall timing)
+- [ ] PPU fetch timing + scroll updates (cycles 257–340, subcycle fetch, attribute fetch, pixel alignment)
+- [ ] Mapper IRQ/MMC1 correctness (MMC3 IRQ timing/placement, MMC1 32KB banking fix)
+- [ ] CPU correctness/timing (ADC 0x71 page-cross, NMI vs IRQ priority, BIT/JMP/JSR/RTI/RTS/SBC logic, relative addressing sign extension, DMA stall timing)
+
+### P1 — Architecture cleanup
+- [ ] Move MMC3 IRQ handling out of ROM/PPU into mapper layer
+- [ ] Replace invalid-register/addressing TODOs with explicit no-op or `unreachable!()`
+- [ ] Remove/clarify doc-only TODOs (audio example note, greyscale comment, PPU master/slave select if intentionally ignored)
+
+### P2 — Optional refactors/optimizations
+- [ ] Opcode table refactor
+- [ ] Register<u8>/Register<u16> merge
+- [ ] Audio buffer cleanup + constant for 4096
+- [ ] Header caching + sprite eval/pos calculation optimizations
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/lib.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 57 | Audio buffer sample code is T.B.D. (doc example) | Not needed for runtime; either remove the TODO or replace with a short note that audio output is omitted in the example. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/apu.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 53 | Fix sample_period (1764000 / 44100) | Needed for accurate audio timing; keep until audio timing is corrected. |
+| 67 | Implement reset properly | Needed for accurate APU reset behavior; keep. |
+| 79 | More precise sampling timing | Needed for correct audio output timing; keep. |
+| 93 | Add note (DMC timer) | Not needed; either add a clarifying comment or remove the TODO. |
+| 102 | More precise frame sequencer timing | Needed for correct APU frame sequencing; keep. |
+| 168 | Check IRQ timing when sending | Needed for correct IRQ behavior; keep. |
+| 276 | DMC CPU memory workaround is hacky; simplify | Optional refactor; keep if you want cleanup, otherwise can remove. |
+| 400 | Throw an error on invalid pulse register | Not needed; invalid register writes are typically ignored. Consider removing TODO or clarifying no-op behavior. |
+| 467 | Fix negated sweep behavior | Needed for accurate sweep; keep. |
+| 612 | Throw an error on invalid triangle register | Not needed; invalid writes can be ignored. Consider removing TODO. |
+| 775 | Throw an error on invalid noise register | Not needed; invalid writes can be ignored. Consider removing TODO. |
+| 949 | DMC invalid register case | Not needed; either document as ignored or remove TODO. |
+| 975 | Remove DMC CPU memory workaround | Optional refactor; keep if you want to eliminate the workaround. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/default_audio.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 29 | Remove side effect in copy_sample_buffer | Optional cleanup; keep if you plan to revisit buffer semantics. |
+| 31 | Remove magic number (4096) | Needed for maintainability; replace with a named constant if audio is used. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/ppu.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 119 | Support data bus decay | Optional accuracy improvement; keep if fidelity matters. |
+| 322 | Support greyscale if needed | Likely optional; greyscale masking is already applied in `load_palette`. Consider removing or clarifying if register-read greyscale behavior is desired. |
+| 495 | Investigate `cycle - 1` vs `cycle - 2` pixel alignment | Needed for render correctness; keep. |
+| 594 | Cycle 257-320 behavior | Needed for correct PPU fetch timing; keep. |
+| 595 | Cycle 321-336 behavior | Needed for correct PPU fetch timing; keep. |
+| 596 | Cycle 337-340 behavior | Needed for correct PPU fetch timing; keep. |
+| 615 | 0-1 subcycle fetch details | Needed for correctness; keep. |
+| 616 | 2-3 subcycle fetch details | Needed for correctness; keep. |
+| 617 | 4-5 subcycle fetch details | Needed for correctness; keep. |
+| 618 | 6-7 subcycle fetch details | Needed for correctness; keep. |
+| 660 | Implement attribute fetch properly | Needed for PPU accuracy; keep. |
+| 690 | Optimize pos calculation | Optional performance cleanup; not required. |
+| 758 | Check MMC3 IRQ timing | Needed for mapper IRQ accuracy; keep. |
+| 759 | MMC3-specific IRQ hook location | Optional refactor; keep if you plan to move this into mapper layer. |
+| 804 | Only increment scroll if rendering enabled? | Needed for correctness; keep. |
+| 830 | Only copy scroll if rendering enabled? | Needed for correctness; keep. |
+| 863 | Optimize sprite evaluation | Optional performance cleanup; not required. |
+| 1020 | Implement color emphasis properly | Needed if emphasis bits should affect output; keep. |
+| 1069 | Implement PPU master/slave select | Likely not needed (unused on NES). Consider removing TODO or documenting it as intentionally ignored. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/register.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 5 | Combine Register<u8> with Register<u16> | Optional refactor; not required. Consider removing if you don’t plan to refactor. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/mapper.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 45 | MMC3-specific `drive_irq_counter` in trait | Optional architecture cleanup; keep if you want a mapper-specific IRQ interface. |
+| 149 | MMC1 32KB banking fix | Needed for correct MMC1 behavior; keep. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/cpu.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 44 | Throw error for unknown button mapping | Not needed; enum should be exhaustive. Replace with `unreachable!()` or remove TODO. |
+| 242 | Replace opcode match with static array | Optional refactor; not required. |
+| 620 | Add +1 cycle if page crossed (ADC 0x71) | Needed for accurate timing; keep. |
+| 1254 | Simplify DMC sample handling | Optional refactor; keep if you want cleanup. |
+| 1258 | Fix DMC stall timing (+4 cycles) | Needed for accuracy; keep. |
+| 1271 | More precise frame update detection | Optional; keep if timing fidelity matters. |
+| 1285 | Implement Poweroff input | Optional feature; keep if you plan to support it. |
+| 1313 | Handle NMI vs IRQ priority | Needed for correctness; keep. |
+| 1368 | Clean up operate() if needed | Not needed; remove TODO unless you plan a refactor. |
+| 1417 | Check BIT instruction logic | Needed for correctness; keep. |
+| 1531 | Throw on INV instruction | Not needed for runtime; prefer `unreachable!()` or remove TODO. |
+| 1552 | Check JMP logic | Needed for correctness; keep. |
+| 1557 | Check JSR logic | Needed for correctness; keep. |
+| 1709 | Check RTI logic | Needed for correctness; keep. |
+| 1716 | Check RTS logic | Needed for correctness; keep. |
+| 1732 | Confirm SBC carry/borrow logic | Needed for correctness; keep. |
+| 1738 | Implement correct SBC overflow logic | Needed for correctness; keep. |
+| 1895 | Clean up store() control flow | Not needed; remove TODO unless refactoring. |
+| 1909 | DMA stall cycle timing | Needed for accuracy (513/514 cycle detail); keep. |
+| 1952 | Optimize interrupt handling | Optional; not required. |
+| 1994 | Confirm relative addressing sign extension | Needed for correctness; keep. |
+| 2116 | Throw on unknown addressing mode | Not needed; prefer `unreachable!()` or remove TODO. |
+
+## extensions/nes/native/nes-core/vendor/nes_rust/src/rom.rs
+| Line | TODO | Assessment |
+| --- | --- | --- |
+| 139 | MMC3-specific `irq_interrupted` in ROM | Optional architecture cleanup; keep if you plan to move IRQ handling into mapper layer. |
+| 145 | Cache RomHeader fields | Optional optimization; not required. |

package/extensions/nes/native/nes-core/vendor/nes_rust/TODO_INVENTORY.md

@@ -0,0 +1,60 @@
+# nes_rust TODO Inventory (vendored)
+
+This inventory tracks TODOs in the vendored `nes_rust` snapshot.
+
+## src/lib.rs
+- L57: Audio buffer sample code T.B.D. (doc example). Likely remove or replace with note.
+
+## src/apu.rs
+- L53: sample_period timing fix needed for audio accuracy.
+- L67: APU reset behavior incomplete.
+- L79: Sampling timing not precise.
+- L93: Add note (DMC timer) — probably remove or add clarification.
+- L102: Frame sequencer timing not precise.
+- L168: IRQ timing needs verification.
+- L276: DMC CPU memory workaround is hacky; optional refactor.
+- L400/612/775/949: Invalid register write handling — probably ignore or document no-op.
+- L467: Sweep negation logic fix needed.
+- L975: Remove DMC memory workaround; optional refactor.
+
+## src/default_audio.rs
+- L29: Remove side effect in copy_sample_buffer (optional).
+- L31: Replace magic number 4096 with constant.
+
+## src/ppu.rs
+- L119: Data bus decay support (accuracy improvement).
+- L322: Greyscale support comment; likely redundant.
+- L495: Pixel alignment off-by-one investigation.
+- L594-L618: Missing cycle/subcycle fetch behavior.
+- L660: Attribute fetch correctness.
+- L690: Optional optimization.
+- L758-L759: MMC3 IRQ timing/placement.
+- L804/L830: Scroll updates conditional on rendering.
+- L863: Optional optimization.
+- L1020: Color emphasis implementation.
+- L1069: PPU master/slave select; likely ignorable on NES.
+
+## src/register.rs
+- L5: Combine Register<u8>/Register<u16> (optional refactor).
+
+## src/mapper.rs
+- L45: MMC3 IRQ hook in trait (optional architecture cleanup).
+- L149: MMC1 32KB banking fix needed.
+
+## src/cpu.rs
+- L44: Unknown button mapping; replace with unreachable or ignore.
+- L242: Opcode table refactor (optional).
+- L620: Page-cross cycle for ADC 0x71 needed.
+- L1254/L1258: DMC sample handling simplification + stall timing fix.
+- L1271: Frame update detection precision.
+- L1285: Poweroff input handling.
+- L1313: NMI vs IRQ ordering.
+- L1368/1895: Cleanup notes (optional).
+- L1417/1552/1557/1709/1716/1732/1738/1994: CPU logic correctness checks.
+- L1531/L2116: Invalid instruction/addressing mode handling.
+- L1909: DMA stall timing detail.
+- L1952: Interrupt handling optimization (optional).
+
+## src/rom.rs
+- L139: MMC3 IRQ in ROM (optional architecture cleanup).
+- L145: Cache header fields (optional).

package/extensions/nes/native/nes-core/vendor/nes_rust/VENDOR.md

@@ -0,0 +1,24 @@
+# Vendored Dependency: nes_rust
+
+## Upstream
+- Repository: https://github.com/takahirox/nes-rust
+- Upstream state: last known push (per GitHub API) 2020-08-28
+
+## Fork
+- Repository: https://github.com/tmustier/nes-rust
+- Purpose: carry project-specific fixes and act as upstream-of-record for this vendor copy.
+
+## Current Vendor Snapshot
+- Source commit/tag: `fd5cf3b` (fork master)
+- Vendored on: 2026-02-02
+- Local patch set: SRAM helpers, CHR RAM support, mapper fixes, PPU timing tweaks, debug hooks.
+
+## Update Process
+1. Sync fork with upstream if needed.
+2. Apply/maintain project patches on the fork.
+3. Re-vendor from fork at a pinned commit/tag.
+4. Update this file with the new commit/tag + patch notes.
+
+## Notes
+- This repo uses a vendored copy under `extensions/nes/native/nes-core/vendor/nes_rust`.
+- Keep patch history in the fork so changes are auditable.

package/extensions/nes/native/nes-core/vendor/nes_rust/src/ppu.rs

@@ -271,6 +271,7 @@ impl Ppu {
 			// ppustatus load
 			0x2002 => {
 				let value = self.ppustatus.load();
+				let was_vblank = (value & 0x80) != 0;
 
 				// clear vblank after reading 0x2002
 				self.ppustatus.clear_vblank();
@@ -287,10 +288,9 @@ impl Ppu {
 				// clears the flag, and won't fire NMI
 
 				// Note: update_flags() which can set vblank is called
-				// after this method in the same cycle, so set supress_vblank true
-				// even at cycle=1 not only cycle=0
-
-				if self.scanline == 241 && (self.cycle == 0 || self.cycle == 1) {
+				// after this method in the same cycle. Only suppress if
+				// vblank was already set when read.
+				if was_vblank && self.scanline == 241 && self.cycle == 1 {
 					self.suppress_vblank = true;
 				}
 
@@ -735,9 +735,13 @@ impl Ppu {
 	fn update_flags(&mut self, rom: &mut Rom) {
 		if self.cycle == 1 {
 			if self.scanline == 241 {
-				// set vblank and occur NMI at cycle 1 in scanline 241
+				// Set vblank and latch NMI at cycle 1 in scanline 241.
+				// NMI delivery is still delayed by CPU instruction timing.
 				if !self.suppress_vblank {
 					self.ppustatus.set_vblank();
+					if self.ppuctrl.is_nmi_enabled() {
+						self.nmi_interrupted = true;
+					}
 				}
 				self.suppress_vblank = false;
 				// Pixels for this frame should be ready so update the display
@@ -751,41 +755,6 @@ impl Ppu {
 			}
 		}
 
-		// According to http://wiki.nesdev.com/w/index.php/PPU_frame_timing#VBL_Flag_Timing
-		// reading 0x2002 at cycle=2 and scanline=241 can suppress NMI
-		// so firing NMI at some cycles away not at cycle=1 so far
-
-		// There is a chance that CPU 0x2002 read gets the data vblank flag set
-		// before CPU starts NMI interrupt routine.
-		// CPU instructions take multiple CPU clocks to complete.
-		// If CPU starts an operation of an istruction including 0x2002 read right before
-		// PPU sets vblank flag and fires NMI,
-		// the 0x2002 read gets the data with vblank flag set even before
-		// CPU starts NMI routine.
-		//
-		//    CPU                              PPU
-		// 1. instruction operation start
-		// 2.   - doing something              vblank start and fire NMI
-		// 3.   - read 0x2002 with
-		//        vblank flag set
-		// 4.   - doing something
-		// 5. Notice NMI and start
-		//    NMI routine
-		//
-		// It seems some games rely on this behavior.
-		// To simulate this behavior we fire NMI at cycle=20 so far.
-		// If CPU reads 0x2002 between PPU cycle 3~20 it gets data
-		// vblank flag set before NMI routine.
-		// (reading at cycle 1~2 suppresses NMI, see load_register())
-		// @TODO: Safer and more appropriate approach.
-
-		if self.cycle == 20 && self.scanline == 241 {
-			if self.ppustatus.is_vblank() &&
-				self.ppuctrl.is_nmi_enabled() {
-				self.nmi_interrupted = true;
-			}
-		}
-
 		// @TODO: check this driving IRQ counter for MMC3Mapper timing is correct
 		// @TODO: This is MMC3Mapper specific. Should this be here?
 
@@ -901,7 +870,7 @@ impl Ppu {
 		// the PPU scans through OAM to determine which sprites
 		// to render on the next scanline
 
-		if self.scanline >= 240 {
+		if self.scanline >= 240 && self.scanline != 261 {
 			return;
 		}
 
@@ -917,16 +886,17 @@ impl Ppu {
 		} else if self.cycle == 257 {
 			// Evaluate at a time at cycle 257 due to performance
 			// and simplicity so far
-			self.process_sprite_pixels(rom);
+			let next_scanline = if self.scanline == 261 { 0 } else { self.scanline + 1 };
+			self.process_sprite_pixels(next_scanline, rom);
 		}
 	}
 
-	fn process_sprite_pixels(&mut self, rom: &Rom) {
+	fn process_sprite_pixels(&mut self, scanline: u16, rom: &Rom) {
 		for i in 0..self.sprite_availables.len() {
 			self.sprite_availables[i] = false;
 		}
 
-		let y = self.scanline as u8;
+		let y = scanline as u8;
 		let height = self.ppuctrl.sprite_height();
 		let mut n = 0;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-nes",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "NES emulator extension for pi",
   "keywords": [
     "pi-package",
@@ -13,9 +13,19 @@
     "type": "git",
     "url": "https://github.com/tmustier/pi-nes.git"
   },
+  "scripts": {
+    "test": "node --import tsx --test tests/paths.test.ts tests/roms.test.ts tests/saves.test.ts tests/config.test.ts tests/input-map.test.ts",
+    "test:unit": "node --import tsx --test tests/paths.test.ts tests/roms.test.ts tests/saves.test.ts tests/config.test.ts tests/input-map.test.ts",
+    "test:core": "node --import tsx --test tests/core-smoke.test.ts",
+    "test:regression": "node --import tsx --test tests/regression.test.ts"
+  },
   "dependencies": {
     "pngjs": "^7.0.0"
   },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*"

package/scripts/update-vendor-nes-rust.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FORK_URL="https://github.com/tmustier/nes-rust.git"
+VENDOR_DIR="extensions/nes/native/nes-core/vendor/nes_rust"
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "Working tree not clean. Commit or stash changes before updating vendor." >&2
+  exit 1
+fi
+
+TMP_DIR="$(mktemp -d -t nes-rust-vendor-XXXX)"
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+git clone --depth 1 "$FORK_URL" "$TMP_DIR"
+
+echo "This will replace contents of $VENDOR_DIR with $FORK_URL"
+read -r -p "Continue? [y/N] " confirm
+if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+  echo "Aborted."
+  exit 1
+fi
+
+rsync -a --delete --exclude ".git" "$TMP_DIR/" "$VENDOR_DIR/"
+
+echo "Vendored from commit: $(git -C "$TMP_DIR" rev-parse HEAD)"
+echo "Update $VENDOR_DIR/VENDOR.md with commit/tag + date + patch summary."

package/tests/README.md

@@ -0,0 +1,122 @@
+# Tests
+
+## Quick Start
+
+```bash
+# Run unit tests (no ROMs needed)
+npm test
+
+# Run with a specific ROM
+NES_TEST_ROM=~/roms/nes/Zelda.nes npm run test:core
+
+# Run regression against all ROMs in a directory  
+NES_ROM_DIR=~/roms/nes npm run test:regression
+
+# Debug a specific game (visual ASCII output)
+npx tsx tests/debug-game.ts ~/roms/nes/Mario.nes
+```
+
+## Test Structure
+
+### Unit Tests (always run)
+
+| File | What it tests |
+|------|---------------|
+| `paths.test.ts` | Path utilities (displayPath, expandHomePath, etc.) |
+| `roms.test.ts` | ROM name parsing |
+| `saves.test.ts` | Save path generation |
+| `config.test.ts` | Config normalization and validation |
+| `input-map.test.ts` | Keyboard-to-button mapping |
+
+### Core Smoke Tests (require ROM)
+
+Set `NES_TEST_ROM=/path/to/rom.nes` to enable.
+
+| File | What it tests |
+|------|---------------|
+| `core-smoke.test.ts` | ROM loading, frame execution, freeze detection, SRAM round-trip |
+
+### Regression Tests (require ROM directory)
+
+Set `NES_ROM_DIR=/path/to/roms` to enable.
+
+| File | What it tests |
+|------|---------------|
+| `regression.test.ts` | Scripted game tests with input sequences |
+| `game-scripts.ts` | Game-specific input sequences (Start, move, etc.) |
+
+### Debug Tool
+
+```bash
+npx tsx tests/debug-game.ts <rom-path>
+```
+
+Shows ASCII rendering of the game after running the script, useful for diagnosing rendering issues.
+
+## CI Usage
+
+For CI without commercial ROMs:
+
+```bash
+npm run test:unit  # Only pure function tests
+```
+
+For local development with ROMs:
+
+```bash
+NES_ROM_DIR=~/roms/nes npm run test:regression
+```
+
+## Interpreting Results
+
+### Regression Output
+
+```
+✅ OK Dragon Quest III [scripted] (425 frames)  # Loaded, ran script, frames animated
+⚠️ FROZE Super Mario Bros [scripted] (475 frames) # Ran script but frames frozen
+❌ ERROR Broken.nes (0 frames)                    # Failed to load or crashed
+```
+
+### What "FROZE" Means
+
+For **scripted** tests, "FROZE" indicates a likely bug:
+- Background renders but sprites missing
+- Game stuck after input sequence
+- No animation after reaching gameplay
+
+The scripted tests simulate actual gameplay (press Start, move character) and verify the screen animates. A frozen screen after pressing right in Mario means the sprite isn't rendering.
+
+### Debug Output Example
+
+```
+Frame Analysis (after script):
+  Non-zero pixels: 59,440 / 61,440 (96.7%)  ← Background renders
+  Unique colors: 9                          ← Limited palette (no sprites)
+  
+ASCII Preview:
+  [Shows level but no Mario sprite visible]
+```
+
+## Adding Game Scripts
+
+Edit `tests/game-scripts.ts` to add scripts for new ROMs:
+
+```typescript
+"my game": {
+  description: "Start game, verify gameplay",
+  sequence: [
+    { type: "wait", frames: 180 },        // 3 seconds
+    { type: "press", button: "start" },   // tap Start
+    { type: "wait", frames: 120 },        // 2 seconds  
+    { type: "hold", button: "right", frames: 30 }, // move
+  ],
+  postSequenceFrames: 60,  // frames to check for animation
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NES_TEST_ROM` | Path to a single ROM for core smoke tests |
+| `NES_ROM_DIR` | Directory containing .nes files for regression tests |

package/tests/config.test.ts

@@ -0,0 +1,96 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { normalizeConfig, DEFAULT_CONFIG, formatConfig } from "../extensions/nes/config.js";
+
+describe("config", () => {
+	describe("normalizeConfig", () => {
+		test("returns defaults for empty object", () => {
+			const config = normalizeConfig({});
+			assert.strictEqual(config.enableAudio, DEFAULT_CONFIG.enableAudio);
+			assert.strictEqual(config.renderer, DEFAULT_CONFIG.renderer);
+			assert.strictEqual(config.imageQuality, DEFAULT_CONFIG.imageQuality);
+			assert.strictEqual(config.pixelScale, DEFAULT_CONFIG.pixelScale);
+		});
+
+		test("returns defaults for null", () => {
+			const config = normalizeConfig(null);
+			assert.strictEqual(config.renderer, "image");
+		});
+
+		test("returns defaults for non-object", () => {
+			const config = normalizeConfig("invalid");
+			assert.strictEqual(config.renderer, "image");
+		});
+
+		test("accepts valid renderer value", () => {
+			const config = normalizeConfig({ renderer: "text" });
+			assert.strictEqual(config.renderer, "text");
+		});
+
+		test("defaults invalid renderer to image", () => {
+			const config = normalizeConfig({ renderer: "invalid" });
+			assert.strictEqual(config.renderer, "image");
+		});
+
+		test("accepts valid imageQuality", () => {
+			const config = normalizeConfig({ imageQuality: "high" });
+			assert.strictEqual(config.imageQuality, "high");
+		});
+
+		test("defaults invalid imageQuality to balanced", () => {
+			const config = normalizeConfig({ imageQuality: "ultra" });
+			assert.strictEqual(config.imageQuality, "balanced");
+		});
+
+		test("clamps pixelScale to valid range", () => {
+			assert.strictEqual(normalizeConfig({ pixelScale: 0.1 }).pixelScale, 0.5);
+			assert.strictEqual(normalizeConfig({ pixelScale: 10 }).pixelScale, 4);
+			assert.strictEqual(normalizeConfig({ pixelScale: 2 }).pixelScale, 2);
+		});
+
+		test("handles NaN pixelScale", () => {
+			const config = normalizeConfig({ pixelScale: NaN });
+			assert.strictEqual(config.pixelScale, DEFAULT_CONFIG.pixelScale);
+		});
+
+		test("preserves valid keybindings", () => {
+			const config = normalizeConfig({
+				keybindings: { a: ["k", "l"] }
+			});
+			assert.deepStrictEqual(config.keybindings.a, ["k", "l"]);
+			// Other keys should have defaults
+			assert.ok(config.keybindings.up.length > 0);
+		});
+
+		test("ignores invalid keybinding values", () => {
+			const config = normalizeConfig({
+				keybindings: { a: "not-an-array" }
+			});
+			// Should fall back to default
+			assert.deepStrictEqual(config.keybindings.a, DEFAULT_CONFIG.keybindings.a);
+		});
+
+		test("accepts boolean enableAudio", () => {
+			assert.strictEqual(normalizeConfig({ enableAudio: true }).enableAudio, true);
+			assert.strictEqual(normalizeConfig({ enableAudio: false }).enableAudio, false);
+		});
+
+		test("defaults non-boolean enableAudio", () => {
+			const config = normalizeConfig({ enableAudio: "yes" });
+			assert.strictEqual(config.enableAudio, DEFAULT_CONFIG.enableAudio);
+		});
+	});
+
+	describe("formatConfig", () => {
+		test("produces valid JSON", () => {
+			const json = formatConfig(DEFAULT_CONFIG);
+			const parsed = JSON.parse(json);
+			assert.strictEqual(parsed.renderer, DEFAULT_CONFIG.renderer);
+		});
+
+		test("is pretty-printed", () => {
+			const json = formatConfig(DEFAULT_CONFIG);
+			assert.ok(json.includes("\n"), "Should be multi-line");
+		});
+	});
+});