imgui-frontend-engineer: update docs and plans

2025-12-28 10:51:31 -06:00
parent 403590585d
commit 8d011bf094
9 changed files with 331 additions and 13 deletions
--- a/docs/public/build/install-options.md
+++ b/docs/public/build/install-options.md
@@ -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-*`).
 - 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
 - Build quick reference: `docs/public/build/quick-reference.md`
 - CMake presets: `CMakePresets.json`
--- a/docs/public/build/quick-reference.md
+++ b/docs/public/build/quick-reference.md
@@ -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`
 - **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`
+- **iOS**: `ios-debug`, `ios-release` (device builds for the thin Xcode shell)
 - **CI**: `ci-linux`, `ci-macos`, `ci-windows`, `ci-windows-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

 | 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
 ```

+### 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)

 Set shared caches once per machine to avoid re-downloading dependencies after
--- a/docs/public/developer/architecture.md
+++ b/docs/public/developer/architecture.md
@@ -2,20 +2,28 @@

 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 |
-|-------------------|--------------|--------|-------|
-| Overworld         | Stable       | 8      | Full feature set with tile16 editor, scratch space. |
-| Message           | Stable       | 4      | Message list, editor, font atlas, dictionary panels. |
-| Emulator          | Stable       | 10     | CPU, PPU, Memory debuggers; AI agent integration. |
-| Palette           | Stable       | 11     | Source of truth for palette helpers. |
-| Assembly          | Stable       | 2      | File browser and editor panels. |
-| Dungeon           | Stable       | 8      | Room selector, matrix, graphics, object editor. |
-| Graphics          | Stable       | 4      | Sheet editor, browser, player animations. |
-| Sprite            | Stable       | 2      | Vanilla and custom sprite panels. |
-| Screen            | Stable       | 5      | Dungeon maps, inventory, title screen, etc. |
-| Music             | Experimental | 3      | Tracker, instrument editor, assembly view. |
+**Status rubric**:
+- **Stable**: Core workflows function reliably; remaining TODOs are UX polish.
+- **Beta**: Core workflows exist, but important features are incomplete or experimental.
+- **Experimental**: WIP, flagged experimental in UI, or has major TODOs in core paths.
+
+| Editor | State | Evidence |
+|--------|-------|----------|
+| Overworld | Stable | E2E coverage; TODOs for v3 settings UI and entity deletion. |
+| Dungeon | Stable | E2E coverage; TODOs for usage tracker, selection preview, and rendering TODOs in `src/zelda3/dungeon`. |
+| Message | Stable | TODO: replace workflow in message editor. |
+| Palette | Stable | TODO: JSON export/import and notifications. |
+| 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)

@@ -30,6 +38,67 @@ This guide summarizes the architecture and implementation standards used across
 - **Dungeon object rendering**: Regression with object visibility
 - **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

 These patterns, established during the Overworld Editor refactoring, should be applied to all new and existing editor components.
--- a/docs/public/developer/testing-guide.md
+++ b/docs/public/developer/testing-guide.md
@@ -41,6 +41,8 @@ test/
 | **E2E** | Simulate user workflows | GUI + ROM | Slow |
 | **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

 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
 ```

+ROM-dependent CTest suites are local-only and will be skipped when ROMs are not configured.
+
 ---

 ## Writing Tests
--- a/docs/public/developer/testing-without-roms.md
+++ b/docs/public/developer/testing-without-roms.md
@@ -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
 - **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

 Mock ROM mode creates a minimal but valid ROM structure with: