docs: add visual branding with heading and cartridge images to README

Author: eddmann

Makefile

@@ -1,12 +1,12 @@
-.PHONY: help setup install test lint shell run clean rebuild build-wasm serve-wasm check-sdl install-sdl run-sdl run-sdl-host
+.PHONY: help setup install test lint shell run run-no-jit clean rebuild build-wasm serve-wasm check-sdl install-sdl run-sdl run-sdl-host
 
 help: ## Show this help message
 	@echo 'Usage: make [target]'
 	@echo ''
 	@echo 'Available targets:'
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
 
-setup: ## Build Docker image with PHP 8.5 RC4
+setup: ## Build Docker image with PHP 8.4
 	docker compose build
 
 rebuild: ## Rebuild Docker image from scratch (no cache)
@@ -27,11 +27,21 @@ lint: ## Run PHPStan static analysis in Docker
 shell: ## Open bash shell in Docker container
 	docker compose run --rm phpboy bash
 
-run: ## Run emulator with ROM in Docker (usage: make run ROM=path/to/rom.gb)
+run: ## Run emulator with ROM in Docker with JIT enabled (usage: make run ROM=path/to/rom.gb)
 	@if [ -z "$(ROM)" ]; then \
 		echo "Error: ROM parameter is required. Usage: make run ROM=path/to/rom.gb"; \
 		exit 1; \
 	fi
+	docker compose run --rm -it \
+		-e PHP_INI_SCAN_DIR=/usr/local/etc/php/conf.d:/app/docker/php-jit \
+		phpboy php -d opcache.jit_buffer_size=100M -d opcache.jit=tracing \
+		bin/phpboy.php $(ROM)
+
+run-no-jit: ## Run emulator without JIT for baseline performance (usage: make run-no-jit ROM=path/to/rom.gb)
+	@if [ -z "$(ROM)" ]; then \
+		echo "Error: ROM parameter is required. Usage: make run-no-jit ROM=path/to/rom.gb"; \
+		exit 1; \
+	fi
 	docker compose run --rm phpboy php bin/phpboy.php $(ROM)
 
 debug: ## Run emulator in debug mode (usage: make debug ROM=path/to/rom.gb)

README.md

@@ -1,61 +1,107 @@
-# PHPBoy - Game Boy Color Emulator
+<p align="center">
+  <img src="docs/heading.png" alt="PHPBoy - Game Boy Emulator" />
+</p>
 
-A readable, well-architected Game Boy Color (GBC) emulator written in PHP 8.5 with multiple frontend options: native SDL2 desktop, CLI terminal, and browser via WebAssembly.
+A readable, well-architected Game Boy (DMG) emulator written in PHP 8.4 with multiple frontend options: CLI terminal (primary), browser via WebAssembly, and native SDL2 desktop (WIP).
+
+## Current Status
+
+PHPBoy is a highly accurate DMG (original Game Boy) emulator with:
+
+- ✅ CLI Terminal Frontend: Fully working, 25-30 FPS baseline, 60+ FPS with PHP JIT enabled
+- ✅ DMG Emulation: Complete CPU, PPU, memory bus, input, and cartridge support (MBC1/MBC3/MBC5)
+- ✅ Test Accuracy: 100% pass rate on Blargg's test suite (11/11 CPU tests + timing test)
+- ✅ Commercial ROMs: Tetris, Pokemon Red, Zelda all run stably
+- ✅ Browser (WASM): Renderer works but very slow due to WASM overhead
+- ⏳ GBC Color Support: Planned for future implementation after DMG emulation is fully complete
+- 🔄 Audio: APU implemented, working on output integration (CLI/SDL2/WASM)
+- 🔄 Mooneye Test Suite: Working on full support (10/39 currently passing)
+- 🔄 Acid Tests: Working on dmg-acid2/cgb-acid2 support
+- 🔄 SDL2 Native Desktop: Work in progress
+
+<p align="center">
+  <img src="docs/cartridges.png" alt="Supported Cartridges" />
+</p>
 
 ## Features
 
