Skip to content

Commit 5f44b3a

Browse files
author
DavidQ
committed
docs: build standard library plan for promoted debug surfaces - v2
1 parent 2814537 commit 5f44b3a

7 files changed

+223
-181
lines changed

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: build standard library plan for promoted debug surfaces
1+
docs: build first opt-in debug surfaces standard library bundle with authoritative preset-led registration

‎docs/dev/reports/change_summary.txt‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,29 @@
1-
Created docs-only BUILD PR bundle for the first debug surfaces standard library.
1+
BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY change summary
22

3-
Included:
4-
- authoritative target structure
5-
- initial shared inventory
6-
- registration pattern
7-
- adoption modes
8-
- validation goals
9-
- rollback strategy
10-
- codex command
11-
- commit comment
12-
- next command
13-
- report files
3+
Summary
4+
- Produced docs-only BUILD bundle for the first shared debug surfaces standard library.
5+
- Established authoritative structure, inventory, and preset-led registration model.
6+
- Kept scope small, opt-in, and single-purpose.
147

15-
Primary intent:
16-
- create a small opt-in shared baseline of panels, providers, commands, and a preset
17-
- keep custom project logic local
8+
Included
9+
- authoritative target structure under `engine/debug/standard`
10+
- initial panel/provider/operator-command inventory
11+
- registration pattern centered on `registerStandardDebugPreset()`
12+
- adoption modes (minimal, standard, hybrid)
13+
- validation goals and rollback strategy
14+
15+
Constraints preserved
16+
- docs-first only
17+
- no feature expansion
18+
- excludes 3D-specific, network-specific, deep-inspector, and project-specific logic
19+
- project-specific panels/providers/commands remain outside shared library
20+
21+
Outputs
22+
- docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
23+
- docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
24+
- docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
25+
- docs/dev/codex_commands.md
26+
- docs/dev/commit_comment.txt
27+
- docs/dev/reports/change_summary.txt
28+
- docs/dev/reports/validation_checklist.txt
29+
- docs/dev/reports/file_tree.txt

‎docs/dev/reports/file_tree.txt‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
1-
BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta/
2-
└── docs/
3-
├── dev/
4-
│ ├── codex_commands.md
5-
│ ├── commit_comment.txt
6-
│ ├── next_command.txt
7-
│ └── reports/
8-
│ ├── change_summary.txt
9-
│ ├── file_tree.txt
10-
│ └── validation_checklist.txt
11-
└── pr/
12-
├── APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
13-
├── BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
14-
└── PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
1+
HTML-JavaScript-Gaming/
2+
|-- docs/
3+
| |-- pr/
4+
| | |-- PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
5+
| | |-- BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
6+
| | `-- APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md
7+
| `-- dev/
8+
| |-- codex_commands.md
9+
| |-- commit_comment.txt
10+
| `-- reports/
11+
| |-- change_summary.txt
12+
| |-- validation_checklist.txt
13+
| `-- file_tree.txt
14+
`-- tmp/
15+
`-- BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,29 @@
1-
Validation Checklist
2-
3-
[x] Authoritative target structure is defined
4-
[x] Initial shared inventory is explicit
5-
[x] Registration pattern is defined
6-
[x] Adoption modes are defined
7-
[x] Initial library remains small
8-
[x] Shared logic remains opt-in
9-
[x] Project-specific logic stays outside shared library
10-
[x] Validation goals are documented
11-
[x] Rollback strategy is documented
12-
[x] APPLY_PR follow-up is identified
1+
BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY validation checklist
2+
3+
Workflow
4+
- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure preserved
5+
- [done] Docs-first only
6+
- [done] One PR per purpose
7+
8+
Build Content
9+
- [done] Authoritative target structure documented
10+
- [done] Initial shared inventory documented
11+
- [done] Registration pattern documented
12+
- [done] Main adoption entry point set to `registerStandardDebugPreset()`
13+
- [done] Adoption modes documented
14+
- [done] Validation goals documented
15+
- [done] Rollback strategy documented
16+
17+
Scope Controls
18+
- [done] Initial library remains small and opt-in
19+
- [done] 3D-specific scope excluded
20+
- [done] network-specific scope excluded
21+
- [done] deep-inspector scope excluded
22+
- [done] project-specific logic excluded from shared library
23+
24+
Outputs
25+
- [done] Docs under docs/pr
26+
- [done] Reports under docs/dev/reports
27+
- [done] Codex command under docs/dev
28+
- [done] Commit comment under docs/dev
29+
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md‎

Lines changed: 20 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,26 @@
11
# APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
22

3-
## Purpose
4-
5-
Apply the approved standard library plan by creating the first reusable set of shared panels, providers, commands, and preset registration in `engine/debug/standard`.
3+
## Objective
4+
Apply the approved standard library build as a focused implementation PR with opt-in adoption and no excluded scope expansion.
65

76
## 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 list/status/show/hide/toggle/showAll/hideAll
29-
30-
### Create Shared Preset
31-
- `registerStandardDebugPreset()`
32-
33-
## Keep Local
34-
- game-specific panels
35-
- game-specific providers
36-
- game-specific commands
37-
- tool-specific panels
38-
- tool-specific adapters
39-
- scene-specific wiring
7+
- implement shared panels/providers/operator commands from the approved v1 inventory
8+
- implement `registerStandardDebugPreset()` as the main shared adoption entry point
9+
- keep project-specific panels/providers/commands outside shared library
4010

4111
## Apply Rules
42-
43-
- keep adoption opt-in
44-
- preserve public API boundaries
45-
- do not pull custom project logic into the shared library
46-
- validate through sample and tool integrations
47-
- do not expand beyond the approved initial inventory
12+
- no 3D-specific additions
13+
- no network-specific additions
14+
- no deep-inspector additions
15+
- no project-specific logic in shared library
16+
- use public APIs/contracts only
17+
18+
## Apply Validation
19+
- standard preset registration succeeds
20+
- minimal and standard adoption both function
21+
- commands and panels follow naming conventions
22+
- shared panels consume provider snapshots only
23+
- boundary checks confirm project-specific logic remains local
24+
25+
## Expected Outcome
26+
A small, opt-in, reusable debug standard library baseline under `engine/debug/standard` with clear extension boundaries.

‎docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md‎

Lines changed: 82 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,42 @@
11
# BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
22

3-
## Purpose
3+
## Objective
4+
Create an authoritative docs-only BUILD bundle for the first shared debug surfaces standard library under `engine/debug/standard`.
45

5-
Convert the approved standard library plan into an implementation-ready docs bundle for Codex.
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
68

7-
## Authoritative Target Structure
9+
## Build Constraints
10+
- docs-first only
11+
- one PR purpose only
12+
- keep initial shared library small and opt-in
13+
- extraction/standardization only; no feature expansion
14+
- exclude 3D-specific, network-specific, deep-inspector, and project-specific logic
815

16+
## Authoritative Target Structure
917
```text
10-
src/
11-
engine/
12-
debug/
13-
standard/
14-
panels/
15-
SystemFpsPanel.js
16-
SystemTimingPanel.js
17-
SceneSummaryPanel.js
18-
SceneEntitiesPanel.js
19-
RenderLayersPanel.js
20-
InputSummaryPanel.js
21-
DebugStatusPanel.js
22-
providers/
23-
SystemTimingProvider.js
24-
SceneSummaryProvider.js
25-
EntityCountProvider.js
26-
RenderLayerSummaryProvider.js
27-
InputSummaryProvider.js
28-
DebugStatusProvider.js
29-
commands/
30-
registerStandardDebugCommands.js
31-
presets/
32-
registerStandardDebugPreset.js
18+
engine/
19+
debug/
20+
standard/
21+
panels/
22+
system/
23+
scene/
24+
render/
25+
input/
26+
debug/
27+
providers/
28+
system/
29+
scene/
30+
render/
31+
input/
32+
debug/
33+
commands/
34+
registerStandardDebugCommands.js
35+
presets/
36+
registerStandardDebugPreset.js
3337
```
3438

35-
## Initial Inventory
36-
39+
## Initial Inventory (v1)
3740
### Shared Panels
3841
- `system.fps`
3942
- `system.timing`
@@ -44,14 +47,14 @@ src/
4447
- `debug.status`
4548

