# Roadmap

**Last Updated: November 29, 2025**

This roadmap tracks upcoming releases and major ongoing initiatives.

## Current Focus (v0.5.0)

- **SDL3 Migration**: Switch to SDL3 with GPU-based rendering, port editors to new backend
- **Plugin Architecture**: Initial framework for community extensions
- **Editor Polish**: Tile16 palette fixes, overworld sprite workflow, dungeon editor improvements
- **Emulator Input/Render**: PPU catch-up, dungeon preview render service, and input persistence

### WASM Web Port Status

**Status**: Technically complete but **EXPERIMENTAL/PREVIEW**
- ✅ Build system, file loading, basic editors functional; GH Pages deploy path hardened (web-build caching/branch gating, updated `src/web/` structure).
- ✅ New browser UI: command palette, file manager, pixel inspector, panelized shell UI, theme definitions, touch gesture support, and expanded debug hooks.
- ✅ Async queue/serialization guard to avoid Asyncify crashes; browser `yaze_agent` build enabled with web AI providers.
- ⚠️ Editors are incomplete/preview quality - not production-ready; emulator audio/plugins/advanced editing still missing; WASM FS/persistence hardening in progress (another agent).
- **Recommendation**: Desktop build for serious ROM hacking
- **Documentation**: See `docs/public/usage/web-app.md`

## 0.4.0 (Current Release) - Music Editor & UI Polish

**Status:** Released
**Type:** Feature Release
**Released:** November 2025

### Highlights

#### Music Editor (New!)
- ✅ Complete SPC music editing with tracker and piano roll views
- ✅ Authentic N-SPC audio preview with ADSR envelopes
- ✅ Instrument and sample editors with bank management
- ✅ Piano roll with playback cursor, note editing, and velocity control
- ✅ ASM export/import for custom music integration
- ✅ Per-song tracker windows (like dungeon room cards)
- ✅ Layout system integration with staggered default positions

### Completed ✅

#### Music Editor Infrastructure
- ✅ SPC parser and music bank loader
- ✅ N-SPC pitch table for authentic note playback
- ✅ Single call site audio initialization (EnsureAudioReady)
- ✅ DSP interpolation type control (Linear/Hermite/Cosine/Cubic)
- ✅ Playback position tracking with cursor visualization
- ✅ Segment seeking and preview callbacks

#### SDL3 Backend Infrastructure (Groundwork)
- ✅ IWindowBackend/IAudioBackend/IInputBackend/IRenderer interfaces (commit a5dc884612)
- ✅ 17 new abstraction files in `src/app/platform/`

#### WASM Web Port (Experimental)
- ✅ Emscripten build preset (`wasm-release`)
- ✅ Web shell with ROM upload/download
- ✅ IndexedDB file system integration
- ✅ Progressive loading with WasmLoadingManager
- ✅ Real-time collaboration (WebSocket-based multi-user editing)
- ✅ Offline support via service workers
- ✅ WebAudio for SPC700 playback
- ✅ CI workflow for automated builds and GitHub Pages deployment
- ✅ Public documentation (web-app.md) with preview status
- ⚠️ **Note**: Infrastructure complete but editors are preview/incomplete quality

#### EditorManager Refactoring
- ✅ Delegated architecture (8 specialized managers)
- ✅ UICoordinator, MenuOrchestrator, PopupManager, SessionCoordinator
- ✅ EditorCardRegistry, LayoutManager, ShortcutConfigurator
- ✅ 34 editor cards with X-button close
- ✅ 10 editor-specific DockBuilder layouts
- ✅ Multi-session support

#### AI Agent Infrastructure
- ✅ Tools directory integration and discoverability
- ✅ Meta-tools (tools-list/describe/search)
- ✅ ToolSchemas for LLM documentation
- ✅ AgentContext for state management
- ✅ Batch execution support
- ✅ ValidationTool + RomDiffTool
- ✅ Semantic Inspection API Phase 1

#### AI Agent UX & Browser Support
- ✅ Dedicated chat/proposals panels, agent sessions, and configuration UI with session-aware chat history, safer provider handling, and YAML autodetect.
- ✅ `yaze_agent` builds enabled in the browser shell with web AI providers wired through the WASM build.

#### WASM Web UX & Stability
- ✅ Command palette, file manager, pixel inspector, panelized shell UI, theme definitions, touch gestures, and debug overlays added to the web app.
- ✅ Async queue/serialization guard to prevent Asyncify crashes; WASM control API and message queue refactors to harden async flows.
- ✅ Web architecture/card layout documentation added; web-build workflow updated for new `src/web/` structure and GH Pages caching/branch gating.

