scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

imgui-frontend-engineer: update docs and plans

Browse Source
This commit is contained in:
scawful
2025-12-28 10:51:31 -06:00
parent 403590585d
commit 8d011bf094
9 changed files with 331 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/internal/agents/coordination-board.md
View File

@@ -3,6 +3,30 @@
**STOP:** Before posting, verify your **Agent ID** in [personas.md](personas.md). Use only canonical IDs. **STOP:** Before posting, verify your **Agent ID** in [personas.md](personas.md). Use only canonical IDs.
**Guidelines:** Keep entries concise (<=5 lines). Archive completed work weekly. Target <=40 active entries. **Guidelines:** Keep entries concise (<=5 lines). Archive completed work weekly. Target <=40 active entries.
### 2025-12-26 imgui-frontend-engineer – Mobile layout + nav pass
- TASK: Improve iPad layout (responsive welcome cards + panel width clamps), add mobile nav switcher, tune iOS touch sizing, and track per-edge safe areas.
- SCOPE: src/app/editor/ui/welcome_screen.*, src/app/editor/menu/right_panel_manager.cc, src/app/editor/menu/activity_bar.cc, src/app/editor/layout/layout_coordinator.cc, src/app/editor/ui/ui_coordinator.*, src/app/platform/ios/ios_window_backend.mm, src/app/platform/ios/ios_platform_state.*
- STATUS: COMPLETE
- NOTES: Compact layout uses floating nav button; right/side panels clamp to viewport; safe-area insets stored for per-edge use.
### 2025-12-25 imgui-frontend-engineer – iOS touch + safe area tuning
- TASK: Add touch target padding + safe-area padding for ImGui on iOS.
- SCOPE: src/app/platform/ios/ios_window_backend.mm
- STATUS: COMPLETE
- NOTES: TouchExtraPadding targets 44pt min; DisplaySafeAreaPadding uses max safe-area insets.
### 2025-12-25 imgui-frontend-engineer – Dashboard responsive layout pass
- TASK: Rebuild dashboard/editor selection grid layout for responsive sizing + theme-based colors.
- SCOPE: src/app/editor/ui/dashboard_panel.cc, src/app/editor/ui/editor_selection_dialog.cc
- STATUS: COMPLETE
- NOTES: z3ed CLI not available; tracking sub-steps locally.
### 2025-12-24 imgui-frontend-engineer – Graphics palette tint regression
- TASK: Fix red-tinted palettes across graphics previews (LoadAssets/Tile16).
- SCOPE: src/app/gfx/types/snes_color.cc, src/app/gfx/types/snes_palette.cc, src/app/editor/overworld/tile16_editor.*
- STATUS: COMPLETE
- NOTES: Corrected CGX palette conversion to avoid 0-255 vs 0-1 misuse; removed redundant set_rgb in palette constructors; restored palette-row offset mapping to skip HUD rows. Follow-up: tile16 palette pipeline preserves encoded CGRAM offsets end-to-end (tile8 + tile16 + previews) unless auto-normalize is enabled, and remaps rows using sheet base.
### 2025-12-06 ai-infra-architect – Overworld Editor Refactoring Phase 2 ### 2025-12-06 ai-infra-architect – Overworld Editor Refactoring Phase 2
- TASK: Critical bug fixes and Tile16 Editor polish - TASK: Critical bug fixes and Tile16 Editor polish
- SCOPE: src/app/editor/overworld/, src/app/gfx/render/ - SCOPE: src/app/editor/overworld/, src/app/gfx/render/
@@ -10,6 +34,36 @@
- NOTES: Fixed tile cache (copy vs move), centralized zoom constants, re-enabled live preview, scaled entity hit detection, restored Tile16 Editor window, fixed SNES palette offset (+1), added palette remapping for source canvas viewing, visual sheet/palette indicators, diagnostic function. Simplified scratch space to single slot. Added toolbar panel toggles. - NOTES: Fixed tile cache (copy vs move), centralized zoom constants, re-enabled live preview, scaled entity hit detection, restored Tile16 Editor window, fixed SNES palette offset (+1), added palette remapping for source canvas viewing, visual sheet/palette indicators, diagnostic function. Simplified scratch space to single slot. Added toolbar panel toggles.
- NEXT: Phase 2 Week 2 - Toolset improvements (eyedropper, flood fill, eraser tools) - NEXT: Phase 2 Week 2 - Toolset improvements (eyedropper, flood fill, eraser tools)
### 2025-12-24 snes-emulator-expert – Overworld palette tint regression
- TASK: Investigate red-tinted overworld palette regression after history compaction.
- SCOPE: src/app/overworld/, src/app/gfx/, src/zelda3/overworld/
- STATUS: COMPLETE
- NOTES: Tile16 palette row mapping now uses ROM palette indices directly (no HUD row offset); adjusted remap logging/comments.
### 2025-12-23 imgui-frontend-engineer – Merge blockers + GLFW/iOS plan
- TASK: Patch merge blockers (dungeon map reserved writes, Asar temp cleanup, 2BPP save guard) and draft GLFW+iOS integration plan with lab/orchestration notes.
- SCOPE: src/zelda3/screen/dungeon_map.cc, src/core/asar_wrapper.cc, src/app/editor/graphics/*, docs/internal.
- STATUS: COMPLETE
- INITIATIVE_DOC: docs/internal/agents/initiative-glfw-ios-backend.md
- NOTES: z3ed CLI not available in environment; tracking sub-steps locally.
### 2025-12-24 imgui-frontend-engineer – iOS rebuild phase 0
- TASK: Start iOS-first execution; stabilize native file picker for iOS.
- SCOPE: src/app/platform/file_dialog.mm, src/ios/*, src/app/platform/ios/ios_host.mm, src/app/gfx/backend/metal_renderer.mm
- STATUS: ACTIVE
- NOTES: Added typed file dialog options + iOS picker type support; stubbed ios_host + metal_renderer, wired Metal renderer into factory/CMake, switched iOS main loop to IOSHost, added Xcode project + Info.plist updates (file sharing + sfc/smc UTTypes), added iOS window backend/platform state + Metal ImGui wiring, and fixed iOS framework links (SDKROOT + ModelIO + forced iOS linker flags). Continuing to split atomic commits + review remaining iOS/mobile changes.
### 2025-12-24 backend-infra-engineer – iOS thin app + XcodeGen
- TASK: CMake-built iOS static libs + generated Xcode app shell.
- SCOPE: CMake presets/platform defs, cmake/dependencies, src/ios/project.yml, scripts/ios.
- STATUS: COMPLETE (added iOS presets + bundle target + XcodeGen spec + build-ios.sh; legacy pbxproj still in repo).
### 2025-12-24 backend-infra-engineer – iOS file dialog async + bundle assets
- TASK: Fix iOS file picker re-entrancy and ensure bundled assets are discoverable.
- SCOPE: src/app/platform/file_dialog.*, src/app/editor/editor_manager.cc, src/app/editor/ui/ui_coordinator.cc, src/util/platform_paths.cc, src/ios/project.yml.
- STATUS: COMPLETE
- NOTES: Added async open dialog API; iOS ROM/project flows now async; assets copied into bundle for fonts/themes; iOS config/docs paths use sandbox via YAZE_IOS guard (avoid /.yaze).
### 2025-12-22 zelda3-hacking-expert – Dungeon map save parity + palette wiring ### 2025-12-22 zelda3-hacking-expert – Dungeon map save parity + palette wiring
- TASK: Align dungeon map save flow with ZScream reference and unblock rom-dependent editor tests. - TASK: Align dungeon map save flow with ZScream reference and unblock rom-dependent editor tests.
- SCOPE: src/zelda3/screen/dungeon_map.cc, test/e2e/rom_dependent/screen_editor_save_test.cc, test/integration/zelda3/dungeon_graphics_transparency_test.cc, src/zelda3/game_data.cc, src/app/gfx/util/palette_manager.cc. - SCOPE: src/zelda3/screen/dungeon_map.cc, test/e2e/rom_dependent/screen_editor_save_test.cc, test/integration/zelda3/dungeon_graphics_transparency_test.cc, src/zelda3/game_data.cc, src/app/gfx/util/palette_manager.cc.
@@ -22,6 +76,18 @@
- STATUS: IN_PROGRESS - STATUS: IN_PROGRESS
- NOTES: Replaced vanilla ROM with clean padded copy; fixed test SaveRomToFile to overwrite test copies; aligned expanded tile16 detection. - NOTES: Replaced vanilla ROM with clean padded copy; fixed test SaveRomToFile to overwrite test copies; aligned expanded tile16 detection.
### 2025-12-22 imgui-frontend-engineer – Lab target for layout designer
- TASK: Move layout designer into a standalone lab target and decouple it from the main editor UI.
- SCOPE: src/lab/, src/lab/layout_designer/, editor menu, CMake, docs/internal/architecture.
- STATUS: COMPLETE
- NOTES: Added YAZE_BUILD_LAB option + `lab` executable, moved layout designer into src/lab/, removed main editor menu hook, and updated layout designer docs for lab usage.
### 2025-12-22 backend-infra-engineer – Local nightly install workflow
- TASK: Create isolated nightly build/install flow for yaze + z3ed + yaze-mcp distinct from dev builds.
- SCOPE: scripts/, CMakeUserPresets.json.example, docs/public/build/quick-reference.md, scripts/README.md
- STATUS: COMPLETE
- NOTES: Added scripts/install-nightly.sh with wrapper commands; documented nightly flow + env overrides in quick-reference/install-options.
### 2025-12-21 backend-infra-engineer – Codebase size reduction review ### 2025-12-21 backend-infra-engineer – Codebase size reduction review
- TASK: Audit repo size + build configuration outputs; propose shrink plan (submodules, build dirs, deps cache). - TASK: Audit repo size + build configuration outputs; propose shrink plan (submodules, build dirs, deps cache).
- SCOPE: build*/ , ext/, vcpkg*, assets/, roms/, CMakePresets.json - SCOPE: build*/ , ext/, vcpkg*, assets/, roms/, CMakePresets.json

