BUILD_PR_OVERLAY_PANEL_PERSISTENCE: define versioned, debug-only persistence contract for overlay panel state; keep registry as runtime source of truth and preserve sample-level integration.

Author: DavidQ

docs/dev/BIG_PICTURE_ROADMAP.md

@@ -0,0 +1,264 @@
+# Debug Surfaces Big Picture Roadmap (Checklist)
+
+## Purpose
+
+Track progress toward a reusable debug surface platform across games, tools, samples, and playable builds.
+
+---
+
+# North Star
+
+- [.] Build a reusable debug surface platform (console + overlay + panels + providers + commands + persistence)
+- [ ] Enable cross-project adoption (games, tools, samples)
+- [ ] Support final playable builds with proper gating
+- [ ] Avoid engine core pollution
+
+---
+
+# Big Picture Architecture
+
+## Engine Core (Minimal)
+
+- [ ] Define debug interfaces
+- [ ] Define registration contracts
+- [ ] Define lifecycle hooks
+- [ ] Define environment/debug gating
+- [ ] Keep UI and debug policy OUT of core
+
+## Engine Debug (Reusable Platform)
+
+- [ ] Extract console host
+- [ ] Extract overlay host
+- [ ] Extract panel registry
+- [ ] Extract provider system
+- [ ] Extract operator command layer
+- [ ] Extract persistence system
+- [ ] Define debug bootstrap/composition
+
+## Project Layer (Games / Tools / Samples)
+
+- [ ] Define panel registration pattern
+- [ ] Define provider registration pattern
+- [ ] Define command registration pattern
+- [ ] Define scene integration pattern
+- [ ] Define presets/defaults pattern
+
+---
+
+# Platform Consumers
+
+## 2D Games
+- [ ] Scene/debug panels
+- [ ] Entity/collision panels
+- [ ] Render layer panels
+- [ ] Camera/debug state panels
+
+## 3D Games
+- [ ] Transform/camera panels
+- [ ] Scene graph inspection
+- [ ] Render pass diagnostics
+- [ ] Material/shader inspection
+- [ ] Lighting/debug panels
+- [ ] Physics/debug volume panels
+
+## Networked / Multiplayer
+- [ ] Connection/session panels
+- [ ] Latency/ping panels
+- [ ] Replication diagnostics
+- [ ] Prediction/rollback visibility
+- [ ] Authority/ownership panels
+- [ ] Desync detection panels
+
+## Tools / Editors
+- [ ] Tool state panels
+- [ ] Selection panels
+- [ ] Asset pipeline diagnostics
+- [ ] Validation panels
+
+## Samples / Learning
+- [ ] Simple integration examples
+- [ ] Example panels/providers/commands
+- [ ] Low-friction setup
+
+## Final Playable Builds
+- [ ] Debug gating
+- [ ] Operator-only access
+- [ ] Safe runtime enablement
+
+---
+
+# Journey Overview
+
+## Phase 0 — Surfaces
+- [x] Dev Console
+- [x] Debug Overlay
+
+## Phase 1 — Boundary
+- [x] Console vs overlay separation
+- [x] Allowed interaction rules
+- [x] Prohibited coupling rules
+
+## Phase 2 — Overlay Structure
+- [x] Panel registry
+- [x] Panel identity
+- [x] Deterministic ordering
+- [ ] Panel lifecycle hooks
+
+## Phase 3 — Data Flow
+- [x] Data providers
+- [x] Read-only snapshots
+- [ ] Snapshot contract formalization
+
+## Phase 4 — Operator Control
+- [x] overlay.* command namespace
+- [x] Public API-only interaction
+- [ ] Output standardization
+
+## Phase 5 — Persistence
+- [x] Panel persistence
+- [ ] Versioned persistence model
+- [ ] Reset/migration handling
+
+## Phase 6 — Promotion Planning
+- [ ] Ownership model (core vs debug vs project)
+- [ ] Migration boundaries
+- [ ] Extraction plan from tools/dev
+
+## Phase 7 — Engine-Debug Extraction
+- [ ] Create engine-debug layer
+- [ ] Move console host
+- [ ] Move overlay host
+- [ ] Move registry/providers/persistence
+- [ ] Define debug bootstrap
+
+## Phase 8 — Core Contracts
+- [ ] Minimal debug interfaces
+- [ ] Registration APIs
+- [ ] Lifecycle hooks
+- [ ] Debug gating hooks
+
+## Phase 9 — Integration Patterns
+- [ ] Game integration pattern
+- [ ] Tool integration pattern
+- [ ] Sample integration pattern
+
+---
+
+# Consumer Expansion Tracks
+
+## 2D Integration
+- [ ] Harden 2D usage
+- [ ] Validate workflows
+
+## Tools Integration
+- [ ] Tool adoption
+- [ ] Editor workflows
+
+## Samples
+- [ ] Learning samples
+- [ ] Reference implementations
+
+## Final Build Support
+- [ ] Debug enablement rules
+- [ ] Feature flags
+- [ ] Safe operator access
+
+## 3D Support
+- [ ] 3D providers
+- [ ] Transform panels
+- [ ] Render diagnostics
+- [ ] Physics visualization
+
+## Network Support
+- [ ] Network providers
+- [ ] Replication panels
+- [ ] Rollback/prediction views
+- [ ] Desync diagnostics
+
+---
+
+# Platform Expansion
+
+## Standard Library
+- [ ] Common panels
+- [ ] Common providers
+- [ ] Common commands
+
+## Presets / Layouts
+- [ ] Gameplay preset
+- [ ] Rendering preset
+- [ ] AI preset
+- [ ] QA preset
+- [ ] Tool preset
+
+## Advanced Inspection
+- [ ] Entity inspector
+- [ ] Scene explorer
+- [ ] Runtime drill-down
+- [ ] Diagnostics summary panels
+
+---
+
+# Stabilization
+
+- [ ] Architecture documentation
+- [ ] Integration documentation
+- [ ] Extension documentation
+- [ ] Ownership model finalized
+
+---
+
+# Recommended Planning Order
+
+## Track A — Foundation
+- [x] Console + Overlay
+- [x] Boundary
+- [x] Panel Registry
+- [x] Data Providers
+- [x] Operator Commands
+- [x] Persistence
+
+## Track B — Promotion Planning
+- [ ] Promotion plan
+- [ ] Ownership mapping
+- [ ] Migration strategy
+
+## Track C — Platform Extraction
+- [ ] Engine-debug layer
+- [ ] Core contracts
+- [ ] Integration patterns
+
+## Track D — Consumer Expansion
+- [ ] 2D stabilization
+- [ ] Tools integration
+- [ ] Sample integration
+- [ ] Final build gating
+- [ ] 3D support
+- [ ] Network support
+
+## Track E — Platform Expansion
+- [ ] Standard panels/providers
+- [ ] Presets/layouts
+- [ ] Advanced inspectors
+- [ ] Cross-project reuse
+
+## Track F — Stabilization
+- [ ] Documentation
+- [ ] Extension model
+- [ ] Maintenance strategy
+
+---
+
+# Immediate Next Step
+
+- [ ] PLAN_PR_DEBUG_SURFACES_PROMOTION
+
+---
+
+# Long-Term Outcome
+
+- [ ] Clean engine core
+- [ ] Reusable debug platform
+- [ ] Cross-project adoption
+- [ ] 2D + 3D + network support
+- [ ] Safe final-build debug capability

