romdevtools 0.21.0 → 0.22.0

package/examples/snes/main.asm

@@ -2,32 +2,49 @@
 ;
 ; What this does:
 ;   1. Standard SNES reset (sei, clc xce → native mode, stack at $1FFF).
-;   2. Uploads a single CGRAM color (bright blue) so you see a colored
-;      backdrop — proof your build is running. NOT just a black screen.
-;   3. Turns on the screen at full brightness, then parks forever.
+;   2. Uploads a 4-colour palette + two 2bpp tiles to VRAM via DMA.
+;   3. Fills a 32x32 BG1 tilemap with a checkerboard of those two tiles
+;      so the whole screen shows a real tiled pattern — NOT a flat one-
+;      colour backdrop (which reads as "blank" to a human / the verifier).
+;   4. Points BG1 at the tile + map bases, enables BG1, turns the screen
+;      on at full brightness, then parks forever.
 ;
-; SUFFICIENT FOR: confirming your toolchain works + your user has
-; something to see in playtest. To go further (load tiles, set up BGs,
-; sprites, sound, vblank handler) see src/platforms/snes/lib/* snippets:
+; SUFFICIENT FOR: confirming your toolchain works AND showing your user a
+; real rendered screen in playtest. To go further (sprites, scrolling,
+; sound, a vblank handler) see src/platforms/snes/lib/* snippets:
 ;
 ;   listStarterSnippets({platform:"snes"})
 ;
 ; The key snippets are:
 ;   - lorom_header.asm: full SNES header (this scaffold's is minimal)
 ;   - cgram_upload.asm: palette upload boilerplate
-;   - vram_dma_upload.asm: fast tile/map uploads
+;   - vram_dma_upload.asm: fast tile/map uploads (used below)
 ;   - oam_upload.asm: sprite table writes
 ;   - nmi_safe.asm: vblank handler skeleton
 ;
 ; BUILD: complete LoROM image, no extra options needed.
-;   build({ output: "rom",  platform: "snes", source: /* this file */ });
+;   build({ output: "run",  platform: "snes", source: /* this file */ });
 
 lorom
 
+; ── PPU / DMA registers ────────────────────────────────────────────────
 INIDISP  = $2100   ; screen brightness / forced blank
+BGMODE   = $2105   ; BG mode + tile-size
+BG1SC    = $2107   ; BG1 tilemap base + size
+BG12NBA  = $210B   ; BG1/BG2 character (tile) base
+TM       = $212C   ; main-screen layer enable
 NMITIMEN = $4200
 CGADD    = $2121
 CGDATA   = $2122
+VMAIN    = $2115   ; VRAM address increment mode
+VMADDL   = $2116   ; VRAM word address (16-bit)
+VMDATAL  = $2118   ; VRAM data port (low)
+DMAP0    = $4300   ; DMA0 control
+BBAD0    = $4301   ; DMA0 B-bus address
+A1T0L    = $4302   ; DMA0 source address (16-bit)
+A1B0     = $4304   ; DMA0 source bank
+DAS0L    = $4305   ; DMA0 byte count (16-bit)
+MDMAEN   = $420B   ; DMA enable
 
 ; -----------------------------------------------------------------------
 org $008000
@@ -40,29 +57,103 @@ START:
         txs             ; stack at $1FFF
         sep #$20        ; A = 8-bit
 
-        ; Blank screen during init.
+        ; Blank screen during init; disable NMI/HDMA.
         lda #$80
         sta INIDISP
-
-        ; Disable interrupts.
         stz NMITIMEN
 
-        ; Upload one color to CGRAM[0] (the backdrop / transparency color).
-        ; BGR-555 little-endian. $7C00 = bright blue.
+        ; ── Palette → CGRAM ───────────────────────────────────────────
+        ; 4 colours (2bpp): 0 = blue backdrop, 1 = white, 2 = green,
+        ; 3 = magenta. BGR-555, little-endian (low byte then high byte).
         stz CGADD
         lda #$00
-        sta CGDATA
+        sta CGDATA          ; colour 0 low  ($7C00 = blue)
+        lda #$7C
+        sta CGDATA          ; colour 0 high
+        lda #$FF
+        sta CGDATA          ; colour 1 low  ($7FFF = white)
+        lda #$7F
+        sta CGDATA          ; colour 1 high
+        lda #$E0
+        sta CGDATA          ; colour 2 low  ($03E0 = green)
+        lda #$03
+        sta CGDATA          ; colour 2 high
+        lda #$1F
+        sta CGDATA          ; colour 3 low  ($7C1F = magenta)
         lda #$7C
-        sta CGDATA
+        sta CGDATA          ; colour 3 high
+
+        ; ── Tile CHR → VRAM word $0000 (DMA channel 0) ────────────────
+        ; Two 8x8 2bpp tiles = 32 bytes. VMAIN $80 = +1 word after the
+        ; high-byte write; B-bus $18 = VMDATAL (auto-alternates to $2119).
+        ldx #$0000
+        stx VMADDL
+        lda #$80
+        sta VMAIN
+        lda #$01
+        sta DMAP0           ; DMA mode 1 (2 regs, word transfers)
+        lda #$18
+        sta BBAD0           ; → $2118 / $2119
+        ldx #TILES
+        stx A1T0L
+        lda #TILES>>16
+        sta A1B0
+        ldx #(TILES_END-TILES)
+        stx DAS0L           ; byte count
+        lda #$01
+        sta MDMAEN          ; fire channel 0
+
+        ; ── Fill BG1 tilemap → VRAM word $0400 (byte $0800) ───────────
+        ; A 32x32 map = 1024 entries. Each entry is a word: low byte =
+        ; tile index, high byte = attributes (0). We write a checkerboard
+        ; of tile 0 / tile 1 directly through the data port (no source
+        ; buffer needed). VMAIN already = +1 word per write.
+        ldx #$0400
+        stx VMADDL
+        rep #$20            ; A = 16-bit for word writes
+        ldy #$0000          ; entry counter (0..1023)
+.maploop:
+        tya
+        and #$0001          ; checker by column parity
+        sta VMDATAL         ; entry = tile 0 or tile 1
+        iny
+        cpy #1024
+        bne .maploop
+        sep #$20            ; back to 8-bit A
 
-        ; Enable screen at full brightness (bit 7 = 0 to disable forced
-        ; blank; low nybble = brightness 0..15).
+        ; ── BG1 base registers ────────────────────────────────────────
+        stz BGMODE          ; mode 0, 8x8 tiles
+        ; BG1SC: bits 2-7 = tilemap base in $0400-word units, bits 0-1 =
+        ; size (00 = 32x32). Map is at word $0400 → base = 1 → ($01<<2)=$04.
+        lda #$04
+        sta BG1SC
+        stz BG12NBA         ; BG1 char base = word $0000 (our tiles)
+        lda #$01
+        sta TM              ; enable BG1 on the main screen
+
+        ; ── Screen ON at full brightness ──────────────────────────────
         lda #$0F
         sta INIDISP
 
 LOOP:
         bra LOOP
 
+; -----------------------------------------------------------------------
+; Tile CHR: two 8x8 2bpp tiles (16 bytes each). 2bpp = 2 bitplanes
+; interleaved per row: byte0=row0 plane0, byte1=row0 plane1, ...
+;
+; Tile 0 — solid colour 1 (plane0 all set, plane1 clear → colour 1).
+; Tile 1 — checker of colour 2 / colour 3 (both planes patterned) so the
+; map's alternating tiles give a busy, multi-colour screen.
+TILES:
+; tile 0 (solid: every pixel colour 1)
+db $FF, $00, $FF, $00, $FF, $00, $FF, $00
+db $FF, $00, $FF, $00, $FF, $00, $FF, $00
+; tile 1 (checkerboard: colour 2 / colour 3 alternating per pixel)
+db $AA, $55, $55, $AA, $AA, $55, $55, $AA
+db $AA, $55, $55, $AA, $AA, $55, $55, $AA
+TILES_END:
+
 ; -----------------------------------------------------------------------
 ; Emulation-mode reset vector (used at boot, before `xce` flips to native).
 ; asar's `lorom` directive handles header + rest of vector table padding.

package/examples/snes/templates/c-hello-data.asm

@@ -320,4 +320,27 @@ palfont:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/c-hello.c

@@ -27,13 +27,20 @@
 #include <snes.h>
 
 extern char tilfont, palfont;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * It has no public prototype in console.h, so declare it here. Call it
  * once per frame (after WaitForVBlank) or via nmiSet(consoleVblank). */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * screen never reads as a flat/blank backdrop. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