#### Editor Layout & Menu Refactor
- ✅ Activity bar/right panel rebuild with menu assets moved under the menu namespace; layout presets documented and popup/toast managers reorganized under UI.
- ✅ Project file/editor refactors and card registry cleanup to reduce coupling; JSON abstraction helper added for consistent serialization.

#### Testing
- ✅ New integration/unit coverage for Tile16 editor workflows and music parsing/playback (SPC parser, music bank, editor integration).

### In Progress 🟡

#### Emulator & SDL3 Readiness
- 🟡 PPU JIT catch-up integration
- 🟡 Shared render service for dungeon object preview
- 🟡 Input persistence (keyboard config, ImGui capture flag)
- 🟡 Semantic API for AI agents (Phase 2 planned)
- 🟡 State injection improvements
- 🟡 SDL3 readiness report plus entry-point/flag cleanup (owned by another agent)

#### Music Editor Overhaul
- 🟡 Tracker + piano roll + instrument/sample editors are in-flight; stabilize playback/export paths and polish UI/shortcuts.

#### Tile16 Editor & Project Persistence
- 🟡 Finalize pending-change workflow UX, palette handling, and overworld context menus; align project metadata/JSON refactor with WASM FS persistence work (ai-infra-architect).

#### Editor Fixes
- 🟡 Dungeon object rendering regression (under investigation)

### Remaining Work (Deferred to 0.5.0)

#### Editor Polish
- Resolve remaining Tile16 palette inconsistencies
- Complete overworld sprite workflow
- Improve dungeon editor labels and tab management
- Add lazy loading for rooms

### CI/CD & Release Health
- Release workflow repairs (cache key/cleanup, Windows crash handler) merged
- Web-build workflow updated for new `src/web/` layout with caching/branch gating
- CI workflows consolidated with standardized Doxygen 1.10 install

---

## 0.5.0 - SDL3 Migration & Feature Expansion

**Status:** Planning
**Type:** Major Breaking Release

### SDL3 Core Migration (Postponed from 0.4.0)
- Switch to SDL3 with GPU-based rendering
- Port editors to new backend
- Implement SDL3 audio/input backends
- Benchmark and tune performance

### Feature Expansion
- **Plugin Architecture**: Initial framework for community extensions
- **Advanced Graphics Editing**: Edit and re-import full graphics sheets
- **`z3ed` AI Agent Enhancements**:
  - Collaborative sessions with shared AI proposals
  - Multi-modal input with screenshot context for Gemini
  - Visual Analysis Tool (Phase 5 ready for implementation)

### Breaking Changes (Planned)
- SDL2 → SDL3 (requires recompilation)
- API changes in graphics backend (for extensions)

---

## 0.6.X - Content & Integration

- **Advanced Content Editors**:
  - Enhanced Hex Editor with search and data interpretation
  - Advanced message editor with font preview
- **Documentation Overhaul**:
  - Auto-generated C++ API documentation
  - Comprehensive user guide for ROM hackers

---

## Recently Completed

### v0.4.0 (November 2025)
- **Music Editor** - Complete SPC music editing with tracker and piano roll views, authentic N-SPC audio preview, instrument/sample editors
- Piano roll with playback cursor, note editing, velocity/duration control
- Per-song tracker windows with layout system integration
- Single call site audio initialization (EnsureAudioReady)
- DSP interpolation type control for audio quality
- AI agent UX revamp (dedicated chat/proposals, session-aware chat, provider safeguards)
- WASM web app stabilization and hardened web-build workflow
- Tile16 workflow and project persistence upgrades
- Editor menu/layout refactor with ActivityBar + layout presets

### v0.3.9 (November 2025)
- WASM web port with real-time collaboration (experimental/preview)
- SDL3 backend infrastructure
- EditorManager refactoring (90% feature parity)
- AI agent tools Phases 1-4
- CI optimization (PR runs ~5-10 min, was 15-20)
- Test suite gating (optional tests OFF by default)
- Documentation cleanup and public web app guide

### v0.3.3 (October 2025)
- Vim mode for `simple-chat`: modal editing, navigation, history, autocomplete
- Autocomplete engine with fuzzy matching and FTXUI dropdown
- TUI enhancements: integrated autocomplete UI components

### v0.3.2
- Dungeon editor: migrated to `TestRomManager`, resolved crash backlog
- Windows build: fixed stack overflows and file dialog regressions
- `z3ed learn`: persistent storage for AI preferences and ROM metadata
- Gemini integration: native function calling API
- Tile16 editor: refactored layout, dynamic zoom controls