docs: build standard library plan for promoted debug surfaces

DavidQ · DavidQ · commit 2814537e5085 · 2026-04-05T20:11:48.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,17 +2,17 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+Create BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
 
 Requirements:
 - Follow PLAN_PR -> BUILD_PR -> APPLY_PR
 - Docs-first only
 - One PR per purpose
-- Plan the first reusable standard library for promoted debug surfaces
-- Define shared panels, shared providers, shared operator commands, adoption models, naming conventions, and target structure
+- 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, and deep-inspector work from this PR
-- Keep project-specific panels/providers/commands outside the shared library
+- Exclude 3D-specific, network-specific, deep-inspector, and project-specific logic from this PR
+- Use `registerStandardDebugPreset()` as the main shared adoption entry point
 - Write outputs under docs/pr and docs/dev/reports
 - Put codex command and commit comment under docs/dev
-- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip
+- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-docs: plan first opt-in debug surfaces standard library with clear shared/local boundaries
+docs: build standard library plan for promoted debug surfaces
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1,2 +1,2 @@
 Next:
-BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,32 +1,17 @@
-PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY change summary
+Created docs-only BUILD PR bundle for the first debug surfaces standard library.
 
-Summary
-- Refreshed docs-only plan bundle for the first debug surfaces standard library.
-- Kept one PR purpose: planning only.
-- Kept initial shared library small and opt-in.
+Included:
+- authoritative target structure
+- initial shared inventory
+- registration pattern
+- adoption modes
+- validation goals
+- rollback strategy
+- codex command
+- commit comment
+- next command
+- report files
 
-Plan coverage
-- shared panel set defined
-- shared provider set defined
-- shared operator command set defined
-- adoption models defined (minimal, preset, hybrid)
-- naming conventions defined
-- target structure defined
-- ownership boundaries reinforced
-
-Constraints preserved
-- docs-first only
-- no implementation in this PR
-- excludes 3D-specific, network-specific, and deep-inspector scope
-- keeps project-specific panels/providers/commands outside shared library
-
-Outputs
-- docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree.txt
-
-Next recommended command
-- BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
+Primary intent:
+- create a small opt-in shared baseline of panels, providers, commands, and a preset
+- keep custom project logic local
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,13 +1,14 @@
-HTML-JavaScript-Gaming/
-|-- docs/
-|   |-- pr/
-|   |   `-- PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
-|   `-- dev/
-|       |-- codex_commands.md
-|       |-- commit_comment.txt
-|       `-- reports/
-|           |-- change_summary.txt
-|           |-- validation_checklist.txt
-|           `-- file_tree.txt
-`-- tmp/
-    `-- PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip
+BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta/
+└── docs/
+    ├── dev/
+    │   ├── codex_commands.md
+    │   ├── commit_comment.txt
+    │   ├── next_command.txt
+    │   └── reports/
+    │       ├── change_summary.txt
+    │       ├── file_tree.txt
+    │       └── validation_checklist.txt
+    └── pr/
+        ├── APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
+        ├── BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
+        └── PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,31 +1,12 @@
-PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY validation checklist
-
-Workflow
-- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure referenced
-- [done] Docs-first only
-- [done] One PR per purpose
-
-Plan Content
-- [done] Shared panels defined
-- [done] Shared providers defined
-- [done] Shared operator commands defined
-- [done] Adoption models defined
-- [done] Naming conventions defined
-- [done] Target structure defined
-- [done] Initial library is small and opt-in
-
-Boundaries
-- [done] Project-specific panels/providers/commands remain outside shared library
-- [done] Dev Console vs Debug Overlay separation preserved
-
-Exclusions
-- [done] 3D-specific scope excluded
-- [done] network-specific scope excluded
-- [done] deep-inspector scope excluded
-
-Outputs
-- [done] Plan doc under docs/pr
-- [done] Codex command under docs/dev
-- [done] Commit comment under docs/dev
-- [done] Reports under docs/dev/reports
-- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip
+Validation Checklist
+
+[x] Authoritative target structure is defined
+[x] Initial shared inventory is explicit
+[x] Registration pattern is defined
+[x] Adoption modes are defined
+[x] Initial library remains small
+[x] Shared logic remains opt-in
+[x] Project-specific logic stays outside shared library
+[x] Validation goals are documented
+[x] Rollback strategy is documented
+[x] APPLY_PR follow-up is identified
diff --git a/docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md b/docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Apply the approved standard library plan by creating the first reusable set of shared panels, providers, and operator commands in `engine/debug/standard`.
+Apply the approved standard library plan by creating the first reusable set of shared panels, providers, commands, and preset registration in `engine/debug/standard`.
 
 ## Apply Scope
 
@@ -25,17 +25,23 @@ Apply the approved standard library plan by creating the first reusable set of s
 
 ### Create Shared Commands
 - debug help/status
-- overlay status/list/show/hide/toggle/showAll/hideAll
+- overlay list/status/show/hide/toggle/showAll/hideAll
 
-### Keep Local
+### Create Shared Preset
+- `registerStandardDebugPreset()`
+
+## Keep Local
 - game-specific panels
 - game-specific providers
 - game-specific commands
-- scene-specific adapters
+- tool-specific panels
+- tool-specific adapters
+- scene-specific wiring
 
 ## Apply Rules
 
 - keep adoption opt-in
 - preserve public API boundaries
-- do not pull custom game logic into the shared library
+- do not pull custom project logic into the shared library
 - validate through sample and tool integrations
+- do not expand beyond the approved initial inventory
diff --git a/docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md b/docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
@@ -2,35 +2,123 @@
 
 ## Purpose
 
-Turn the standard library plan into a docs-only build bundle for Codex.
+Convert the approved standard library plan into an implementation-ready docs bundle for Codex.
 
-## Build Scope
+## Authoritative Target Structure
 
-Define:
+```text
+src/
+  engine/
+    debug/
+      standard/
+        panels/
+          SystemFpsPanel.js
+          SystemTimingPanel.js
+          SceneSummaryPanel.js
+          SceneEntitiesPanel.js
+          RenderLayersPanel.js
+          InputSummaryPanel.js
+          DebugStatusPanel.js
+        providers/
+          SystemTimingProvider.js
+          SceneSummaryProvider.js
+          EntityCountProvider.js
+          RenderLayerSummaryProvider.js
+          InputSummaryProvider.js
+          DebugStatusProvider.js
+        commands/
+          registerStandardDebugCommands.js
+        presets/
+          registerStandardDebugPreset.js
+```
 
-- the first shared library contents
-- exact ownership
-- target structure
-- registration patterns
-- adoption presets
-- validation rules
+## Initial Inventory
 
-## Required Deliverables
+### Shared Panels
+- `system.fps`
+- `system.timing`
+- `scene.summary`
+- `scene.entities`
+- `render.layers`
+- `input.summary`
+- `debug.status`
 
-- authoritative target tree
-- shared component inventory
-- adoption models
-- validation checklist
-- rollback notes
-- codex command
-- commit comment
-- next command
+### Shared Providers
+- `systemTiming`
+- `sceneSummary`
+- `entityCount`
+- `renderLayerSummary`
+- `inputSummary`
+- `debugStatus`
+
+### Shared Commands
+- `debug.help`
+- `debug.status`
+- `overlay.list`
+- `overlay.status`
+- `overlay.show <panelId>`
+- `overlay.hide <panelId>`
+- `overlay.toggle <panelId>`
+- `overlay.showAll`
+- `overlay.hideAll`
+
+## Registration Pattern
+
+Use one shared registration entry point:
+
+- `registerStandardDebugPreset()`
+
+This preset should:
+1. register shared providers
+2. register shared panels
+3. register shared commands
+
+This keeps adoption simple and consistent.
+
+## Adoption Modes
+
+### Minimal Adoption
+Consumer registers:
+- 1–2 standard providers
+- 1–2 standard panels
+- optional shared commands
+
+### Standard Adoption
+Consumer registers:
+- full `registerStandardDebugPreset()`
+
+### Custom Adoption
+Consumer registers:
+- selected shared providers/panels/commands
+- local project-specific additions
 
 ## Build Rules
 
 - one PR purpose only
 - docs-first only
-- keep the initial shared library small
-- no 3D/network-specific features in this PR
-- no deep inspectors in this PR
-- preserve opt-in adoption
+- keep the initial library small
+- no 3D-specific diagnostics
+- no network-specific diagnostics
+- no deep inspectors
+- no game-specific logic in shared panels
+- no direct runtime access from shared panels
+- shared panels consume shared/public providers only
+- shared commands act through public APIs only
+
+## Validation Goals
+
+- shared preset registers end-to-end
+- panels render from provider data only
+- commands operate through public overlay/debug APIs
+- partial adoption works
+- full adoption works
+- local project extensions remain possible
+- no project-specific logic leaks into the shared library
+
+## Rollback Strategy
+
+If the initial library is too broad or unstable:
+- keep the directory structure
+- reduce the initial inventory
+- preserve preset entry point
+- revalidate minimal adoption before re-expanding
diff --git a/docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md b/docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-docs: plan first opt-in debug surfaces standard library with clear shared/local boundaries`
	`1`	`+docs: build standard library plan for promoted debug surfaces`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`Next:`
`2`		`-BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY`
	`2`	`+APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY`