3 commits

Author	SHA1	Message	Date
Claude	688d9afcec	platformer: end-to-end side-scroller demo + three runtime bug fixes ... Adds `examples/platformer.ne`, a full side-scrolling game that exercises nearly every subsystem of the compiler in one program: custom CHR tileset, 32×30 background nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, moving enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with autopilot so the headless jsnes harness captures real gameplay at frame 180. Tile art + nametable are generated by `scripts/gen_platformer_tiles.rs` (`cargo run --bin gen_platformer_tiles`). Building this out uncovered three independent runtime bugs that together made the example render as black-on-black smileys. All three are fixed in this commit: 1. **`gen_init` enabled sprite rendering before the linker's initial palette/background load runs.** The PPU's v-register auto-increments on every `$2007` write *during active rendering*, so the palette load (32 B) and nametable load (1024 B) were scrambled past the first ~72 bytes — every existing program with a `background Level { ... }` block was silently rendering zero-filled VRAM. Fix: leave `PPU_MASK = 0` at the end of `gen_init` and emit a new `gen_enable_rendering` call *after* all initial VRAM writes complete. 2. **Audio tick corrupted `ZP_CURRENT_STATE`.** The audio driver's period-table lookup reused `$02/$03` as a temporary indirect pointer with a comment claiming the slots were free because the tick doesn't call mul/div. But `$03` is also `ZP_CURRENT_STATE` used by the state dispatch loop, so every music note silently overwrote the state index with the high byte of `__period_table` (`0xC5` in the platformer ROM), wedging the state machine forever. Fix: `gen_nmi` now PHAs `$02/$03` on entry and PLA-restores them on exit, and the audio tick JSR moves inside that save/restore window (it used to be spliced by the linker *before* the register saves, so even A/X/Y were technically being trashed pre-save). Only `audio_demo`'s audio hash shifts (its note timings move a few cycles); every other golden is unchanged. 3. **Sub-palette mirroring footgun.** Writing a 32-byte palette blob sequentially causes the sprite sub-palettes' "index 0" slots at `$3F10/$3F14/$3F18/$3F1C` to clobber the background universal colour at `$3F00/$3F04/$3F08/$3F0C` via NES hardware mirroring. The example's palette sets all eight first bytes to `$22` (sky blue) for this reason; `docs/future-work.md` picks up a TODO to warn on inconsistent first-byte values in the analyzer. Also: - `docs/platformer.gif` — 6-second recording of the example running in jsnes, generated by the new `tests/emulator/record_gif.mjs` puppeteer helper (encodes via `gifenc`, committed as a dev-dependency under `tests/emulator/package.json`). - README / examples/README tables and the 497-test count are updated to cover the new example. https://claude.ai/code/session_01BcCcHi6FUmTh8jC7UgkA3A	2026-04-13 13:04:26 +00:00
Claude	2d66b68c7f	tests/emulator: byte-exact golden-image diffs ... The smoke test used to check a per-example `nonBlack` floor — "at least one sprite rendered," plus a per-example minimum for the multi-sprite examples. That catches gross regressions (a compiler bug that makes everything go black) but silently lets through anything that changes a handful of pixels without dropping below the sprite floor. The whole point of this harness is to catch compiler miscompiles before they land; a softer check means bugs can still sneak in. This swap makes every run diff the raw canvas framebuffer against a committed PNG golden. One mismatched byte at pixel (120, 119) is enough to fail CI — there's nowhere for a regression to hide. Workflow: # normal — fails on any pixel change node tests/emulator/run_examples.mjs # when the diff is intentional, rewrite the goldens UPDATE_GOLDENS=1 node tests/emulator/run_examples.mjs # or: node tests/emulator/run_examples.mjs --update-goldens git diff tests/emulator/goldens/ # review the change git add tests/emulator/goldens/ git commit # explain WHY in the message When a run fails without `UPDATE_GOLDENS`, the runner writes: tests/emulator/actual/<name>.png the run's raw output tests/emulator/actual/<name>.diff.png red-highlighted pixel diff so reviewers can eyeball what changed without rerunning locally. `actual/` is gitignored and re-created on every run. The CI job now uploads `actual/`, `goldens/`, and `report.json` together as a single `emulator-diff` artifact on failure — side by side means the "what changed" story is obvious without cloning. Implementation: - `tests/emulator/screenshots/` is renamed to `tests/emulator/goldens/`. All 18 existing PNGs are preserved as the initial goldens (git detected them as pure renames). - `harness.html` gets a new `window.nesHarness.rawPixelsBase64()` that returns the 245760-byte (256 × 240 × 4 bytes) RGBA canvas buffer as base64. The runner compares raw pixels, not PNG bytes, so encoder quirks (zlib level, filter heuristics) can't cause false positives across Chrome versions or platforms. - The runner uses `pngjs` (pure-JS, no native deps) to decode goldens and to write diff PNGs. `PNG.sync.write` is byte-deterministic for identical pixels, so `git diff` on a committed golden only ever shows up when the actual rendered pixels changed — not because two machines produced slightly different compression. - The committed goldens were re-encoded with pngjs in this commit so the baseline is consistent from day one. File sizes are a touch larger than Chrome's output (~1KB vs ~800B on average), but that's negligible and it eliminates one entire class of flaky-looking diffs in the future. Determinism verification: I ran each of the 18 ROMs twice through fresh `NES` instances in fresh puppeteer pages, hashed the 245760-byte framebuffers at frame 180 with SHA-256, and confirmed `run1 == run2` for every single one. Exact-pixel diffs are safe for this ROM set. Negative path verification: I corrupted one golden (flipped one pixel to pure red via pngjs) and reran the runner. It printed DIFF hello_sprite 1/61440 pixels differ; first at (120,120) expected [255,0,0] got [0,0,0] actual: tests/emulator/actual/hello_sprite.png diff: tests/emulator/actual/hello_sprite.diff.png and exited 1 as expected. The diff PNG shows a dim-grayscale silhouette of the expected frame with a bright-red dot on the one mismatched pixel — enough visual context to locate the regression at a glance. All 18 examples match their goldens in strict mode. `cargo fmt --check`, `cargo clippy --release --all-targets -- -D warnings`, and `cargo test --release` (313 unit + 37 integration) are all still green. https://claude.ai/code/session_014Z5y3Q9krLcAxYpZQJhZ5V	2026-04-12 21:30:18 +00:00
Claude	81f3fd7de0	Add jsnes emulator harness and fix four codegen bugs it surfaced ... Running the compiled example ROMs through a headless puppeteer + local jsnes harness exposed four latent bugs that the header-structure-only integration tests couldn't catch: - src/asm/mod.rs: the first pass treated ANY instruction with `AddressingMode::Label` as a label definition, silently dropping every `JMP`/`JSR` to a label. Now only `NOP + Label` is a label def; other opcodes emit the opcode byte plus a 2-byte absolute fixup resolved in pass two. Without this, every example crashed with "invalid opcode at $1xxx" once the CPU fell through into the math runtime and hit an unbalanced `RTS`. - src/ir/lowering.rs (lower_handler): handler-local `VarDecl`s (e.g. `var i: u8 = 0` inside a `while`) were pushed onto `current_locals` but the handler built its own throwaway `locals` list, so those var ids never got RAM addresses and every `LoadVar`/`StoreVar` for them silently emitted nothing. Seed `current_locals` with the state's declared locals and reuse it so `lower_statement`'s appends flow through to the `IrFunction`. Fixes the black screen in `arrays_and_functions`. - src/ir/lowering.rs (global init): struct-literal initializers on globals (`var player: Player = Player { x: 120, ... }`) fell through to `eval_const`, which returned `None` for a non-literal, so no init code was emitted. Now the per-field synthetic globals each get their own `init_value`. Fixes the black screen in `structs_enums_for`. - src/codegen/mod.rs: the legacy AST codegen was emitting `JSR __fn_poke` / treating `peek` as `LDA #0` for the hardware intrinsics. It only "worked" before because the broken assembler swallowed the bogus JSR. Handle `poke`/`peek` as direct STA/LDA to a compile-time-constant absolute address, matching the IR codegen's intrinsic path. The harness lives in `tests/emulator/`: a tiny HTML page that wraps the `jsnes` npm package, driven by a puppeteer script that loads each ROM, runs ~180 frames, snapshots the canvas, and records a smoke-test verdict (booted without a CPU crash, non-zero pixels rendered, frames differ over time). `npm install && node run_examples.mjs` from `tests/emulator/` runs the full sweep. 9/9 example ROMs now load, render, and animate where expected. All 324 unit + 35 integration tests still pass. https://claude.ai/code/session_014Z5y3Q9krLcAxYpZQJhZ5V	2026-04-12 18:46:58 +00:00