docs/dev/CODEX_COMMANDS.md

@@ -2,20 +2,32 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_OVERLAY_OPERATOR_COMMANDS
+Follow PLAN_PR -> BUILD_PR -> APPLY_PR
+
+Create BUILD_PR_OVERLAY_PANEL_PERSISTENCE
 
 Requirements:
-- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
+- Docs-first unless BUILD/APPLY implementation work is explicitly requested
+- No engine core changes in this PR
 - One PR per purpose
-- No engine core changes
 - Keep integration sample-level
-- Use MultiSystemDemoScene.js as the integration target
-- Register overlay.* operator commands through the Dev Console command registry
-- Use only approved public overlay/registry APIs
-- Support: overlay.help, overlay.list, overlay.status, overlay.show <panelId>, overlay.hide <panelId>, overlay.toggle <panelId>, overlay.showAll, overlay.hideAll, overlay.order
-- Provide deterministic operator-readable outputs
-- Fail safely on invalid or missing panel IDs
-- Keep everything debug-only
-- Validate with node --check and sample command execution
-- Write docs under docs/pr and reports under docs/dev/reports
-- Package to <project folder>/tmp/BUILD_PR_OVERLAY_OPERATOR_COMMANDS_delta.zip
+- Use MultiSystemDemoScene.js as the integration reference
+- Add a clean overlay persistence adapter boundary
+- Persist overlay panel enabled/disabled state only
+- Registry remains runtime source of truth
+- Operator commands save through public APIs only
+- Handle invalid/unknown stored panel ids safely
+- Add versioned snapshot shape
+- Write outputs under docs/pr and docs/dev/reports
+- Package to <project folder>/tmp/BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
+
+NEXT RECOMMENDED COMMAND:
+Create PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION
+
+Requirements:
+- Docs-only
+- Evaluate whether dev console and debug overlay should move into engine core
+- Compare promotion options: keep sample-owned, move to engine debug package, or partial core extraction
+- Preserve console vs overlay separation
+- Define promotion criteria, boundaries, risks, and rollout phases
+- Do not implement core migration yet

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD_PR_OVERLAY_OPERATOR_COMMANDS: add debug-only overlay operator command contract and sample-level console integration using public overlay APIs only
+BUILD_PR_OVERLAY_PANEL_PERSISTENCE: define versioned, debug-only persistence contract for overlay panel state; keep registry as runtime source of truth and preserve sample-level integration.

