yaze/docs/internal/agents/yaze-app-ux-proposals.md

YAZE Desktop App UX Proposals (Panels, Flags, ROM Loading)

Status: IN_PROGRESS
Owner: ai-infra-architect
Created: 2025-12-01
Last Reviewed: 2025-12-01
Next Review: 2025-12-08
Board: docs/internal/agents/coordination-board.md (2025-12-01 ai-infra-architect – z3ed CLI UX/TUI Improvement Proposals)

Summary

• Improve the desktop ImGui/SDL app startup, profiles, ROM onboarding, and layout/panel ergonomics separate from the z3ed CLI/TUI.
• Make service status (agent control, HTTP/collab, AI runtime) visible and scriptable; reduce brittle flag combinations.
• Provide safe ROM handling (recent list, mock fallback, hot-swap guard) and shareable layout presets for overworld/dungeon/graphics/testing workflows.

Observations

• Startup relies on ad-hoc flags; no bundled profiles (dev/AI/ROM/viewer) and no in-app profile selector. Users must memorize combinations to enable agent control, autosave, collaboration, or stay read-only.
• ROM onboarding is brittle: errors surface via stderr; no first-run picker, recent ROM list, autodetect of common paths, or “use mock ROM” fallback; hot-swapping ROMs risks state loss without confirmation.
• Panel/layout presets are implicit—users rebuild layouts each session. No first-class presets for overworld, dungeon, graphics/palette, testing/doctor, or AI console. Export/import of layouts is absent.
• Runtime status is opaque: no unified HUD showing ROM title/version, profile/layout, mock-ROM flag, active services (agent/collab/HTTP), autosave status, or feature flags.
• Configuration surfaces are fragmented; parity between CLI flags and in-app toggles is unclear, making automation brittle.

Improvement Proposals

• Profiles & bundled flags: Add --profile {dev, ai, rom, viewer, wasm} with an in-app profile picker. Each profile sets sane defaults (agent control on/off, autosave cadence, mock-ROM allowed, telemetry, collaboration) and selects a default layout preset. Persist per-user.
• ROM onboarding & recovery: Show a startup ROM picker with recent list and autodetect (./zelda3.sfc, assets/zelda3.sfc, env var). Validate and, on failure, offer retry/browse and “Use mock ROM” instead of exiting. Add --rom-prompt to force picker even when a path is supplied for shared environments.
• Layout presets & persistence: Ship named presets (Overworld Editing, Dungeon Editing, Graphics/Palette, Testing/Doctor, AI Agent Console). Provide --layout <name> and an in-app switcher; persist per profile and allow export/import for handoff.
• Unified status HUD: Add an always-visible status bar/dashboard summarizing ROM info, profile/layout, service state (agent/HTTP/collab), mock-ROM flag, autosave recency, and feature flags. Expose the same state via a lightweight JSON status endpoint/command for automation.
• Safer ROM/context switching: On ROM change, prompt with unsaved-change summary and autosave option; offer “clone to temp” for experiments; support --readonly-rom for analysis sessions.
• Config discoverability: Centralize runtime settings (ROM path, profile, feature toggles, autosave cadence, telemetry) in a single pane that mirrors CLI flags. Add --export-config/--import-config to script setups and share configurations.

Exit Criteria (for this scope)

• Profiles and layout presets are selectable at startup and in-app, with persisted choices.
• ROM onboarding flow handles missing/invalid ROMs gracefully with mock fallback and recent list.
• Status HUD (and JSON endpoint/command) surfaces ROM/profile/service state for humans and automation.
• Layouts are exportable/importable; presets cover main workflows (overworld, dungeon, graphics, testing, AI console).