@tmustier/pi-nes 0.2.4 → 0.2.6

package/AGENTS.md

@@ -1,6 +1,94 @@
 # AGENTS.md
 
-Project guidance for release and publishing.
+Technical guidance for AI agents working on this codebase.
+
+## Architecture
+
+pi-nes is a NES emulator extension for [pi](https://github.com/mariozechner/pi). It uses a Rust-based emulator core compiled as a Node.js native addon.
+
+### Project Structure
+
+```
+pi-nes/
+├── package.json              # Pi package manifest (pi.extensions points to ./extensions/nes)
+└── extensions/nes/
+    ├── index.ts              # Extension entry - registers /nes and /nes-config commands
+    ├── nes-core.ts           # TypeScript wrapper for native addon
+    ├── nes-session.ts        # Game session management (frame timing, SRAM saves)
+    ├── nes-component.ts      # TUI overlay component (input handling, render loop)
+    ├── renderer.ts           # Frame rendering (Kitty image protocol, PNG, ANSI)
+    ├── config.ts             # User config (~/.pi/nes/config.json)
+    ├── paths.ts              # Path resolution utilities
+    ├── roms.ts               # ROM directory listing
+    ├── saves.ts              # SRAM persistence
+    └── native/
+        ├── nes-core/         # Rust NES emulator addon (required)
+        │   ├── Cargo.toml    # Dependencies: nes_rust, napi
+        │   ├── src/lib.rs    # Exposes NativeNes class via napi-rs
+        │   └── index.node    # Compiled binary
+        └── kitty-shm/        # Rust shared memory addon (optional)
+            ├── src/lib.rs    # POSIX shm_open/mmap for zero-copy frames
+            └── index.node    # Compiled binary
+```
+
+### Native Core
+
+The emulator uses the [`nes_rust`](https://crates.io/crates/nes_rust) crate with [napi-rs](https://napi.rs) bindings.
+
+**API exposed to JavaScript:**
+- `new NativeNes()` - Create emulator instance
+- `setRom(Uint8Array)` - Load ROM data
+- `bootup()` / `reset()` - Start/restart emulation
+- `stepFrame()` - Advance one frame (~60fps)
+- `pressButton(n)` / `releaseButton(n)` - Controller input (0=select, 1=start, 2=A, 3=B, 4-7=dpad)
+- `getFramebuffer()` - Returns RGB pixel data (256×240×3 bytes, zero-copy via external buffer)
+
+### Rendering Pipeline
+
+```
+NES Core → RGB framebuffer (256×240×3) → Renderer → Terminal
+                                           │
+                                           ├─ Kitty shared memory (t=s) — fastest, requires kitty-shm addon
+                                           ├─ Kitty file transport (t=f) — writes to /dev/shm or temp file
+                                           ├─ Kitty PNG — base64-encoded PNG fallback
+                                           └─ ANSI half-blocks — ▀▄ characters, works everywhere
+```
+
+- 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
+
+### Session Lifecycle
+
+1. `/nes` creates a `NesSession` that owns the core and runs the frame loop
+2. `NesOverlayComponent` attaches to display frames and handle input
+3. `Ctrl+Q` detaches the component but keeps the session running in background
+4. `/nes` reattaches to existing session; `/nes <path>` starts a new one
+5. `Q` or `session_shutdown` event stops the session and disposes the core
+
+## Building Native Addons
+
+Requires Rust toolchain (cargo + rustc).
+
+```bash
+# NES core (required)
+cd extensions/nes/native/nes-core
+npm install && npm run build
+
+# Kitty shared memory (optional, faster rendering)
+cd extensions/nes/native/kitty-shm
+npm install && npm run build
+```
+
+The addons compile to `index.node`. The JS wrapper (`index.js`) tries to load it and exports `isAvailable: boolean`.
+
+## 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
+
+## Release and Publishing
 
 ## Version Bumps (Git + npm)
 

package/README.md

@@ -1,72 +1,65 @@
 # pi-nes
 
-NES emulator extension for pi (targeting Kitty).
+Play NES games in your terminal. A [pi](https://github.com/mariozechner/pi) extension that runs a full NES emulator with Kitty graphics support.
 
-## Setup
+## Installation
 
 ```bash
-cd /Users/thomasmustier/projects/pi-nes
-npm install
+pi install npm:@tmustier/pi-nes
 ```
 
-### Build native addons (required core + optional Kitty shared memory)
+Or from git:
+```bash
+pi install git:github.com/tmustier/pi-nes
+```
 
-Requires a Rust toolchain (cargo + rustc).
+## Quick Start
 
 ```bash
-# Native NES core (required)
-cd /Users/thomasmustier/projects/pi-nes/extensions/nes/native/nes-core
-npm install
-npm run build
-
-# Kitty shared-memory renderer (optional, faster)
-cd /Users/thomasmustier/projects/pi-nes/extensions/nes/native/kitty-shm
-npm install
-npm run build
+/nes              # Pick a ROM from your library
+/nes ~/roms/smb.nes   # Load a specific ROM
 ```
 
-If the native core addon isn’t built, `/nes` will show an error and exit. The shared-memory renderer is optional; we fall back to the Kitty file transport if it’s missing.
+On first run, you'll be prompted to set your ROM directory and display quality.
 
-## Install as a pi package
+## Controls
 
-```bash
-# From npm
-pi install npm:@tmustier/pi-nes
+### Game Controls
 
-# From git
-pi install git:github.com/tmustier/pi-nes
-```
+| Action | Keys |
+|--------|------|
+| D-pad | Arrow keys or WASD |
+| A button | Z |
+| B button | X |
+| Start | Enter or Space |
+| Select | Tab |
 
-## Usage
+### Emulator Controls
 
-```bash
-# Local path
-pi --extension /Users/thomasmustier/projects/pi-nes
-```
+| Action | Key |
+|--------|-----|
+| Detach (keep running) | Ctrl+Q |
+| Quit | Q |
 
-Commands:
-- `/nes` — pick a ROM from the configured directory or reattach to a running session
-- `/nes <path>` — load a specific ROM
-- `/nes debug [<path>]` — enable debug overlay (FPS/memory stats)
-- `/nes config` — guided configuration (ROM directory + quality)
-- `/nes-config` — edit configuration (alias)
+**Tip:** Detach with `Ctrl+Q` to return to pi, then run `/nes` to reattach to your game.
 
-Controls:
-- `Ctrl+Q` — detach overlay (keeps the session running)
-- `Q` — quit emulator
+## Commands
 
-Note: if a session is running, `/nes` reattaches. Use `/nes <path>` to start a new ROM.
+| Command | Description |
+|---------|-------------|
+| `/nes` | Pick a ROM or reattach to running session |
+| `/nes <path>` | Load a specific ROM file |
+| `/nes config` | Configure ROM directory and quality |
+| `/nes debug` | Show FPS and memory stats |
 
 ## Configuration
 
-Config file: `~/.pi/nes/config.json` (use `/nes config` for guided setup or `/nes-config` to edit JSON directly). On first run, `/nes` will prompt you to configure ROM directory + quality.
+Config is stored at `~/.pi/nes/config.json`. Use `/nes config` for guided setup.
 
-Example:
 ```json
 {
   "romDir": "/roms/nes",
-  "saveDir": "/Users/you/.pi/nes/saves",
-  "enableAudio": false,
+  "saveDir": "/roms/nes/saves",
   "renderer": "image",
   "pixelScale": 1.2,
   "keybindings": {
@@ -82,14 +75,50 @@ Example:
 }
 ```
 
-## Core
+### Options
 
-The extension uses the **native Rust core** only (required build step). Battery-backed SRAM persistence for native is tracked in issue #3.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `romDir` | `/roms/nes` | Where to look for ROM files |
+| `saveDir` | `/roms/nes/saves` | Where to store battery saves (defaults to `<romDir>/saves`) |
+| `renderer` | `"image"` | `"image"` (Kitty graphics) or `"text"` (ANSI) |
+| `pixelScale` | `1.2` | Display scale (0.5–4.0) |
 
-## Rendering
+## Terminal Support
 
-Default renderer is `image`, which uses Kitty's image protocol for high resolution. On Kitty, we **prefer shared-memory transport (`t=s`)** when the native addon is built, falling back to the **file transport (`t=f`)** path if the addon isn’t available; non-Kitty terminals fall back to PNG. Image mode runs **nearly full-screen** (no overlay) because Kitty graphics sequences can't be safely composited inside overlays; it caps to ~90% height and centers vertically + horizontally to reduce terminal compositor load. Image mode also **throttles rendering to ~30fps** to keep emulation speed stable. Set `renderer: "text"` if you prefer ANSI half-block rendering in an overlay. You can tweak `pixelScale` to 1.5–2.0 for larger images in PNG mode.
+**Best experience:** [Kitty](https://sw.kovidgoyal.net/kitty/) terminal with image protocol support.
 
-## Audio
+- **Kitty** — Full graphics via image protocol (shared memory or file transport)
+- **Other terminals** — Falls back to ANSI half-block characters (`▀▄`)
 
-Audio output is currently disabled (no safe dependency selected). If you set `enableAudio: true`, the extension will warn and continue in silent mode.
+Set `"renderer": "text"` if you prefer the ANSI renderer or have display issues.
+
+## Limitations
+
+- **No audio** — Sound is not currently supported
+- **No save states** — Only battery-backed SRAM saves work
+
+---
+
+## Building from Source
+
+Requires Rust toolchain (cargo + rustc).
+
+```bash
+git clone https://github.com/tmustier/pi-nes
+cd pi-nes
+npm install
+
+# Build the NES core (required)
+cd extensions/nes/native/nes-core
+npm install && npm run build
+
+# Build shared memory renderer (optional, faster on Kitty)
+cd ../kitty-shm
+npm install && npm run build
+```
+
+Run locally:
+```bash
+pi --extension /path/to/pi-nes
+```

package/extensions/nes/config.ts

@@ -15,9 +15,15 @@ export interface NesConfig {
 	keybindings: InputMapping;
 }
 
+const DEFAULT_ROM_DIR = path.join(path.sep, "roms", "nes");
+
+function defaultSaveDir(romDir: string): string {
+	return path.join(romDir, "saves");
+}
+
 export const DEFAULT_CONFIG: NesConfig = {
-	romDir: path.join(path.sep, "roms", "nes"),
-	saveDir: path.join(os.homedir(), ".pi", "nes", "saves"),
+	romDir: DEFAULT_ROM_DIR,
+	saveDir: defaultSaveDir(DEFAULT_ROM_DIR),
 	enableAudio: false,
 	renderer: "image",
 	pixelScale: 1.2,
@@ -39,15 +45,18 @@ export function getConfigPath(): string {
 
 export function normalizeConfig(raw: unknown): NesConfig {
 	const parsed = typeof raw === "object" && raw !== null ? (raw as RawConfig) : {};
+	const romDir =
+		typeof parsed.romDir === "string" && parsed.romDir.length > 0
+			? normalizePath(parsed.romDir, DEFAULT_CONFIG.romDir)
+			: DEFAULT_CONFIG.romDir;
+	const saveDirFallback = defaultSaveDir(romDir);
+	const saveDir =
+		typeof parsed.saveDir === "string" && parsed.saveDir.length > 0
+			? normalizePath(parsed.saveDir, saveDirFallback)
+			: saveDirFallback;
 	return {
-		romDir:
-			typeof parsed.romDir === "string" && parsed.romDir.length > 0
-				? normalizePath(parsed.romDir, DEFAULT_CONFIG.romDir)
-				: DEFAULT_CONFIG.romDir,
-		saveDir:
-			typeof parsed.saveDir === "string" && parsed.saveDir.length > 0
-				? normalizePath(parsed.saveDir, DEFAULT_CONFIG.saveDir)
-				: DEFAULT_CONFIG.saveDir,
+		romDir,
+		saveDir,
 		enableAudio: typeof parsed.enableAudio === "boolean" ? parsed.enableAudio : DEFAULT_CONFIG.enableAudio,
 		renderer: parsed.renderer === "text" ? "text" : DEFAULT_CONFIG.renderer,
 		pixelScale: normalizePixelScale(parsed.pixelScale),
@@ -61,12 +70,15 @@ export function formatConfig(config: NesConfig): string {
 
 export async function loadConfig(): Promise<NesConfig> {
 	const configPath = getConfigPath();
+	let config: NesConfig;
 	try {
 		const raw = await fs.readFile(configPath, "utf8");
-		return normalizeConfig(JSON.parse(raw));
+		config = normalizeConfig(JSON.parse(raw));
 	} catch {
-		return DEFAULT_CONFIG;
+		config = DEFAULT_CONFIG;
 	}
+	await ensureDirectory(config.saveDir);
+	return config;
 }
 
 export async function configExists(): Promise<boolean> {
@@ -84,6 +96,14 @@ export async function saveConfig(config: NesConfig): Promise<void> {
 	await fs.writeFile(configPath, formatConfig(config));
 }
 
+async function ensureDirectory(dirPath: string): Promise<void> {
+	try {
+		await fs.mkdir(dirPath, { recursive: true });
+	} catch {
+		// ignore
+	}
+}
+
 function normalizePixelScale(raw: unknown): number {
 	if (typeof raw !== "number" || Number.isNaN(raw)) {
 		return DEFAULT_CONFIG.pixelScale;

package/extensions/nes/native/nes-core/Cargo.lock

@@ -124,8 +124,6 @@ dependencies = [
 [[package]]
 name = "nes_rust"
 version = "0.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ee42b041b46e53bf4e4705ca0ffe66cbc7789929c3d013fa0700d7d61cf45c6"
 
 [[package]]
 name = "once_cell"

package/extensions/nes/native/nes-core/Cargo.toml

@@ -9,7 +9,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 libc = "0.2"
-nes_rust = "0.1.2"
+nes_rust = { path = "vendor/nes_rust" }
 napi = { version = "2", features = ["napi8"] }
 napi-derive = "2"
 

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

@@ -9,6 +9,11 @@ export class NativeNes {
   reset(): void;
   pressButton(button: number): void;
   releaseButton(button: number): void;
+  hasBatteryBackedRam(): boolean;
+  getSram(): Uint8Array;
+  setSram(data: Uint8Array): void;
+  isSramDirty(): boolean;
+  markSramSaved(): void;
   getFramebuffer(): Uint8Array;
 }
 

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

@@ -13,5 +13,10 @@ export declare class NativeNes {
   reset(): void
   pressButton(button: number): void
   releaseButton(button: number): void
+  hasBatteryBackedRam(): boolean
+  getSram(): Uint8Array
+  setSram(data: Uint8Array): void
+  isSramDirty(): boolean
+  markSramSaved(): void
   getFramebuffer(): Uint8Array
 }

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

@@ -108,6 +108,31 @@ impl NativeNes {
 		}
 	}
 
+	#[napi]
+	pub fn has_battery_backed_ram(&self) -> bool {
+		self.nes.has_battery_backed_ram()
+	}
+
+	#[napi]
+	pub fn get_sram(&self) -> Uint8Array {
+		Uint8Array::from(self.nes.get_sram())
+	}
+
+	#[napi]
+	pub fn set_sram(&mut self, data: Uint8Array) {
+		self.nes.set_sram(data.to_vec());
+	}
+
+	#[napi]
+	pub fn is_sram_dirty(&self) -> bool {
+		self.nes.is_sram_dirty()
+	}
+
+	#[napi]
+	pub fn mark_sram_saved(&mut self) {
+		self.nes.mark_sram_saved();
+	}
+
 	#[napi]
 	pub fn get_framebuffer(&mut self) -> Uint8Array {
 		let ptr = self.framebuffer.as_mut_ptr();

package/extensions/nes/native/nes-core/vendor/nes_rust/.cargo-ok

@@ -0,0 +1 @@
+{"v":1}

package/extensions/nes/native/nes-core/vendor/nes_rust/.cargo_vcs_info.json

@@ -0,0 +1,5 @@
+{
+  "git": {
+    "sha1": "3bedf08313ada63f709e909232b87b408fb40696"
+  }
+}

package/extensions/nes/native/nes-core/vendor/nes_rust/.travis.yml

@@ -0,0 +1,3 @@
+language: rust
+rust:
+  - stable

package/extensions/nes/native/nes-core/vendor/nes_rust/Cargo.toml

@@ -0,0 +1,23 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies
+#
+# If you believe there's an error in this file please file an
+# issue against the rust-lang/cargo repository. If you're
+# editing this file be aware that the upstream Cargo.toml
+# will likely look very different (and much more reasonable)
+
+[package]
+name = "nes_rust"
+version = "0.1.2"
+authors = ["Takahiro <hogehoge@gachapin.jp>"]
+exclude = ["resources/*", "screenshots/*", "roms/*", "cli/*", "wasm/*"]
+description = "NES emulator written in Rust"
+homepage = "https://github.com/takahirox/nes-rust"
+license = "MIT"
+repository = "https://github.com/takahirox/nes-rust"
+[badges.travis-ci]
+repository = "takahirox/nes-rust"

package/extensions/nes/native/nes-core/vendor/nes_rust/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Takahiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/nes/native/nes-core/vendor/nes_rust/README.md

@@ -0,0 +1,59 @@
+# nes-rust
+
+[![Build Status](https://travis-ci.com/takahirox/nes-rust.svg?branch=master)](https://travis-ci.com/takahirox/nes-rust)
+[![Crate](https://img.shields.io/crates/v/nes_rust.svg)](https://crates.io/crates/nes_rust)
+[![npm version](https://badge.fury.io/js/nes_rust_wasm.svg)](https://badge.fury.io/js/nes_rust_wasm)
+
+nes-rust is a NES emulator written in Rust. It can be compiled to WebAssembly.
+
+## Online Demos / Videos
+
+- [Online Singleplay Demo](https://takahirox.github.io/nes-rust/wasm/web/index.html)
+- [Online Multiplay Demo](https://takahirox.github.io/nes-rust/wasm/web/multiplay.html) / [Video](https://twitter.com/superhoge/status/1205427421010247680)
+- [Online VR Multiplay Demo](https://takahirox.github.io/nes-rust/wasm/web/vr.html) / [Video](https://twitter.com/superhoge/status/1209685614074875906)
+
+## Screenshots
+
+[nestest](http://wiki.nesdev.com/w/index.php/Emulator_tests)
+
+![nestest](./screenshots/nestest.png)
+
+[Sgt. Helmet Training Day](http://www.mojontwins.com/juegos_mojonos/sgt-helmet-training-day-nes/)
+
+![Sgt. Helmet Training Day](./screenshots/Sgt_Helmet.png)
+
+## Features
+
+- Audio support with SDL2 / WebAudio
+- WebAssembly support
+- Remote multiplay support with WebRTC
+
+## How to import into your Rust project
+
+The emulator module and document are released at [crates.io](https://crates.io/crates/nes_rust).
+
+## How to build core library locally
+
+```
+$ git clone https://github.com/takahirox/nes-rust.git
+$ cd nes-rust
+$ cargo build --release
+```
+
+## How to run as desktop application
+
+Prerequirements
+- Install [Rust-SDL2](https://github.com/Rust-SDL2/rust-sdl2#rust)
+
+```
+$ cd nes-rust/cli
+$ cargo run --release path_to_rom_file
+```
+
+## How to import and use WebAssembly NES emulator in a web browser
+
+See [wasm/web](https://github.com/takahirox/nes-rust/tree/master/wasm/web)
+
+## How to install and use WebAssembly NES emulator npm package
+
+See [wasm/npm](https://github.com/takahirox/nes-rust/tree/master/wasm/npm)