@tmustier/pi-nes 0.2.21 → 0.2.23

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");
+		});
+	});
+});

package/tests/core-smoke.test.ts

@@ -0,0 +1,124 @@
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert";
+import { readFile } from "node:fs/promises";
+import { createNesCore, type NesCore } from "../extensions/nes/nes-core.js";
+
+const TEST_ROM = process.env.NES_TEST_ROM;
+const SKIP_REASON = "Set NES_TEST_ROM=/path/to/rom.nes to run core tests";
+
+function hashFramebuffer(data: Uint8Array): number {
+	let hash = 0;
+	// Sample every 1000th byte for speed
+	for (let i = 0; i < data.length; i += 1000) {
+		hash = ((hash << 5) - hash + data[i]) | 0;
+	}
+	return hash;
+}
+
+describe("core-smoke", { skip: !TEST_ROM ? SKIP_REASON : undefined }, () => {
+	let core: NesCore;
+	let romData: Uint8Array;
+
+	before(async () => {
+		if (!TEST_ROM) return;
+		romData = new Uint8Array(await readFile(TEST_ROM));
+	});
+
+	after(() => {
+		core?.dispose();
+	});
+
+	test("native core is available", () => {
+		// This will throw if native module not built
+		core = createNesCore();
+		assert.ok(core, "Core should be created");
+	});
+
+	test("loads ROM without crashing", () => {
+		core.loadRom(romData);
+		// If we get here, it loaded
+		assert.ok(true);
+	});
+
+	test("runs 60 frames without crashing", () => {
+		for (let i = 0; i < 60; i++) {
+			core.tick();
+		}
+		assert.ok(true);
+	});
+
+	test("framebuffer contains data", () => {
+		const fb = core.getFrameBuffer();
+		assert.ok(fb.data.length > 0, "Framebuffer should have data");
+		// Check it's not all zeros (at least some pixels rendered)
+		const hasNonZero = fb.data.some(b => b !== 0);
+		assert.ok(hasNonZero, "Framebuffer should have non-zero pixels");
+	});
+
+	test("frames change over time (not frozen)", () => {
+		const hashes: number[] = [];
+		for (let i = 0; i < 30; i++) {
+			core.tick();
+			const fb = core.getFrameBuffer();
+			hashes.push(hashFramebuffer(fb.data));
+		}
+		const uniqueHashes = new Set(hashes);
+		// Should have at least a few different frames
+		assert.ok(uniqueHashes.size > 1, `Expected frame changes, got ${uniqueHashes.size} unique frames out of 30`);
+	});
+
+	test("button input does not crash", () => {
+		core.setButton("a", true);
+		core.tick();
+		core.setButton("a", false);
+		core.setButton("start", true);
+		core.tick();
+		core.setButton("start", false);
+		core.tick();
+		assert.ok(true);
+	});
+
+	// Note: reset() exists in native but isn't exposed via NesCore interface
+});
+
+describe("sram-roundtrip", { skip: !TEST_ROM ? SKIP_REASON : undefined }, () => {
+	test("SRAM save and restore", async () => {
+		if (!TEST_ROM) return;
+
+		const romData = new Uint8Array(await readFile(TEST_ROM));
+		const core = createNesCore();
+		
+		try {
+			core.loadRom(romData);
+
+			// Run some frames
+			for (let i = 0; i < 60; i++) {
+				core.tick();
+			}
+
+			const sram = core.getSram();
+			if (!sram) {
+				// ROM doesn't have battery-backed SRAM, skip
+				return;
+			}
+
+			// Modify SRAM dirty state
+			assert.strictEqual(typeof core.isSramDirty(), "boolean");
+
+			// Create new core and restore SRAM
+			const core2 = createNesCore();
+			try {
+				core2.loadRom(romData);
+				core2.setSram(sram);
+
+				const restored = core2.getSram();
+				assert.ok(restored, "Should be able to get SRAM after setting");
+				assert.strictEqual(restored.length, sram.length, "SRAM length should match");
+			} finally {
+				core2.dispose();
+			}
+		} finally {
+			core.dispose();
+		}
+	});
+});

package/tests/debug-game.ts

@@ -0,0 +1,203 @@
+/**
+ * Debug script to visually inspect what a game looks like after scripted input
+ * 
+ * Usage:
+ *   npx tsx tests/debug-game.ts ~/roms/nes/Mario.nes
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createNesCore, type NesCore, type NesButton } from "../extensions/nes/nes-core.js";
+import { findScript, type GameScript } from "./game-scripts.js";
+
+const FRAME_WIDTH = 256;
+const FRAME_HEIGHT = 240;
+
+function hashFramebuffer(data: Uint8Array): number {
+	let hash = 0;
+	for (let i = 0; i < data.length; i += 500) {
+		hash = ((hash << 5) - hash + data[i]) | 0;
+	}
+	return hash;
+}
+
+function analyzeFrame(data: Uint8Array): { nonZeroPixels: number; uniqueColors: number; brightness: number } {
+	let nonZeroPixels = 0;
+	let totalBrightness = 0;
+	const colors = new Set<number>();
+
+	for (let i = 0; i < data.length; i += 3) {
+		const r = data[i];
+		const g = data[i + 1];
+		const b = data[i + 2];
+		
+		if (r !== 0 || g !== 0 || b !== 0) {
+			nonZeroPixels++;
+		}
+		
+		const color = (r << 16) | (g << 8) | b;
+		colors.add(color);
+		totalBrightness += (r + g + b) / 3;
+	}
+
+	return {
+		nonZeroPixels,
+		uniqueColors: colors.size,
+		brightness: totalBrightness / (FRAME_WIDTH * FRAME_HEIGHT),
+	};
+}
+
+function renderFrameAscii(data: Uint8Array, width: number = 64, height: number = 24): string[] {
+	const lines: string[] = [];
+	const scaleX = FRAME_WIDTH / width;
+	const scaleY = FRAME_HEIGHT / height;
+	const chars = " .:-=+*#%@";
+
+	for (let y = 0; y < height; y++) {
+		let line = "";
+		for (let x = 0; x < width; x++) {
+			const srcX = Math.floor(x * scaleX);
+			const srcY = Math.floor(y * scaleY);
+			const idx = (srcY * FRAME_WIDTH + srcX) * 3;
+			const r = data[idx] || 0;
+			const g = data[idx + 1] || 0;
+			const b = data[idx + 2] || 0;
+			const brightness = (r + g + b) / 3 / 255;
+			const charIdx = Math.min(chars.length - 1, Math.floor(brightness * chars.length));
+			line += chars[charIdx];
+		}
+		lines.push(line);
+	}
+	return lines;
+}
+
+async function debugGame(romPath: string) {
+	const filename = path.basename(romPath);
+	console.log(`\n${"=".repeat(70)}`);
+	console.log(`Debugging: ${filename}`);
+	console.log(`${"=".repeat(70)}\n`);
+
+	const romData = new Uint8Array(await readFile(romPath));
+	const core = createNesCore();
+	
+	try {
+		core.loadRom(romData);
+		console.log("✅ ROM loaded successfully\n");
+
+		const script = findScript(filename);
+		if (!script) {
+			console.log("⚠️  No script found for this ROM, running default frames\n");
+			for (let i = 0; i < 300; i++) {
+				core.tick();
+			}
+		} else {
+			console.log(`📜 Script: ${script.description}\n`);
+			console.log("Executing script...\n");
+
+			let totalFrames = 0;
+			for (const action of script.sequence) {
+				switch (action.type) {
+					case "wait":
+						console.log(`  ⏳ Wait ${action.frames} frames (${(action.frames / 60).toFixed(1)}s)`);
+						for (let i = 0; i < action.frames; i++) {
+							core.tick();
+							totalFrames++;
+						}
+						break;
+					case "press":
+						console.log(`  🎮 Press ${action.button}`);
+						core.setButton(action.button, true);
+						for (let i = 0; i < (action.frames ?? 5); i++) {
+							core.tick();
+							totalFrames++;
+						}
+						core.setButton(action.button, false);
+						break;
+					case "hold":
+						console.log(`  🎮 Hold ${action.button} for ${action.frames} frames`);
+						core.setButton(action.button, true);
+						for (let i = 0; i < action.frames; i++) {
+							core.tick();
+							totalFrames++;
+						}
+						core.setButton(action.button, false);
+						break;
+					case "release":
+						console.log(`  🎮 Release ${action.button}`);
+						core.setButton(action.button, false);
+						break;
+				}
+			}
+			console.log(`\n✅ Script complete, ran ${totalFrames} frames\n`);
+		}
+
+		// Analyze current frame
+		const fb = core.getFrameBuffer();
+		const analysis = analyzeFrame(fb.data);
+		
+		console.log("Frame Analysis (after script):");
+		console.log(`  Non-zero pixels: ${analysis.nonZeroPixels.toLocaleString()} / ${(FRAME_WIDTH * FRAME_HEIGHT).toLocaleString()} (${(analysis.nonZeroPixels / (FRAME_WIDTH * FRAME_HEIGHT) * 100).toFixed(1)}%)`);
+		console.log(`  Unique colors: ${analysis.uniqueColors}`);
+		console.log(`  Average brightness: ${analysis.brightness.toFixed(1)}`);
+		console.log(`  Frame hash: ${hashFramebuffer(fb.data)}`);
+		
+		console.log("\nASCII Preview:");
+		console.log("┌" + "─".repeat(64) + "┐");
+		for (const line of renderFrameAscii(fb.data)) {
+			console.log("│" + line + "│");
+		}
+		console.log("└" + "─".repeat(64) + "┘");
+
+		// Run more frames and check for changes
+		console.log("\nRunning 60 more frames to check for animation...\n");
+		const hashes: number[] = [hashFramebuffer(fb.data)];
+		
+		for (let i = 0; i < 60; i++) {
+			core.tick();
+			if (i % 10 === 0) {
+				const currentFb = core.getFrameBuffer();
+				hashes.push(hashFramebuffer(currentFb.data));
+			}
+		}
+
+		const uniqueHashes = new Set(hashes);
+		console.log(`Frame hashes sampled: ${hashes.length}`);
+		console.log(`Unique hashes: ${uniqueHashes.size}`);
+		console.log(`Hashes: ${hashes.join(", ")}`);
+		
+		if (uniqueHashes.size <= 1) {
+			console.log("\n⚠️  FROZEN: No frame changes detected!");
+		} else {
+			console.log("\n✅ ANIMATED: Frames are changing");
+		}
+
+		// Final frame
+		const finalFb = core.getFrameBuffer();
+		const finalAnalysis = analyzeFrame(finalFb.data);
+		
+		console.log("\nFinal Frame Analysis:");
+		console.log(`  Non-zero pixels: ${finalAnalysis.nonZeroPixels.toLocaleString()} (${(finalAnalysis.nonZeroPixels / (FRAME_WIDTH * FRAME_HEIGHT) * 100).toFixed(1)}%)`);
+		console.log(`  Unique colors: ${finalAnalysis.uniqueColors}`);
+
+		console.log("\nFinal ASCII Preview:");
+		console.log("┌" + "─".repeat(64) + "┐");
+		for (const line of renderFrameAscii(finalFb.data)) {
+			console.log("│" + line + "│");
+		}
+		console.log("└" + "─".repeat(64) + "┘");
+
+	} finally {
+		core.dispose();
+	}
+}
+
+// Main
+const romPath = process.argv[2];
+if (!romPath) {
+	console.error("Usage: npx tsx tests/debug-game.ts <rom-path>");
+	process.exit(1);
+}
+
+debugGame(romPath).catch(err => {
+	console.error("Error:", err);
+	process.exit(1);
+});

package/tests/game-scripts.ts

@@ -0,0 +1,123 @@
+import type { NesButton } from "../extensions/nes/nes-core.js";
+
+/**
+ * Input action in a game script
+ */
+export type ScriptAction =
+	| { type: "wait"; frames: number }
+	| { type: "press"; button: NesButton; frames?: number }  // tap (default 5 frames)
+	| { type: "hold"; button: NesButton; frames: number }    // hold for duration
+	| { type: "release"; button: NesButton };
+
+/**
+ * Script for testing a specific game
+ */
+export interface GameScript {
+	/** Input sequence to execute */
+	sequence: ScriptAction[];
+	/** Description of what the script does */
+	description: string;
+	/** Frames to run after sequence to check for freeze (default 60) */
+	postSequenceFrames?: number;
+}
+
+// Helper to convert seconds to frames (at 60fps)
+const sec = (s: number) => Math.round(s * 60);
+
+/**
+ * Game-specific test scripts
+ * Keys should match ROM filename (without extension, case-insensitive)
+ */
+export const GAME_SCRIPTS: Record<string, GameScript> = {
+	"dragon quest iii": {
+		description: "Wait for title, press Start, wait for game to load",
+		sequence: [
+			{ type: "wait", frames: sec(3) },      // Wait for title screen
+			{ type: "press", button: "start" },    // Press Start
+			{ type: "wait", frames: sec(3) },      // Wait for game to load
+		],
+		postSequenceFrames: 60,
+	},
+
+	"super mario bros": {
+		description: "Start game, move Mario right to verify sprites render",
+		sequence: [
+			{ type: "wait", frames: sec(2) },      // Wait for title
+			{ type: "press", button: "start" },    // Press Start (1 player game)
+			{ type: "wait", frames: sec(3) },      // Wait for level to load
+			{ type: "hold", button: "right", frames: 30 },  // Move right
+			{ type: "wait", frames: 10 },
+			{ type: "hold", button: "right", frames: 30 },  // Move right again
+			{ type: "wait", frames: 10 },
+			{ type: "hold", button: "right", frames: 30 },  // Move right again
+		],
+		postSequenceFrames: 60,
+	},
+
+	// Multi-cart version
+	"super mario bros. + duck hunt + world class track meet (usa) (rev 1)": {
+		description: "Select SMB from menu, start game, move Mario",
+		sequence: [
+			{ type: "wait", frames: sec(2) },      // Wait for menu
+			{ type: "press", button: "start" },    // Select first game (SMB)
+			{ type: "wait", frames: sec(2) },      // Wait for SMB title
+			{ type: "press", button: "start" },    // Start game
+			{ type: "wait", frames: sec(3) },      // Wait for level
+			{ type: "hold", button: "right", frames: 30 },
+			{ type: "wait", frames: 10 },
+			{ type: "hold", button: "right", frames: 30 },
+		],
+		postSequenceFrames: 60,
+	},
+
+	"legend of zelda": {
+		description: "Start game, select file, begin playing",
+		sequence: [
+			{ type: "wait", frames: sec(3) },      // Wait for title
+			{ type: "press", button: "start" },    // Press Start
+			{ type: "wait", frames: sec(1) },      // Wait for file select
+			{ type: "press", button: "start" },    // Select first file
+			{ type: "wait", frames: sec(2) },      // Wait for game
+			{ type: "hold", button: "up", frames: 20 },     // Move up
+			{ type: "wait", frames: 10 },
+			{ type: "hold", button: "down", frames: 20 },   // Move down
+		],
+		postSequenceFrames: 60,
+	},
+
+	"metroid": {
+		description: "Start game, move Samus",
+		sequence: [
+			{ type: "wait", frames: sec(3) },      // Wait for title
+			{ type: "press", button: "start" },    // Press Start
+			{ type: "wait", frames: sec(2) },      // Wait for game
+			{ type: "hold", button: "right", frames: 30 },  // Move right
+			{ type: "wait", frames: 10 },
+			{ type: "hold", button: "left", frames: 30 },   // Move left
+		],
+		postSequenceFrames: 60,
+	},
+};
+
+/**
+ * Find a script for a ROM by filename
+ */
+export function findScript(romFilename: string): GameScript | null {
+	const baseName = romFilename
+		.replace(/\.nes$/i, "")
+		.toLowerCase();
+	
+	// Exact match first
+	if (GAME_SCRIPTS[baseName]) {
+		return GAME_SCRIPTS[baseName];
+	}
+
+	// Partial match (for ROMs with extra suffixes)
+	for (const [key, script] of Object.entries(GAME_SCRIPTS)) {
+		if (baseName.includes(key) || key.includes(baseName)) {
+			return script;
+		}
+	}
+
+	return null;
+}

package/tests/input-map.test.ts

@@ -0,0 +1,46 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { getMappedButtons, DEFAULT_INPUT_MAPPING } from "../extensions/nes/input-map.js";
+
+describe("input-map", () => {
+	describe("DEFAULT_INPUT_MAPPING", () => {
+		test("has all required buttons", () => {
+			const buttons = ["up", "down", "left", "right", "a", "b", "start", "select"];
+			for (const button of buttons) {
+				assert.ok(button in DEFAULT_INPUT_MAPPING, `Missing button: ${button}`);
+				assert.ok(Array.isArray(DEFAULT_INPUT_MAPPING[button as keyof typeof DEFAULT_INPUT_MAPPING]));
+			}
+		});
+	});
+
+	describe("getMappedButtons", () => {
+		test("maps 'z' to 'a' button", () => {
+			const buttons = getMappedButtons("z");
+			assert.ok(buttons.includes("a"), `Expected 'a' in ${JSON.stringify(buttons)}`);
+		});
+
+		test("maps 'x' to 'b' button", () => {
+			const buttons = getMappedButtons("x");
+			assert.ok(buttons.includes("b"), `Expected 'b' in ${JSON.stringify(buttons)}`);
+		});
+
+		test("maps 'w' to 'up' button", () => {
+			const buttons = getMappedButtons("w");
+			assert.ok(buttons.includes("up"), `Expected 'up' in ${JSON.stringify(buttons)}`);
+		});
+
+		test("returns empty for unmapped key", () => {
+			const buttons = getMappedButtons("q");
+			assert.strictEqual(buttons.length, 0);
+		});
+
+		test("uses custom mapping when provided", () => {
+			const customMapping = {
+				...DEFAULT_INPUT_MAPPING,
+				a: ["k"],
+			};
+			const buttons = getMappedButtons("k", customMapping);
+			assert.ok(buttons.includes("a"));
+		});
+	});
+});

