romdev-mcp 0.1.1

package/src/platforms/snes/MENTAL_MODEL.md

@@ -0,0 +1,275 @@
+# Super Nintendo / Super Famicom — mental model
+
+One page. Read once before you write your first SNES game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## CPU memory map (LoROM layout)
+
+The SNES has a 24-bit address space; LoROM splits bank+offset. Most
+homebrew uses LoROM unless the cart is > 2 MB.
+
+```
+$00:0000-$00:1FFF   WRAM mirror (8 KB low RAM, mirrored across banks)
+$00:2100-$00:213F   PPU registers (BG, OAM, CGRAM access, INIDISP)
+$00:2140-$00:217F   SPC700 sound CPU APUIO ports (4 bytes mirrored)
+$00:2180-$00:2183   WMDATA / WMADDx (WRAM access port)
+$00:4016-$00:4017   joypad I/O
+$00:4200-$00:421F   PPU/CPU control regs (NMI enable, joypad auto-read)
+$00:4300-$00:437F   DMA channel registers (8 channels × 16 bytes)
+$00:8000-$00:FFFF   first 32 KB of ROM (mirrored to other banks)
+$7E:0000-$7E:FFFF   work RAM (128 KB, banks $7E + $7F)
+$7F:0000-$7F:FFFF   work RAM (continued — 128 KB total)
+```
+
+Direct page (the SNES equivalent of zero-page) is configurable but
+defaults to $00:0000. The stack lives in bank $00, growing down from
+$01FF.
+
+## PPU memory (separate from CPU bus!)
+
+```
+VRAM    64 KB   tile patterns + tilemaps
+CGRAM   512 B   palette (256 colors × 2 bytes BGR-555)
+OAM     544 B   sprite-attribute table (128 sprites + high table)
+```
+
+PPU memory is reached through registers `$2115-$2119` (VMADD/VMDATA),
+`$2121-$2122` (CGADD/CGDATA), `$2102-$2104` (OAMADD/OAMDATA).
+
+For bulk uploads (tile data, palette, OAM) use **DMA** — channel 0
+of `$4300-$430F` is the canonical "VRAM-fill" channel. PVSnesLib's
+`dmaCopyVram` wraps this.
+
+## Background modes
+
+The SNES has 8 BG modes selected via PPU register $2105 (BGMODE):
+
+```
+0  4 BGs × 4 colors      — text-mode look
+1  3 BGs (16+16+4 col)   — default for most games (Super Mario World)
+2  2 BGs × 16 col + tilemap offset-per-tile (Yoshi's Island)
+3  1 BG × 256 col + 1 BG × 16 col (Donkey Kong Country)
+4  1 BG × 256 col + 1 BG × 4 col with offset-per-tile
+5  2 BGs hi-res (512 px wide, half-height)
+6  hi-res mosaic
+7  1 BG with affine transform (Mario Kart, F-Zero)
+```
+
+PVSnesLib's default is `BG_MODE1` (`setMode(BG_MODE1, 0)`) — three
+background layers, plenty of palette space.
+
+## Sprites (OAM)
+
+128 sprites × 4 bytes + 32 bytes of high table = 544 bytes. The high
+table packs the sprite's size flag and the upper bit of X for each
+sprite (4 sprites per byte).
+
+Per sprite:
+
+```
++0  X position (low 8 bits — upper bit is in the high table)
++1  Y position (8 bits)
++2  tile index (low 8 bits)
++3  attributes:
+      bit 0   tile index high bit (so 9-bit tile range)
+      bit 1-3 palette (palette = 0..7)
+      bit 4-5 priority (0..3 — higher = drawn on top)
+      bit 6   horizontal flip
+      bit 7   vertical flip
+```
+
+Sprite sizes are configurable via OBSEL ($2101): small + large pair
+(8x8 + 16x16, 8x8 + 32x32, 16x16 + 32x32, etc.). Each sprite picks
+small OR large via its high-table bit.
+
+The PPU draws **up to 32 sprites per scanline**, **up to 34 tiles
+per scanline** total. Beyond that, drops happen low-OAM-index-first.
+
+### The OBJ stable-path recipe (do this; it's the one that works)
+
+Most "my SNES sprites are garbage/flashing/invisible" pain comes from
+deviating from this. Follow it exactly until the game works, *then*
+optimize:
+
+1. **Use fixed OAM slots.** Decide slot N for each sprite up front. The
+   PVSnesLib OAM table is byte-addressed: **slot N lives at byte offset
+   `N << 2`** (i.e. `N*4`). Don't shuffle slots between frames — a moving
+   sprite keeps its slot and just changes X/Y.
+2. **Upload EVERY OBJ palette line you reference — before you show the
+   sprite.** OBJ palettes are CGRAM lines 8..15 (absolute index
+   `128 + line*16`, 16 colors each). If a sprite's attr names palette
+   line 2 but you only uploaded line 0, line 2 is whatever was in CGRAM
+   (usually zero) → garbage/transparent. Either upload all the lines you
+   use, or point every sprite at line 0 until art is in. (This is the #1
+   bug — `inspectSprites` now WARNS when a renderable sprite references an
+   all-zero OBJ palette line.)
+3. **Know your OBJ VRAM rules.** OBSEL picks the OBJ tile base (a page in
+   VRAM, in 0x2000-word steps) and the small/large size pair. A 16×16 OBJ
+   is a 2×2 block of 8×8 cells in the OBJ char table, laid out **+1 across,
+   +0x10 down** (the OBJ name table is 16 tiles wide). Tile index in OAM is
+   9-bit (attr bit 0 is the high bit / second-page select).
+4. **ROM-backed tiles beat runtime-generated tiles** for getting started.
+   DMA a fixed tile sheet to the OBJ VRAM page once at init; don't generate
+   OBJ tiles on the fly until the static path renders correctly. The "SNES
+   Invaders" stable path = static ship-angle frames + explicit asteroid
+   tiles + all palettes uploaded + fixed slots + a low sprite budget.
+5. **Verify with the tools, don't guess.** After a build that should show
+   sprites, call `getRenderingContext({platform:'snes'})` (it now decodes
+   OBSEL: OBJ size, tile base, and whether the OBJ layer is enabled on the
+   main screen via TM) and `inspectSprites({platform:'snes'})` (per-sprite
+   `renderable` vs hidden, resolved `tileVramAddr`, `cgramPaletteRange`, and
+   uninitialized-palette warnings). If `renderableCount` is 0 but you placed
+   sprites, the answer is right there: OBJ layer off in TM, all sprites
+   parked at Y≥0xE0, or off the X edges.
+
+## Palette (CGRAM)
+
+256 colors × 2 bytes = 512 bytes, BGR-555:
+
+```
+$xy where word = 0bbbbbgggggrrrrr  → red is low, blue is high
+```
+
+(Same word order as Sega, different bit packing.)
+
+For sprites: palettes 0..7 of the 16-color palette block from CGRAM
+$80..$FF — sprite tile uses 4bpp tiles, so 16 colours per palette.
+
+PVSnesLib helpers:
+
+```c
+setPaletteColor(idx, color);   // CGRAM by absolute index
+setBGPaletteColor(slot, val);  // BG palettes 0..7
+```
+
+## Frame heartbeat
+
+PVSnesLib gives you `WaitForVBlank()`. Game loop shape:
+
+```c
+while (1) {
+    /* update game state */
+    /* stage OAM via oamSet() */
+    oamUpdate();           /* flushes shadow OAM via DMA */
+    WaitForVBlank();       /* blocks until vblank; auto-DMA fires */
+}
+```
+
+`oamUpdate()` flushes the RAM-side shadow buffer to OAM via DMA;
+`WaitForVBlank()` blocks the CPU until the next vertical-blanking
+interval. The NMI handler does joypad auto-read + any chained
+PVSnesLib housekeeping.
+
+## Input
+
+`u16 pad = padsCurrent(0)` returns the bitmask for controller 0.
+Bits:
+
+```
+KEY_A      BIT(7)         KEY_RIGHT  BIT(8)
+KEY_B      BIT(15)        KEY_LEFT   BIT(9)
+KEY_X      BIT(6)         KEY_DOWN   BIT(10)
+KEY_Y      BIT(14)        KEY_UP     BIT(11)
+KEY_L      BIT(5)         KEY_START  BIT(12)
+KEY_R      BIT(4)         KEY_SELECT BIT(13)
+```
+
+Edge-detect by `(pad & KEY) && !(prev & KEY)`.
+
+## Sound
+
+The S-DSP is driven by the SPC700, a separate 8-bit CPU running its
+own program. You upload an SPC binary into APU RAM at boot, then
+poke the 4 APUIO ports to trigger sound events.
+
+PVSnesLib bundles a music driver. Workflow:
+
+```c
+spcBoot();                  /* uploads driver */
+spcSetSoundEntry(0, 0, 1, 0, &my_sfx_brrs);
+spcPlay(0);                 /* trigger SFX channel 0 */
+```
+
+(Hand-authoring SPC drivers is hard. For SFX, PVSnesLib's PSG-style
+helpers are the canonical entry point.)
+
+## ROM layout (LoROM)
+
+```
+$00:0000-$00:7FFF   first 32 KB of ROM (low half of bank 0)
+$00:8000-$00:FFFF   first 32 KB of ROM (mirrored at high half of bank 0)
+$01:0000-$01:7FFF   next 32 KB (low half bank 1)
+...
+$00:FFC0-$00:FFDF   ROM title (21 chars)
+$00:FFD5            map mode (LoROM=$20, HiROM=$21)
+$00:FFD6            cart type (RAM, battery, etc.)
+$00:FFD7            ROM size code
+$00:FFFC-$00:FFFD   RESET vector (where the SNES starts execution)
+$00:FFEA-$00:FFEB   NMI vector
+```
+
+PVSnesLib's `hdr.asm` fills these in.
+
+## Where the SDK lives (and how to read it)
+
+`createProject({platform:"snes"})` ships the FULL PVSnesLib source +
+header tree into the new project at `vendor/pvsneslib/`. So when
+your code does `#include <snes.h>`, those headers come from
+`vendor/pvsneslib/include/`:
+
+```
+vendor/pvsneslib/include/snes.h           ← top-level umbrella
+vendor/pvsneslib/include/snes/
+  background.h   bgSet*, BG_MODE0..7
+  console.h      consoleInitText, consoleDrawText, consoleSetText*
+  dma.h          dmaCopyVram, dmaFill*
+  input.h        padsCurrent, KEY_A..KEY_SELECT, padsClear
+  interrupt.h    WaitForVBlank, setNMIHandler
+  object.h       (legacy alias — use sprite.h)
+  pixel.h        setPaletteColor, setBGPaletteColor, RGB5
+  scores.h
+  snestypes.h    u8/u16/s8/s16 typedefs
+  sound.h        spcBoot, spcSetSoundEntry, spcPlay
+  sprite.h       oamInit, oamSet, oamSetEx, oamSetXY, oamUpdate
+  video.h        setMode, setScreenOn, setScreenOff
+```
+
+To find what an SDK function does, GREP the vendor tree — the C
+source for every helper ships at `vendor/pvsneslib/source/`. This is
+the same pattern as the Lynx cc65 vendor dir: the agent reads the
+library it's calling instead of inferring from header comments.
+
+## Build pipeline
+
+When you call `buildSource({platform:"snes", language:"c"})`:
+
+1. `tcc-65816` (TinyCC fork → WASM) compiles each `.c` → `.asm`
+   (wla-65816 syntax).
+2. `wla-65816` (WLA-DX → WASM) assembles each `.asm` → `.o` object.
+3. `wla-65816` also assembles the `hdr.asm` + `crt0_snes.obj`.
+4. `wlalink` (WLA-DX → WASM) links all `.o` + PVSnesLib runtime
+   archives (`crt0_snes.obj`, `libm.obj`, `libtcc.obj`, `libc.obj`)
+   per a linkfile → raw `.sfc` SNES ROM.
+
+Loadable via snes9x (`loadMedia`).
+
+## Horizontal scrolling (for side-scrollers)
+
+The `platformer` scaffold is single-screen. SNES scrolling is the easiest of
+the tile platforms because each BG layer has its own hardware scroll register
+and parallax is nearly free.
+
+- **Hardware scroll:** write the BG1 horizontal offset register (`BG1HOFS`,
+  `$210D`, write twice — low byte then high byte/13-bit) each frame to camera
+  X. PVSnesLib: `bgSetScroll(0, camX, camY);`.
+- **Parallax:** scroll BG2 at a fraction of camX (e.g. `camX>>1`) for a
+  background layer that lags — instant depth, no extra CPU.
+- **Streaming:** the BG tilemap is 32×32 (or 64×32) cells. For a world wider
+  than the map, rewrite the column entering view as the camera crosses each
+  8-px boundary (DMA the new column into VRAM during vblank).
+- **Fixed HUD:** put the HUD on a separate BG layer and exclude it from the
+  scroll write, or use a mid-frame HDMA/IRQ to reset the scroll for the HUD
+  scanlines.
+
+Track `camX` in pixels; actor screen-X = `worldX - camX`.

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -0,0 +1,208 @@
+# Super Nintendo / Super Famicom — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first for the "what's
+going on" version (via `getPlatformDoc({platform:"snes", name:"mental_model"})`).
+
+## "ROM builds but the screen is black / forced blank"
+
+The SNES PPU starts in **forced blank** state. INIDISP register
+$2100 has bit 7 set on reset, which means "display off, allow VRAM
+write any time". You must clear bit 7 of INIDISP before anything
+appears on screen.
+
+PVSnesLib provides `setScreenOn()` to do this. Forget it → black
+screen forever, even if the rest of your code is perfect.
+
+```c
+setMode(BG_MODE1, 0);
+consoleDrawText(10, 10, "hi");
+setScreenOn();   /* ← without this, nothing draws */
+while (1) WaitForVBlank();
+```
+
+## "tcc-65816 fails with `';' expected` on `for (u16 i = 0; ...)`"
+
+tcc-65816 is C89-only. You cannot declare variables inline in `for`
+loops, mid-block, or as the rhs of expressions. Move all declarations
+to the top of each function or block.
+
+```c
+/* WRONG (C99+) */
+for (u16 i = 0; i < 10; i++) { ... }
+
+/* RIGHT (C89) */
+u16 i;
+for (i = 0; i < 10; i++) { ... }
+```
+
+Same applies to mid-block declarations like `u16 v = expr;` after
+statements — must be hoisted to block top.
+
+## "wla-65816 link fails with `unresolved external 'tilfont'`"
+
+Your `main.c` references `tilfont` / `palfont` symbols, but no
+sibling `.asm` defines them. PVSnesLib's `consoleInitText` requires
+these — they hold the font tile data and palette respectively.
+
+Stub them with zero bytes in a sibling `data.asm`:
+
+```asm
+.section ".rodata1" superfree
+tilfont:
+.db 0, 0, 0, 0, 0, 0, 0, 0
+palfont:
+.db 0, 0, 0, 0, 0, 0, 0, 0
+.ends
+```
+
+Then build with both files:
+```js
+buildSource({platform:"snes", language:"c",
+  sources: {"main.c": ..., "data.asm": ...}});
+```
+
+For real fonts, run PVSnesLib's `gfx4snes` tool natively to convert
+a PNG → `.pic` + `.pal`, then `.incbin` them in `data.asm`.
+
+## "Sprites don't appear" (or appear as garbage / flashing colors)
+
+**Diagnose first, don't guess.** Two tool calls tell you exactly what's
+wrong — they read the live PPU registers (OBSEL/TM) and OAM/CGRAM:
+
+- `getRenderingContext({platform:'snes'})` → `snes.obj.enabledMain` (is the
+  OBJ layer even on in TM?), `snes.obj.size`, `snes.obj.tileBaseByte`.
+- `inspectSprites({platform:'snes'})` → `renderableCount` (how many are
+  actually on-screen vs parked), each sprite's `renderable`/`hiddenReason`,
+  resolved `tileVramAddr` + `cgramPaletteRange`, and **`warnings` for any
+  renderable sprite pointing at an all-zero (never-uploaded) OBJ palette
+  line.**
+
+Common causes, in the order the tools will point you to:
+
+1. **OBJ layer disabled on the main screen.** `getRenderingContext`'s
+   `obj.enabledMain` is false → you never set TM ($212c) bit 4. In
+   PVSnesLib `setScreenOn()` + the OAM helpers normally handle this; if you
+   poked registers directly you may have clobbered it.
+2. **You called `oamSet()` but not `oamUpdate()`.** PVSnesLib's `oamSet`
+   writes a RAM-side shadow buffer; `oamUpdate()` DMAs it to OAM. Without
+   it the PPU sees stale OAM. (`inspectSprites` reads real OAM, so if it
+   shows your sprite but the screen doesn't, this is it.)
+3. **Sprite Y is in the off-screen range.** Y≥$E0 is the "hide" convention;
+   `inspectSprites` reports those as `renderable:false` with
+   `hiddenReason:"parked off-screen-top"`. A sprite you forgot to position
+   may sit at Y=0 (visible) or wherever uninitialized OAM left it.
+4. **Garbage / flashing colors = unintended OBJ palette line.** You used
+   palette line 1..3 but only uploaded line 0. `inspectSprites` WARNS via
+   `uninitializedObjPalettes` / `suspiciousObjPalettes` (+ `objPaletteReport`)
+   — and it catches MORE than all-zero lines: a line that's a flat fill, a
+   smooth default-looking ramp, or simply referenced *above* the contiguous
+   uploaded-from-line-0 block all get flagged as "likely never uploaded."
+   Fix: upload every line you reference (CGRAM `128 + line*16`), or point
+   sprites at an authored line.
+5. **No sprite tile data uploaded.** `oamInitGfxSet` is the canonical
+   "upload sprite tiles + palette to VRAM" call. Forget it and OAM points at
+   garbage tiles. `inspectSprites`'s `tileVramAddr` tells you where the
+   sprite's tile is — cross-check with `inspectPatternTiles` at that base.
+
+See MENTAL_MODEL.md → "The OBJ stable-path recipe" for the layout that
+avoids all five.
+
+## "BG mode is wrong / background is glitched"
+
+`setMode(BG_MODE1, 0)` configures Mode 1: BG0 + BG1 (16-color), BG2
+(4-color). If you're using `consoleInitText` for text, it writes
+into BG0 of Mode 1 by default. You need to also call
+`bgSetDisable(1)` and `bgSetDisable(2)` if you're not using those
+layers — otherwise they'll render whatever happens to be at their
+default VRAM addresses (often garbage).
+
+```c
+setMode(BG_MODE1, 0);
+bgSetDisable(1);   /* disable BG1 */
+bgSetDisable(2);   /* disable BG2 */
+```
+
+## "Build fails with `RAM overflow` / `code section overflow`"
+
+The SNES LoROM bank layout maps only 32 KB per bank (the upper half).
+PVSnesLib's default linkfile gives you 8 banks = 256 KB. Symptoms:
+
+- "code section overflow" → your compiled code is larger than the
+  remaining ROM space.
+- "RAM overflow" → too many globals + the C stack don't fit in the
+  8 KB low-RAM region.
+
+Fixes:
+- Compile with `-Os` to reduce code size.
+- Move large constant arrays to `const` so they go to ROM, not RAM.
+- For really big games, switch to a bigger ROM (extend the LoROM
+  layout to 16 banks).
+
+## "Audio doesn't work / silent"
+
+Three layers:
+
+1. **SPC700 driver not booted.** PVSnesLib has `spcBoot()` — call
+   once at startup. Forget it and `spcPlay()` does nothing.
+2. **APUIO ports stuck.** The SPC700 communication is via $2140-$2143.
+   On reset both sides write zeros and then handshake; if you bypass
+   PVSnesLib's `spc*` helpers and poke the ports directly, your
+   handshake may be wrong.
+3. **No sound data loaded.** `spcSetSoundEntry()` registers BRR
+   samples + sequence pointers — without these, channels are silent.
+
+PVSnesLib's API is the path of least resistance. Roll your own SPC
+driver only when you really need the control.
+
+## "consoleDrawText output is corrupt / shifted"
+
+`consoleInitText(palnum, palsize, tilfont, palfont)` configures the
+font palette. If you pass `palnum=0` (palette 0) but your `palfont`
+isn't 32 bytes of valid 16-color BGR-555, the font renders with
+garbage colors.
+
+Also: `consoleSetTextMapPtr`, `consoleSetTextGfxPtr`,
+`consoleSetTextOffset` must all be set BEFORE `consoleInitText`.
+PVSnesLib doesn't validate; bad ptrs → corrupt text.
+
+Canonical setup:
+
+```c
+consoleSetTextMapPtr(0x6800);    /* BG map base in VRAM */
+consoleSetTextGfxPtr(0x3000);    /* tile data base in VRAM */
+consoleSetTextOffset(0x0100);    /* first text tile in tilemap */
+consoleInitText(0, 16 * 2, &tilfont, &palfont);
+```
+
+## "Save states don't include the SPC700 state"
+
+snes9x snapshot includes APU state by default, so this should work
+out of the box. If you find SFX restart on load, double-check that
+your driver doesn't reinitialise itself unconditionally in the NMI
+handler.
+
+## "First C build is slow but later ones are instant"
+
+Expected. tcc-65816.wasm + wla-65816.wasm cold-load + compile takes
+1-2s. Subsequent builds reuse the warm worker pool (R12 crash
+isolation infrastructure). Steady-state builds are sub-second.
+
+## "I want to use real graphics from a PNG"
+
+`gfx4snes` (the PVSnesLib companion tool) converts PNG → .pic + .pal.
+It's not yet bundled in romdev's WASM toolchain. Workflow:
+
+1. Run `gfx4snes` natively on your build machine to produce
+   `mysprite.pic` + `mysprite.pal`.
+2. Ship those binary files alongside `main.c` + `data.asm` in
+   your project.
+3. In `data.asm`:
+   ```asm
+   tilsprite:
+   .incbin "mysprite.pic"
+   palsprite:
+   .incbin "mysprite.pal"
+   ```
+
+(romdev's `buildSource` accepts binary `.pic` / `.pal` blobs
+as sibling resources.)

package/src/platforms/snes/UPSTREAM_SOURCES.md

@@ -0,0 +1,50 @@
+# SNES — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/snes/templates/*.c`).
+2. **Bundled runtime source** — `src/platforms/snes/lib/c/snes_sfx.c`,
+   the SPC driver in `lib/audio/spc_driver.asm`, the `apu_blob.asm`
+   uploader.
+3. **Bundled library source** (R58) — PVSnesLib at
+   `src/platforms/snes/lib/pvsneslib/source/`. The complete PVSnesLib
+   source tree — every API (`consoleDrawText`, `setMode`,
+   `WaitForVBlank`, `padsCurrent`, OAM helpers, palette helpers) has
+   readable C/asm here.
+4. **Upstream GitHub** (NOT bundled):
+
+   | What | Upstream |
+   |---|---|
+   | PVSnesLib | https://github.com/alekmaul/pvsneslib |
+   | tcc-65816 (the C compiler we ship for SNES) | https://github.com/alekmaul/tcc/tree/65816 |
+   | wla-dx (65816 assembler we link with) | https://github.com/vhelin/wla-dx |
+   | asar (the alternative 65816 asm we ship) | https://github.com/RPGHacker/asar |
+   | snes9x libretro core | https://github.com/libretro/snes9x |
+
+## SNES hardware docs
+
+- **SNES Dev Manual** (Nintendo's, scanned): https://archive.org/details/SNESDevManual
+- **Anomie's SNES docs** (the modern reference): http://www.romhacking.net/community/566/
+- **Fullsnes** (problemkaputt, pan-docs style): https://problemkaputt.de/fullsnes.htm
+- **superfamicom.org**: https://snes.nesdev.org/
+
+## SPC700 (audio subsystem)
+
+The SNES audio chip is a separate CPU (Sony SPC700) with its own
+64 KB ARAM. Main 65816 → SPC communication via 4 mailbox bytes at
+$2140-$2143. Our `snes_sfx.c` + `spc_driver.asm` handle the upload
++ command protocol; for music driver internals see:
+
+- Our bundled SPC driver: `src/platforms/snes/lib/audio/spc_driver.asm`
+  (152 bytes — tiny, fully readable)
+- SPC700 reference: https://wiki.superfamicom.org/spc700-reference
+- BRR sample format: https://wiki.superfamicom.org/bit-rate-reduction-(brr)
+
+## When to use what
+
+- "How does `consoleDrawText` lay out the tilemap?" → `pvsneslib/source/`
+  + grep `consoleDrawText`
+- "What does `WaitForVBlank` actually do?" → same dir
+- "Why doesn't my BRR sample loop?" → BRR docs above + `apu_blob.asm`
+- "How does tcc-65816 lay out the stack?" → tcc-65816 GitHub
+- "snes9x doesn't expose register X" → libretro snes9x GitHub