@tmustier/pi-nes 0.2.36 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-nes",
-  "version": "0.2.36",
+  "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"
   }
 }