@tmustier/pi-nes 0.2.20 → 0.2.22

package/README.md

@@ -86,6 +86,12 @@ Config is stored at `~/.pi/nes/config.json`. Use `/nes config` for quick setup.
 | `imageQuality` | `"balanced"` | `"balanced"` (30 fps) or `"high"` (60 fps) |
 | `pixelScale` | `1.0` | Display scale (0.5–4.0) |
 
+## Saves
+
+Battery-backed SRAM is saved to `<saveDir>/<rom-name>-<hash>.sav` where the hash is derived from the full ROM path to avoid collisions. Old `<rom-name>.sav` files are ignored.
+
+Saves are flushed on quit and periodically during play.
+
 ## Terminal Support
 
 **Best experience:** a Kitty-protocol terminal like Ghostty, Kitty, or WezTerm (image protocol + key-up events).

package/extensions/nes/config.ts

@@ -47,17 +47,26 @@ export function getConfigPath(): string {
 	return path.join(os.homedir(), ".pi", "nes", "config.json");
 }
 
+function resolveConfigPath(value: string): string {
+	if (path.isAbsolute(value)) {
+		return value;
+	}
+	return path.resolve(path.dirname(getConfigPath()), value);
+}
+
 export function normalizeConfig(raw: unknown): NesConfig {
 	const parsed = typeof raw === "object" && raw !== null ? (raw as RawConfig) : {};
-	const romDir =
+	const romDirInput =
 		typeof parsed.romDir === "string" && parsed.romDir.length > 0
-			? normalizePath(parsed.romDir, DEFAULT_CONFIG.romDir)
+			? parsed.romDir
 			: DEFAULT_CONFIG.romDir;
+	const romDir = resolveConfigPath(normalizePath(romDirInput, DEFAULT_CONFIG.romDir));
 	const saveDirFallback = getDefaultSaveDir(romDir);
-	const saveDir =
+	const saveDirInput =
 		typeof parsed.saveDir === "string" && parsed.saveDir.length > 0
-			? normalizePath(parsed.saveDir, saveDirFallback)
+			? parsed.saveDir
 			: saveDirFallback;
+	const saveDir = resolveConfigPath(normalizePath(saveDirInput, saveDirFallback));
 	const imageQuality = normalizeImageQuality(parsed.imageQuality);
 	const pixelScale = normalizePixelScale(parsed.pixelScale);
 	return {
@@ -80,7 +89,12 @@ export async function loadConfig(): Promise<NesConfig> {
 	let config: NesConfig;
 	try {
 		const raw = await fs.readFile(configPath, "utf8");
-		config = normalizeConfig(JSON.parse(raw));
+		const parsed = JSON.parse(raw);
+		const normalized = normalizeConfig(parsed);
+		if (raw.trim() !== formatConfig(normalized)) {
+			await saveConfig(normalized);
+		}
+		config = normalized;
 	} catch {
 		config = DEFAULT_CONFIG;
 	}

package/extensions/nes/index.ts

@@ -24,6 +24,7 @@ const TEXT_RENDER_INTERVAL_MS = 1000 / 60;
 
 let activeSession: NesSession | null = null;
 
+// ROM selection helpers.
 async function selectRom(
 	args: string | undefined,
 	romDir: string,
@@ -43,21 +44,24 @@ async function selectRom(
 			return null;
 		}
 
-		const selection = await ctx.ui.select(
-			"Select a ROM",
-			roms.map((rom) => rom.name),
-		);
+		const options = roms.map((rom, index) => `${index + 1}. ${rom.name}`);
+		const selection = await ctx.ui.select("Select a ROM", options);
 		if (!selection) {
 			return null;
 		}
-		const match = roms.find((rom) => rom.name === selection);
-		return match?.path ?? null;
+		const index = options.indexOf(selection);
+		if (index < 0) {
+			ctx.ui.notify("ROM selection failed. Please try again.", "error");
+			return null;
+		}
+		return roms[index]?.path ?? null;
 	} catch {
 		ctx.ui.notify(`Failed to read ROM directory: ${romDir}. Update ${configPath} to set romDir.`, "error");
 		return null;
 	}
 }
 
+// Command argument parsing.
 function parseArgs(args?: string): { debug: boolean; romArg?: string } {
 	if (!args) {
 		return { debug: false, romArg: undefined };
@@ -79,6 +83,7 @@ function parseArgs(args?: string): { debug: boolean; romArg?: string } {
 	return { debug: false, romArg: trimmed };
 }
 
+// ROM directory validation/creation.
 async function ensureRomDir(pathValue: string, ctx: ExtensionCommandContext): Promise<boolean> {
 	try {
 		const stat = await fs.stat(pathValue);
@@ -99,20 +104,7 @@ async function ensureRomDir(pathValue: string, ctx: ExtensionCommandContext): Pr
 	}
 }
 
-async function validateRomDir(pathValue: string, ctx: ExtensionCommandContext): Promise<boolean> {
-	try {
-		const stat = await fs.stat(pathValue);
-		if (!stat.isDirectory()) {
-			ctx.ui.notify(`ROM directory is not a folder: ${pathValue}`, "error");
-			return false;
-		}
-		return true;
-	} catch {
-		ctx.ui.notify(`ROM directory not found: ${pathValue}`, "error");
-		return false;
-	}
-}
-
+// Config UI.
 async function editConfigJson(
 	ctx: ExtensionCommandContext,
 	config: Awaited<ReturnType<typeof loadConfig>>,
@@ -145,7 +137,7 @@ async function configureWithWizard(
 	const romDirDefaultLabel = config.romDir === DEFAULT_CONFIG.romDir ? "Use default" : "Use current";
 	const romDirOptions = [
 		`${romDirDefaultLabel} (${romDirDisplay}) — creates if missing`,
-		"Enter a custom path (must exist)",
+		"Enter a custom path (creates if missing)",
 	];
 	const romDirChoice = await ctx.ui.select("ROM directory", romDirOptions);
 	if (!romDirChoice) {
@@ -164,8 +156,8 @@ async function configureWithWizard(
 			return false;
 		}
 		romDir = resolvePathInput(trimmedRomDir, ctx.cwd);
-		const valid = await validateRomDir(romDir, ctx);
-		if (!valid) {
+		const ensured = await ensureRomDir(romDir, ctx);
+		if (!ensured) {
 			return false;
 		}
 	} else {
@@ -233,6 +225,7 @@ async function editConfig(ctx: ExtensionCommandContext): Promise<void> {
 	ctx.ui.notify(`Saved config to ${getConfigPath()}`, "info");
 }
 
+// Session lifecycle.
 async function createSession(romPath: string, ctx: ExtensionCommandContext, config: Awaited<ReturnType<typeof loadConfig>>): Promise<NesSession | null> {
 	let romData: Uint8Array;
 	try {
@@ -249,7 +242,7 @@ async function createSession(romPath: string, ctx: ExtensionCommandContext, conf
 		const message = error instanceof Error ? error.message : String(error);
 		ctx.ui.notify(`Failed to initialize NES core: ${message}`, "error");
 		ctx.ui.notify(
-			"Build native core: cd ~/Projects/pi-nes/extensions/nes/native/nes-core && npm install && npm run build",
+			"Build native core: cd extensions/nes/native/nes-core && npm install && npm run build",
 			"warning",
 		);
 		return null;
@@ -335,6 +328,7 @@ async function attachSession(
 	return shouldStop;
 }
 
+// Command registration.
 export default function (pi: ExtensionAPI) {
 	pi.on("session_shutdown", async () => {
 		if (activeSession) {

package/extensions/nes/native/nes-core/index.d.ts

@@ -1,5 +1,3 @@
-export function nativeVersion(): string;
-
 export interface CpuDebugState {
   pc: number;
   a: number;
@@ -33,7 +31,6 @@ export class NativeNes {
   bootup(): void;
   stepFrame(): void;
   refreshFramebuffer(): void;
-  reset(): void;
   pressButton(button: number): void;
   releaseButton(button: number): void;
   hasBatteryBackedRam(): boolean;

package/extensions/nes/native/nes-core/native.d.ts

@@ -3,7 +3,6 @@
 
 /* auto-generated by NAPI-RS */
 
-export declare function nativeVersion(): string
 export interface CpuDebugState {
   pc: number
   a: number
@@ -34,7 +33,6 @@ export declare class NativeNes {
   bootup(): void
   stepFrame(): void
   refreshFramebuffer(): void
-  reset(): void
   pressButton(button: number): void
   releaseButton(button: number): void
   hasBatteryBackedRam(): boolean

package/extensions/nes/native/nes-core/src/lib.rs

@@ -7,11 +7,6 @@ use nes_rust::display::{Display, SCREEN_HEIGHT, SCREEN_WIDTH};
 use nes_rust::rom::Rom;
 use nes_rust::Nes;
 
-#[napi]
-pub fn native_version() -> String {
-	env!("CARGO_PKG_VERSION").to_string()
-}
-
 struct NativeDisplay {
 	pixels: Vec<u8>,
 }
@@ -119,11 +114,6 @@ impl NativeNes {
 		self.nes.copy_pixels(&mut self.framebuffer);
 	}
 
-	#[napi]
-	pub fn reset(&mut self) {
-		self.nes.reset();
-	}
-
 	#[napi]
 	pub fn press_button(&mut self, button: u8) {
 		if let Some(mapped) = map_button(button) {

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.20",
+  "version": "0.2.22",
   "description": "NES emulator extension for pi",
   "keywords": [
     "pi-package",

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).