Skip to content

Commit f5c11b3

Browse files
author
DavidQ
committed
docs: plan standard library for promoted debug surfaces
1 parent 66c84d9 commit f5c11b3

9 files changed

Lines changed: 282 additions & 50 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,17 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_DEBUG_SURFACES_PROMOTION
5+
Create PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
66

77
Requirements:
88
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
99
- Docs-first only
1010
- One PR per purpose
11-
- Extraction/relocation only; no feature expansion
12-
- Build authoritative target structure for engine-core vs engine-debug vs project-owned integrations
13-
- Include ownership matrix, ordered migration steps, validation goals, rollback strategy, and rollout notes
14-
- Keep sample-specific panels/providers/commands outside shared layers
15-
- Preserve `MultiSystemDemoScene.js` as the proving integration
11+
- Plan the first reusable standard library for promoted debug surfaces
12+
- Define shared panels, shared providers, shared operator commands, adoption models, naming conventions, and target structure
13+
- Keep the initial library small and opt-in
14+
- Exclude 3D-specific, network-specific, and deep-inspector work from this PR
15+
- Keep project-specific panels/providers/commands outside the shared library
1616
- Write outputs under docs/pr and docs/dev/reports
1717
- Put codex command and commit comment under docs/dev
18-
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
18+
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: build debug surfaces promotion extraction plan with authoritative ownership and migration rules
1+
docs: plan first opt-in debug surfaces standard library with clear shared/local boundaries

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Next:
2-
APPLY_PR_DEBUG_SURFACES_PROMOTION
2+
BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY

‎docs/dev/reports/change_summary.txt‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,32 @@
1-
BUILD_PR_DEBUG_SURFACES_PROMOTION change summary
1+
PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY change summary
22

33
Summary
4-
- Produced a docs-first BUILD bundle for debug surfaces promotion.
5-
- Kept scope to extraction/relocation planning only (no feature expansion).
6-
- Locked authoritative ownership across engine-core, engine-debug, and project/sample/tool layers.
4+
- Refreshed docs-only plan bundle for the first debug surfaces standard library.
5+
- Kept one PR purpose: planning only.
6+
- Kept initial shared library small and opt-in.
77

8-
Included
9-
- authoritative target structure
10-
- ownership matrix
11-
- ordered migration steps
12-
- validation goals
13-
- rollback strategy
14-
- rollout notes
15-
- codex command and commit comment
16-
- report files
8+
Plan coverage
9+
- shared panel set defined
10+
- shared provider set defined
11+
- shared operator command set defined
12+
- adoption models defined (minimal, preset, hybrid)
13+
- naming conventions defined
14+
- target structure defined
15+
- ownership boundaries reinforced
1716

18-
Boundary outcomes
19-
- sample-specific panels/providers/commands remain outside shared layers
20-
- `MultiSystemDemoScene.js` preserved as proving integration
21-
- engine-core remains minimal and contract-only
17+
Constraints preserved
18+
- docs-first only
19+
- no implementation in this PR
20+
- excludes 3D-specific, network-specific, and deep-inspector scope
21+
- keeps project-specific panels/providers/commands outside shared library
2222

2323
Outputs
24-
- docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md
25-
- docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md
26-
- docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md
24+
- docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
2725
- docs/dev/codex_commands.md
2826
- docs/dev/commit_comment.txt
2927
- docs/dev/reports/change_summary.txt
3028
- docs/dev/reports/validation_checklist.txt
3129
- docs/dev/reports/file_tree.txt
30+
31+
Next recommended command
32+
- BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY

‎docs/dev/reports/file_tree.txt‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
HTML-JavaScript-Gaming/
22
|-- docs/
33
| |-- pr/
4-
| | |-- PLAN_PR_DEBUG_SURFACES_PROMOTION.md
5-
| | |-- BUILD_PR_DEBUG_SURFACES_PROMOTION.md
6-
| | `-- APPLY_PR_DEBUG_SURFACES_PROMOTION.md
4+
| | `-- PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
75
| `-- dev/
86
| |-- codex_commands.md
97
| |-- commit_comment.txt
@@ -12,4 +10,4 @@ HTML-JavaScript-Gaming/
1210
| |-- validation_checklist.txt
1311
| `-- file_tree.txt
1412
`-- tmp/
15-
`-- BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
13+
`-- PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,31 @@
1-
BUILD_PR_DEBUG_SURFACES_PROMOTION validation checklist
1+
PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY validation checklist
22

33
Workflow
4-
- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure preserved
4+
- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure referenced
55
- [done] Docs-first only
66
- [done] One PR per purpose
77

8-
Scope
9-
- [done] Extraction/relocation only (no feature expansion)
10-
- [done] Engine-core changes minimized by contract-only ownership model
11-
- [done] Integration proving reference preserved: MultiSystemDemoScene.js
8+
Plan Content
9+
- [done] Shared panels defined
10+
- [done] Shared providers defined
11+
- [done] Shared operator commands defined
12+
- [done] Adoption models defined
13+
- [done] Naming conventions defined
14+
- [done] Target structure defined
15+
- [done] Initial library is small and opt-in
1216

13-
Build Content
14-
- [done] Authoritative target structure documented
15-
- [done] Ownership matrix documented
16-
- [done] Ordered migration steps documented
17-
- [done] Validation goals documented
18-
- [done] Rollback strategy documented
19-
- [done] Rollout notes documented
20-
- [done] Sample-specific panels/providers/commands explicitly kept outside shared layers
17+
Boundaries
18+
- [done] Project-specific panels/providers/commands remain outside shared library
19+
- [done] Dev Console vs Debug Overlay separation preserved
20+
21+
Exclusions
22+
- [done] 3D-specific scope excluded
23+
- [done] network-specific scope excluded
24+
- [done] deep-inspector scope excluded
2125

2226
Outputs
23-
- [done] Docs under docs/pr
24-
- [done] Reports under docs/dev/reports
27+
- [done] Plan doc under docs/pr
2528
- [done] Codex command under docs/dev
2629
- [done] Commit comment under docs/dev
27-
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
30+
- [done] Reports under docs/dev/reports
31+
- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
2+
3+
## Purpose
4+
5+
Apply the approved standard library plan by creating the first reusable set of shared panels, providers, and operator commands in `engine/debug/standard`.
6+
7+
## Apply Scope
8+
9+
### Create Shared Panels
10+
- system fps
11+
- system timing
12+
- scene summary
13+
- scene entities
14+
- render layers
15+
- input summary
16+
- debug status
17+
18+
### Create Shared Providers
19+
- timing
20+
- scene summary
21+
- entity counts
22+
- render layer summary
23+
- input summary
24+
- debug status
25+
26+
### Create Shared Commands
27+
- debug help/status
28+
- overlay status/list/show/hide/toggle/showAll/hideAll
29+
30+
### Keep Local
31+
- game-specific panels
32+
- game-specific providers
33+
- game-specific commands
34+
- scene-specific adapters
35+
36+
## Apply Rules
37+
38+
- keep adoption opt-in
39+
- preserve public API boundaries
40+
- do not pull custom game logic into the shared library
41+
- validate through sample and tool integrations

‎docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
2+
3+
## Purpose
4+
5+
Turn the standard library plan into a docs-only build bundle for Codex.
6+
7+
## Build Scope
8+
9+
Define:
10+
11+
- the first shared library contents
12+
- exact ownership
13+
- target structure
14+
- registration patterns
15+
- adoption presets
16+
- validation rules
17+
18+
## Required Deliverables
19+
20+
- authoritative target tree
21+
- shared component inventory
22+
- adoption models
23+
- validation checklist
24+
- rollback notes
25+
- codex command
26+
- commit comment
27+
- next command
28+
29+
## Build Rules
30+
31+
- one PR purpose only
32+
- docs-first only
33+
- keep the initial shared library small
34+
- no 3D/network-specific features in this PR
35+
- no deep inspectors in this PR
36+
- preserve opt-in adoption

‎docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
2+
3+
## Objective
4+
Plan the first reusable, opt-in standard library for promoted debug surfaces so projects can adopt a consistent baseline without pulling project-specific logic into shared layers.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: define the standard library plan.
11+
12+
## Scope
13+
In scope:
14+
- shared panel candidates
15+
- shared provider candidates
16+
- shared operator command candidates
17+
- adoption models
18+
- naming conventions
19+
- target structure and ownership boundaries
20+
- validation strategy, risk controls, and rollout notes
21+
22+
Out of scope:
23+
- implementation in this PR
24+
- 3D-specific diagnostics
25+
- network-specific diagnostics
26+
- deep-inspector features
27+
- promotion of project-specific debug artifacts into shared library
28+
29+
## Design Constraints
30+
- docs-first only
31+
- keep initial library small
32+
- keep adoption opt-in
33+
- preserve Dev Console (command/control) vs Debug Overlay (telemetry/visual) separation
34+
- keep project-specific panels/providers/commands outside shared library
35+
36+
## Ownership Model
37+
### Engine Core (minimal)
38+
- contracts/hooks only when required
39+
- no shared panel/provider/command implementations
40+
41+
### Engine Debug (shared implementation)
42+
- standard library shared panels/providers/commands
43+
- shared registration helpers and small presets
44+
45+
### Project/Sample/Tool Layers (local)
46+
- project-specific panels/providers/commands
47+
- scene/tool adapters and defaults
48+
- custom local presets
49+
50+
## Initial Standard Library (Small Baseline)
51+
### Shared Panels (initial)
52+
- `system.fps`
53+
- `system.timing`
54+
- `scene.summary`
55+
- `scene.entities`
56+
- `render.layers`
57+
- `input.summary`
58+
- `debug.status`
59+
60+
### Shared Providers (initial)
61+
- `system.timing`
62+
- `scene.summary`
63+
- `scene.entities`
64+
- `render.layers`
65+
- `input.summary`
66+
- `debug.status`
67+
68+
### Shared Operator Commands (initial)
69+
- `debug.help`
70+
- `debug.status`
71+
- `overlay.list`
72+
- `overlay.status`
73+
- `overlay.show <panelId>`
74+
- `overlay.hide <panelId>`
75+
- `overlay.toggle <panelId>`
76+
- `overlay.showAll`
77+
- `overlay.hideAll`
78+
- `overlay.order`
79+
80+
## Naming Conventions
81+
### Panel IDs
82+
- dot notation, stable and human-readable
83+
- examples: `system.fps`, `scene.summary`, `render.layers`
84+
85+
### Provider IDs
86+
- align with panel domain IDs where practical
87+
- examples: `system.timing`, `scene.entities`, `debug.status`
88+
89+
### Command Namespaces
90+
- `debug.*` for console-level status/help
91+
- `overlay.*` for overlay operator controls
92+
93+
## Target Structure
94+
```text
95+
engine/
96+
debug/
97+
standard/
98+
panels/
99+
system/
100+
scene/
101+
render/
102+
input/
103+
debug/
104+
providers/
105+
system/
106+
scene/
107+
render/
108+
input/
109+
debug/
110+
commands/
111+
registerStandardDebugCommands.js
112+
presets/
113+
registerStandardDebugPreset.js
114+
```
115+
116+
Project/sample/tool-owned custom debug artifacts remain outside this shared tree.
117+
118+
## Adoption Models
119+
### Minimal Adoption
120+
- register shared commands
121+
- register 1-3 providers
122+
- register 1-3 panels
123+
124+
### Preset Adoption
125+
- register standard preset bundle
126+
- override with local excludes/includes
127+
128+
### Hybrid Adoption
129+
- use shared commands/providers
130+
- replace or extend panel set locally
131+
132+
## Validation Strategy
133+
- contract validation: shared IDs follow naming conventions and remain stable
134+
- behavior validation: shared commands operate through public APIs only
135+
- integration validation: sample/tool can adopt minimal set without custom refactors
136+
- boundary validation: no project-specific panels/providers/commands promoted into shared library
137+
138+
## Risk Controls
139+
- keep initial baseline small to prevent scope creep
140+
- reject runtime-specific leakage into shared providers/panels
141+
- require opt-in registration (no forced defaults)
142+
- keep advanced inspections deferred to future PRs
143+
144+
## Rollout Notes
145+
1. This PLAN PR is docs-only.
146+
2. BUILD PR defines authoritative inventory and implementation map.
147+
3. APPLY PR implements initial library incrementally with sample-level proving.
148+
4. Expansion (3D, network, deep inspector) requires separate PRs.
149+
150+
## Next Commands
151+
1. `BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY`
152+
2. `APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY`

0 commit comments

Comments
 (0)