4649
### Shared Providers
47-
- `systemTiming`
48-
- `sceneSummary`
49-
- `entityCount`
50-
- `renderLayerSummary`
51-
- `inputSummary`
52-
- `debugStatus`
53-
54-
### Shared Commands
50+
- `system.timing`
51+
- `scene.summary`
52+
- `scene.entities`
53+
- `render.layers`
54+
- `input.summary`
55+
- `debug.status`
56+
57+
### Shared Operator Commands
5558
- `debug.help`
5659
- `debug.status`
5760
- `overlay.list`
@@ -61,64 +64,60 @@ src/
6164
- `overlay.toggle <panelId>`
6265
- `overlay.showAll`
6366
- `overlay.hideAll`
67+
- `overlay.order`
6468

65-
## Registration Pattern
66-
67-
Use one shared registration entry point:
68-
69+
## Registration Pattern (Authoritative)
70+
Main shared adoption entry point:
6971
- `registerStandardDebugPreset()`
7072

71-
This preset should:
72-
1. register shared providers
73-
2. register shared panels
74-
3. register shared commands
73+
Expected registration sequence:
74+
1. register standard providers
75+
2. register standard panels
76+
3. register standard operator commands
77+
4. return a registration summary/report
7578

76-
This keeps adoption simple and consistent.
79+
Rules:
80+
- registration is opt-in
81+
- registration uses public contracts only
82+
- registration is deterministic and idempotent-safe where practical
7783

7884
## Adoption Modes
79-
8085
### Minimal Adoption
81-
Consumer registers:
82-
- 1–2 standard providers
83-
- 1–2 standard panels
84-
- optional shared commands
86+
- register selected providers and 1-3 panels
87+
- optionally register shared commands
8588

8689
### Standard Adoption
87-
Consumer registers:
88-
- full `registerStandardDebugPreset()`
89-
90-
### Custom Adoption
91-
Consumer registers:
92-
- selected shared providers/panels/commands
93-
- local project-specific additions
90+
- call `registerStandardDebugPreset()` to register the full baseline set
9491

95-
## Build Rules
96-
97-
- one PR purpose only
98-
- docs-first only
99-
- keep the initial library small
100-
- no 3D-specific diagnostics
101-
- no network-specific diagnostics
102-
- no deep inspectors
103-
- no game-specific logic in shared panels
104-
- no direct runtime access from shared panels
105-
- shared panels consume shared/public providers only
106-
- shared commands act through public APIs only
92+
### Hybrid Adoption
93+
- call `registerStandardDebugPreset()` then extend/override locally with project-owned panels/providers/commands
10794

10895
## Validation Goals
109-
110-
- shared preset registers end-to-end
111-
- panels render from provider data only
112-
- commands operate through public overlay/debug APIs
113-
- partial adoption works
114-
- full adoption works
115-
- local project extensions remain possible
116-
- no project-specific logic leaks into the shared library
96+
- baseline preset registers successfully end-to-end
97+
- shared panels consume provider data only
98+
- shared commands operate through public overlay/debug APIs only
99+
- partial and full adoption modes both work
100+
- naming remains stable and deterministic
101+
- project-specific logic remains outside shared library
117102

118103
## Rollback Strategy
119-
120-
If the initial library is too broad or unstable:
121-
- keep the directory structure
122-
- reduce the initial inventory
123-
- preserve preset entry point
124-
- revalidate minimal adoption before re-expanding
104+
If v1 library is too broad or unstable:
105+
1. keep target directory structure and preset entry point
106+
2. reduce initial inventory to highest-value subset
107+
3. preserve command/panel/provider naming contracts
108+
4. revalidate minimal adoption before re-expanding
109+
110+
## Rollout Notes
111+
- BUILD bundle is docs-only and implementation-ready
112+
- APPLY should implement inventory incrementally (providers -> panels -> commands -> preset)
113+
- do not widen scope into excluded areas in this track
114+
115+
## Deliverables
116+
- `docs/pr/PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md`
117+
- `docs/pr/BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md`
118+
- `docs/pr/APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY.md`
119+
- `docs/dev/codex_commands.md`
120+
- `docs/dev/commit_comment.txt`
121+
- `docs/dev/reports/change_summary.txt`
122+
- `docs/dev/reports/validation_checklist.txt`
123+
- `docs/dev/reports/file_tree.txt`

0 commit comments

Comments
 (0)