@tmustier/pi-nes 0.2.35 → 0.2.37

package/AGENTS.md

@@ -20,11 +20,12 @@ pi-nes/
     ├── config.ts             # User config (~/.pi/nes/config.json)
     ├── paths.ts              # Path resolution utilities
     ├── roms.ts               # ROM directory listing
+    ├── rom-selector.ts       # Filterable ROM picker UI
     ├── saves.ts              # SRAM persistence
     └── native/
         ├── nes-core/         # Rust NES emulator addon (required)
-        │   ├── Cargo.toml    # Dependencies: vendored nes_rust, napi
-        │   ├── vendor/nes_rust/ # Patched nes_rust crate (SRAM helpers)
+        │   ├── Cargo.toml    # Dependencies: vendored nes_rust, napi, optional cpal
+        │   ├── vendor/nes_rust/ # Patched nes_rust crate (SRAM helpers + mapper fixes)
         │   ├── src/lib.rs    # Exposes NativeNes class via napi-rs
         │   └── index.node    # Compiled binary
         └── kitty-shm/        # Rust shared memory addon (optional)
@@ -34,7 +35,7 @@ pi-nes/
 
 ### Native Core
 
-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.
+The emulator uses the [`nes_rust`](https://crates.io/crates/nes_rust) crate (vendored + patched in `native/nes-core/vendor/nes_rust`) with [napi-rs](https://napi.rs) bindings. Optional audio uses a Rust-only backend (`cpal`) when built with `audio-cpal`.
 
 ### Vendored `nes_rust` workflow
 
@@ -46,12 +47,16 @@ The emulator uses the [`nes_rust`](https://crates.io/crates/nes_rust) crate (ven
 **API exposed to JavaScript:**
 - `new NativeNes()` - Create emulator instance
 - `setRom(Uint8Array)` - Load ROM data
-- `bootup()` / `reset()` - Start/restart emulation
+- `bootup()` - Start emulation
 - `stepFrame()` - Advance one frame (~60fps)
+- `refreshFramebuffer()` - Copy framebuffer from core
 - `pressButton(n)` / `releaseButton(n)` - Controller input (0=select, 1=start, 2=A, 3=B, 4-7=dpad)
+- `setVideoFilter(mode)` - 0=off, 1=ntsc-composite, 2=ntsc-svideo, 3=ntsc-rgb
+- `setAudioEnabled(bool)` - Returns false if audio backend unavailable
 - `hasBatteryBackedRam()` - Whether the ROM supports battery SRAM
 - `getSram()` / `setSram(Uint8Array)` - Read/write SRAM
 - `isSramDirty()` / `markSramSaved()` - Dirty tracking for SRAM persistence
+- `getDebugState()` - CPU/mapper debug info
 - `getFramebuffer()` - Returns RGB pixel data (256×240×3 bytes, zero-copy via external buffer)
 
 ### Rendering Pipeline
@@ -67,7 +72,7 @@ NES Core → RGB framebuffer (256×240×3) → Renderer → Terminal
 
 - Image mode (`renderer: "image"`) runs at ~30fps to keep emulation stable
 - Text mode (`renderer: "text"`) runs at ~60fps in an overlay
-- Image mode uses near-fullscreen (90% height) because Kitty graphics can't composite in overlays
+- Image mode uses a windowed overlay (90% width/height) to avoid Kitty full-screen artifacts
 
 ### Session Lifecycle
 
@@ -86,8 +91,11 @@ Requires Rust toolchain (cargo + rustc).
 cd extensions/nes/native/nes-core
 npm install && npm run build
 
+# NES core with audio (optional)
+npm run build:audio
+
 # Kitty shared memory (optional, faster rendering)
-cd extensions/nes/native/kitty-shm
+cd ../kitty-shm
 npm install && npm run build
 ```
 
@@ -95,13 +103,13 @@ The addons compile to `index.node`. The JS wrapper (`index.js`) tries to load it
 
 ## Known Limitations
 
-- **No audio** — `enableAudio` config exists but no audio backend is implemented
-- **No save states** — Only battery-backed SRAM saves are persisted
-- **SRAM for native core** — Tracked in issue #3
+- **Audio is opt-in** — Requires a native core built with `audio-cpal` and `enableAudio: true`.
+- **Overlay flicker** — Kitty overlay can show a 1-line flicker at overlay boundaries (see issue #9).
+- **No save states** — Only battery-backed SRAM saves are persisted.
 
 ## Release and Publishing
 
-## Version Bumps (Git + npm)
+### Version Bumps (Git + npm)
 
 Preferred flow (creates a git tag):
 
@@ -127,7 +135,7 @@ git push
 git push --tags
 ```
 
-## npm Publish
+### npm Publish
 
 ```bash
 npm login
@@ -140,7 +148,7 @@ If you need to validate the tarball first:
 npm pack
 ```
 
-## GitHub Release Notes
+### GitHub Release Notes
 
 ```bash
 gh release create vX.Y.Z --title "vX.Y.Z" --notes "<release notes>"

package/README.md

@@ -51,13 +51,13 @@ On first run, you'll be prompted to set your ROM directory and display quality.
 |---------|-------------|
 | `/nes` | Pick a ROM or reattach to running session |
 | `/nes <path>` | Load a specific ROM file |
-| `/nes config` | Configure ROM directory and quality |
-| `/nes-config` | Toggle audio + access advanced config options |
+| `/nes config` | Quick setup (ROM directory + audio) |
+| `/nes-config` | Toggle audio, quality, and display style + advanced options |
 | `/nes debug` | Show FPS and memory stats |
 
 ## Configuration
 
-Config is stored at `~/.pi/nes/config.json`. Use `/nes config` for quick setup, or `/nes-config` to toggle audio inline and access advanced options.
+Config is stored at `~/.pi/nes/config.json`. Use `/nes config` for quick setup (ROM dir + audio), or `/nes-config` to toggle audio/quality/style inline and access advanced options.
 
 ```json
 {

package/extensions/nes/index.ts

@@ -14,6 +14,7 @@ import {
 	loadConfig,
 	normalizeConfig,
 	saveConfig,
+	type ImageQuality,
 	type NesConfig,
 	type VideoFilter,
 } from "./config.js";
@@ -27,6 +28,17 @@ const IMAGE_RENDER_INTERVAL_BALANCED_MS = 1000 / 30;
 const IMAGE_RENDER_INTERVAL_HIGH_MS = 1000 / 60;
 const TEXT_RENDER_INTERVAL_MS = 1000 / 60;
 
+const AUDIO_OPTIONS = ["off (default)", "on"] as const;
+const QUALITY_OPTIONS: Array<{ label: string; value: ImageQuality }> = [
+	{ label: "Balanced (default) — 30 fps", value: "balanced" },
+	{ label: "High — 60 fps", value: "high" },
+];
+const DISPLAY_FILTER_OPTIONS: Array<{ label: string; value: VideoFilter }> = [
+	{ label: "CRT Classic (default) — authentic scanlines + color bleed", value: "ntsc-composite" },
+	{ label: "CRT Soft — subtle retro look", value: "ntsc-rgb" },
+	{ label: "Sharp — pixel-perfect, no filtering", value: "off" },
+];
+
 let activeSession: NesSession | null = null;
 
 // ROM selection helpers.
@@ -163,31 +175,13 @@ async function configureWithWizard(
 		}
 	}
 
-	const qualityChoice = await ctx.ui.select("Quality", [
-		"Balanced (recommended) — 30 fps",
-		"High — 60 fps",
-	]);
-	if (!qualityChoice) {
-		return false;
-	}
-
-	const isHighQuality = qualityChoice.startsWith("High");
-	const imageQuality = isHighQuality ? "high" : "balanced";
-
-	const filterOptions: Array<{ label: string; value: VideoFilter }> = [
-		{ label: "CRT Classic (default) — authentic scanlines + color bleed", value: "ntsc-composite" },
-		{ label: "CRT Soft — subtle retro look", value: "ntsc-rgb" },
-		{ label: "Sharp — pixel-perfect, no filtering", value: "off" },
-	];
-	const filterChoice = await ctx.ui.select(
-		"Display style",
-		filterOptions.map((option) => option.label),
-	);
-	if (!filterChoice) {
+	const audioChoice = await ctx.ui.select("Audio", ["Off (default)", "On"]);
+	if (!audioChoice) {
 		return false;
 	}
-	const videoFilter =
-		filterOptions.find((option) => option.label === filterChoice)?.value ?? DEFAULT_CONFIG.videoFilter;
+	const enableAudio = audioChoice === "On";
+	const imageQuality = config.imageQuality;
+	const videoFilter = config.videoFilter;
 	const pixelScale = config.pixelScale;
 
 	const defaultSaveDir = getDefaultSaveDir(config.romDir);
@@ -197,35 +191,62 @@ async function configureWithWizard(
 		...config,
 		romDir,
 		saveDir,
+		enableAudio,
 		imageQuality,
 		videoFilter,
 		pixelScale,
 	});
 	await saveConfig(normalized);
 	ctx.ui.notify(`Saved config to ${getConfigPath()}`, "info");
+	await ctx.ui.select(
+		"Toggle audio, quality, and more in /nes-config",
+		["Run /nes to load your games"],
+	);
 	return true;
 }
 
 type ConfigMenuResult = "close" | "more";
 
+type ConfigUpdate = Partial<NesConfig>;
+
 class NesConfigMenu extends Container {
 	private readonly settingsList: SettingsList;
 
 	constructor(
 		config: NesConfig,
 		theme: Theme,
-		onAudioChange: (enabled: boolean) => void,
+		onUpdate: (update: ConfigUpdate) => void,
 		onDone: (result: ConfigMenuResult) => void,
 	) {
 		super();
 		const audioValue = config.enableAudio ? "on" : "off (default)";
+		const qualityValue =
+			QUALITY_OPTIONS.find((option) => option.value === config.imageQuality)?.label
+			?? QUALITY_OPTIONS[0].label;
+		const displayValue =
+			DISPLAY_FILTER_OPTIONS.find((option) => option.value === config.videoFilter)?.label
+			?? DISPLAY_FILTER_OPTIONS[0].label;
 		const items: SettingItem[] = [
 			{
 				id: "audio",
 				label: "Audio",
 				description: "Enable audio output (requires native core built with audio-cpal)",
 				currentValue: audioValue,
-				values: ["off (default)", "on"],
+				values: [...AUDIO_OPTIONS],
+			},
+			{
+				id: "quality",
+				label: "Quality",
+				description: "Target frame rate for image rendering",
+				currentValue: qualityValue,
+				values: QUALITY_OPTIONS.map((option) => option.label),
+			},
+			{
+				id: "display",
+				label: "Display style",
+				description: "CRT filter preset (applied in the native core)",
+				currentValue: displayValue,
+				values: DISPLAY_FILTER_OPTIONS.map((option) => option.label),
 			},
 			{
 				id: "more",
@@ -238,11 +259,21 @@ class NesConfigMenu extends Container {
 
 		this.settingsList = new SettingsList(
 			items,
-			6,
+			8,
 			getSettingsListTheme(),
 			(id, value) => {
 				if (id === "audio") {
-					onAudioChange(value === "on");
+					onUpdate({ enableAudio: value === "on" });
+					return;
+				}
+				if (id === "quality") {
+					const option = QUALITY_OPTIONS.find((entry) => entry.label === value);
+					onUpdate({ imageQuality: option?.value ?? config.imageQuality });
+					return;
+				}
+				if (id === "display") {
+					const option = DISPLAY_FILTER_OPTIONS.find((entry) => entry.label === value);
+					onUpdate({ videoFilter: option?.value ?? config.videoFilter });
 					return;
 				}
 				if (id === "more") {
@@ -271,20 +302,14 @@ async function editConfig(ctx: ExtensionCommandContext): Promise<void> {
 		return;
 	}
 	const config = await loadConfig();
+	const updateConfig = async (update: ConfigUpdate) => {
+		const normalized = normalizeConfig({ ...config, ...update });
+		await saveConfig(normalized);
+		Object.assign(config, normalized);
+		ctx.ui.notify(`Saved config to ${getConfigPath()}`, "info");
+	};
 	const action = await ctx.ui.custom<ConfigMenuResult>((_tui, theme, _keybindings, done) =>
-		new NesConfigMenu(
-			config,
-			theme,
-			(enabled) => {
-				void (async () => {
-					const normalized = normalizeConfig({ ...config, enableAudio: enabled });
-					await saveConfig(normalized);
-					config.enableAudio = normalized.enableAudio;
-					ctx.ui.notify(`Saved config to ${getConfigPath()}`, "info");
-				})();
-			},
-			done,
-		),
+		new NesConfigMenu(config, theme, (update) => void updateConfig(update), done),
 	);
 	if (action !== "more") {
 		return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-nes",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "description": "NES emulator extension for pi",
   "keywords": [
     "pi-package",
@@ -33,6 +33,7 @@
   "pi": {
     "extensions": [
       "./extensions/nes"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/tmustier/pi-nes/main/assets/demo.gif"
   }
 }