backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

2025-12-22 00:20:49 +00:00
parent 2934c82b75
commit 5c4cd57ff8
1259 changed files with 239160 additions and 43801 deletions
--- a/docs/internal/archive/plans/dungeon-object-rendering-plan.md
+++ b/docs/internal/archive/plans/dungeon-object-rendering-plan.md
@@ -0,0 +1,58 @@
+# Dungeon Object Rendering & Editor Roadmap
+
+This is the canonical reference for ALTTP dungeon object rendering research and the editor/preview implementation. It lifts the active plan out of the `.claude/plans` directory so everyone can find and update it in one place.
+
+## Context
+- Runtime entrypoints live in ALTTP `bank_00` (see `assets/asm/usdasm/bank_00.asm`): reset/NMI/IRQ plus the module dispatcher (`RunModule`) that jumps to gameplay modules (Underworld load/run, Overworld load/run, Interface, etc.). When wiring emulator-based previews or state snapshots, remember the main loop increments `$1A`, clears OAM, calls `RunModule`, and the NMI handles joypad + PPU/HDMA updates.
+- Dungeon object rendering depends on object handler tables in later banks (Phase 1 below), plus WRAM state (tilemap buffers, offsets, drawing flags) and VRAM/CHR layout matching what the handlers expect.
+
+## Phases
+
+### Phase 1: ALTTP Disassembly Deep Dive
+- Dump and document object handler tables (Type1/2/3), categorize handlers, map shared subroutines.
+- Trace WRAM usage: tilemap buffers, offsets, drawing flags, object pointers, room/floor state; build init tables.
+- Verify ROM address mapping; answer LoROM/HiROM offsets per handler bank.
+- Deliverables: `docs/internal/alttp-object-handlers.md`, `docs/internal/alttp-wram-state.md`, WRAM dump examples.
+- ✅ Handler tables extracted from ROM; summary published in `docs/internal/alttp-object-handlers.md` (Type1/2/3 addresses and common handlers). Next: fill per-handler WRAM usage.
+
+### Phase 2: Emulator Preview Fixes
+- Fix handler execution (e.g., $3479 timeout) with cycle traces and required WRAM state.
+- Complete WRAM initialization for drawing context, offsets, flags.
+- Verify VRAM/CHR and palette setup.
+- Validate key objects (0x00 floor, 0x01 walls, 0x60 vertical wall) against ZScream.
+- **State injection roadmap (for later emulator manipulation):** capture a minimal WRAM/VRAM snapshot that boots directly into a target dungeon room with desired inventory/state. Needed fields: room ID/submodule, Link coords, camera offsets, inventory bitfields (sword/shield/armor/keys/map/compass), dungeon progress flags (boss, pendant/crystal), BG tilemap buffers, palette state. This ties WRAM tracing to the eventual “load me into this dungeon with these items” feature.
+ - **Testing plan (headless + MCP):**
+   1) Build/launch headless with gRPC: `SDL_VIDEODRIVER=dummy ./scripts/dev_start_yaze.sh` (script now auto-finds `build_ai/bin/Debug/yaze.app/...`).
+   2) Run yaze-mcp server: `/Users/scawful/Code/yaze-mcp/venv/bin/python /Users/scawful/Code/yaze-mcp/server.py` (Codex MCP configured with `yaze-debugger` entry).
+   3) Dump WRAM via MCP: `read_memory address="7E0000" size=0x8000` before/after room entry or object draw; diff snapshots.
+   4) Annotate diffs in `alttp-wram-state.md` (purpose/default/required-for-preview vs state injection); script minimal WRAM initializer once stable.
+
+### Phase 3: Emulator Preview UI/UX
+- Object browser with names/search/categories/thumbnails.
+- Controls: size slider, layer selector, palette override, room graphics selector.
+- Preview features: auto-render, zoom, grid, PNG export; status with cycle counts and error hints.
+
+### Phase 4: Restore Manual Draw Routines
+- Keep manual routines as fallback (`ObjectRenderMode`: Manual/Emulator/Hybrid).
+- Revert/retain original patterns for extensible walls/floors.
+- Toggle in `dungeon_canvas_viewer` (or equivalent) to switch modes.
+
+### Phase 5: Object Editor – Selection & Manipulation
+- Selection system (single/multi, marquee, Ctrl/Shift toggles).
+- Movement via drag + grid snap; keyboard nudge.
+- Context menu (cut/copy/paste/duplicate/delete, send to back/front, properties).
+- Scroll-wheel resize with clamping; undo/redo coverage for add/delete/move/resize/property changes.
+
+### Phase 6: Object List Panel
+- Sidebar list with thumbnails, type name, position/size/layer, selection sync.
+- Drag to reorder (draw order), right-click menu, double-click to edit, add dropdown.
+
+### Phase 7: Integration & Polish
+- Shortcuts (Ctrl+A/C/X/V/D/Z/Y, Delete, arrows, +/- resize, Escape clear).
+- Visual feedback: selection borders/handles, drag overlays, status bar (selected count, tool mode, grid snap, zoom).
+- Performance: thumbnail caching, lazy/offscreen rendering, batched updates, debounced re-renders.
+
+## Immediate Next Steps
+- Continue Phase 1 WRAM tracing for problematic handlers (e.g., $3479).
+- Finish selection/UX wiring from Phase 5 once the current editor diffs stabilize.
+- Keep this doc in sync with code changes; avoid editing the `.claude/plans` copy going forward.
--- a/docs/internal/archive/plans/initiative_v040.md
+++ b/docs/internal/archive/plans/initiative_v040.md
@@ -0,0 +1,284 @@
+# Initiative: YAZE v0.4.0 - SDL3 Modernization & Emulator Accuracy
+
+**Created**: 2025-11-23  
+**Last Updated**: 2025-11-27  
+**Owner**: Multi-agent coordination  
+**Status**: ACTIVE  
+**Target Release**: Q1 2026
+
+---
+
+## Executive Summary
+
+YAZE v0.4.0 represents a major release focusing on two pillars:
+1. **Emulator Accuracy** - Implementing cycle-accurate PPU rendering and AI integration
+2. **SDL3 Modernization** - Migrating from SDL2 to SDL3 with backend abstractions
+
+This initiative coordinates 7 specialized agents across 5 parallel workstreams.
+
+---
+
+## Background
+
+### Current State (v0.3.9)
+- ✅ AI agent infrastructure complete (z3ed CLI, Phases 1-4)
+- ✅ Card-based UI system functional (EditorManager refactoring complete)
+- ✅ Emulator debugging framework established
+- ✅ CI/CD pipeline optimized (PR runs ~5-10 min)
+- ✅ WASM web port complete (experimental/preview - editors incomplete)
+- ✅ SDL3 backend infrastructure complete (17 abstraction files)
+- ✅ Semantic Inspection API Phase 1 complete
+- ✅ Public documentation reviewed and updated (web app guide added)
+- 🟡 Active work: Emulator render service, input persistence, UI refinements
+- 🟡 Known issues: Dungeon object rendering, ZSOW v3 palettes, WASM release crash
+
+### Recently Completed Infrastructure (November 2025)
+- SDL3 backend interfaces (IWindowBackend/IAudioBackend/IInputBackend/IRenderer)
+- WASM platform layer (8 phases complete, experimental/preview status)
+- AI agent tools (meta-tools, schemas, context, batching, validation)
+- EditorManager delegation architecture (8 specialized managers)
+- GUI bug fixes (BeginChild/EndChild patterns, duplicate rendering)
+- Documentation cleanup and web app user guide
+- Format documentation organization (moved to public/reference/)
+
+---
+
+## Milestones
+
+### Milestone 1: Emulator Accuracy (Weeks 1-6)
+
+#### 1.1 PPU JIT Catch-up Completion
+**Agent**: `snes-emulator-expert`
+**Status**: IN_PROGRESS (uncommitted work exists)
+**Files**: `src/app/emu/video/ppu.cc`, `src/app/emu/video/ppu.h`
+
+**Tasks**:
+- [x] Add `last_rendered_x_` tracking
+- [x] Implement `StartLine()` method
+- [x] Implement `CatchUp(h_pos)` method
+- [ ] Integrate `CatchUp()` calls into `Snes::WriteBBus`
+- [ ] Add unit tests for mid-scanline register writes
+- [ ] Verify with raster-effect test ROMs
+
+**Success Criteria**: Games with H-IRQ effects (Tales of Phantasia, Star Ocean) render correctly
+
+#### 1.2 Semantic Inspection API
+**Agent**: `ai-infra-architect`
+**Status**: ✅ PHASE 1 COMPLETE
+**Files**: `src/app/emu/debug/semantic_introspection.h/cc`
+
+**Tasks**:
+- [x] Create `SemanticIntrospectionEngine` class
+- [x] Connect to `Memory` and `SymbolProvider`
+- [x] Implement `GetPlayerState()` using ALTTP RAM offsets
+- [x] Implement `GetSpriteState()` for sprite tracking
+- [x] Add JSON export for AI consumption
+- [ ] Create debug overlay rendering for vision models (Phase 2)
+
+**Success Criteria**: ✅ AI agents can query game state semantically via JSON API
+
+#### 1.3 State Injection API
+**Agent**: `snes-emulator-expert`
+**Status**: PLANNED
+**Files**: `src/app/emu/emulator.h/cc`, new `src/app/emu/state_patch.h`
+
+**Tasks**:
+- [ ] Define `GameStatePatch` structure
+- [ ] Implement `Emulator::InjectState(patch)`
+- [ ] Add fast-boot capability (skip intro sequences)
+- [ ] Create ALTTP-specific presets (Dungeon Test, Overworld Test)
+- [ ] Integrate with z3ed CLI for "test sprite" workflow
+
+**Success Criteria**: Editors can teleport emulator to any game state programmatically
+
+#### 1.4 Audio System Fix
+**Agent**: `snes-emulator-expert`
+**Status**: PLANNED
+**Files**: `src/app/emu/audio/`, `src/app/emu/apu/`
+
+**Tasks**:
+- [ ] Diagnose SDL2 audio device initialization
+- [ ] Fix SPC700 → SDL2 format conversion
+- [ ] Verify APU handshake timing
+- [ ] Add audio debugging tools to UI
+- [ ] Test with music playback in ALTTP
+
+**Success Criteria**: Audio plays correctly during emulation
+
+---
+
+### Milestone 2: SDL3 Migration (Weeks 3-8)
+
+#### 2.1 Directory Restructure
+**Agent**: `backend-infra-engineer`
+**Status**: IN_PROGRESS
+**Scope**: Move `src/lib/` + `third_party/` → `external/`
+
+**Tasks**:
+- [ ] Create `external/` directory structure
+- [ ] Move SDL2 (to be replaced), imgui, etc.
+- [ ] Update CMakeLists.txt references
+- [ ] Update submodule paths
+- [ ] Validate builds on all platforms
+
+#### 2.2 SDL3 Backend Infrastructure
+**Agent**: `imgui-frontend-engineer`
+**Status**: ✅ COMPLETE (commit a5dc884612)
+**Files**: `src/app/platform/`, `src/app/emu/audio/`, `src/app/emu/input/`, `src/app/gfx/backend/`
+
+**Tasks**:
+- [x] Create `IWindowBackend` abstraction interface
+- [x] Create `IAudioBackend` abstraction interface
+- [x] Create `IInputBackend` abstraction interface
+- [x] Create `IRenderer` abstraction interface
+- [x] 17 new abstraction files for backend system
+- [ ] Implement SDL3 concrete backend (next phase)
+- [ ] Update ImGui to SDL3 backend
+- [ ] Port window creation and event handling
+
+#### 2.3 SDL3 Audio Backend
+**Agent**: `snes-emulator-expert`
+**Status**: PLANNED (after audio fix)
+**Files**: `src/app/emu/audio/sdl3_audio_backend.h/cc`
+
+**Tasks**:
+- [ ] Implement `IAudioBackend` for SDL3
+- [ ] Migrate audio initialization code
+- [ ] Verify audio quality matches SDL2
+
+#### 2.4 SDL3 Input Backend
+**Agent**: `imgui-frontend-engineer`
+**Status**: PLANNED
+**Files**: `src/app/emu/ui/input_handler.cc`
+
+**Tasks**:
+- [ ] Implement SDL3 input backend
+- [ ] Add gamepad support improvements
+- [ ] Verify continuous key polling works
+
+---
+
+### Milestone 3: Editor Fixes (Weeks 2-4)
+
+#### 3.1 Tile16 Palette System Fix
+**Agent**: `zelda3-hacking-expert`
+**Status**: PLANNED
+**Files**: `src/app/editor/graphics/tile16_editor.cc`
+
+**Tasks**:
+- [ ] Fix Tile8 source canvas palette application
+- [ ] Fix palette button 0-7 switching logic
+- [ ] Ensure color alignment across canvases
+- [ ] Add unit tests for palette operations
+
+**Success Criteria**: Tile editing workflow fully functional
+
+#### 3.2 Overworld Sprite Movement
+**Agent**: `zelda3-hacking-expert`
+**Status**: PLANNED
+**Files**: `src/app/editor/overworld/overworld_editor.cc`
+
+**Tasks**:
+- [ ] Debug canvas interaction system
+- [ ] Fix drag operation handling for sprites
+- [ ] Test sprite placement workflow
+
+**Success Criteria**: Sprites respond to drag operations
+
+#### 3.3 Dungeon Sprite Save Integration
+**Agent**: `zelda3-hacking-expert`
+**Status**: IN_PROGRESS (uncommitted)
+**Files**: `src/zelda3/dungeon/room.cc/h`
+
+**Tasks**:
+- [x] Implement `EncodeSprites()` method
+- [x] Implement `SaveSprites()` method
+- [ ] Integrate with dungeon editor UI
+- [ ] Add unit tests
+- [ ] Commit and verify CI
+
+---
+
+## Agent Assignments
+
+| Agent | Primary Responsibilities | Workstream |
+|-------|-------------------------|------------|
+| `snes-emulator-expert` | PPU catch-up, audio fix, state injection, SDL3 audio | Stream 1 |
+| `imgui-frontend-engineer` | SDL3 core, SDL3 input, UI updates | Stream 2 |
+| `zelda3-hacking-expert` | Tile16 fix, sprite movement, dungeon save | Stream 3 |
+| `ai-infra-architect` | Semantic API, multimodal context | Stream 4 |
+| `backend-infra-engineer` | Directory restructure, CI updates | Stream 2 |
+| `test-infrastructure-expert` | Test suite for new features | Support |
+| `docs-janitor` | Documentation updates | Support |
+
+---
+
+## Parallel Workstreams
+
+```
+Week 1-2:
+├── Stream 1: snes-emulator-expert → Complete PPU catch-up
+├── Stream 3: zelda3-hacking-expert → Tile16 palette fix
+└── Stream 4: ai-infra-architect → Semantic API design
+
+Week 3-4:
+├── Stream 1: snes-emulator-expert → Audio system fix
+├── Stream 2: backend-infra-engineer → Directory restructure
+├── Stream 3: zelda3-hacking-expert → Sprite movement fix
+└── Stream 4: ai-infra-architect → Semantic API implementation
+
+Week 5-6:
+├── Stream 1: snes-emulator-expert → State injection API
+├── Stream 2: imgui-frontend-engineer → SDL3 core integration
+└── Stream 3: zelda3-hacking-expert → Dungeon sprite integration
+
+Week 7-8:
+├── Stream 1: snes-emulator-expert → SDL3 audio backend
+├── Stream 2: imgui-frontend-engineer → SDL3 input backend
+└── All: Integration testing and stabilization
+```
+
+---
+
+## Success Criteria
+
+### v0.4.0 Release Readiness
+- [ ] PPU catch-up renders raster effects correctly
+- [ ] Semantic API provides structured game state (Phase 1 ✅, Phase 2 pending)
+- [ ] State injection enables "test sprite" workflow
+- [ ] Audio system functional
+- [ ] SDL3 builds pass on Windows, macOS, Linux
+- [ ] No performance regression vs v0.3.x
+- [ ] Critical editor bugs resolved (dungeon rendering, ZSOW v3 palettes)
+- [ ] WASM release build stabilized
+- [x] Documentation updated for v0.3.9 features (web app, format specs)
+
+---
+
+## Risk Mitigation
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| SDL3 breaking changes | Medium | High | Maintain SDL2 fallback branch |
+| Audio system complexity | High | Medium | Prioritize diagnosis before migration |
+| Cross-platform issues | Medium | Medium | CI validation on all platforms |
+| Agent coordination conflicts | Low | Medium | Strict coordination board protocol |
+
+---
+
+## Communication
+
+- **Daily**: Coordination board updates
+- **Weekly**: Progress sync via initiative status
+- **Blockers**: Post `BLOCKER` tag on coordination board immediately
+- **Handoffs**: Use `REQUEST →` format for task transitions
+
+---
+
+## References
+
+- [Emulator Accuracy Report](emulator_accuracy_report.md)
+- [Roadmap](../roadmaps/roadmap.md)
+- [Feature Parity Analysis](../roadmaps/feature-parity-analysis.md)
+- [Code Review Next Steps](../roadmaps/code-review-critical-next-steps.md)
+- [Coordination Board](coordination-board.md)