-- **Modern PHP 8.5 RC**: Leverages the latest PHP 8.5 release candidate features including strict types, readonly properties, enums, typed class constants, and property hooks
-- **Multiple Frontends**:
-  - **SDL2 Native Desktop**: Hardware-accelerated rendering with true native performance ⭐ **NEW!**
-  - **Browser (WebAssembly)**: Runs in the browser via php-wasm - no backend required!
-  - **CLI Terminal**: ANSI color rendering in your terminal
-- **Fully Dockerized Development**: All PHP/Composer/testing tools run exclusively in Docker containers for consistency
-- **Comprehensive Testing**: PHPUnit 10 for unit and integration tests
-- **Static Analysis**: PHPStan at maximum level (9) for type safety
-- **Modular Architecture**: Clean separation of concerns with dedicated namespaces for CPU, PPU, APU, Bus, and Frontend
+- Modern PHP 8.4: Leverages the latest PHP 8.4 features including strict types, readonly properties, enums, typed class constants, and property hooks
+- Excellent Performance: Achieves 60+ FPS with PHP JIT enabled on typical hardware
+- Multiple Frontends:
+  - CLI Terminal ✅: ANSI color rendering in your terminal - primary working frontend
+  - Browser (WebAssembly) ✅: Runs in the browser via php-wasm - no backend required! (slow performance)
+  - SDL2 Native Desktop 🔄: Hardware-accelerated rendering (WIP)
+- High Accuracy: 100% pass rate on Blargg's CPU instruction and timing tests
+- Fully Dockerized Development: All PHP/Composer/testing tools run exclusively in Docker containers for consistency
+- Comprehensive Testing: PHPUnit 10 for unit and integration tests
+- Static Analysis: PHPStan at maximum level (9) for type safety
+- Modular Architecture: Clean separation of concerns with dedicated namespaces for CPU, PPU, APU, Bus, and Frontend
 
 ## Requirements
 
 - Docker
 - Docker Compose
 - Make (for convenient task automation)
 
-**Important**: All PHP, Composer, PHPUnit, and PHPStan commands must run through Docker. Never run these tools directly on the host machine.
-
 ## Getting Started
 
 ### Initial Setup
 
 1. Clone the repository:
+
 ```bash
 git clone <repository-url>
 cd phpboy
 ```
 
 2. Build the Docker image:
+
 ```bash
 make setup
 ```
 
 3. Install PHP dependencies:
+
 ```bash
 make install
 ```
 
+### Running a Game Boy ROM
+
+The CLI terminal frontend is the primary way to run PHPBoy:
+
+```bash
+# Run with CLI frontend (JIT enabled by default for 60+ FPS)
+make run ROM=path/to/rom.gb
+
+# Run without JIT for baseline performance testing (25-30 FPS)
+make run-no-jit ROM=path/to/rom.gb
+```
+
+CLI Controls:
+
+- Arrow Keys: D-pad
+- Z: A button
+- X: B button
+- Enter: Start
+- Shift: Select
+- Q: Quit
+
 ### Development Workflow
 
-All development tasks are managed through the Makefile and run inside Docker containers. **Never run PHP, Composer, PHPUnit, or PHPStan directly on the host machine.**
+All development tasks are managed through the Makefile and run inside Docker containers.
 
 #### Available Commands
 
 - `make help` - Show available commands
-- `make setup` - Build Docker image with PHP 8.5 RC4
+- `make setup` - Build Docker image with PHP 8.4
 - `make rebuild` - Rebuild Docker image from scratch (no cache)
 - `make install` - Install Composer dependencies in Docker
 - `make test` - Run PHPUnit tests in Docker
 - `make lint` - Run PHPStan static analysis in Docker
 - `make shell` - Open bash shell in Docker container
-- `make run ROM=path/to/rom.gb` - Run emulator with specified ROM in Docker
+- `make run ROM=path/to/rom.gb` - Run emulator with JIT enabled (60+ FPS)
+- `make run-no-jit ROM=path/to/rom.gb` - Run emulator without JIT (25-30 FPS baseline)
 - `make build-wasm` - Build WebAssembly version for browser
 - `make serve-wasm` - Serve WASM build locally on port 8080
 - `make clean` - Remove vendor directory and composer.lock
@@ -76,77 +122,39 @@ make lint
 #### Opening a Shell
 
 For debugging or manual operations:
+
 ```bash
 make shell
 ```
 
-### Running with SDL2 Native Frontend
-
-PHPBoy supports true native desktop rendering using SDL2 for hardware-accelerated, low-latency gameplay.
-
-#### Prerequisites
+## Performance
 
-1. Install SDL2 development libraries:
-   ```bash
-   # Ubuntu/Debian
-   sudo apt-get install libsdl2-dev
+PHPBoy achieves excellent performance thanks to PHP 8.4's JIT compiler:
 
-   # macOS
-   brew install sdl2
-   ```
+- Baseline (no JIT): 25-30 FPS
+- With JIT enabled: 60+ FPS (full Game Boy speed!)
+- Commercial ROMs: Tetris, Pokemon Red, Zelda all run stably at full speed
 
-2. Install SDL2 PHP extension:
-   ```bash
-   sudo pecl install sdl-beta
-   echo "extension=sdl.so" | sudo tee -a $(php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||")
-   ```
+The JIT compiler provides a 2-3x performance improvement, allowing PHPBoy to exceed the original Game Boy's 60 FPS target on modern hardware.
 
-3. Verify installation:
-   ```bash
-   make check-sdl
-   ```
+## Additional Frontends
 
-#### Running a ROM
-
-```bash
-# Run with SDL2 frontend (on host machine)
-make run-sdl-host ROM=path/to/rom.gb
-
-# Or directly with PHP
-php bin/phpboy.php path/to/rom.gb --frontend=sdl
-```
-
-**Features**:
-- ✅ Hardware-accelerated rendering (GPU-based)
-- ✅ VSync support for smooth 60fps
-- ✅ Native desktop window
-- ✅ Low-latency keyboard input
-- ✅ Pixel-perfect integer scaling
-- ✅ Cross-platform (Linux, macOS, Windows)
-
-**Default Controls**:
-- Arrow Keys: D-pad
-- Z or A: A button
-- X or S: B button
-- Enter: Start
-- Right Shift: Select
-
-**Documentation**:
-- [SDL2 Setup Guide](docs/sdl2-setup.md) - Installation instructions
-- [SDL2 Usage Guide](docs/sdl2-usage.md) - Usage and customization
-
-### Running in the Browser
+### Running in the Browser (WebAssembly)
 
 PHPBoy can run entirely in the browser via WebAssembly using [php-wasm](https://github.com/seanmorris/php-wasm).
 
+Note: The WASM frontend works but has significant performance overhead. Expect slower-than-realtime performance. Audio is work in progress.
+
 #### Build for Browser
 
 1. Build the WASM distribution:
+
 ```bash
 make build-wasm
 ```
 
 2. Serve locally:
+
 ```bash
 make serve-wasm
 ```
@@ -155,96 +163,55 @@ make serve-wasm
 
 4. Load a ROM file and play!
 
-**Features**:
+Features:
+
 - ✅ Full emulation in the browser
 - ✅ No backend server required
 - ✅ Keyboard controls
 - ✅ Speed control
 - ✅ Pause/Resume
 - ✅ Works offline after first load
+- 🔄 Audio output integration in progress
+- ⚠️ Performance: Very slow due to WASM overhead
+
+Browser Requirements:
 
-**Browser Requirements**:
 - Chrome 90+, Firefox 88+, Safari 14+, or Edge 90+
 - WebAssembly support required
 
-**Documentation**:
+Documentation:
+
 - [WASM Build Guide](docs/wasm-build.md) - How to build and deploy
 - [Browser Usage Guide](docs/browser-usage.md) - How to use in browser
 - [WASM Options Evaluation](docs/wasm-options.md) - Technical decisions
 
-## Project Structure
+### Running with SDL2 Native Frontend (Work in Progress)
 
-```
-phpboy/
-├── bin/                    # CLI entry point
-├── docs/                   # Documentation
-│   ├── research.md        # Game Boy hardware research
-│   ├── sdl2-setup.md      # SDL2 native frontend setup
-│   ├── sdl2-usage.md      # SDL2 usage guide
-│   ├── wasm-build.md      # WebAssembly build guide
-│   ├── browser-usage.md   # Browser usage guide
-│   └── wasm-options.md    # WASM implementation options
-├── src/                   # Source code
-│   ├── Apu/              # Audio Processing Unit
-│   ├── Bus/              # Memory bus
-│   ├── Cartridge/        # ROM/MBC handling
-│   ├── Cpu/              # CPU emulation
-│   ├── Frontend/         # Multiple frontend implementations
-│   │   ├── Cli/         # CLI terminal frontend
-│   │   ├── Sdl/         # SDL2 native desktop frontend
-│   │   └── Wasm/        # WebAssembly browser frontend
-│   ├── Ppu/              # Pixel Processing Unit
-│   └── Support/          # Utilities and helpers
-├── tests/                # Test suite
-│   ├── Integration/      # Integration tests
-│   └── Unit/            # Unit tests
-├── third_party/          # External resources
-│   ├── references/       # Technical documentation
-│   └── roms/            # Test ROMs
-├── web/                  # Browser frontend
-│   ├── index.html       # Main page
-│   ├── css/             # Stylesheets
-│   ├── js/              # JavaScript bridge
-│   └── phpboy-wasm.php  # PHP entry point
-├── composer.json         # PHP dependencies
-├── package.json         # npm dependencies (for php-wasm)
-├── Dockerfile           # Docker image definition
-├── docker-compose.yml   # Docker services
-├── Makefile            # Task automation
-├── phpstan.neon        # PHPStan configuration
-├── phpunit.xml         # PHPUnit configuration
-└── PLAN.md             # Development roadmap
-```
+PHPBoy has experimental support for native desktop rendering using SDL2 for hardware-accelerated, low-latency gameplay.
 
-## Development Philosophy
+Status: 🔄 Work in progress - code implemented but not fully tested/integrated.
 
-PHPBoy follows a step-by-step development approach, implementing each Game Boy subsystem incrementally. Each step includes:
+Documentation:
 
-- Historical context about the Game Boy hardware
-- Clear implementation tasks
-- Comprehensive tests
-- Documentation updates
-- Verification criteria
+- [SDL2 Setup Guide](docs/sdl2-setup.md) - Installation instructions
+- [SDL2 Usage Guide](docs/sdl2-usage.md) - Usage and customization
+
+## Testing & Accuracy
 
-See `PLAN.md` for the complete development roadmap.
+PHPBoy has excellent accuracy verified by industry-standard test ROMs:
 
-## Testing
+### Test Suite Results
 
-PHPBoy uses industry-standard test ROMs to verify accuracy:
+- ✅ Blargg's CPU Instruction Tests: 11/11 passing (100%)
+  - `cpu_instrs` - All CPU instructions validated
+  - `instr_timing` - Instruction timing accuracy verified
+- 🔄 Mooneye Test Suite: 10/39 passing - working on full support
+  - Focus on improving timing accuracy for remaining tests
+- 🔄 Acid Tests: Working on dmg-acid2/cgb-acid2 support
+  - PPU rendering accuracy improvements in progress
 
-- **Blargg's test suite**: CPU instruction validation
-- **Mooneye test suite**: Hardware behavior verification
-- **dmg-acid2/cgb-acid2**: PPU rendering accuracy
+See `docs/test-results.md` for detailed test results.
 
 ## License
 
 MIT License
-
-## Contributing
-
-Contributions are welcome! Please ensure:
-
-1. All code passes PHPStan level 9
-2. Tests are included for new features
-3. Follow conventional commits format
-4. Use the Makefile for all operations