67
docs/internal/agents/initiative-glfw-ios-backend.md Normal file
View File

@@ -0,0 +1,67 @@
# Initiative: GLFW Backend + iOS Rebuild + Lab Orchestration
Status: DRAFT
Owner: imgui-frontend-engineer
Created: 2025-12-23
Last Reviewed: 2025-12-23
Next Review: 2026-01-06
Validation/Exit Criteria:
- GLFW backend can run the editor shell with ImGui viewports enabled and stable.
- iOS app boots, loads a ROM via native document picker, and renders the editor UI.
- Lab target supports backend selection and layout import/export for rapid UX iteration.
- Editor orchestration is separated from editor implementations and reusable across desktop/iOS/lab.
## Goals
- Add a GLFW + OpenGL backend option to unlock ImGui viewports for experimentation.
- Rebuild the iOS host app with native iOS integrations and the ImGui editor system.
- Use the lab target as the sandbox for layout and orchestration experiments.
- Decouple UX orchestration from editor logic for fine-grained control.
## Scope
- Window backend abstraction updates needed for non-SDL windows.
- OpenGL renderer path that satisfies `IRenderer` requirements (textures + blits).
- iOS host refactor (metal + imgui backend, document picker, app lifecycle hooks).
- Lab target improvements (backend selection, layout import/export, viewport stress tests).
## Non-Goals
- Full emulator input parity on GLFW (defer to follow-up once input backend is defined).
- Complete SDL removal (GLFW remains optional).
- Shipping viewports as the default on desktop.
## Phased Plan
### Phase 1: Backend Abstraction and GLFW Entry Point
- Define a backend-neutral native window handle and remove SDL-only assumptions in the renderer init path.
- Introduce `WindowBackendType::GLFW` and `RendererBackendType::OpenGL`.
- Add `GLFWWindowBackend` using `imgui_impl_glfw` + `imgui_impl_opengl3`.
- Add OpenGL renderer that can handle `CreateTexture`, `UpdateTexture`, and `RenderCopy`.
### Phase 2: Lab Target Expansion
- Add backend selection flags to the lab target for quick viewport testing.
- Add layout import/export round-trip and preset management.
- Add viewport stress scenes (multi-dock + texture-heavy panels).
### Phase 3: iOS App Rebuild
- New iOS host app with Metal-backed ImGui renderer and full app lifecycle support.
- Native integrations: document picker, share sheet, background/foreground safe handling.
- Mobile layout presets and a touch-first panel navigation surface.
### Phase 4: Orchestration Decoupling
- Extract `UIOrchestrator` that owns dockspace/menu/panel visibility.
- Keep editors focused on data/model and panel registration.
- Expose per-panel visibility and orchestration state for fine-grained control.
## Risks / Constraints
- `IRenderer` currently assumes SDL types; refactor must avoid breaking existing SDL2/SDL3 paths.
- OpenGL renderer must handle palette-indexed textures sourced from SDL surfaces.
- iOS input and file access require security-scoped bookmarks and careful threading.
## Dependencies
- GLFW + OpenGL toolchain availability on macOS.
- ImGui OpenGL backend support (no GL loader assumed, use platform headers).
- iOS signing and entitlements for file access.
## Milestones
- M1: GLFW backend runs lab target with viewports enabled.
- M2: OpenGL renderer draws tilemaps and editor textures.
- M3: iOS app boots with ROM load and core UI flow.
- M4: Orchestration decoupling merged and used by lab/iOS.

2
docs/internal/testing/README.md
View File

@@ -8,6 +8,8 @@
This document serves as the central hub for all testing infrastructure in the yaze project. It coordinates testing strategies across local development, CI/CD, and release validation workflows. This document serves as the central hub for all testing infrastructure in the yaze project. It coordinates testing strategies across local development, CI/CD, and release validation workflows.
**ROM policy**: GitHub CI runs without ROMs and skips ROM-dependent suites. Run ROM tests locally with `YAZE_ENABLE_ROM_TESTS=ON` and `YAZE_TEST_ROM_*` paths, or force-skip with `YAZE_SKIP_ROM_TESTS=1`.
## Quick Links ## Quick Links
- **Developer Quick Start**: [Testing Quick Start Guide](../../public/developer/testing-quick-start.md) - **Developer Quick Start**: [Testing Quick Start Guide](../../public/developer/testing-quick-start.md)

43
docs/plans/MCP_UNIFICATION.md Normal file
View File

@@ -0,0 +1,43 @@
# Yaze MCP Unification Plan
**Status:** Draft
**Goal:** Create a high-quality, unified toolset for AI-assisted debugging in Zelda3 ROM hacking.
## 1. Backend Consolidation (C++)
### A. Move `EmulatorServiceImpl` to `yaze_grpc_support`
- Relocate `src/cli/service/agent/emulator_service_impl.{cc,h}` to `src/app/service/`.
- Update `src/app/service/grpc_support.cmake` to include these files.
- This allows the GUI application to link against the emulator control logic.
### B. Update `YazeGRPCServer`
- Modify `YazeGRPCServer::Initialize` to accept a `yaze::emu::Emulator*`.
- In `BuildServer()`, register the `EmulatorServiceImpl`.
- Result: A single gRPC port (default 50052) handles ROM I/O, GUI automation, AND Emulator control.
## 2. MCP Server Enhancements (Python)
### A. Semantic Translation (Knowledge Graph)
- Integrate `hafs` knowledge base.
- Add a lookup layer: if a tool returns an address (e.g., `$028000`), the MCP server should look up the label in `symbols.json` and append it: `$02:8000 [Module07_Underworld]`.
- Allow tools to accept labels directly: `read_memory("Link_X_Coord")` -> `read_memory("$7EF36D")`.
### B. Visualization Support
- Implement `capture_screenshot` using the `CanvasAutomationService`.
- Return high-resolution PNGs to the AI agent for visual debugging of sprite positions and menu states.
### C. Watchpoint History Analysis
- Improve `get_watchpoint_history` to provide a summary of *why* memory changed (e.g., "Address $7EF36D changed from $00 to $01 during `Link_MoveX`").
## 3. Sandboxed Test Suites
### A. Headless Validation
- Use `z3ed` (the CLI) to run the unified gRPC server in a headless mode.
- Create a suite of Python scripts that use the MCP tools to verify common scenarios:
- Can I set a breakpoint and have it hit?
- Can I read Link's health and modify it?
- Can I step through a routine and verify the CPU flags change?
### B. Integration with ALTTP ROMs
- Provide a set of "Golden State" snapshots for vanilla ALTTP.
- Test routines against these snapshots to ensure the MCP tools provide consistent and accurate data across different game regions.

