romdevtools 0.13.0

package/src/platforms/lynx/lib/cc65-src/tgi_colors.s

@@ -0,0 +1,9 @@
+;
+; Target-specific black & white values for use by the target-shared TGI kernel
+;
+; NOTE: These are indices into the default palette
+
+        .include        "tgi-kernel.inc"
+
+        .export         tgi_color_black:zp = $01
+        .export         tgi_color_white:zp = $0F

package/src/platforms/lynx/lib/cc65-src/tgi_irq.s

@@ -0,0 +1,11 @@
+;
+; Oliver Schmidt, 2018-02-02
+;
+
+        .export         tgi_libref
+        .interruptor    tgi_irq         ; Export as IRQ handler
+
+        .data
+
+tgi_libref:
+tgi_irq:        .byte   $60, $00, $00   ; RTS plus two dummy bytes

package/src/platforms/lynx/lib/cc65-src/tgi_stat_stddrv.s

@@ -0,0 +1,14 @@
+;
+; Address of the static standard tgi driver
+;
+; Oliver Schmidt, 2012-11-01
+;
+; const void tgi_static_stddrv[];
+;
+
+        .export _tgi_static_stddrv
+        .import _lynx_160_102_16_tgi
+
+.rodata
+
+_tgi_static_stddrv := _lynx_160_102_16_tgi

package/src/platforms/lynx/lib/cc65-src/tgi_stddrv.s

@@ -0,0 +1,13 @@
+;
+; Name of the standard tgi driver
+;
+; Oliver Schmidt, 2012-11-01
+;
+; const char tgi_stddrv[];
+;
+
+        .export _tgi_stddrv
+
+.rodata
+
+_tgi_stddrv:    .asciiz "lynx-160-102-16.tgi"

package/src/platforms/lynx/lib/cc65-src/uploader.s

@@ -0,0 +1,81 @@
+        .include        "lynx.inc"
+        .include        "extzp.inc"
+        .interruptor    _UpLoaderIRQ
+        .export         __UPLOADER__: absolute = 1
+
+load_len=_FileDestAddr
+load_ptr=_FileFileLen
+load_ptr2=_FileCurrBlock
+
+.segment "UPCODE"
+
+ComLynxReadAndExec:
+        ldy     #4
+loop0:
+        jsr     read_byte
+        sta     load_len-1,y
+        dey
+        bne     loop0       ; get destination and length
+        tax                 ; lowbyte of length
+
+        lda     load_ptr
+        sta     load_ptr2
+        lda     load_ptr+1
+        sta     load_ptr2+1
+
+loop1:
+        inx
+        bne     cont1
+        inc     load_len+1
+        bne     cont1
+        jmp     (load_ptr)
+
+cont1:
+        jsr     read_byte
+        sta     (load_ptr2),y
+        sta     PALETTE + 1         ; feedback ;-)
+        iny
+        bne     loop1
+        inc     load_ptr2+1
+        bra     loop1
+
+read_byte:
+        bit     SERCTL         ; Check for RXRDY ($40)
+        bvc     read_byte
+        lda     SERDAT
+        rts
+
+_UpLoaderIRQ:
+        lda     INTSET
+        and     #SERIAL_INTERRUPT
+        bne     @L0
+        clc
+        rts
+@L0:
+        lda     SERDAT          ; wait for the start sequence
+        bit     flag            ; already seen $81 ?
+        bpl     again           ; >= 0 => no
+        cmp     #$50            ; "P" ?
+        bne     again           ; not correct, so clear flag
+        sei
+        jmp     ComLynxReadAndExec
+
+again:
+        stz     flag
+        cmp     #$81
+        bne     exit
+        sta     flag
+;
+; last action : clear interrupt
+;
+exit:
+        lda     #SERIAL_INTERRUPT
+        sta     INTRST
+        clc
+        rts
+
+.segment "UPDATA"
+
+flag:
+        .byte   0
+

package/src/platforms/lynx/song.js