docs/dev/NEXT_COMMAND.txt

@@ -1,11 +1 @@
-Create BUILD_PR_OVERLAY_PANEL_PERSISTENCE
-
-Requirements:
-- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
-- One PR per purpose
-- No engine core changes
-- Keep integration sample-level
-- Persist overlay panel enabled/disabled state through approved debug-only storage
-- Restore state safely on sample boot without coupling console to overlay internals
-- Document validation, failure paths, and fallback defaults
-- Package to <project folder>/tmp/BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
+Create PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION with docs-only evaluation of dev console and debug overlay promotion into engine-level debug surfaces after persistence validation.

docs/dev/reports/change_summary.txt

@@ -1,31 +1,25 @@
-BUILD_PR_OVERLAY_OPERATOR_COMMANDS change summary
+BUILD_PR_OVERLAY_PANEL_PERSISTENCE change summary
 
-Implemented
-- Added a new Dev Console command pack:
-  - `tools/dev/commandPacks/overlayCommandPack.js`
-- Wired overlay command pack into Dev Console integration:
-  - `tools/dev/devConsoleIntegration.js`
+Summary
+- Refreshed PLAN/BUILD/APPLY docs for overlay panel persistence.
+- Kept this bundle docs-first and single-purpose.
+- Preserved debug-only, sample-level scope with MultiSystemDemoScene.js as reference.
 
-Overlay commands registered
-- `overlay.help`
-- `overlay.list`
-- `overlay.status`
-- `overlay.show <panelId>`
-- `overlay.hide <panelId>`
-- `overlay.toggle <panelId>`
-- `overlay.showAll`
-- `overlay.hideAll`
-- `overlay.order`
+Key decisions
+- Added a clean persistence adapter boundary (`load/save/clear`).
+- Persist enabled/disabled panel state only.
+- Registry remains runtime source of truth.
+- Operator commands save state via public APIs only.
+- Unknown/invalid stored panel IDs are ignored safely.
+- Added versioned snapshot contract (`contract`, `version`, `panels`, `savedAt`).
 
-Contract and boundary outcomes
-- Commands use public runtime/registry APIs only.
-- Deterministic operator-readable output is enforced.
-- Invalid/missing panel IDs fail safely with explicit error codes.
-- Debug-only scope maintained.
-- No engine core changes.
-- Sample-level integration target preserved (`MultiSystemDemoScene.js`).
+Files in this bundle
+- docs/pr/PLAN_PR_OVERLAY_PANEL_PERSISTENCE.md
+- docs/pr/BUILD_PR_OVERLAY_PANEL_PERSISTENCE.md
+- docs/pr/APPLY_PR_OVERLAY_PANEL_PERSISTENCE.md
+- docs/dev/reports/change_summary.txt
+- docs/dev/reports/validation_checklist.txt
+- docs/dev/reports/file_tree.txt
 
-Docs updated
-- docs/pr/PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md
-- docs/pr/BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md
-- docs/pr/APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md
+Next recommended command
+- PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION