docs: plan reusable presets for promoted debug surfaces

Author: DavidQ

docs/dev/BIG_PICTURE_ROADMAP.md

@@ -1,264 +1,112 @@
-# Debug Surfaces Big Picture Roadmap (Checklist)
+# 🧭 Debug Platform & Ecosystem Roadmap
 
-## Purpose
-
-Track progress toward a reusable debug surface platform across games, tools, samples, and playable builds.
+## Status Legend
+- [ ] Todo
+- [.] In Progress
+- [x] Complete
 
 ---
 
-# North Star
+# 🧱 TRACK A — DEBUG FOUNDATION (COMPLETE)
 
-- [.] 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
+- [x] Dev Console (input + command execution)
+- [x] Debug Overlay (visual panels)
+- [x] Console ↔ Overlay Boundary
+- [x] Panel Registry
+- [x] Data Providers (read-only model)
+- [x] Operator Commands (control surface)
+- [x] Panel Persistence
 
 ---
 
-# 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
+# 🚀 TRACK B — PROMOTION TO ENGINE LAYER
 
-## Engine Debug (Reusable Platform)
+- [x] PLAN_PR_DEBUG_SURFACES_PROMOTION
+- [x] BUILD_PR_DEBUG_SURFACES_PROMOTION
+- [ ] APPLY_PR_DEBUG_SURFACES_PROMOTION
 
-- [ ] 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)
+# 📦 TRACK C — STANDARD DEBUG LIBRARY
 
-- [ ] Define panel registration pattern
-- [ ] Define provider registration pattern
-- [ ] Define command registration pattern
-- [ ] Define scene integration pattern
-- [ ] Define presets/defaults pattern
+- [x] PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+- [x] BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+- [ ] APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
 
 ---
 
-# 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
-
----
+# 🎛️ TRACK D — DEBUG PRESETS (ACTIVE)
 
-# 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
+- [x] PLAN_PR_DEBUG_SURFACES_PRESETS
+- [ ] BUILD_PR_DEBUG_SURFACES_PRESETS
+- [ ] APPLY_PR_DEBUG_SURFACES_PRESETS
 
 ---
 
-# Consumer Expansion Tracks
-
-## 2D Integration
-- [ ] Harden 2D usage
-- [ ] Validate workflows
+# 🧰 TRACK E — ADVANCED DEBUG UX
 
-## Tools Integration
-- [ ] Tool adoption
-- [ ] Editor workflows
+- [ ] Preset persistence rules
+- [ ] Role-based presets
+- [ ] Panel grouping
+- [ ] Quick-toggle shortcuts
+- [ ] Command macros
 
-## 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
+# 🎮 TRACK F — GAME INTEGRATION
 
-## Network Support
-- [ ] Network providers
-- [ ] Replication panels
-- [ ] Rollback/prediction views
-- [ ] Desync diagnostics
+- [ ] Sample game uses full debug platform
+- [ ] Production-safe debug toggle
+- [ ] Performance-safe overlays
+- [ ] Build-time debug flags
 
 ---
 
-# Platform Expansion
+# 🌐 TRACK G — NETWORK / MULTIPLAYER DEBUG
 
-## 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
+- [ ] Connection status panel
+- [ ] Latency / RTT panel
+- [ ] Replication state viewer
+- [ ] Client/server divergence inspector
+- [ ] Event tracing
 
 ---
 
-# Stabilization
+# 🧊 TRACK H — 3D DEBUG SUPPORT
 
-- [ ] Architecture documentation
-- [ ] Integration documentation
-- [ ] Extension documentation
-- [ ] Ownership model finalized
+- [ ] Transform inspector
+- [ ] Camera debug panel
+- [ ] Render pipeline stages
+- [ ] Collision overlays
+- [ ] Scene graph inspector
 
 ---
 
-# Recommended Planning Order
+# 🔬 TRACK I — INSPECTORS & TOOLING
 
-## 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
+- [ ] Entity inspector
+- [ ] Component inspector
+- [ ] State diff viewer
+- [ ] Timeline debugger
+- [ ] Event stream viewer
 
 ---
 
-# Immediate Next Step
+# 🧠 TRACK J — ENGINE MATURITY
 
-- [ ] PLAN_PR_DEBUG_SURFACES_PROMOTION
+- [ ] Stable debug API
+- [ ] Plugin system
+- [ ] External documentation
+- [ ] Versioned contracts
+- [ ] Performance benchmarks
 
 ---
 
-# Long-Term Outcome
+# 🏁 END STATE
 
-- [ ] Clean engine core
-- [ ] Reusable debug platform
-- [ ] Cross-project adoption
-- [ ] 2D + 3D + network support
-- [ ] Safe final-build debug capability
+A full debug ecosystem:
+- Engine Core → contracts only
+- Engine Debug → platform
+- Standard Library → reusable baseline
+- Presets → usability layer
+- Extensions → 3D, network, inspectors

docs/dev/CODEX_COMMANDS.md

@@ -2,17 +2,17 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+Create PLAN_PR_DEBUG_SURFACES_PRESETS
 
 Requirements:
 - Follow PLAN_PR -> BUILD_PR -> APPLY_PR
 - Docs-first only
 - One PR per purpose
-- Build the first shared standard library under engine/debug/standard
-- Define authoritative target structure, initial inventory, registration pattern, adoption modes, validation goals, and rollback strategy
-- Keep the initial library small and opt-in
-- Exclude 3D-specific, network-specific, deep-inspector, and project-specific logic from this PR
-- Use `registerStandardDebugPreset()` as the main shared adoption entry point
+- Plan a reusable presets system for promoted debug surfaces
+- Define preset registry, preset applier, shared baseline presets, preset commands, precedence with persistence, adoption models, naming conventions, and target structure
+- Keep the first version small and opt-in
+- Focus only on panel visibility and optional ordering
+- Exclude layout editors, docking systems, 3D-specific, network-specific, and project-specific preset implementations from the shared layer
 - Write outputs under docs/pr and docs/dev/reports
 - Put codex command and commit comment under docs/dev
-- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip
+- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PRESETS_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: build first opt-in debug surfaces standard library bundle with authoritative preset-led registration
+docs: plan reusable debug surfaces presets system with registry/applier contracts and persistence precedence

docs/dev/NEXT_COMMAND.txt

@@ -1,2 +1,2 @@
 Next:
-APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+BUILD_PR_DEBUG_SURFACES_PRESETS