Add cartridge banking, DMA, joypad, and ROM tests

.gitattributes

@@ -0,0 +1,11 @@
+# Normalize line endings so format checks behave the same on every OS.
+# Files are stored with LF and checked out with LF on all platforms.
+* text=auto
+*.zig text eol=lf
+*.zon text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.asm text eol=lf
+*.gb binary
+*.png binary
+*.jpg binary

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      - name: Format check
+        run: zig fmt --check .
+      - name: Unit and integration tests
+        run: zig build test -Dsdl2=off --summary all
+      - name: Regenerate bundled ROMs
+        run: zig build fixtures -Dsdl2=off
+      - name: Committed fixtures match regeneration
+        if: ${{ runner.os == 'Linux' }}
+        run: git diff --exit-code -- fixtures
+      - name: Demo ROM reports PASS
+        run: zig build run-demo -Dsdl2=off
+      - name: Battery RAM save round-trip
+        run: |
+          zig build run-headless -Dsdl2=off -- fixtures/roms/sram.gb --save sram.sav
+          zig build run-headless -Dsdl2=off -- fixtures/roms/sram.gb --load-save sram.sav
+      - name: Build headless tools
+        run: zig build -Dsdl2=off
+
+  windowed:
+    name: Windowed frontend (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      - name: Install SDL2
+        run: sudo apt-get update && sudo apt-get install -y libsdl2-dev
+      - name: Build windowed frontend
+        run: zig build --summary all

.gitignore

@@ -1,4 +1,5 @@
 .zig-cache/
+.zig-global-cache/
 zig-out/
 *.o
 *.obj
@@ -8,5 +9,6 @@ zig-out/
 *.exe
 .DS_Store
 *.gb
+!fixtures/roms/*.gb
 *.sav
 *.swp

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for helping with Dot Matrix Deck.
+This guide explains how to contribute cleanly.
+
+## Before you start
+
+Read the ROADMAP file.
+It lists what the project delivers and what remains.
+Pick an item from the "Next" list or open an issue first.
+
+## Build and test
+
+Build the headless tools.
+
+```text
+zig build -Dsdl2=off
+```
+
+Run the whole test suite.
+
+```text
+zig build test -Dsdl2=off
+```
+
+Run the format check.
+
+```text
+zig fmt --check .
+```
+
+Fix formatting with `zig fmt .`.
+The CI pipeline enforces both checks.
+
+## Make a change
+
+Follow these rules.
+
+- Keep every module small and focused.
+- Match the style of the surrounding code.
+- Do not add comments that restate the code.
+- Add deterministic tests for new behavior.
+- Keep the public API stable unless a test requires a change.
+
+## Regenerate fixtures
+
+Update the bundled ROMs only through their sources.
+
+```text
+zig build fixtures -Dsdl2=off
+```
+
+Commit each `.asm` source and the generated `.gb` image together.
+The round-trip tests check that they stay in sync.
+Each ROM must print PASS over the serial port.
+Keep the ROM small so the headless runner stays fast.
+
+## Open a pull request
+
+- Write a clear title and summary.
+- Keep the change as small as possible.
+- Confirm that tests, format, and builds pass.
+- Confirm the windowed frontend still builds when SDL2 is present.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dot Matrix Deck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NOTICE

@@ -0,0 +1,16 @@
+# Notice
+
+This project includes and links to the following third-party software.
+
+## SDL2
+
+The windowed frontend links against Simple DirectMedia Layer (SDL2).
+SDL2 is licensed under the zlib license.
+The zlib license text is available at https://libsdl.org/license.php
+
+## Test ROM sources
+
+The bundled demo, DMA, and banking ROMs are written for this project.
+The blargg cpu_instrs test suite is not bundled.
+You add it yourself to run the optional suite.
+Refer to the original suite license when you use it.