package/tests/paths.test.ts

@@ -0,0 +1,78 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import os from "node:os";
+import path from "node:path";
+import { displayPath, expandHomePath, normalizePath, resolvePathInput } from "../extensions/nes/paths.js";
+
+const HOME = os.homedir();
+
+describe("paths", () => {
+	describe("displayPath", () => {
+		test("replaces home directory with ~", () => {
+			assert.strictEqual(displayPath(`${HOME}/roms/nes`), "~/roms/nes");
+		});
+
+		test("leaves non-home paths unchanged", () => {
+			assert.strictEqual(displayPath("/usr/local/bin"), "/usr/local/bin");
+		});
+
+		test("handles home directory exactly", () => {
+			assert.strictEqual(displayPath(HOME), "~");
+		});
+	});
+
+	describe("expandHomePath", () => {
+		test("expands ~ to home directory", () => {
+			assert.strictEqual(expandHomePath("~"), HOME);
+		});
+
+		test("expands ~/path to home + path", () => {
+			assert.strictEqual(expandHomePath("~/roms/nes"), path.join(HOME, "roms/nes"));
+		});
+
+		test("leaves absolute paths unchanged", () => {
+			assert.strictEqual(expandHomePath("/usr/local"), "/usr/local");
+		});
+
+		test("leaves relative paths unchanged", () => {
+			assert.strictEqual(expandHomePath("roms/nes"), "roms/nes");
+		});
+	});
+
+	describe("normalizePath", () => {
+		test("returns fallback for empty string", () => {
+			assert.strictEqual(normalizePath("", "/default"), "/default");
+		});
+
+		test("returns fallback for whitespace-only", () => {
+			assert.strictEqual(normalizePath("   ", "/default"), "/default");
+		});
+
+		test("expands ~ and returns path", () => {
+			assert.strictEqual(normalizePath("~/roms", "/default"), path.join(HOME, "roms"));
+		});
+
+		test("trims whitespace", () => {
+			assert.strictEqual(normalizePath("  /roms  ", "/default"), "/roms");
+		});
+	});
+
+	describe("resolvePathInput", () => {
+		test("returns cwd for empty input", () => {
+			assert.strictEqual(resolvePathInput("", "/home/user"), "/home/user");
+		});
+
+		test("expands ~ paths", () => {
+			assert.strictEqual(resolvePathInput("~/roms", "/cwd"), path.join(HOME, "roms"));
+		});
+
+		test("resolves relative paths against cwd", () => {
+			const result = resolvePathInput("roms/nes", "/home/user");
+			assert.strictEqual(result, "/home/user/roms/nes");
+		});
+
+		test("keeps absolute paths as-is", () => {
+			assert.strictEqual(resolvePathInput("/absolute/path", "/cwd"), "/absolute/path");
+		});
+	});
+});