+    u16 i;
+
     /* ── 1. PVSnesLib text-mode setup ─────────────────────────────
      * Map + tile-data + palette-offset addresses are conventions —
      * any free VRAM region will work, these match PVSnesLib's
@@ -54,7 +61,17 @@ int main(void) {
     setMode(BG_MODE1, 0);
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the screen never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of the console gfx
+     * $3000 / map $6800). Map entries use palette block 1 (0x0400) so the
+     * wallpaper palette doesn't disturb the console font palette in block 0
+     * (HUD text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     /* ── 3. Draw text ─────────────────────────────────────────────

package/examples/snes/templates/hello_sprite-data.asm

@@ -340,4 +340,27 @@ palsprite:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00, $00, $00, $00, $00, $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/hello_sprite.c

@@ -24,14 +24,20 @@
 
 extern char tilfont, palfont;
 extern char tilsprite, palsprite;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * screen never reads as a flat/blank backdrop. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
     u16 x = 120, y = 100;
     u16 prev = 0;
+    u16 i;
 
     /* Text setup — same layout as c-hello. */
     consoleSetTextMapPtr(0x6800);
@@ -44,7 +50,17 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the screen never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of sprites $0000 and
+     * the console gfx $3000 / map $6800). Map entries use palette block 1
+     * (0x0400) so the wallpaper palette doesn't disturb the console font
+     * palette in block 0 (status text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     /* OAM init — sprite tiles at VRAM $0000, 8x8 default. */

package/examples/snes/templates/music_demo-data.asm

@@ -315,4 +315,27 @@ palfont:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/music_demo.c

@@ -26,16 +26,22 @@
 #include "snes_sfx.c"
 
 extern char tilfont, palfont;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * screen never reads as a flat/blank backdrop. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
     u16 pad;
     u16 prev = 0;
     u16 frame = 0;
     u8 music_running;
+    u16 i;
 
     /* ── Text-mode setup (PVSnesLib convention) ─────────────────── */
     consoleSetTextMapPtr(0x6800);
@@ -47,11 +53,18 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
-    bgSetDisable(2);
 
-    /* ── Upload SPC driver + sample bank + song table to ARAM ──── */
-    sfx_init();
+    /* BG1 = full-screen wallpaper so the screen never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of the console gfx
+     * $3000 / map $6800). Map entries use palette block 1 (0x0400) so the
+     * wallpaper palette doesn't disturb the console font palette in block 0
+     * (HUD text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
+    bgSetDisable(2);
 
     consoleDrawText( 8, 6,  "SNES MUSIC DEMO");
     consoleDrawText( 3, 11, "B    = SHOOT SFX");
@@ -60,6 +73,11 @@ int main(void) {
 
     setScreenOn();
 
+    /* Upload SPC driver + sample bank + song table to ARAM. sfx_init() must
+     * run AFTER setScreenOn() (snes_sfx.h:63) — if the SPC stalls before the
+     * screen is on you get a black/forced-blank screen forever. */
+    sfx_init();
+
     /* Auto-start music. */
     sfx_music_play();
     music_running = 1;

package/examples/snes/templates/platformer.c

@@ -107,10 +107,13 @@ int main(void) {
     consoleDrawText( 9, 12, "|64");
     consoleDrawText(17, 12, "|128");
     consoleDrawText(25, 12, "|192");
-    sfx_init();
 
     oamSet(0, 32, 100, 3, 0, 0, 0, 0);
+    /* Screen ON first, THEN sound. sfx_init() must run AFTER setScreenOn()
+     * (snes_sfx.h:63) — if the SPC stalls before the screen is on you get a
+     * black/forced-blank screen forever. */
     setScreenOn();
+    sfx_init();
 
     while (1) {
         pad = padsCurrent(0);

package/examples/snes/templates/puzzle.c

@@ -176,10 +176,13 @@ int main(void) {
 
     consoleDrawText(14, 2, "SCORE");
     consoleDrawText(2, 26, "LR MOVE A ROT START DROP");
-    sfx_init();
     draw_grid();
 
+    /* Screen ON first, THEN sound. sfx_init() must run AFTER setScreenOn()
+     * (snes_sfx.h:63) — if the SPC stalls before the screen is on you get a
+     * black/forced-blank screen forever. */
     setScreenOn();
+    sfx_init();
 
     while (1) {
         pad = padsCurrent(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/cheats/gamegenie.js

@@ -446,7 +446,6 @@ export function decodeWithDevice(code, platform) {
 
 /** Format a raw ADDR:VAL[:COMPARE] code from decoded parts (hex, no 0x). */
 export function encodeRaw({ address, value, compare }) {
-  const h = (n, w) => (n & ((1 << (4 * w)) - 1) >>> 0).toString(16).toUpperCase().padStart(w, "0");
   const addrHex = (address >>> 0).toString(16).toUpperCase();
   const valHex = (value & 0xFF).toString(16).toUpperCase().padStart(2, "0");
   return compare != null

package/src/cli/smoke.js

@@ -14,7 +14,7 @@
 // temp file and loaded into the matching libretro core. Platform is
 // inferred from the file extension if not given.
 
-import { writeFile, mkdtemp, readdir } from "node:fs/promises";
+import { writeFile, mkdtemp } from "node:fs/promises";
 import { existsSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -108,12 +108,10 @@ async function playCommand(romPath, opts) {
 
   // Extract zip if needed
   let actualPath = romPath;
-  let extracted = false;
   if (path.extname(romPath).toLowerCase() === ".zip") {
     console.error(`unzipping ${path.basename(romPath)}...`);
     const { tempPath, originalName } = await extractFirstRomFromZip(romPath);
     actualPath = tempPath;
-    extracted = true;
     console.error(`  → ${originalName} (${statSync(tempPath).size} bytes)`);
   }
 

package/src/host/LibretroHost.js

@@ -301,7 +301,20 @@ export class LibretroHost {
     mod._free(infoPtr);
 
     if (!ok) {
-      throw new Error(`retro_load_game failed for ${mediaPath}`);
+      // This is the failure path for EVERY bad/wrong-platform/corrupt/
+      // unsupported-mapper image — the most common loadMedia failure. The core
+      // returns a bare false, so name the likely causes + the exact checks
+      // rather than leaving the agent with "failed".
+      throw new Error(
+        `The '${platform}' core REFUSED this ${mediaKind || "media"} ` +
+        `(${data.length} bytes${ext ? `, ${ext}` : ""}, path ${mediaPath}). ` +
+        `retro_load_game returned false — the bytes reached the core but it would not accept them. ` +
+        `Common causes: (1) wrong platform for this file (a GB ROM loaded as 'nes', etc.) — ` +
+        `confirm the platform matches the file; (2) a corrupt or TRUNCATED image — re-check the byte length; ` +
+        `(3) an unsupported mapper/board or a missing/!bad header. ` +
+        `Inspect the file with cart({op:'identify'}) to see what platform/mapper it really is, ` +
+        `then load with the matching platform.`,
+      );
     }
 
     this.status.platform = platform;
@@ -436,7 +449,7 @@ export class LibretroHost {
    */
   stepFrames(n) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (this.status.paused) return 0;
     for (let i = 0; i < n; i++) {
       mod._retro_run();
@@ -455,7 +468,7 @@ export class LibretroHost {
    *  Returns the frame count after. */
   renderOneFrame() {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     mod._retro_run();
     this.status.frameCount++;
     if (this.state.lastFrame) {
@@ -594,7 +607,7 @@ export class LibretroHost {
   /** @param {string} name */
   loadState(name) {
     const snapshot = this.namedStates.get(name);
-    if (!snapshot) throw new Error(`no save state named '${name}'`);
+    if (!snapshot) throw new Error(this._noStateError(name));
     return this.unserializeState(snapshot); // returns # cheats cleared
   }
 
@@ -641,10 +654,21 @@ export class LibretroHost {
    *  disturbing the live host). Throws if the slot doesn't exist. */
   getStateBlob(name) {
     const blob = this.namedStates.get(name);
-    if (!blob) throw new Error(`no save state named '${name}'`);
+    if (!blob) throw new Error(this._noStateError(name));
     return blob;
   }
 
+  /** Build a "no save state named X" error that lists the slots that DO exist
+   *  (or says there are none) and names the op to create one. */
+  _noStateError(name) {
+    const names = [...this.namedStates.keys()];
+    return names.length
+      ? `No save state named '${name}'. Existing in-memory slots: ${names.map((n) => `'${n}'`).join(", ")}. ` +
+        `(List them with state({op:'list'}); create one with state({op:'save', name}).)`
+      : `No save state named '${name}' — this session has NO in-memory save slots yet. ` +
+        `Create one with state({op:'save', name:'${name}'}) first (or load from disk with state({op:'load', path})).`;
+  }
+
   /**
    * @param {import("./types.js").MemoryRegion} region
    * @param {number} offset
@@ -667,7 +691,7 @@ export class LibretroHost {
   readMemory(region, offset, length) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
-    if (id === undefined) throw new Error(`unknown memory region '${region}'`);
+    if (id === undefined) throw new Error(this._unknownRegionError(region));
     const ptr = mod._retro_get_memory_data(id);
     const size = mod._retro_get_memory_size(id);
     if (!ptr || !size) throw new Error(this._emptyRegionError(region));
@@ -685,7 +709,7 @@ export class LibretroHost {
   writeMemory(region, offset, bytes) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
-    if (id === undefined) throw new Error(`unknown memory region '${region}'`);
+    if (id === undefined) throw new Error(this._unknownRegionError(region));
     const ptr = mod._retro_get_memory_data(id);
     const size = mod._retro_get_memory_size(id);
     if (!ptr || !size) throw new Error(this._emptyRegionError(region));
@@ -1058,7 +1082,7 @@ export class LibretroHost {
 
   runUntilPC(address, maxFrames = 600) {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.pcBreakSupported()) {
       throw new Error("PC breakpoint not supported by this core (Genesis today; other cores as patched).");
     }
@@ -1090,7 +1114,7 @@ export class LibretroHost {
    */
   runUntilRead(address, maxFrames = 600) {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.readWatchSupported()) {
       throw new Error("read watchpoint not supported by this core (Genesis today; other cores as patched).");
     }
@@ -1122,7 +1146,7 @@ export class LibretroHost {
    */
   stepInstruction() {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.pcBreakSupported()) {
       throw new Error("single-step not supported by this core (Genesis today; other cores as patched).");
     }
@@ -1190,8 +1214,8 @@ export class LibretroHost {
    * @param {(host:LibretroHost)=>any} [a.capture] read result from core RAM BEFORE restore
    */
   callSubroutine(a) {
-    const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMod();
+    this._needMedia();
     if (!this.setRegSupported()) {
       throw new Error("cpu({op:'call'}) not supported by this core (rebuild with romdev_setreg/romdev_getreg).");
     }
@@ -1427,7 +1451,7 @@ export class LibretroHost {
    */
   watchRange(lo, hi, mode, frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.rangeWatchSupported()) throw new Error("range watch not supported by this core.");
     const m = mode === "read" ? 1 : mode === "write" ? 2 : 3;
     mod._romdev_range_set(lo >>> 0, hi >>> 0, m, 1);
@@ -1460,7 +1484,7 @@ export class LibretroHost {
    */
   logPCRange(lo, hi, frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.rangeWatchSupported()) throw new Error("coverage trace not supported by this core.");
     mod._romdev_cov_set(lo >>> 0, hi >>> 0, 1);
     this._runFramesExclusive(() => false, frames);
@@ -1500,7 +1524,7 @@ export class LibretroHost {
    */
   watchDma(frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.dmaWatchSupported()) throw new Error("VDP-DMA watch not supported by this core (Genesis only).");
     mod._romdev_dmawatch_set(1);
     this._runFramesExclusive(() => false, frames);
@@ -1538,6 +1562,21 @@ export class LibretroHost {
     return this.mod;
   }
 
+  // Guard for every op that needs a loaded game. The bare "no media loaded"
+  // left the agent guessing; this names the fix (loadMedia) and the gotcha
+  // (emulator state is in-memory, so a reconnect/restart drops it). The richer
+  // session-aware recovery (echoing the exact prior loadMedia call) lives at the
+  // tool layer in state.js getHost(); this is the host-level twin.
+  _needMedia() {
+    if (!this.status.loaded) {
+      throw new Error(
+        "No media loaded — call loadMedia({platform, path}) before this op. " +
+        "(If you DID load and hit this after a reconnect/restart, the host's in-memory " +
+        "state didn't survive — re-run loadMedia with your ROM to pick back up.)",
+      );
+    }
+  }
+
   /**
    * Build a friendly error message when a memory region is empty (the
    * core didn't expose it). Includes per-platform suggestions when we
@@ -1548,6 +1587,21 @@ export class LibretroHost {
    * "my VRAM writes are being optimized away" spiral — when in fact
    * gambatte exposes VRAM as `gb_vram`, not the generic id.
    */
+  _unknownRegionError(region) {
+    // A bad region name should never leave the agent guessing — list the valid
+    // ones (the single source of truth, MemoryRegionToRetro) so it can pick the
+    // right one. The cross-platform names (system_ram / video_ram / save_ram)
+    // exist everywhere; the rest are platform-specific.
+    const valid = Object.keys(MemoryRegionToRetro).sort();
+    const common = valid.filter((r) => ["system_ram", "video_ram", "save_ram", "rom"].includes(r));
+    return (
+      `Unknown memory region '${region}'. ` +
+      `Common (most platforms): ${common.join(", ")}. ` +
+      `All registered region names: ${valid.join(", ")}. ` +
+      `(Region availability is per platform — some names only resolve on the platform that has that hardware.)`
+    );
+  }
+
   _emptyRegionError(region) {
     const plat = this.status && this.status.platform;
     // SRAM gets an honest, specific answer: empty save_ram almost always means