romdev-mcp 0.1.1

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -0,0 +1,221 @@
+# Game Boy / Game Boy Color — symptom → fix
+
+Stuck? Find your symptom below; each entry has the 1-line diagnosis and
+the MCP tool call that confirms it. **Run the diagnosis BEFORE you start
+bisecting the C source** — most "GB doesn't render" bugs are one of these
+five things.
+
+## "Screen is blank / stays grey-white forever"
+
+**Cause #1: LCD is off.** `LCDC.7 = 0` means the screen never updates.
+```js
+loadCategory({category:"memory"})
+readMemory({region:"gb_io", offset:0x40, length:1})  // LCDC byte
+// 0x80+ = on, 0x00-0x7F = off
+```
+
+**Cause #2: stuck in `wait_vblank()` with LCD off.** Before the
+2026-05-25 runtime fix the helper hung forever in this case; now it
+returns immediately. If you've inlined your own `while (LY < 144)`
+wait, replace it with `wait_vblank()` from `gb_runtime.h`.
+```js
+loadCategory({category:"debug"})
+getCPUState({})  // PC stuck inside your wait loop? You hit this bug.
+```
+
+**Cause #3: BG and OBJ both disabled.** `LCDC` must have bit 0 (BG on)
+and/or bit 1 (OBJ on) set, or there's nothing to draw. The `gb_runtime`
+helper `lcd_init_default()` sets a known-good value
+(`LCDC = 0x83`: on + BG + OBJ + tile data $8000).
+
+## "Sprite doesn't appear"
+
+Check in this order:
+1. **OAM byte 0 is the Y position. Y=0 hides the sprite.** Hardware Y =
+   screen Y + 16, so the top edge of the screen is OAM Y=16. Same for X
+   (hardware X = screen X + 8, off-screen = X<8 or X>=168).
+   ```js
+   readMemory({region:"gb_oam", offset:0, length:16})
+   // bytes 0..3 = slot 0: [Y, X, tile, attr]
+   ```
+2. **Tile index points at unuploaded VRAM.** If your tile data is at
+   $8010+ (slot 1+) but the OAM byte 2 (tile index) is 0, you're showing
+   the blank slot 0.
+3. **LCDC.1 (OBJ enable) is off.** Same as above — `lcd_init_default()`
+   turns it on.
+4. **OAM DMA never ran.** You staged the sprite in `shadow_oam[]` but
+   forgot to call `oam_dma_flush()` each vblank.
+   ```js
+   loadCategory({category:"debug"})
+   inspectSprites({platform:"gbc"})   // shows what the LCD sees right now
+   ```
+
+## ⚠ "Sprites/tiles never show AND the CPU crashed (PC near $002B)" — the #1 SDCC footgun
+
+**The single most common way a GB/GBC C game silently dies.** SDCC's sm83
+backend **miscompiles a byte-copy loop that writes through an `__xdata`
+pointer** — the canonical "copy my tiles into VRAM" pattern:
+
+```c
+uint8_t *dst = (uint8_t *)0x8000;   // VRAM
+for (uint8_t i = 0; i < 16; i++) dst[i] = src[i];   // ☠ MISCOMPILES
+```
+
+SDCC emits code that writes to the **return address** instead of `dst`,
+corrupting the stack → the CPU jumps to garbage and crashes (you'll see
+`PC` stuck around `$002B`, `SP` corrupt). The build SUCCEEDS and the ROM
+boots, so it looks like a logic bug — but it's codegen. Symptom: sprites/
+tiles never appear, OAM stays zero, `getCPUState` shows a wild PC.
+
+**Fix — use the bundled helper, never a raw `dst[i]=src[i]` loop to VRAM:**
+```c
+memcpy_vram(dst, src, 16);   // ships in gb_runtime.c — does the copy safely
+```
+`memcpy_vram()` is in every GB/GBC project's `gb_runtime.c`. Any time you copy
+bytes into VRAM ($8000-$9FFF) or another `__xdata` region, call it instead of
+hand-rolling a for-loop. (`buildSource` with `lint:"strict"` will also flag the
+raw pattern as a preflight error.)
+
+## ⚠ "Loop never ends / all code after a loop is dead" — uint8 loop-bound trap
+
+```c
+uint8_t i;
+for (i = 0; i < 32 * 32; i++) { ... }   // ☠ 255 < 1024 is ALWAYS true → infinite
+```
+A `uint8_t` counter can't reach a bound >255, so the loop never exits and
+everything after it is dead code. SDCC does **not** warn. Use `uint16_t` for any
+loop whose bound can exceed 255. (The preflight linter flags this too.) See also
+the cross-platform note: [[sdcc-uint8-loop-bound-trap]].
+
+## "Wrong colors on GBC"
+
+1. **`$0143` is not $80.** This is the CGB-mode header byte.
+   `buildSource` / `runSource` set it automatically from the platform —
+   build with `platform:"gbc"` and it's $80/$C0; build with
+   `platform:"gb"` and it stays $00 (DMG). So if colors are wrong, first
+   check you didn't build this as a `.gb` ROM — rebuild with
+   `platform:"gbc"`. (To force a value on an existing ROM: set it in your
+   `gb_crt0.s` header section, run `patchGbHeader({path:"out.gbc"})`, or
+   run `node patch-header.js out.gbc`.) Verify:
+   ```sh
+   xxd -s 0x143 -l 1 out.gbc      # expect: 80
+   ```
+2. **You wrote to `BGP` / `OBP0` / `OBP1` instead of `BCPD` /
+   `OCPD`.** DMG and CGB use different palette registers. On CGB,
+   `BGP` is ignored — you must drive the 64-byte BG palette RAM via
+   `BCPS` (bit 7 = auto-increment) + `BCPD` for writes.
+3. **Forgot to set BCPS/OCPS auto-increment bit.** `BCPS = 0x80`
+   means "palette 0, color 0, low byte, auto-advance after every
+   BCPD write". Without bit 7, you have to set the address before
+   every byte.
+4. **Tile attributes (VRAM bank 1) aren't set.** CGB BG colors come
+   from the attribute map in VRAM bank 1 at $9800-$9BFF. Default is
+   all zeros = palette 0 for every tile. To use other palettes:
+   ```c
+   VBK = 1;
+   *((uint8_t *)0x9800) = 1;  // first tile uses palette 1
+   VBK = 0;
+   ```
+
+## "Game freezes / hangs"
+
+1. **PC is at $0040 (vblank IRQ vector) but no handler.** You enabled
+   `IE` and `EI` but didn't `RETI` from the IRQ vector. Result: the
+   CPU is permanently in the IRQ. The default `gb_crt0.s` puts
+   `RETI` at every IRQ vector — so this only happens if you've
+   replaced the crt0.
+2. **Stack overflow.** With a 32 KB ROM you have ~8 KB of WRAM
+   ($C000-$DFFF). Default SP is $E000 (top). If you're recursing
+   deeply or putting huge arrays on the stack, you can hit $C000 and
+   corrupt initialized globals.
+   ```js
+   loadCategory({category:"debug"})
+   getCPUState({})   // check SP
+   ```
+3. **`halt` without `IE`.** A bare `halt` with no enabled interrupts
+   on DMG can deadlock or skip an instruction (the halt-bug). The
+   runtime's `oam_dma_copy` and `wait_vblank` use polling, not
+   `halt`, to avoid this.
+
+## "Build succeeds but ROM doesn't load (`retro_load_game failed`)"
+
+**Cause: ROM has no Nintendo logo or bad checksum.** The build
+pipeline patches in the canonical logo + checksums for every gb/gbc
+build automatically (search `NINTENDO_LOGO` in
+`src/toolchains/index.js`). If you're seeing this error:
+
+1. You're loading a hand-built ROM from somewhere other than this
+   pipeline (e.g. an asm-only ROM not run through rgbfix).
+2. Confirm the bytes:
+   ```sh
+   xxd your.gbc | sed -n '/00000100:/,/00000150:/p'
+   ```
+   At $0104-$0133 you should see the Nintendo logo (starts `CE ED 66 66`).
+   At $014D you should see the header checksum.
+
+## "Code at $0100-$014F got clobbered"
+
+The `gb_crt0.s` reserves $0100-$014F for the cartridge header. The
+SDCC linker is configured with `-b _CODE=0x0150` so user code starts
+at $0150. If you see code in that window, either:
+- You're not using the bundled crt0 (passing your own `crt0:` to the
+  build), in which case make sure it reserves the header window.
+- A custom `linkerConfig` is overriding the code base. The default
+  works; don't override it for GB/GBC unless you know what you're
+  doing.
+
+## Debug recipes
+
+A few high-leverage tools you might not know exist:
+
+- **`inspectSprites({platform:"gbc"})`** — pretty-prints all 40 OAM
+  slots showing which are on-screen + tile index + attributes.
+- **`inspectBackgroundMap({platform:"gbc", render:true})`** — renders
+  the BG map as a PNG so you can see what tiles the LCD is reading.
+- **`inspectPalette({platform:"gbc"})`** — shows BG and OBJ palettes
+  as colors instead of raw BGR555 bytes.
+- **`getCPUState({})`** — PC + registers, useful when you suspect a
+  hang.
+- **`watchMemory({region:"gb_oam", offset:0, length:4})`** — trace
+  every write to OAM slot 0, returns the PC that wrote it.
+- **`stepFrames({frames:3600})`** — runs a full minute of game time
+  in milliseconds. Don't be conservative with frame counts when
+  hunting bugs.
+
+## Mental model
+
+Boot order that always works for GBC:
+
+```
+1. LCDC = 0  (turn off LCD; safe even if already off — runtime checks)
+2. Write tile data to $8000+ via VRAM bank 0
+3. Write CGB attribute map to $9800+ via VRAM bank 1 (set VBK=1 first)
+4. BCPS = 0x80 ; BCPD writes set up BG palette (64 bytes)
+5. OCPS = 0x80 ; OCPD writes set up OBJ palette (64 bytes)
+6. Build initial OAM via oam_set() into shadow_oam[]
+7. LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO
+8. for (;;) {
+     wait_vblank();         // LY hits 144
+     oam_dma_flush();       // shadow_oam → $FE00
+     pad = joypad_read();   // read input AFTER OAM is up
+     /* update game state */
+     oam_set(...);          // restage sprites
+   }
+```
+
+Cribbed from `examples/gbc/templates/tile_engine.c` — start a fresh
+game from that template with:
+
+```js
+createProject({
+  platform: "gbc",
+  template: "tile_engine",
+  name: "mygame",
+  path: "/abs/path/to/dir",
+});
+```
+
+## Adding a new symptom
+
+Hit something not on this list? Open an issue with a 5-line repro and
+the symptom at https://github.com/monteslu/romdev/issues.

package/src/platforms/gb/UPSTREAM_SOURCES.md

@@ -0,0 +1,43 @@
+# Game Boy — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/gb/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/gb/lib/c/gb_runtime.c`,
+   `gb_crt0.s`, `patch-header.js`, `hUGEDriver.c` (full source).
+3. **SDCC sm83 port** — we ship the WASM compiler but NOT the SDCC
+   source tree. For SDCC bugs, see upstream below.
+4. **Upstream GitHub**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ + https://sourceforge.net/projects/sdcc/ |
+   | hUGEDriver | https://github.com/SuperDisk/hUGEDriver |
+   | RGBDS (asm path) | https://github.com/gbdev/rgbds |
+   | gambatte libretro core | https://github.com/libretro/gambatte-libretro |
+   | gambatte proper | https://github.com/sinamas/gambatte |
+
+## GB hardware docs
+
+- **Pan Docs** (canonical, everything): https://gbdev.io/pandocs/
+- **GBDev community resources**: https://gbdev.io/
+- **opcode reference**: https://gbdev.io/gb-opcodes/optables/
+- **SDCC sm83 specifics**: see `src/platforms/gb/lib/c/SDCC_GOTCHAS.md`
+
+## hUGEDriver music format
+
+See `src/platforms/gb/lib/c/hUGEDriver.c` header comment + the
+upstream README. Songs are exported from hUGETracker
+(https://github.com/SuperDisk/hUGETracker) as `.c` files —
+`song_data.c` in our bundle is one such export.
+
+## When to use what
+
+- "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
+  `gb_runtime.c` `oam_dma_copy` implementation
+- "BGP write does nothing" → check $0143 (CGB flag) via
+  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+- "How does hUGEDriver process a song row?" → `hUGEDriver.c`
+  `hUGE_dosound` body — fully readable
+- "Why is gambatte refusing my ROM?" → check the header, then
+  libretro-gambatte source for the load path

package/src/platforms/gb/image-to-tilemap.js

@@ -0,0 +1,173 @@
+// Game Boy / Game Boy Color image-to-tilemap converter.
+//
+// DMG mode: 160×144 screen (20×18 tiles), 2bpp interleaved tile format,
+// 4-shade palette. BG map is 32×32 bytes (we fill the visible 20×18 cells).
+//
+// CGB extends DMG with: 16 BG palettes × 4 colors (BGR555), per-tile
+// palette attribute (bits 0-2 of BG map's bank 1 attribute byte), VRAM
+// bank 1 for tile attributes + bank 0/1 for tile data. This module
+// handles DMG only — agents who need CGB-specific behavior pass GBC
+// palette + use the cgbAttr output field if extended later.
+
+import { PNG } from "pngjs";
+import { DMG_PALETTE } from "./ppu.js";
+
+const W = 160;
+const H = 144;
+
+/** Encode one 8×8 region of the source PNG as a 16-byte GB tile (2bpp interleaved). */
+function encodeTile(pxIdx, tx, ty, w) {
+  const out = new Uint8Array(16);
+  for (let row = 0; row < 8; row++) {
+    let lo = 0, hi = 0;
+    for (let col = 0; col < 8; col++) {
+      const c = pxIdx[(ty * 8 + row) * w + (tx * 8 + col)];
+      if (c & 1) lo |= 1 << (7 - col);
+      if (c & 2) hi |= 1 << (7 - col);
+    }
+    out[row * 2 + 0] = lo;
+    out[row * 2 + 1] = hi;
+  }
+  return out;
+}
+
+/**
+ * @param {Object} args
+ * @param {Buffer | Uint8Array} args.pngBytes  160×144 PNG, pre-quantized to ≤4 colors.
+ * @param {[number,number,number][]} [args.shadePalette] target 4 RGB shades
+ *   (default DMG green). Used only for the preview render — the encoded
+ *   bytes are palette-index 0..3, the hardware BGP register selects shades.
+ * @returns {{
+ *   chr: Uint8Array,        // tile data (2bpp interleaved, 16B/tile)
+ *   nametable: Uint8Array,  // 32×32 map (we fill 20×18 + zeros)
+ *   attr: Uint8Array,       // empty (DMG has no per-cell attr)
+ *   palette: Uint8Array,    // empty (DMG palette is in BGP/OBP regs, not RAM)
+ *   uniqueTilesBeforeMerge: number,
+ *   uniqueTiles: number,
+ *   imageColors: number,
+ *   previewPng: Buffer,
+ * }}
+ */
+export function gbImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`GB image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+  const shadePalette = args.shadePalette ?? DMG_PALETTE;
+
+  // 1) Quantize to ≤4 distinct colors. Map by tuple identity.
+  /** @type {Map<number, number>} */
+  const colorIndex = new Map();
+  const pxIdx = new Uint8Array(W * H);
+  const colorKey = (r, g, b) => (r << 16) | (g << 8) | b;
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const ck = colorKey(png.data[k], png.data[k + 1], png.data[k + 2]);
+    let idx = colorIndex.get(ck);
+    if (idx === undefined) {
+      idx = colorIndex.size;
+      if (idx >= 4) {
+        throw new Error(
+          `GB DMG mode takes ≤4 colors; image quantizes to more. ` +
+          `Pre-dither with \`magick … -colors 4 -dither FloydSteinberg\` or ` +
+          `pass a palette via getPlatformPalettePng({platform:"gb"}).`
+        );
+      }
+      colorIndex.set(ck, idx);
+    }
+    pxIdx[i] = idx;
+  }
+
+  // 2) Encode tiles + dedupe (no h/v flip dedup for v1 — GB tile-map cells
+  // don't have flip flags in DMG mode).
+  const tilesAcross = W / 8;  // 20
+  const tilesDown = H / 8;    // 18
+  const tileByKey = new Map();
+  const chr = [];
+  let uniqueBefore = 0;
+
+  // GB BG map is 32 cols × 32 rows; we write the visible 20×18 area and
+  // leave the rest as tile 0.
+  const nametable = new Uint8Array(32 * 32);
+
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      uniqueBefore++;
+      const tile = encodeTile(pxIdx, tx, ty, W);
+      let key = "";
+      for (const b of tile) key += b.toString(16).padStart(2, "0");
+      let idx = tileByKey.get(key);
+      if (idx === undefined) {
+        if (chr.length >= 256) {
+          throw new Error(
+            `GB DMG tilemap exceeded 256 unique tiles after dedup. ` +
+            `Reduce image detail or use bank-switched tile data (CGB only).`
+          );
+        }
+        idx = chr.length;
+        tileByKey.set(key, idx);
+        chr.push(tile);
+      }
+      nametable[ty * 32 + tx] = idx;
+    }
+  }
+
+  const chrFlat = new Uint8Array(chr.length * 16);
+  for (let i = 0; i < chr.length; i++) chrFlat.set(chr[i], i * 16);
+
+  // 3) Preview re-render from encoded data.
+  const preview = new PNG({ width: W, height: H });
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const tileIdx = nametable[ty * 32 + tx];
+      const tileBase = tileIdx * 16;
+      for (let row = 0; row < 8; row++) {
+        const lo = chrFlat[tileBase + row * 2 + 0];
+        const hi = chrFlat[tileBase + row * 2 + 1];
+        for (let col = 0; col < 8; col++) {
+          const bit = 7 - col;
+          const pi = ((lo >> bit) & 1) | (((hi >> bit) & 1) << 1);
+          const [r, g, b] = shadePalette[pi];
+          const o = ((ty * 8 + row) * W + (tx * 8 + col)) * 4;
+          preview.data[o + 0] = r;
+          preview.data[o + 1] = g;
+          preview.data[o + 2] = b;
+          preview.data[o + 3] = 0xff;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable,
+    attr: new Uint8Array(0),
+    palette: new Uint8Array(0),
+    uniqueTilesBeforeMerge: uniqueBefore,
+    uniqueTiles: chr.length,
+    imageColors: colorIndex.size,
+    previewPng: PNG.sync.write(preview),
+  };
+}
+
+/**
+ * Generate a PNG containing the 4 DMG shades. Use as -remap target for
+ * pre-dithering input art.
+ */
+export function gbPalettePng() {
+  const cell = 32;
+  const png = new PNG({ width: 4 * cell, height: cell });
+  for (let i = 0; i < 4; i++) {
+    const [r, g, b] = DMG_PALETTE[i];
+    for (let y = 0; y < cell; y++) {
+      for (let x = 0; x < cell; x++) {
+        const o = (y * 4 * cell + i * cell + x) * 4;
+        png.data[o + 0] = r;
+        png.data[o + 1] = g;
+        png.data[o + 2] = b;
+        png.data[o + 3] = 0xff;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}

package/src/platforms/gb/lib/README.md

@@ -0,0 +1,115 @@
+# Game Boy / Game Boy Color — quickstart
+
+The compressed version of "everything I had to learn the hard way
+building a GB ROM with romdev."
+
+## Language: RGBDS assembly
+
+Game Boy uses RGBDS (rgbasm + rgblink + rgbfix) — the canonical
+toolchain for GB homebrew. `buildSource({platform:"gb", source: <asm>})`
+builds + links + runs `rgbfix` to fix the cart header. GBC builds the
+same way; pass `platform:"gbc"` to enable the CGB-only opcodes (KEY1,
+BCPS, etc.) — gambatte detects mode from the cart header byte at $0143.
+
+C is theoretically supported via GBDK (sdcc-gbz80 backend) but is NOT
+bundled today; the SM83 backend in sdcc 4.4.0 has been less tested for
+us than the z80 backend.
+
+## Snippets shipped in this directory
+
+| File | Purpose |
+|---|---|
+| `header.asm` | $0100-$014F cartridge header. rgbfix fills in the Nintendo logo, title, checksums; you can ship as-is for a working cart. |
+| `lcd_init.asm` | LCD off / on helpers. Turning the LCD off lets you bulk-upload VRAM safely; turn back on once tiles/palette/map are in place. |
+| `vblank_wait.asm` | Polling vblank wait (LY $\geq$ 144). The IRQ-driven variant uses halt to save battery on a real DMG. |
+| `joypad_read.asm` | Reads the joypad via the two-pass $FF00 protocol. Returns one byte: D-pad in low nybble, buttons in high nybble. |
+| `load_palette.asm` | DMG palette setup (BGP/OBP0/OBP1). Standard $E4 = white→gray→darkgray→black. |
+| `load_tiles.asm` | Bulk VRAM upload. Assumes LCD is OFF — pause renders for big uploads. |
+| `dma_oam.asm` | The canonical HRAM-resident OAM DMA routine. Copies shadow OAM at $C000 to actual OAM at $FE00 in 160 µs. |
+
+Fetch any with `getStarterSnippet({platform:"gb", name:"<file>"})`.
+
+## The five gotchas that cost the most time
+
+### 1. VRAM is only safely writable when the PPU isn't reading it
+
+The PPU has the VRAM bus locked during scanlines (PPU modes 2 + 3).
+Writes during those modes are silently dropped. Safe write windows:
+
+- **LCD off** (LCDC bit 7 = 0): unrestricted. Use this for big uploads
+  at startup. Turn LCD off, upload everything, turn back on.
+- **Vblank** (LY ≥ 144): about 1140 cycles per frame — enough for a
+  large but not huge upload (~150 tiles).
+- **Hblank** (PPU mode 0): ~50 cycles each, but you'd be reading STAT
+  bit 1-0 = 0 to detect it. Used for HDMA-style streaming on GBC.
+
+The "screen flashes white when uploading mid-frame" bug is almost
+always missing this. `inspectPatternTiles` shows you exactly what
+landed in VRAM — if it's empty after your upload, the LCD was on.
+
+### 2. OAM DMA must run from HRAM
+
+The OAM DMA pauses the main CPU bus for 160 µs; instructions can only
+fetch from HRAM ($FF80-$FFFE) during that time. The conventional pattern
+is to copy a tiny stub (10 bytes) into HRAM at startup, then call it
+once per vblank. See `dma_oam.asm` for the shipped version — it includes
+both the setup routine (run once) and the HRAM-resident copy stub.
+
+### 3. The cart header MUST have the Nintendo logo + a valid checksum
+
+The boot ROM verifies bytes $0104-$0133 against the Nintendo logo and
+the header checksum at $014D against the sum of $0134-$014C. If either
+fails, the boot ROM halts the console at the logo screen. `rgbfix -v -p 0`
+auto-fixes both:
+
+```bash
+rgbfix -v -p 0 -m MBC1 -t "MYGAME" out.gb
+```
+
+Most emulators (gambatte included) skip the verification when running
+in "headless" mode, so you'll see your game run in romdev's
+gambatte even with an invalid header. Real hardware won't.
+
+### 4. DMG colors are 4 SHADES, not 4 colors
+
+Tile pixel value 0-3 doesn't directly pick an RGB color — it indexes
+into the BGP register, which itself picks a shade from a hardware-
+fixed 4-shade ramp. So "tile pixel = 0" is whatever shade BGP's low
+2 bits select; you can remap shades at runtime by changing BGP.
+
+This is why the same tile data looks completely different in different
+games — they all use 4 shades, but the BGP mapping varies. To preview
+art, use `previewTileArt({platform:"gb", ...})` with an explicit
+palette, or `paletteFromEmulator:true` after loading.
+
+### 5. GBC adds banked VRAM + KEY1 double-speed + 32-color palette
+
+CGB extends DMG in three orthogonal ways:
+
+- **VRAM bank 1**: $FF4F bit 0 swaps which 8 KB of VRAM is mapped to
+  $8000-$9FFF. Bank 1 holds BG tile attribute bytes (palette index,
+  VRAM bank for the tile data, h/v flip, priority).
+- **Palette RAM**: $FF68-$FF6B for BG, $FF6A-$FF6B for sprites. Each
+  palette is 4 × 15-bit BGR. Write the index to $FF68, then read/write
+  data to $FF69 (auto-increment via bit 7 of $FF68).
+- **KEY1** at $FF4D: bit 0 = pending speed switch, bit 7 = double-speed
+  active. Trigger with `stop` instruction. Doubles CPU clock; everything
+  else (PPU, audio) stays at single speed.
+
+`getRenderingContext({platform:"gbc"})` decodes all three.
+
+## A real GB working loop
+
+After init (LCD off → tiles + palette + map → LCD on), the inner loop is:
+
+```
+vblank_wait_poll      ; or halt with vblank IRQ
+call oam_dma          ; DMA shadow OAM to $FE00
+call joypad_read      ; update JoypadState in HRAM
+call game_update      ; your logic — moves shadow OAM around
+jr   main_loop
+```
+
+The shadow-OAM-in-WRAM + DMA-in-vblank pattern is the foundation of
+every commercial GB game. Memory addresses + register names follow the
+RGBDS convention (`hl/de/bc` registers, `ldh` for $FF00-$FFFF I/O).

package/src/platforms/gb/lib/c/LICENSE-HUGEDRIVER

@@ -0,0 +1,25 @@
+hUGEDriver and hUGETracker
+==========================
+
+Repository: https://github.com/SuperDisk/hUGEDriver
+Upstream README (`Quick start (GBDK)` + `License` sections) bundled as
+`hUGEDriver.upstream.asm` (the canonical RGBDS implementation, ~1900 lines).
+
+From the upstream README:
+
+> ## License
+>
+> hUGETracker and hUGEDriver are dedicated to the public domain.
+
+That is, hUGEDriver carries no encumbrance — distributed under CC0 / public
+domain dedication. We therefore include both:
+
+  - hUGEDriver.upstream.asm     The full RGBDS source-of-truth (CC0).
+  - hUGEDriver.{c,h}            A compact SDCC-native rewrite providing the
+                                hUGE_init / hUGE_dosound / hUGE_mute_channel
+                                surface against a simplified song format,
+                                authored from scratch for romdev.
+
+The compact rewrite is independently CC0-dedicated for the same reason —
+no upstream code is copied; it implements a documented public-domain
+interface against the public GB APU register set.