9
docs/public/build/install-options.md
View File

@@ -65,6 +65,15 @@ cd build-wasm && npx http-server .
- When creating packages (Homebrew/Chocolatey/winget), pin the release URL and checksum and align dependencies to the CMake presets (`mac-*/lin-*/win-*`). - When creating packages (Homebrew/Chocolatey/winget), pin the release URL and checksum and align dependencies to the CMake presets (`mac-*/lin-*/win-*`).
- Keep CLI and GUI in the same archive to avoid mismatched versions; CLI entry is `z3ed`, GUI entry is `yaze`. - Keep CLI and GUI in the same archive to avoid mismatched versions; CLI entry is `z3ed`, GUI entry is `yaze`.
## Local Nightly (Self-Build)
For an isolated nightly build separate from your dev tree, use:
```bash
scripts/install-nightly.sh
```
This installs into `~/.local/yaze/nightly/current` and exposes wrapper commands
(`yaze-nightly`, `z3ed-nightly`, `yaze-mcp-nightly`).
Re-run the script to update to the latest commit.
## Quick Links ## Quick Links
- Build quick reference: `docs/public/build/quick-reference.md` - Build quick reference: `docs/public/build/quick-reference.md`
- CMake presets: `CMakePresets.json` - CMake presets: `CMakePresets.json`

56
docs/public/build/quick-reference.md
View File

@@ -50,6 +50,7 @@ YAZE uses CMake presets for consistent builds. Configure with `cmake --preset <n
- **macOS**: `mac-dbg`, `mac-dbg-v`, `mac-rel`, `mac-dev`, `mac-ai`, `mac-ai-fast`, `mac-uni`, `mac-sdl3`, `mac-test` - **macOS**: `mac-dbg`, `mac-dbg-v`, `mac-rel`, `mac-dev`, `mac-ai`, `mac-ai-fast`, `mac-uni`, `mac-sdl3`, `mac-test`
- **Windows**: `win-dbg`, `win-dbg-v`, `win-rel`, `win-dev`, `win-ai`, `win-z3ed`, `win-arm`, `win-arm-rel`, `win-vs-dbg`, `win-vs-rel`, `win-vs-ai`, `win-sdl3`, `win-test` - **Windows**: `win-dbg`, `win-dbg-v`, `win-rel`, `win-dev`, `win-ai`, `win-z3ed`, `win-arm`, `win-arm-rel`, `win-vs-dbg`, `win-vs-rel`, `win-vs-ai`, `win-sdl3`, `win-test`
- **Linux**: `lin-dbg`, `lin-dbg-v`, `lin-rel`, `lin-dev`, `lin-ai`, `lin-sdl3`, `lin-test` - **Linux**: `lin-dbg`, `lin-dbg-v`, `lin-rel`, `lin-dev`, `lin-ai`, `lin-sdl3`, `lin-test`
- **iOS**: `ios-debug`, `ios-release` (device builds for the thin Xcode shell)
- **CI**: `ci-linux`, `ci-macos`, `ci-windows`, `ci-windows-ai` - **CI**: `ci-linux`, `ci-macos`, `ci-windows`, `ci-windows-ai`
- **WASM**: `wasm-debug`, `wasm-release`, `wasm-crash-repro`, `wasm-ai` - **WASM**: `wasm-debug`, `wasm-release`, `wasm-crash-repro`, `wasm-ai`
@@ -59,6 +60,21 @@ YAZE uses CMake presets for consistent builds. Configure with `cmake --preset <n
--- ---
### iOS (Device) Build Flow
Use the thin iOS shell backed by CMake-built static libs:
```bash
scripts/build-ios.sh # builds ios-debug + generates Xcode project
scripts/build-ios.sh ios-release
```
This generates `src/ios/yaze_ios.xcodeproj` and a bundled static library at
`build-ios/ios/libyaze_ios_bundle.a`. Open the Xcode project and run on device.
Requires `xcodegen` (`brew install xcodegen`) and the iOS SDK from Xcode.
---
## 3. Build Directory Policy ## 3. Build Directory Policy
| Build Type | Default Directory | | Build Type | Default Directory |
@@ -88,6 +104,46 @@ For AI-enabled builds, use the `*-ai` presets and specify only the targets you n
cmake --build --preset mac-ai --target yaze z3ed cmake --build --preset mac-ai --target yaze z3ed
``` ```
### Local Nightly Install (Isolated)
Use `scripts/install-nightly.sh` to keep a separate clone and install prefix for
nightly builds so your dev `build/` stays untouched.
```bash
scripts/install-nightly.sh
```
Wrappers are created under `~/.local/bin`:
- `yaze-nightly` (GUI)
- `yaze-nightly-grpc` (GUI + gRPC for MCP)
- `z3ed-nightly` (CLI)
- `yaze-mcp-nightly` (MCP server; expects `~/Code/yaze-mcp/venv`)
How it works:
- Clones `origin` into `$YAZE_NIGHTLY_REPO` (default `~/Code/yaze-nightly`) and keeps it clean.
- Builds into `$YAZE_NIGHTLY_BUILD_DIR` (default `~/Code/yaze-nightly/build-nightly`).
- Installs into `$YAZE_NIGHTLY_PREFIX/releases/<timestamp>` and updates `.../current` symlink.
- Writes wrapper scripts to `$YAZE_NIGHTLY_BIN_DIR` (default `~/.local/bin`).
Updating:
```bash
scripts/install-nightly.sh # re-pulls and installs a new release
```
Removing:
```bash
rm -rf ~/.local/yaze/nightly ~/.local/bin/yaze-nightly* ~/.local/bin/z3ed-nightly ~/.local/bin/yaze-mcp-nightly
```
Key overrides:
```bash
export YAZE_NIGHTLY_REPO="$HOME/Code/yaze-nightly"
export YAZE_NIGHTLY_PREFIX="$HOME/.local/yaze/nightly"
export YAZE_NIGHTLY_BUILD_TYPE=RelWithDebInfo
export YAZE_GRPC_PORT=50051
export YAZE_MCP_REPO="$HOME/Code/yaze-mcp"
```
### Shared Dependency Caches (Recommended) ### Shared Dependency Caches (Recommended)
Set shared caches once per machine to avoid re-downloading dependencies after Set shared caches once per machine to avoid re-downloading dependencies after

95
docs/public/developer/architecture.md
View File

@@ -2,20 +2,28 @@
This guide summarizes the architecture and implementation standards used across the editor codebase. This guide summarizes the architecture and implementation standards used across the editor codebase.
## Editor Status (November 2025) ## Editor Status (December 2025)
| Editor | State | Panels | Notes | **Status rubric**:
|-------------------|--------------|--------|-------| - **Stable**: Core workflows function reliably; remaining TODOs are UX polish.
| Overworld | Stable | 8 | Full feature set with tile16 editor, scratch space. | - **Beta**: Core workflows exist, but important features are incomplete or experimental.
| Message | Stable | 4 | Message list, editor, font atlas, dictionary panels. | - **Experimental**: WIP, flagged experimental in UI, or has major TODOs in core paths.
| Emulator | Stable | 10 | CPU, PPU, Memory debuggers; AI agent integration. |
| Palette | Stable | 11 | Source of truth for palette helpers. | | Editor | State | Evidence |
| Assembly | Stable | 2 | File browser and editor panels. | |--------|-------|----------|
| Dungeon | Stable | 8 | Room selector, matrix, graphics, object editor. | | Overworld | Stable | E2E coverage; TODOs for v3 settings UI and entity deletion. |
| Graphics | Stable | 4 | Sheet editor, browser, player animations. | | Dungeon | Stable | E2E coverage; TODOs for usage tracker, selection preview, and rendering TODOs in `src/zelda3/dungeon`. |
| Sprite | Stable | 2 | Vanilla and custom sprite panels. | | Message | Stable | TODO: replace workflow in message editor. |
| Screen | Stable | 5 | Dungeon maps, inventory, title screen, etc. | | Palette | Stable | TODO: JSON export/import and notifications. |
| Music | Experimental | 3 | Tracker, instrument editor, assembly view. | | Graphics | Beta | Explicit experimental section; screen editor marked WIP. |
| Sprite | Stable | Core sprite panels present; no WIP markers in editor code. |
| Screen | Experimental | `screen_editor.h` labeled WIP; title/inventory TODOs. |
| Emulator | Beta | Debug UI + PPU TODOs; save-state UI not fully wired. |
| Assembly | Beta | TODOs in assembly editor and project file editor. |
| Hex | Beta | Memory editor lacks search and richer UX; see `src/app/editor/code`. |
| Agent | Experimental | Chain mode labeled experimental; collaboration TODOs. |
| Music | Experimental | Sample import/export and BRR tooling TODOs; serialization incomplete. |
| Settings | Beta | Settings/project manager and layout serialization TODOs. |
### Recent Improvements (v0.3.9) ### Recent Improvements (v0.3.9)
@@ -30,6 +38,67 @@ This guide summarizes the architecture and implementation standards used across
- **Dungeon object rendering**: Regression with object visibility - **Dungeon object rendering**: Regression with object visibility
- **ZSOW v3 palettes**: Large-area palette issues being investigated - **ZSOW v3 palettes**: Large-area palette issues being investigated
## Codebase Map
```text
yaze/
├── src/
│ ├── app/ # Desktop app (editors, gfx, emu, UI)
│ ├── zelda3/ # Domain data + ROM parsing (overworld, dungeon, music)
│ ├── rom/ # Core ROM container, transactions, diagnostics
│ ├── cli/ # z3ed CLI + agent tooling
│ ├── lab/ # Sandbox targets (layout designer, UI experiments)
│ ├── web/ # WASM UI + browser integration
│ ├── core/ # Shared core utilities/patch logic
│ └── util/ # Logging, file IO, helpers
├── incl/ # Public C API headers
├── test/ # Unit/integration/e2e/benchmarks
├── tools/ # Dev tools and build helpers
├── assets/ # Built-in assets (no ROMs)
├── cmake/ # Build system and dependency wiring
├── scripts/ # Automation helpers
└── docs/ # Documentation (public/internal)
```
```mermaid
flowchart TD
app[src/app] --> zelda3[src/zelda3]
zelda3 --> rom[src/rom]
app --> gfx[src/app/gfx]
app --> emu[src/app/emu]
cli[src/cli] --> rom
cli --> zelda3
web[src/web] --> app
tools[src/tools] --> rom
```
## ROM Operations and Data Flow
- **Load**: `RomFileManager`/`SessionCoordinator` load ROMs into `Rom` and hydrate `zelda3::GameData`.
- **Read/Write**: `Rom` provides byte/word/long access; `Transaction` batches edits safely.
- **Domain parse**: `zelda3::*` modules interpret ROM data (overworld, dungeon rooms, sprites, music).
- **Edit**: Editors mutate domain models, then persist via save helpers (overworld, dungeon maps, palettes).
- **Patch/compare**: Asar wrapper, ROM diff tools, and doctor commands validate or patch data.
- **Test**: `TestRomManager` resolves ROMs locally; CI runs without ROMs and skips ROM-dependent suites.
## UX/UI Feature Map
- **Card-based layout**: EditorCardRegistry + LayoutManager for dockable panels and presets.
- **Session-aware UI**: Multi-session coordinator, per-editor panel visibility, activity bar.
- **Command tooling**: Command palette, shortcut manager, action registry.
- **Theming**: Shared palette + semantic color tokens via AgentUI theme helpers.
- **Agent UI**: Chat panels, tool execution, and multimodal test harnesses.
- **Layout designer**: WYSIWYG layout tooling for panel arrangements.
## Density Reduction Opportunities
- **Quarantine legacy ROM code**: `src/rom/rom_old.*` can move to a legacy target or be removed if unused.
- **Make WIP editors optional**: Gate agent UI and music editor behind build flags; layout designer now ships via the lab target.
- **Split editor system**: `yaze_editor_system_{panels,session,shortcuts}` targets now isolate editor system components.
- **Isolate experimental UI**: Layout designer now lives under `src/lab/` and builds via `YAZE_BUILD_LAB` (default OFF).
- **De-duplicate editor panels**: Consolidate shared panel patterns across dungeon/overworld/screen.
- **Reduce build surface**: Make emulator and web UI optional in minimal builds.
## 1. Core Architectural Patterns ## 1. Core Architectural Patterns
These patterns, established during the Overworld Editor refactoring, should be applied to all new and existing editor components. These patterns, established during the Overworld Editor refactoring, should be applied to all new and existing editor components.

