@tmustier/pi-nes 0.2.21 → 0.2.23

package/extensions/nes/nes-component.ts

@@ -2,13 +2,10 @@ import type { Component, TUI } from "@mariozechner/pi-tui";
 import { isKeyRelease, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
 import type { InputMapping } from "./input-map.js";
 import { DEFAULT_INPUT_MAPPING, getMappedButtons } from "./input-map.js";
-import type { FrameBuffer, NesCore } from "./nes-core.js";
+import type { NesButton, FrameBuffer, NesCore } from "./nes-core.js";
 import type { NesSessionStats } from "./nes-session.js";
-import type { RendererMode } from "./renderer.js";
-import { NesImageRenderer } from "./renderer.js";
-
-const FRAME_WIDTH = 256;
-const FRAME_HEIGHT = 240;
+import type { RendererMode } from "./config.js";
+import { FRAME_HEIGHT, FRAME_WIDTH, NesImageRenderer } from "./renderer.js";
 
 function readRgb(frameBuffer: FrameBuffer, index: number): [number, number, number] {
 	const data = frameBuffer.data;
@@ -80,7 +77,8 @@ function averageBlock(
 export class NesOverlayComponent implements Component {
 	wantsKeyRelease = true;
 	private readonly inputMapping: InputMapping;
-	private readonly tapTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	private readonly tapTimers = new Map<"start" | "select", ReturnType<typeof setTimeout>>();
+	private readonly heldButtons = new Set<NesButton>();
 	private readonly imageRenderer = new NesImageRenderer();
 	private readonly rendererMode: RendererMode;
 	private readonly pixelScale: number;
@@ -115,11 +113,13 @@ export class NesOverlayComponent implements Component {
 	handleInput(data: string): void {
 		const released = isKeyRelease(data);
 		if (!released && matchesKey(data, "ctrl+q")) {
+			this.releaseAllButtons();
 			this.cleanupImage();
 			this.onDetach();
 			return;
 		}
 		if (!released && (matchesKey(data, "q") || matchesKey(data, "shift+q"))) {
+			this.releaseAllButtons();
 			this.cleanupImage();
 			this.onQuit();
 			return;
@@ -137,6 +137,11 @@ export class NesOverlayComponent implements Component {
 				}
 				continue;
 			}
+			if (released) {
+				this.heldButtons.delete(button);
+			} else {
+				this.heldButtons.add(button);
+			}
 			this.core.setButton(button, !released);
 		}
 	}
@@ -150,22 +155,39 @@ export class NesOverlayComponent implements Component {
 		const frameBuffer = this.core.getFrameBuffer();
 		const debugLines = this.debug ? this.buildDebugLines() : [];
 		const footerRows = this.debug ? 1 + debugLines.length : 1;
+
 		if (this.rendererMode === "image") {
-			const lines = this.imageRenderer.render(
-				frameBuffer,
-				this.tui,
-				width,
-				footerRows,
-				this.pixelScale,
-				!this.windowed,
-			);
-			for (const line of debugLines) {
-				lines.push(truncateToWidth(line, width));
-			}
-			lines.push(truncateToWidth(`\x1b[2m${footer}\x1b[0m`, width));
-			return lines;
+			const lines = this.renderImage(frameBuffer, width, footerRows);
+			return this.appendFooter(lines, width, debugLines, footer, "");
 		}
 
+		const { lines, padPrefix } = this.renderText(frameBuffer, width, footerRows);
+		return this.appendFooter(lines, width, debugLines, footer, padPrefix);
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		this.releaseAllButtons();
+		this.cleanupImage();
+	}
+
+	private renderImage(frameBuffer: FrameBuffer, width: number, footerRows: number): string[] {
+		return this.imageRenderer.render(
+			frameBuffer,
+			this.tui,
+			width,
+			footerRows,
+			this.pixelScale,
+			!this.windowed,
+		);
+	}
+
+	private renderText(
+		frameBuffer: FrameBuffer,
+		width: number,
+		footerRows: number,
+	): { lines: string[]; padPrefix: string } {
 		const maxFrameRows = Math.max(1, this.tui.terminal.rows - footerRows);
 		const scaleX = Math.max(1, Math.ceil(FRAME_WIDTH / width));
 		const scaleY = Math.max(1, Math.ceil(FRAME_HEIGHT / (maxFrameRows * 2)));
@@ -176,21 +198,22 @@ export class NesOverlayComponent implements Component {
 
 		const rawLines = renderHalfBlock(frameBuffer, targetCols, targetRows, scaleX, scaleY);
 		const lines = rawLines.map((line) => truncateToWidth(`${padPrefix}${line}`, width));
-		for (const line of debugLines) {
-			lines.push(truncateToWidth(`${padPrefix}${line}`, width));
-		}
-		lines.push(truncateToWidth(`\x1b[2m${padPrefix}${footer}\x1b[0m`, width));
-		return lines;
+		return { lines, padPrefix };
 	}
 
-	invalidate(): void {}
-
-	dispose(): void {
-		this.cleanupImage();
-		for (const timer of this.tapTimers.values()) {
-			clearTimeout(timer);
+	private appendFooter(
+		lines: string[],
+		width: number,
+		debugLines: string[],
+		footer: string,
+		padPrefix: string,
+	): string[] {
+		const output = [...lines];
+		for (const line of debugLines) {
+			output.push(truncateToWidth(`${padPrefix}${line}`, width));
 		}
-		this.tapTimers.clear();
+		output.push(truncateToWidth(`\x1b[2m${padPrefix}${footer}\x1b[0m`, width));
+		return output;
 	}
 
 	private cleanupImage(): void {
@@ -201,6 +224,18 @@ export class NesOverlayComponent implements Component {
 		this.imageCleared = true;
 	}
 
+	private releaseAllButtons(): void {
+		for (const button of this.heldButtons) {
+			this.core.setButton(button, false);
+		}
+		this.heldButtons.clear();
+		for (const [button, timer] of this.tapTimers.entries()) {
+			clearTimeout(timer);
+			this.core.setButton(button, false);
+		}
+		this.tapTimers.clear();
+	}
+
 	private buildDebugLines(): string[] {
 		const stats = this.statsProvider?.();
 		if (!stats) {

package/extensions/nes/nes-core.ts

@@ -46,7 +46,6 @@ export interface NesCore {
 	markSramSaved(): void;
 	getAudioWarning(): string | null;
 	getDebugState(): NesDebugState | null;
-	reset(): void;
 	dispose(): void;
 }
 
@@ -59,7 +58,6 @@ interface NativeNesInstance {
 	bootup(): void;
 	stepFrame(): void;
 	refreshFramebuffer(): void;
-	reset(): void;
 	pressButton(button: number): void;
 	releaseButton(button: number): void;
 	hasBatteryBackedRam(): boolean;
@@ -181,11 +179,10 @@ class NativeNesCore implements NesCore {
 		return this.nes.getDebugState();
 	}
 
-	reset(): void {
-		this.nes.reset();
+	dispose(): void {
+		// No explicit native teardown required; napi instance is GC-managed.
+		this.hasSram = false;
 	}
-
-	dispose(): void {}
 }
 
 export function createNesCore(options: CreateNesCoreOptions = {}): NesCore {

package/extensions/nes/nes-session.ts

@@ -61,6 +61,8 @@ export class NesSession {
 		dropped: 0,
 	};
 	private readonly loopDelay = monitorEventLoopDelay({ resolution: 10 });
+	private fatalErrorLogged = false;
+	private saveErrorLogged = false;
 
 	constructor(options: NesSessionOptions) {
 		this.core = options.core;
@@ -210,7 +212,12 @@ export class NesSession {
 				this.statsWindow.ticks = 0;
 				this.statsWindow.dropped = 0;
 			}
-		} catch {
+		} catch (error) {
+			if (!this.fatalErrorLogged) {
+				this.fatalErrorLogged = true;
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(`NES session crashed: ${message}`);
+			}
 			void this.stop();
 		}
 	}
@@ -230,6 +237,12 @@ export class NesSession {
 		try {
 			await saveSram(this.saveDir, this.romPath, sram);
 			this.core.markSramSaved();
+		} catch (error) {
+			if (!this.saveErrorLogged) {
+				this.saveErrorLogged = true;
+				const message = error instanceof Error ? error.message : String(error);
+				console.warn(`NES save failed: ${message}`);
+			}
 		} finally {
 			this.saveInFlight = false;
 		}

package/extensions/nes/renderer.ts

@@ -8,13 +8,14 @@ import { Image } from "@mariozechner/pi-tui";
 import { allocateImageId, deleteKittyImage, getCapabilities, getCellDimensions } from "@mariozechner/pi-tui";
 import type { FrameBuffer } from "./nes-core.js";
 
-const FRAME_WIDTH = 256;
-const FRAME_HEIGHT = 240;
+export const FRAME_WIDTH = 256;
+export const FRAME_HEIGHT = 240;
 const RAW_FRAME_BYTES = FRAME_WIDTH * FRAME_HEIGHT * 3;
 const FALLBACK_TMP_DIR = "/tmp";
 const SHM_DIR = "/dev/shm";
 const IMAGE_HEIGHT_RATIO = 0.9;
 
+// Renderer state + native addon loading.
 const require = createRequire(import.meta.url);
 
 interface SharedMemoryHandle {
@@ -45,8 +46,6 @@ function getKittyShmModule(): KittyShmModule | null {
 	return kittyShmModule;
 }
 
-export type RendererMode = "image" | "text";
-
 export class NesImageRenderer {
 	private readonly imageId = allocateImageId();
 	private cachedImage?: { base64: string; width: number; height: number };
@@ -61,6 +60,8 @@ export class NesImageRenderer {
 	private sharedMemoryModule: KittyShmModule | null = null;
 	private lastFrameHash = 0;
 	private rawVersion = 0;
+	private lastLines: string[] = [];
+	private readonly renderErrors = new Set<string>();
 
 	render(
 		frameBuffer: FrameBuffer,
@@ -74,12 +75,17 @@ export class NesImageRenderer {
 		if (caps.images === "kitty") {
 			const shared = this.renderKittySharedMemory(frameBuffer, tui, widthCells, footerRows, pixelScale, padToHeight);
 			if (shared) {
+				this.lastLines = [...shared];
 				return shared;
 			}
-			return this.renderKittyRaw(frameBuffer, tui, widthCells, footerRows, pixelScale, padToHeight);
+			const raw = this.renderKittyRaw(frameBuffer, tui, widthCells, footerRows, pixelScale, padToHeight);
+			this.lastLines = [...raw];
+			return raw;
 		}
 
-		return this.renderPng(frameBuffer, tui, widthCells, footerRows, pixelScale, padToHeight);
+		const png = this.renderPng(frameBuffer, tui, widthCells, footerRows, pixelScale, padToHeight);
+		this.lastLines = [...png];
+		return png;
 	}
 
 	dispose(tui: TUI): void {
@@ -89,6 +95,8 @@ export class NesImageRenderer {
 		this.cachedImage = undefined;
 		this.cachedRaw = undefined;
 		this.lastFrameHash = 0;
+		this.lastLines = [];
+		this.renderErrors.clear();
 		if (this.sharedMemoryQueue.length > 0 && this.sharedMemoryModule) {
 			for (const handle of this.sharedMemoryQueue) {
 				try {
@@ -172,9 +180,13 @@ export class NesImageRenderer {
 		const layout = computeKittyLayout(tui, widthCells, footerRows, pixelScale);
 		const { availableRows, columns, rows, padLeft } = layout;
 
-		this.fillRawBuffer(frameBuffer);
-		const fd = this.ensureRawFile();
-		fs.writeSync(fd, this.rawBuffer, 0, this.rawBuffer.length, 0);
+		try {
+			this.fillRawBuffer(frameBuffer);
+			const fd = this.ensureRawFile();
+			fs.writeSync(fd, this.rawBuffer, 0, this.rawBuffer.length, 0);
+		} catch (error) {
+			return this.handleRenderError("kitty-raw", error);
+		}
 
 		let cached = this.cachedRaw;
 		if (!cached || cached.columns !== columns || cached.rows !== rows) {
@@ -220,26 +232,30 @@ export class NesImageRenderer {
 
 		const hash = hashFrame(frameBuffer, targetWidth, targetHeight);
 		if (!this.cachedImage || this.lastFrameHash !== hash) {
-			const png = new PNG({ width: targetWidth, height: targetHeight });
-			for (let y = 0; y < targetHeight; y += 1) {
-				const srcY = Math.floor((y / targetHeight) * FRAME_HEIGHT);
-				for (let x = 0; x < targetWidth; x += 1) {
-					const srcX = Math.floor((x / targetWidth) * FRAME_WIDTH);
-					const [r, g, b] = readRgb(frameBuffer, srcY * FRAME_WIDTH + srcX);
-					const idx = (y * targetWidth + x) * 4;
-					png.data[idx] = r;
-					png.data[idx + 1] = g;
-					png.data[idx + 2] = b;
-					png.data[idx + 3] = 0xff;
+			try {
+				const png = new PNG({ width: targetWidth, height: targetHeight });
+				for (let y = 0; y < targetHeight; y += 1) {
+					const srcY = Math.floor((y / targetHeight) * FRAME_HEIGHT);
+					for (let x = 0; x < targetWidth; x += 1) {
+						const srcX = Math.floor((x / targetWidth) * FRAME_WIDTH);
+						const [r, g, b] = readRgb(frameBuffer, srcY * FRAME_WIDTH + srcX);
+						const idx = (y * targetWidth + x) * 4;
+						png.data[idx] = r;
+						png.data[idx + 1] = g;
+						png.data[idx + 2] = b;
+						png.data[idx + 3] = 0xff;
+					}
 				}
+				const buffer = PNG.sync.write(png, { deflateLevel: 0, filterType: 0 });
+				this.cachedImage = {
+					base64: buffer.toString("base64"),
+					width: targetWidth,
+					height: targetHeight,
+				};
+				this.lastFrameHash = hash;
+			} catch (error) {
+				return this.handleRenderError("png", error);
 			}
-			const buffer = PNG.sync.write(png, { deflateLevel: 0, filterType: 0 });
-			this.cachedImage = {
-				base64: buffer.toString("base64"),
-				width: targetWidth,
-				height: targetHeight,
-			};
-			this.lastFrameHash = hash;
 		}
 
 		const image = new Image(
@@ -254,6 +270,15 @@ export class NesImageRenderer {
 		return padToHeight ? centerLines(padded, availableRows) : padded;
 	}
 
+	private handleRenderError(kind: string, error: unknown): string[] {
+		if (!this.renderErrors.has(kind)) {
+			this.renderErrors.add(kind);
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(`NES renderer ${kind} failed: ${message}`);
+		}
+		return this.lastLines.length > 0 ? [...this.lastLines] : [];
+	}
+
 	private fillRawBuffer(frameBuffer: FrameBuffer): void {
 		this.fillRawBufferTarget(frameBuffer, this.rawBuffer);
 	}
@@ -323,8 +348,10 @@ export class NesImageRenderer {
 	}
 }
 
-function encodeKittyRawFile(
-	base64Path: string,
+// Kitty graphics protocol (ESC_G ... ESC\\).
+// t=f (file) / t=s (shared memory), f=24 (RGB), p=1 (no scaling), q=2 (quiet), z=layer.
+function buildKittyParams(
+	transport: "f" | "s",
 	options: {
 		widthPx: number;
 		heightPx: number;
@@ -334,13 +361,13 @@ function encodeKittyRawFile(
 		imageId?: number;
 		zIndex?: number;
 	},
-): string {
+): string[] {
 	const params: string[] = [
 		"a=T",
 		"f=24",
-		"t=f",
+		`t=${transport}`,
 		"p=1",
-		`q=2`,
+		"q=2",
 		`s=${options.widthPx}`,
 		`v=${options.heightPx}`,
 		`S=${options.dataSize}`,
@@ -349,7 +376,22 @@ function encodeKittyRawFile(
 	if (options.rows) params.push(`r=${options.rows}`);
 	if (options.imageId) params.push(`i=${options.imageId}`);
 	if (options.zIndex !== undefined) params.push(`z=${options.zIndex}`);
+	return params;
+}
 
+function encodeKittyRawFile(
+	base64Path: string,
+	options: {
+		widthPx: number;
+		heightPx: number;
+		dataSize: number;
+		columns?: number;
+		rows?: number;
+		imageId?: number;
+		zIndex?: number;
+	},
+): string {
+	const params = buildKittyParams("f", options);
 	return `\x1b_G${params.join(",")};${base64Path}\x1b\\`;
 }
 
@@ -365,24 +407,11 @@ function encodeKittyRawSharedMemory(
 		zIndex?: number;
 	},
 ): string {
-	const params: string[] = [
-		"a=T",
-		"f=24",
-		"t=s",
-		"p=1",
-		`q=2`,
-		`s=${options.widthPx}`,
-		`v=${options.heightPx}`,
-		`S=${options.dataSize}`,
-	];
-	if (options.columns) params.push(`c=${options.columns}`);
-	if (options.rows) params.push(`r=${options.rows}`);
-	if (options.imageId) params.push(`i=${options.imageId}`);
-	if (options.zIndex !== undefined) params.push(`z=${options.zIndex}`);
-
+	const params = buildKittyParams("s", options);
 	return `\x1b_G${params.join(",")};${base64Name}\x1b\\`;
 }
 
+// Temp file/SHM selection.
 function resolveRawDir(): string {
 	const candidates = [process.env.TMPDIR, SHM_DIR, FALLBACK_TMP_DIR, os.tmpdir()].filter(
 		(value): value is string => Boolean(value && value.length > 0),
@@ -401,6 +430,7 @@ function resolveRawDir(): string {
 	return os.tmpdir();
 }
 
+// Layout helpers.
 function getAvailableRows(tui: TUI, footerRows: number): number {
 	return Math.max(1, tui.terminal.rows - footerRows);
 }

package/extensions/nes/roms.ts

@@ -24,16 +24,3 @@ export async function listRoms(romDir: string): Promise<RomEntry[]> {
 		.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-export async function resolveRomPath(args: string | undefined, romDir: string): Promise<string | null> {
-	const trimmed = args?.trim();
-	if (trimmed && trimmed.length > 0) {
-		return path.resolve(trimmed);
-	}
-
-	try {
-		const roms = await listRoms(romDir);
-		return roms.length > 0 ? roms[0]?.path ?? null : null;
-	} catch {
-		return null;
-	}
-}

package/extensions/nes/saves.ts

@@ -1,10 +1,17 @@
+import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { getRomDisplayName } from "./roms.js";
 
+function getSaveId(romPath: string): string {
+	const resolved = path.resolve(romPath);
+	return createHash("sha1").update(resolved).digest("hex").slice(0, 8);
+}
+
 export function getSavePath(saveDir: string, romPath: string): string {
 	const romName = getRomDisplayName(romPath);
-	return path.join(saveDir, `${romName}.sav`);
+	const hash = getSaveId(romPath);
+	return path.join(saveDir, `${romName}-${hash}.sav`);
 }
 
 export async function loadSram(saveDir: string, romPath: string): Promise<Uint8Array | null> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-nes",
-  "version": "0.2.21",
+  "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/spec.md

@@ -60,7 +60,8 @@ pi-nes/
 - Use `isKeyRelease()` for clean key‑up events.
 
 ## Saves
-- Store SRAM at `<saveDir>/<rom-name>.sav` (default `/roms/nes/saves`).
+- Store SRAM at `<saveDir>/<rom-name>-<hash>.sav` (default `/roms/nes/saves`).
+- Hash is derived from the full ROM path to avoid collisions; old `<rom-name>.sav` files are ignored.
 - Load SRAM on ROM start.
 - Persist on exit and periodically (e.g., every 5–10 seconds).
 

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 |