@@ -0,0 +1,291 @@
+// Lynx (Mikey) song compiler — note/duration song → the exact bytestream the
+// BUNDLED cc65 sound driver (lib/cc65-src/lynx-snd.s) plays via lynx_snd_play().
+//
+// This is NOT a port of an external tool: the Lynx has no canonical "song
+// compiler". The only playable format is whatever OUR bundled driver reads, and
+// that driver is cc65's lynx-snd.s. We emit the byte stream its SndGetCmd /
+// SndNewNote loop parses, and we pick note values that index its built-in
+// SndPrescaler / SndReload pitch tables.
+//
+// ── Byte-stream format (parsed in SndGetCmd, lynx-snd.s) ────────────────────
+//   cmd0:  lda (ptr)
+//          beq SndStop          ; byte $00            → TERMINATE the stream
+//          bmi (high bit set)   ; byte $80..$ff       → COMMAND (low 7 bits
+//                                                       index SndCmdsLo/Hi)
+//          else                 ; byte $01..$7f       → NOTE, consumes TWO bytes:
+//                                 byte0 = note index (1..127), byte1 = length in
+//                                 240 Hz player ticks (SndDelay).  (SndNewNote)
+//
+//   So a melody row is the pair  [noteIndex, lengthTicks].  A rest is the
+//   command  $82 (SndPause) followed by  [lengthTicks].  The stream ends with a
+//   single  $00  byte (SndStop). These three are all this compiler emits; the
+//   richer commands ($84 SndSetInstr, $85 SndNewNote2, $86 SndCallPattern,
+//   $88..$8d envelopes, $8e stereo, $91 tempo, $92 SndReturnAll) are documented
+//   in lynx_music.c but are out of scope for a plain note/duration song.
+//
+// ── How a note index becomes a pitch (SndNewNote → SndPrescaler/SndReload) ──
+//   SndNewNote does:  lda SndPrescaler,x → AUDx ctl (timer clock select)
+//                     lda SndReload,x    → AUDx backup (timer reload)
+//   where X is the note index. Both tables hold 128 entries. The Mikey audio
+//   timer emits a square wave at:
+//
+//       f = 1_000_000 / ( 2^prescaler * (reload+1) * 2 )      [Hz]
+//
+//   (1 MHz Mikey base; timer underflows every (reload+1) ticks of a
+//   2^prescaler-µs clock; the output toggles each underflow → ÷2.) A reload
+//   byte of $00 wraps as 256. This formula, applied to the bundled tables,
+//   reproduces a chromatic-ish scale with **index 28 = 440.14 Hz = A4 (+1
+//   cent)** — the anchor this compiler keys off.
+//
+// ── IMPORTANT approximation (read this) ─────────────────────────────────────
+//   The bundled SndReload table was hand-tuned "by ear" (see lynx-snd.s /
+//   lynx_music.c headers) and is NOT a uniform 12-semitone-per-octave scale.
+//   Measured step sizes between adjacent indices range from ~45 cents at the
+//   low end to ~170 cents (wider than a whole tone) in the mid range. There is
+//   no exact integer "midi → index" formula. So this compiler does the same
+//   thing the Atari 7800 32-pitch driver does: it computes each note's IDEAL
+//   equal-tempered frequency (from a configurable base, default A4=440) and
+//   SNAPS to the table index whose Mikey frequency is closest in cents. Each
+//   row reports how many cents it had to bend. Well-served notes (A2,A4,A5,
+//   most of octaves 3–6) land within a few cents; sparse regions can be off by
+//   a quarter-tone. Use `{ index: N }` to bypass snapping and emit a raw index.
+
+/** Semitone index within an octave for each note letter (C=0). */
+const NOTE_BASE = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+
+/**
+ * The bundled driver's SndPrescaler table (lynx-snd.s) — timer clock select
+ * (0..6) per note index. 128 entries; index 0 is the rest/terminator slot.
+ * @type {number[]}
+ */
+export const SND_PRESCALER = [
+  0x00, 0x06, 0x06, 0x06, 0x06, 0x05, 0x05, 0x05, 0x05, 0x05, 0x05, 0x05, 0x04, 0x04, 0x04, 0x04,
+  0x04, 0x04, 0x04, 0x04, 0x03, 0x03, 0x03, 0x03, 0x03, 0x03, 0x03, 0x03, 0x03, 0x03, 0x02, 0x02,
+  0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x02, 0x01, 0x01, 0x01, 0x01, 0x01,
+  0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+];
+
+/**
+ * The bundled driver's SndReload table (lynx-snd.s) — timer backup/reload per
+ * note index. 128 entries; a byte of $00 means 256 (timer wrap).
+ * @type {number[]}
+ */
+export const SND_RELOAD = [
+  0x00, 0x9A, 0x96, 0x8F, 0x86, 0xFA, 0xE5, 0xD1, 0xBE, 0xAC, 0x9C, 0x8D, 0x00, 0xE8, 0xD3, 0xC0,
+  0xAF, 0xA0, 0x93, 0x87, 0xFA, 0xE7, 0xD6, 0xC6, 0xB8, 0xAC, 0xA1, 0x96, 0x8D, 0x84, 0xFA, 0xEB,
+  0xDE, 0xD2, 0xC7, 0xBC, 0xB3, 0xAA, 0xA1, 0x9A, 0x93, 0x8C, 0x86, 0x00, 0xF5, 0xEB, 0xE1, 0xD8,
+  0xCF, 0xC7, 0xC0, 0xB9, 0xB2, 0xAB, 0xA5, 0xA0, 0x9A, 0x95, 0x90, 0x8B, 0x87, 0x82, 0xFD, 0xF5,
+  0xEE, 0xE7, 0xE0, 0xD9, 0xD3, 0xCD, 0xC8, 0xC2, 0xBD, 0xB8, 0xB3, 0xAE, 0xAA, 0xA5, 0xA1, 0x9D,
+  0x99, 0x96, 0x92, 0x8F, 0x8B, 0x88, 0x85, 0x82, 0x7F, 0x7C, 0x79, 0x77, 0x74, 0x72, 0x6F, 0x6D,
+  0x6B, 0x69, 0x67, 0x64, 0x63, 0x61, 0x5F, 0x5D, 0x5B, 0x59, 0x58, 0x56, 0x55, 0x53, 0x51, 0x50,
+  0x4F, 0x4D, 0x4C, 0x4B, 0x49, 0x48, 0x47, 0x46, 0x44, 0x43, 0x42, 0x41, 0x40, 0x3F, 0x3E, 0x3D,
+];
+
+/** Command byte: rest for N ticks (next byte = N). SndPause in lynx-snd.s. */
+export const CMD_PAUSE = 0x82;
+/** Stream terminator byte. SndStop in lynx-snd.s (a $00 byte). */
+export const STREAM_END = 0x00;
+
+/**
+ * Parse a scientific-pitch note name ("C4", "A#3", "Gb5", "C-4") to an absolute
+ * semitone number where C0 = 0, C4 = 48, A4 = 57. (Same convention as the SNES
+ * compiler — copied so the files stay independent.)
+ * @param {string} name
+ * @returns {number} absolute semitone index
+ */
+export function noteToSemitone(name) {
+  const m = /^([A-Ga-g])([#b-]?)(-?\d+)$/.exec(String(name).trim());
+  if (!m) throw new Error(`Lynx song: bad note name "${name}" (expected like "C4", "A#3", "Gb5").`);
+  const letter = m[1].toUpperCase();
+  let semi = NOTE_BASE[letter];
+  if (m[2] === '#') semi += 1;
+  else if (m[2] === 'b') semi -= 1;
+  // '-' is just a separator (FamiTracker-style "C-4"), no accidental.
+  const octave = parseInt(m[3], 10);
+  return octave * 12 + semi;
+}
+
+/**
+ * Mikey square-wave frequency (Hz) produced by note index `i` using the bundled
+ * SndPrescaler / SndReload tables.  f = 1e6 / (2^prescaler * (reload+1) * 2),
+ * with reload $00 wrapping to 256.
+ * @param {number} i note index 1..127
+ * @returns {number} frequency in Hz
+ */
+export function indexToFreq(i) {
+  if (i < 1 || i > 127) throw new Error(`Lynx song: note index ${i} out of range 1..127.`);
+  const presc = SND_PRESCALER[i];
+  const reload = SND_RELOAD[i] === 0 ? 256 : SND_RELOAD[i];
+  return 1e6 / (Math.pow(2, presc) * (reload + 1) * 2);
+}
+
+/**
+ * Find the bundled-table note index whose Mikey frequency is closest (in cents)
+ * to `targetHz`. The table is non-uniform and hand-tuned, so this is a SNAP to
+ * the nearest available pitch (see the approximation note at the top of file).
+ * @param {number} targetHz desired frequency in Hz
+ * @returns {{index:number, freq:number, cents:number}} chosen index, its actual
+ *   frequency, and the bend (positive = table is sharp of target) in cents.
+ */
+export function snapToIndex(targetHz) {
+  let best = 1;
+  let bestCents = Infinity;
+  for (let i = 1; i <= 127; i++) {
+    const cents = 1200 * Math.log2(indexToFreq(i) / targetHz);
+    if (Math.abs(cents) < Math.abs(bestCents)) {
+      bestCents = cents;
+      best = i;
+    }
+  }
+  return { index: best, freq: indexToFreq(best), cents: bestCents };
+}
+
+/**
+ * Frequency (Hz) of an absolute semitone in equal temperament, given the base.
+ * @param {number} semi absolute semitone (C0=0)
+ * @param {number} baseSemi absolute semitone of the reference pitch
+ * @param {number} baseHz frequency of the reference pitch
+ * @returns {number} frequency in Hz
+ */
+export function semitoneToFreq(semi, baseSemi, baseHz) {
+  return baseHz * Math.pow(2, (semi - baseSemi) / 12);
+}
+
+/**
+ * Compile a song to the bundled cc65 Lynx driver's bytestream.
+ *
+ * @param {object} song
+ * @param {Array<{note?:string, index?:number, rest?:boolean, ticks?:number}|string>} song.rows
+ *   One entry per row. Forms:
+ *     - `{note:"A4", ticks:30}`     → snap A4 to the nearest table index, length 30 ticks.
+ *     - `{index:28, ticks:30}`      → emit raw note index 28 (no snapping), length 30.
+ *     - `{rest:true, ticks:30}`     → emit a $82 (SndPause) rest of 30 ticks.
+ *     - `"A4"` / `"A4:30"`          → shorthand for `{note, ticks}` (ticks default below).
+ *     - `"rest"` / `"rest:30"`      → shorthand for a rest.
+ * @param {string|number} [song.base="A4"]   reference note name (or absolute
+ *   semitone) for the equal-tempered grid the snapper targets.
+ * @param {number} [song.baseHz=440]   frequency of `base` in Hz.
+ * @param {number} [song.defaultTicks=30]  ticks for shorthand entries (30 @ 240Hz ≈ 125 ms).
+ * @returns {{bytes: Uint8Array, cSource: string, asm: string, rows: number,
+ *           detail: Array<{kind:string, note?:string, index?:number, ticks:number,
+ *                          freq?:number, target?:number, cents?:number}>}}
+ *   bytes = the raw stream (note/length pairs + rest commands + a $00 terminator);
+ *   cSource = a drop-in `unsigned char song[] = { ... };` matching lynx_music.c's
+ *   `demo_music`; asm = a ca65 `.byte` block; rows = number of input rows;
+ *   detail = per-row resolution info (incl. snap error in cents).
+ */
+export function compileSong(song) {
+  if (!song || !Array.isArray(song.rows)) {
+    throw new Error('Lynx song: expected { rows: [...] }.');
+  }
+  const baseSemi = typeof song.base === 'number' ? song.base : noteToSemitone(song.base ?? 'A4');
+  const baseHz = song.baseHz ?? 440;
+  const defaultTicks = song.defaultTicks ?? 30;
+
+  const out = [];
+  const detail = [];
+
+  for (const raw of song.rows) {
+    let note;
+    let index;
+    let rest = false;
+    let ticks;
+
+    if (typeof raw === 'string') {
+      const [n, t] = raw.split(':');
+      ticks = t != null ? parseInt(t, 10) : defaultTicks;
+      if (n === 'rest' || n === 'R' || n === '-') rest = true;
+      else note = n;
+    } else {
+      note = raw.note;
+      index = raw.index;
+      rest = !!raw.rest;
+      ticks = raw.ticks ?? defaultTicks;
+    }
+
+    if (!Number.isInteger(ticks) || ticks < 1 || ticks > 255) {
+      throw new Error(`Lynx song: ticks ${ticks} out of range 1..255.`);
+    }
+
+    if (rest) {
+      // Rest = SndPause command ($82) + length byte.
+      out.push(CMD_PAUSE, ticks & 0xff);
+      detail.push({ kind: 'rest', ticks });
+      continue;
+    }
+
+    if (index == null && note == null) {
+      throw new Error('Lynx song: a row needs `note`, `index`, or `rest`.');
+    }
+
+    if (index != null) {
+      if (!Number.isInteger(index) || index < 1 || index > 127) {
+        throw new Error(`Lynx song: raw index ${index} out of range 1..127.`);
+      }
+      out.push(index & 0xff, ticks & 0xff);
+      detail.push({ kind: 'note', note, index, ticks, freq: indexToFreq(index) });
+      continue;
+    }
+
+    // Resolve a note name → ideal frequency → snap to nearest table index.
+    const target = semitoneToFreq(noteToSemitone(note), baseSemi, baseHz);
+    const snap = snapToIndex(target);
+    out.push(snap.index & 0xff, ticks & 0xff);
+    detail.push({
+      kind: 'note',
+      note,
+      index: snap.index,
+      ticks,
+      freq: snap.freq,
+      target,
+      cents: snap.cents,
+    });
+  }
+
+  out.push(STREAM_END); // $00 → SndStop, terminate the stream.
+
+  const bytes = new Uint8Array(out);
+
+  // ── C source: a drop-in replacement for lynx_music.c's demo_music[] ──
+  const hex = (b) => '0x' + (b & 0xff).toString(16).padStart(2, '0').toUpperCase();
+  const cLines = [];
+  cLines.push('/* Generated by lynx/song.js — drop into the bundled cc65 driver:');
+  cLines.push(' *   lynx_snd_init();');
+  cLines.push(' *   lynx_snd_play(0, song);');
+  cLines.push(' * Byte stream parsed by SndGetCmd (lynx-snd.s): note/length pairs,');
+  cLines.push(' * 0x82=rest, 0x00=end. Note indices snapped to SndReload/SndPrescaler. */');
+  cLines.push('unsigned char song[] = {');
+  for (const d of detail) {
+    if (d.kind === 'rest') {
+      cLines.push(`  ${hex(CMD_PAUSE)}, ${String(d.ticks).padStart(3)},  /* rest ${d.ticks}t */`);
+    } else {
+      const c = d.cents != null ? ` ${d.cents >= 0 ? '+' : ''}${d.cents.toFixed(0)}c` : '';
+      const nm = d.note ? d.note : `idx${d.index}`;
+      cLines.push(`  ${String(d.index).padStart(3)}, ${String(d.ticks).padStart(3)},  /* ${nm} @ ${d.freq.toFixed(1)}Hz${c}, ${d.ticks}t */`);
+    }
+  }
+  cLines.push(`  ${hex(STREAM_END)}            /* SndStop — end of stream */`);
+  cLines.push('};');
+  const cSource = cLines.join('\n') + '\n';
+
+  // ── ca65 .byte block (same data, asm flavour) ──
+  const asmLines = ['song:'];
+  for (const d of detail) {
+    if (d.kind === 'rest') {
+      asmLines.push(`        .byte $82, ${d.ticks}        ; rest ${d.ticks}t`);
+    } else {
+      const nm = d.note ? d.note : `idx${d.index}`;
+      asmLines.push(`        .byte ${String(d.index).padStart(3)}, ${String(d.ticks).padStart(3)}      ; ${nm} ${d.freq.toFixed(0)}Hz`);
+    }
+  }
+  asmLines.push('        .byte $00              ; SndStop');
+  const asm = asmLines.join('\n') + '\n';
+
+  return { bytes, cSource, asm, rows: song.rows.length, detail };
+}
+
+export default compileSong;

package/src/platforms/msx/MENTAL_MODEL.md

@@ -0,0 +1,115 @@
+# MSX / MSX2 — mental model
+
+One page. Read once before you write your first MSX game. The TROUBLESHOOTING.md
+alongside this file is for when something's broken; this is the "what's going on"
+version.
+
+## Start here — don't hand-write the VDP/PSG plumbing
+
+romdev ships a **hardware helper library** (`src/platforms/msx/lib/c/`:
+`msx_hw.h` + `msx_vdp.c`, plus the cartridge `msx_crt0.s`) so you call
+`msx_set_screen2()`, `msx_vram_write()`, `msx_set_sprite()`, `msx_read_joystick()`,
+`msx_psg_tone()` in plain C. It uses DIRECT Z80 I/O ports (the reliable path —
+NOT fragile inline-asm BIOS wrappers).
+
+The fastest way to a working game: **`scaffold({op:'project', platform: "msx", template:
+"sprite_move"})`** (also `music_sfx`, `catch_game`). It drops a complete,
+*building* project — a verified playable example + the helper lib + the cart
+crt0 + docs. Read the example's `main.c`, then change it. Examples live in
+`examples/msx/`. **Gotcha:** read joystick **port 1** (`msx_read_joystick(1)`) —
+port 0 is the keyboard, which an emulator's gamepad doesn't drive.
+
+## CPU — Z80 (16-bit address space, paged in 16 KB slots)
+
+```
+$0000-$3FFF   slot 0 — BIOS ROM (C-BIOS): BDOS-ish entry points, the font, INITXT etc.
+$4000-$BFFF   slot 1 — YOUR CARTRIDGE (32 KB) maps here
+$C000-$FFFF   slot 3 — work RAM
+```
+
+The MSX uses a slot/subslot memory system; a 32 KB cartridge maps at
+**$4000-$BFFF**. You don't manage slots for a simple ROM — the BIOS pages your
+cart in and CALLs it.
+
+The Z80 has a separate **I/O port** space (`in`/`out`). The VDP, PSG, and PPI
+(keyboard/joystick) are reached via ports, but for most things you call **BIOS
+routines** in slot 0 instead of touching ports directly.
+
+## The cartridge boot handshake (critical)
+
+A cart ROM begins with a 16-byte header at $4000:
+```
+$4000  "AB"           cartridge magic (0x41 0x42)
+$4002  INIT  pointer  the BIOS CALLs this to start your program
+$4004  STATEMENT      BASIC hook (0 = none)
+$4006  DEVICE         (0 = none)
+$4008  TEXT           (0 = none)
+$400A..$400F          reserved (0)
+```
+On boot the BIOS scans slots, finds "AB", and **CALLs INIT**. Two rules:
+1. **INIT must NOT return.** If it `ret`s, the BIOS decides no bootable cart is
+   present and prints "No cartridge found" (after running your code, so you'll
+   *see* your output flash, then the error). End `main()` in an infinite loop.
+2. **C-BIOS shows its logo for ~2-3 s (≈150 frames) BEFORE calling INIT.** Step
+   at least 240 frames before expecting output on screen.
+
+romdev's `msx_crt0.s` starter emits this header and handles the handoff; build
+your `main.c` together with it (`crt0:'.module empty\n'`).
+
+## Video — V9938 VDP (TMS9918 superset on MSX2)
+
+VRAM up to 128 KB. The VDP has 64 registers (`msx_vdp_regs`) + 16 status
+registers (`msx_vdp_status`):
+- **R1 bit 6** is the master display enable. If clear, you see only the border
+  color. `background({view:'renderState'})` reads this.
+- Screen mode is selected by M1-M5 bits across R0/R1. Text (screen 0/1), tiled
+  (screen 2), and MSX2 bitmap (screen 4+) modes have different VRAM table layouts;
+  `background({view:'renderState'})` decodes the mode and the pattern/color/sprite table base
+  addresses for you.
+- **Palette:** on MSX2 bitmap modes, 16 programmable entries (`msx_palette`),
+  each a **9-bit GRB** value. On MSX1/TMS9918 modes the palette is a fixed
+  16-color hardware set. `palette({source:'live'})` picks the right source automatically.
+- **Sprites:** up to 32, defined in a VRAM sprite-attribute table (base from R5/
+  R11). Y=208 ($D0) terminates the list. `sprites({op:'inspect'})` reads it.
+
+## Frame heartbeat
+
+The VDP raises a VBlank interrupt (~60 Hz NTSC / 50 Hz PAL). Status register 0
+bit 7 is the VBlank flag. The BIOS's interrupt handler runs each frame; your code
+can hook it or just poll.
+
+## Build pipeline
+
+`build({output:'rom', platform: "msx"})` → SDCC (z80, C89) → sdasz80 → sdld with your
+`msx_crt0.s` → a 32 KB `$4000`-based cartridge image. The fastest visible output
+is BIOS calls: **INITXT ($006C)** (40-col text mode + clear + enable display),
+**CHPUT ($00A2)** (print the char in register A). The `hello_msx.c` starter does
+exactly this.
+
+## Art + input
+
+- `encodeArt({stage:'tiles', platform: "msx"})` — PNG → MSX screen-2 tiles. Returns
+  TWO streams: `pattern.bin` (1bpp) + `color.bin` (per-row fg/bg nibbles into the
+  fixed 16-color TMS9918 palette). Each 8-pixel row is limited to 2 colors —
+  that's the classic MSX constraint. DMA pattern.bin to the pattern-generator
+  base and color.bin to the color-table base (getRenderingContext shows both).
+- `input({op:'layout', platform: "msx"})` — the joystick path via BIOS GTSTCK
+  ($00D5) + GTTRIG ($00D8). **Driving input over MCP:** bluemsx maps `input({op:'set'})`
+  straight through (verified live, no inversion): `{a}`→trigger 1 (east),
+  `{b}`→trigger 2 (west). So `input({op:'set', a: true})` presses trigger 1 as
+  expected — unlike the genesis_plus_gx platforms, there's no surprise here.
+
+## Debugging tools
+
+- `cpu({op:'read'})` — Z80 PC/SP/AF/BC/DE/HL/IX/IY + shadow regs + flags + IFF/IM.
+- `background({view:'renderState'})` — VDP R1 display-enable, screen mode, VRAM table bases.
+- `palette({source:'live'})` — V9938 9-bit GRB (or TMS9918 fixed) 16 entries.
+- `sprites({op:'inspect'})` — VRAM sprite-attribute table, up to 32 sprites.
+- `symbols({op:'map', map})` — pass the sdld `.map` (the `symbols` field from
+  buildSourceWithDebug) to see where SDCC placed your variables/code, grouped by
+  region (bios / cart_rom / work_ram).
+- `audioDebug({op:'inspect', chip: "ay8910"})` — the AY-3-8910 PSG: 3 square-wave
+  channels (tone period→Hz, amplitude, tone/noise enable) + a shared noise
+  generator + the envelope (period + shape bits).
+- `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
+  `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).

package/src/platforms/msx/TROUBLESHOOTING.md

@@ -0,0 +1,62 @@
+# MSX — troubleshooting (symptom → cause → fix)
+
+Read this when something's broken. For the "how it works" overview, read
+MENTAL_MODEL.md first.
+
+## "No cartridge found" — but I SEE my text flash first
+
+**THE most common MSX cart trap.** Your INIT routine returned. C-BIOS CALLs the
+cart INIT to hand over the machine; if INIT `ret`s, the BIOS concludes there's no
+bootable cart and prints "No cartridge found" — *after* running your code, so you
+see your output for a moment, then the error replaces it.
+
+**Fix:** a cartridge INIT must NEVER return. End `main()` in an infinite loop
+(`for (;;) {}`). A real game does its input/update/draw in that loop. The
+`hello_msx.c` starter does this.
+
+## Black/border-only screen, only the C-BIOS logo
+
+Two possibilities:
+1. **You didn't step long enough.** C-BIOS shows its logo for ~2-3 s (≈150
+   frames) BEFORE calling the cart INIT. Step >= 240 frames before judging.
+2. **The cart wasn't recognized.** Check the first 4 bytes of your ROM are
+   `41 42 xx xx` ("AB" + INIT pointer). If not, you're missing `msx_crt0.s` or
+   didn't pass `crt0:'.module empty\n'`. romdev synthesizes a fallback header if
+   the crt0 didn't, but the INIT must point at real code.
+
+## Display is off (border color only) after INIT runs
+
+The V9938 display-enable bit is clear. `background({view:'renderState'})` shows
+`screenEnabled:false` → VDP R1 bit 6 is 0. Call **INITXT ($006C)** (or your
+mode-set BIOS routine) which sets the screen mode AND enables display. Raw VDP
+users: set R1 bit 6.
+
+## Text prints garbage or nothing
+
+- `INITXT` must run before `CHPUT` — it sets text mode and uploads the font.
+- File-scope `__asm`/`__endasm` is a **SDCC syntax error** ("syntax error: token
+  '__endasm'"). Put asm data (your message bytes + its label) INSIDE a function's
+  asm block, jumped over with `jr`. See `hello_msx.c`.
+- Don't rely on SDCC's stack-frame calling convention for a char-print helper;
+  the robust pattern is one asm block that loads `hl` with the string address and
+  loops `ld a,(hl) / call $00A2 / inc hl`.
+
+## Colors wrong on an MSX2 bitmap screen
+
+The V9938 palette is **9-bit GRB** packed as `red=(v>>4)&7, green=v&7,
+blue=(v>>8)&7`, each ×255/7 — NOT RGB. `palette({source:'live'})` decodes it (it reports
+`paletteSource: "v9938"` vs `"tms9918"`). On MSX1/TMS9918 modes the palette is
+fixed hardware colors — you choose indices, not RGB.
+
+## Sprites invisible
+
+- `sprites({op:'inspect'})` shows the VRAM sprite-attribute table (base from R5/R11).
+  A Y value of **208 ($D0)** terminates the list — sprites after it are off.
+- MSX sprites have no flip bits; priority is by slot order (slot 0 = frontmost).
+- Sprite size/magnify come from VDP R1 bits 0-1 (8×8 vs 16×16, ×1 vs ×2).
+
+## Build fails intermittently on main.c
+
+The build worker pool can transiently fail. Re-run the build. If it fails
+consistently, read the `log` — SDCC's C89 parser errors are terse; common causes
+are `//` comments, mid-block declarations, or file-scope inline asm (see above).

package/src/platforms/msx/UPSTREAM_SOURCES.md

@@ -0,0 +1,46 @@
+# MSX — upstream sources
+
+Pointers to the bundled library source + upstream repos, for when romdev's
+examples aren't enough and you need ground truth.
+
+## Toolchain — SDCC (z80 port)
+
+- Upstream: https://sourceforge.net/projects/sdcc/ (the `z80` port).
+- Bundled in romdev-toolchain-sdcc. romdev does NOT use a vendored MSX SDK; you
+  call the C-BIOS / MSX BIOS routines directly from inline asm (`call 0x006C`
+  etc.). The `msx_crt0.s` starter provides the cartridge boot handshake.
+- SDCC is **C89** with quirks: declare locals at the top of a block, no `//` in
+  strict mode, and **file-scope `__asm` is a syntax error** — inline asm only
+  inside functions (put data labels in a function asm block, jumped over).
+- Standard MSX BIOS entry points you'll use: INITXT $006C (text screen),
+  INIT32 $006F (32-col), CHPUT $00A2 (print char in A), CHGET $009F (read key),
+  GTSTCK $00D5 (joystick), GTTRIG $00D8 (trigger). These live in C-BIOS slot 0.
+
+## Emulator core — blueMSX (libretro)
+
+- Upstream: https://github.com/libretro/blueMSX-libretro (blueMSX by Daniel
+  Vik et al., BSD-3-Clause).
+- romdev pins a specific commit (scripts/versions.json) and applies TWO patches:
+  - `scripts/patches/bluemsx-emscripten-build.patch` — REQUIRED build fix.
+    Adds `-fno-common` (the non-obvious one: `-fcommon` makes blueMSX's tentative
+    definitions VANISH under wasm-ld) + clang warning relaxations.
+  - `scripts/patches/bluemsx-romdev-memory-regions.patch` — exposes the V9938
+    VRAM/regs/status/palette + Z80 CPU snapshot via `retro_get_memory_data` for
+    the inspect tools (blueMSX has no public accessors, so it adds getters in
+    `Src/VideoChips/VDP.c` reading the `theVdp` singleton, and reads the CPU via
+    `(R800*)boardInfo.cpuRef` in `libretro.c`).
+- Ground-truth files (in the blueMSX source): `Src/VideoChips/VDP.c` (the VDP —
+  the 9-bit GRB palette pack at ~line 1338, the screen-mode dispatch at ~line 425,
+  `vdpRegs[64]` / `vdpStatus[16]` / `paletteReg[16]` fields), `Src/Z80/R800.h`
+  (the CpuRegs struct), `Src/Board/MSX.c` (cart/board setup).
+
+## BIOS — C-BIOS
+
+- Upstream: https://cbios.sourceforge.net/ (C-BIOS, 2-clause BSD). An
+  open-source MSX/MSX2/MSX2+ BIOS that lets cartridge homebrew boot with no
+  proprietary ROM.
+- romdev ships the C-BIOS machine tree (Machines/{MSX,MSX2,MSX2+} - C-BIOS) in
+  the romdev-core-bluemsx package's `bios/` dir; the host mirrors it into the
+  emulator's virtual filesystem and forces the "MSX2+ - C-BIOS" machine
+  automatically. You don't need to configure anything.
+- C-BIOS does NOT implement BASIC or disk — it's enough for cartridge games.