4
docs/public/developer/testing-guide.md
View File

@@ -41,6 +41,8 @@ test/
| **E2E** | Simulate user workflows | GUI + ROM | Slow | | **E2E** | Simulate user workflows | GUI + ROM | Slow |
| **Benchmarks** | Measure performance | None | Variable | | **Benchmarks** | Measure performance | None | Variable |
**ROM policy**: GitHub CI does not run ROM-dependent tests. Run them locally with `YAZE_ENABLE_ROM_TESTS=ON` and `YAZE_TEST_ROM_*` paths. Use `YAZE_SKIP_ROM_TESTS=1` to force-skip ROM suites.
### Unit Tests ### Unit Tests
Fast, isolated tests with no external dependencies. Run in CI on every commit. Fast, isolated tests with no external dependencies. Run in CI on every commit.
@@ -101,6 +103,8 @@ ctest --preset dev # Stable tests
ctest --preset all # All tests ctest --preset all # All tests
``` ```
ROM-dependent CTest suites are local-only and will be skipped when ROMs are not configured.
--- ---
## Writing Tests ## Writing Tests

2
docs/public/developer/testing-without-roms.md
View File

@@ -12,6 +12,8 @@ The `z3ed` AI agent now supports **mock ROM mode** for testing without requiring
- **Contributors** - Test the agent without needing to provide ROMs - **Contributors** - Test the agent without needing to provide ROMs
- **Automated testing** - Consistent, reproducible test environments - **Automated testing** - Consistent, reproducible test environments
GitHub CI does not run ROM-dependent editor tests; those must be exercised locally with real ROMs.
## How Mock ROM Mode Works ## How Mock ROM Mode Works
Mock ROM mode creates a minimal but valid ROM structure with: Mock ROM mode creates a minimal but valid ROM structure with: