Skip to content

Commit ccb5a73

Browse files
author
DavidQ
committed
docs(debug): define overlay data provider contract and next-step execution path
1 parent cee20b3 commit ccb5a73

9 files changed

Lines changed: 299 additions & 56 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,20 @@
11
MODEL: GPT-5.4-codex
22
REASONING: high
33

4-
COMMAND:
5-
Follow PLAN_PR -> BUILD_PR -> APPLY_PR.
4+
Create BUILD_PR_OVERLAY_DATA_PROVIDERS
65

7-
Create OVERLAY_PANEL_REGISTRY_delta focused on a clean contract for overlay panels.
6+
Follow PLAN_PR -> BUILD_PR -> APPLY_PR
87

98
Requirements:
10-
- Docs-first planning/bundle structure unless explicitly executing BUILD/APPLY implementation
11-
- One PR per purpose
9+
- Docs-first unless APPLY explicitly needs code guidance notes
1210
- No engine core changes
11+
- One PR per purpose
1312
- Keep integration sample-level
14-
- Preserve Dev Console vs Debug Overlay boundary
1513
- Use MultiSystemDemoScene.js as the integration reference
16-
- Define and/or implement an OverlayPanelRegistry with deterministic ordering
17-
- Define panel descriptor validation and approved panel context boundaries
18-
- Allow only approved console interactions through public registry calls
19-
- Reject direct panel-to-console coupling and overlay host special cases
20-
- Write PR docs to docs/pr/
21-
- Write commit comment and next command under docs/dev/
22-
- Write reports under docs/dev/reports/
23-
- Package as <project folder>/tmp/OVERLAY_PANEL_REGISTRY_delta.zip
14+
- Define a clean read-only provider layer for Debug Overlay panels
15+
- Preserve the Dev Console = command/control boundary
16+
- Preserve the Debug Overlay = telemetry/visual boundary
17+
- Panels must consume provider snapshots instead of direct runtime reads
18+
- Include recommended provider IDs, descriptor shape, guardrails, validation, accomplishments summary, and next-step recommendations
19+
- Write outputs under docs/pr and docs/dev/reports
20+
- Package to <project folder>/tmp/BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Define clean overlay panel registry contract with deterministic registration, approved panel context, and sample-level integration boundaries.
1+
docs(debug): define overlay data provider contract and next-step execution path

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Create BUILD_PR_OVERLAY_PANEL_PRESETS_AND_TOGGLES as a docs-first follow-up that defines curated panel sets, visibility presets, and command-safe toggles on top of the registry contract without widening overlay/console coupling.
1+
Create BUILD_PR_OVERLAY_OPERATOR_COMMANDS as the next docs-first bundle, scoped to public console commands for querying/toggling overlay state through approved overlay contracts only.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
1-
OVERLAY_PANEL_REGISTRY_delta
1+
BUILD_PR_OVERLAY_DATA_PROVIDERS change summary
22

3-
Summary
4-
- Produced docs-first PLAN/BUILD/APPLY bundle for a single PR purpose: clean OverlayPanelRegistry contract.
5-
- Kept integration sample-level using MultiSystemDemoScene.js as the reference touchpoint.
6-
- Preserved Dev Console vs Debug Overlay boundary.
7-
- Defined deterministic panel ordering, descriptor validation, panel context boundaries, and approved console interaction limits.
8-
- Rejected direct panel-to-console coupling and overlay host special-case behavior by contract.
3+
What was updated
4+
- Refreshed PLAN/BUILD/APPLY docs for overlay data providers.
5+
- Kept scope docs-first and sample-level.
6+
- Preserved Dev Console (command/control) vs Debug Overlay (telemetry/visual) boundary.
7+
- Defined read-only provider model where panels consume provider snapshots only.
98

10-
Scope
11-
- docs/pr: PLAN, BUILD, APPLY for overlay panel registry only.
12-
- docs/dev: codex command, commit comment, next command.
13-
- docs/dev/reports: change summary, validation checklist, file tree.
9+
Key contract outcomes
10+
- Recommended provider IDs documented.
11+
- Descriptor shape and validation rules documented.
12+
- Guardrails documented to prevent panel-to-console coupling and overlay host special cases.
13+
- Validation goals documented for deterministic snapshot behavior and graceful fallback.
14+
- Accomplishments summary and next-step recommendations included.
1415

15-
Out of Scope
16-
- Engine core changes.
17-
- Runtime implementation changes.
18-
- Overlay preset/persistence expansion.
19-
- Console-overlay merger.
16+
Files included
17+
- docs/pr/PLAN_PR_OVERLAY_DATA_PROVIDERS.md
18+
- docs/pr/BUILD_PR_OVERLAY_DATA_PROVIDERS.md
19+
- docs/pr/APPLY_PR_OVERLAY_DATA_PROVIDERS.md
20+
- docs/dev/reports/change_summary.txt
21+
- docs/dev/reports/validation_checklist.txt
22+
- docs/dev/reports/file_tree.txt

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,13 @@
11
HTML-JavaScript-Gaming/
22
|-- docs/
33
| |-- pr/
4-
| | |-- PLAN_PR_OVERLAY_PANEL_REGISTRY.md
5-
| | |-- BUILD_PR_OVERLAY_PANEL_REGISTRY.md
6-
| | `-- APPLY_PR_OVERLAY_PANEL_REGISTRY.md
4+
| | |-- PLAN_PR_OVERLAY_DATA_PROVIDERS.md
5+
| | |-- BUILD_PR_OVERLAY_DATA_PROVIDERS.md
6+
| | `-- APPLY_PR_OVERLAY_DATA_PROVIDERS.md
77
| `-- dev/
8-
| |-- codex_commands.md
9-
| |-- commit_comment.txt
10-
| |-- next_command.txt
118
| `-- reports/
129
| |-- change_summary.txt
1310
| |-- validation_checklist.txt
1411
| `-- file_tree.txt
1512
`-- tmp/
16-
`-- OVERLAY_PANEL_REGISTRY_delta.zip
13+
`-- BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,31 @@
1-
OVERLAY_PANEL_REGISTRY_delta Validation Checklist
1+
BUILD_PR_OVERLAY_DATA_PROVIDERS validation checklist
22

33
Workflow
44
- [done] PLAN_PR documented
55
- [done] BUILD_PR documented
66
- [done] APPLY_PR documented
77
- [done] One PR purpose only
8-
- [done] Docs-first bundle only
8+
- [done] Docs-first bundle
99

10-
Scope
10+
Scope and Boundaries
1111
- [done] No engine core changes
12-
- [done] Integration remains sample-level
13-
- [done] MultiSystemDemoScene.js referenced
14-
- [done] Dev Console vs Debug Overlay boundary preserved
12+
- [done] Sample-level integration reference documented
13+
- [done] MultiSystemDemoScene.js used as reference
14+
- [done] Dev Console boundary preserved
15+
- [done] Debug Overlay boundary preserved
1516

16-
Contract
17-
- [done] OverlayPanelRegistry deterministic ordering rules documented
18-
- [done] Panel descriptor validation contract documented
19-
- [done] Approved panel context boundary documented
20-
- [done] Approved console interaction via public registry calls documented
21-
- [done] Direct panel-to-console coupling prohibited
22-
- [done] Overlay host special-case behavior prohibited
17+
Provider Contract
18+
- [done] Read-only provider layer defined
19+
- [done] Recommended provider IDs documented
20+
- [done] Provider descriptor shape documented
21+
- [done] Provider guardrails documented
22+
- [done] Panels consume provider snapshots, not direct runtime reads
23+
- [done] Validation rules documented
24+
25+
Build Quality
26+
- [done] Accomplishments summary included
27+
- [done] Next-step recommendations included
2328

2429
Packaging
25-
- [done] PR docs written under docs/pr
26-
- [done] Commit comment and next command written under docs/dev
27-
- [done] Reports written under docs/dev/reports
28-
- [done] Delta zip created at <project folder>/tmp/OVERLAY_PANEL_REGISTRY_delta.zip
30+
- [done] Outputs written under docs/pr and docs/dev/reports
31+
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip

‎docs/pr/APPLY_PR_OVERLAY_DATA_PROVIDERS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
APPLY_PR_OVERLAY_DATA_PROVIDERS.md
5+
6+
# APPLY_PR_OVERLAY_DATA_PROVIDERS
7+
8+
## Objective
9+
Apply the approved overlay data provider contract in a later implementation PR while keeping integration sample-level and boundary-safe.
10+
11+
## Scope
12+
- provider descriptors and snapshot assembly on overlay side
13+
- panel consumption through `ctx.providers`
14+
- sample reference path: `MultiSystemDemoScene.js`
15+
16+
## Guardrails
17+
- no engine core changes
18+
- no direct panel runtime reads
19+
- no provider-to-console coupling
20+
- no overlay host panel special cases
21+
22+
## Apply Checklist
23+
1. Add/read provider descriptors using approved shape.
24+
2. Enforce unique provider IDs.
25+
3. Build snapshot map in overlay update/render flow.
26+
4. Pass providers into panel context.
27+
5. Refactor sample panels to read only from providers.
28+
6. Verify Dev Console stays command/control only.
29+
7. Verify Debug Overlay stays telemetry/visual only.
30+
31+
## Validation Checklist
32+
- provider IDs resolve deterministically
33+
- descriptor validation rejects invalid providers
34+
- snapshot generation handles unavailable providers gracefully
35+
- panels still render with partial provider data
36+
- no direct cross-calls between panel rendering and console internals
37+
- `node --check` passes on touched JS files
38+
39+
## Expected Outcome
40+
Overlay panels consume normalized provider snapshots, runtime read logic is centralized, and console/overlay boundaries remain intact.
41+
42+
## Next Command
43+
`PLAN_PR_OVERLAY_PROVIDER_HEALTH_AND_METRICS`

‎docs/pr/BUILD_PR_OVERLAY_DATA_PROVIDERS.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_OVERLAY_DATA_PROVIDERS.md
5+
6+
# BUILD_PR_OVERLAY_DATA_PROVIDERS
7+
8+
## Objective
9+
Produce a docs-first BUILD bundle for a read-only Overlay Data Provider layer that keeps Dev Console and Debug Overlay responsibilities separated.
10+
11+
## Build Constraints
12+
- one PR purpose only
13+
- no engine core changes
14+
- sample-level integration only
15+
- preserve Dev Console vs Debug Overlay boundary
16+
17+
## Integration Reference
18+
- `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`
19+
20+
## Provider Layer Contract
21+
Provider descriptor:
22+
23+
```js
24+
{
25+
id: "render.layers",
26+
version: "1.0.0",
27+
collect(context) { ... },
28+
isAvailable?(context) { ... }
29+
}
30+
```
31+
32+
Provider snapshot map:
33+
34+
```js
35+
{
36+
"system.frame": {...},
37+
"scene.active": {...},
38+
"scene.entities": {...},
39+
"render.layers": {...},
40+
"debug.status": {...}
41+
}
42+
```
43+
44+
Panel context boundary:
45+
46+
```js
47+
{
48+
providers,
49+
frame,
50+
layout,
51+
flags
52+
}
53+
```
54+
55+
Panels must read from `providers` only.
56+
57+
## Recommended Provider IDs
58+
- `system.frame`: fps, deltaMs, frameIndex
59+
- `scene.active`: sceneId, sceneState
60+
- `scene.entities`: total, activeGroups
61+
- `render.layers`: orderedLayerNames, visibleCount
62+
- `debug.status`: overlayVisible, panelCount, errors
63+
64+
## Approved Console Interactions
65+
Allowed through public registry/provider host calls only:
66+
- list provider IDs
67+
- query provider availability/status
68+
- trigger safe provider snapshot refresh request (no direct panel mutation)
69+
70+
Not allowed:
71+
- console invoking panel render internals
72+
- console mutating provider descriptor shape
73+
- provider calling console actions
74+
75+
## Guardrails
76+
1. Providers are read-only and side-effect free.
77+
2. Overlay host owns provider snapshot collection.
78+
3. Panels do not perform direct runtime reads.
79+
4. Overlay host must not hardcode panel special cases.
80+
5. Any missing provider data must degrade gracefully.
81+
82+
## Validation
83+
- valid descriptor accepted
84+
- invalid descriptor rejected with structured error
85+
- duplicate provider id rejected
86+
- snapshot map deterministic for a given input frame
87+
- panel rendering succeeds with partial provider availability
88+
- boundary checks confirm no panel-to-console coupling
89+
90+
## Accomplishments Summary
91+
- Boundary between Dev Console and Debug Overlay already documented and preserved.
92+
- Overlay panel registry contract already documented for deterministic panel ordering.
93+
- This BUILD adds the missing read-only data seam so panels become purely presentational.
94+
95+
## Next-Step Recommendations
96+
1. `APPLY_PR_OVERLAY_DATA_PROVIDERS`
97+
2. `BUILD_PR_OVERLAY_PROVIDER_HEALTH_PANEL`
98+
3. `BUILD_PR_OVERLAY_PANEL_PRESETS_AND_TOGGLES`
99+
100+
## Deliverables In This Bundle
101+
- `docs/pr/PLAN_PR_OVERLAY_DATA_PROVIDERS.md`
102+
- `docs/pr/BUILD_PR_OVERLAY_DATA_PROVIDERS.md`
103+
- `docs/pr/APPLY_PR_OVERLAY_DATA_PROVIDERS.md`
104+
- `docs/dev/reports/change_summary.txt`
105+
- `docs/dev/reports/validation_checklist.txt`
106+
- `docs/dev/reports/file_tree.txt`

‎docs/pr/PLAN_PR_OVERLAY_DATA_PROVIDERS.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
PLAN_PR_OVERLAY_DATA_PROVIDERS.md
5+
6+
# PLAN_PR_OVERLAY_DATA_PROVIDERS
7+
8+
## Goal
9+
Define a clean, read-only provider layer for Debug Overlay panels so panels consume provider snapshots instead of reading runtime state directly.
10+
11+
## Workflow
12+
PLAN_PR -> BUILD_PR -> APPLY_PR
13+
14+
## Single PR Purpose
15+
Overlay data providers only.
16+
17+
## In Scope
18+
- provider IDs and naming guidance
19+
- provider descriptor contract
20+
- provider snapshot collection model
21+
- panel consumption boundary (`ctx.providers[...]`)
22+
- validation goals and sample-level integration reference
23+
24+
## Out of Scope
25+
- engine core changes
26+
- Dev Console command expansion
27+
- overlay layout redesign
28+
- panel persistence/presets
29+
30+
## Boundary Preservation
31+
- Dev Console = command/control surface
32+
- Debug Overlay = telemetry/visual surface
33+
- Providers = read-only normalization seam for overlay panels
34+
35+
## Integration Reference
36+
- `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`
37+
38+
## Provider Contract Draft
39+
Recommended descriptor shape:
40+
41+
```js
42+
{
43+
id: "system.frame",
44+
version: "1.0.0",
45+
collect(context) { ... },
46+
isAvailable?(context) { ... }
47+
}
48+
```
49+
50+
Rules:
51+
1. `id` must be unique and stable.
52+
2. `collect(context)` is required and read-only.
53+
3. `isAvailable` is optional and side-effect free.
54+
4. Provider output should be plain JSON-safe data.
55+
56+
## Recommended Provider IDs
57+
- `system.frame`
58+
- `scene.active`
59+
- `scene.entities`
60+
- `render.layers`
61+
- `debug.status`
62+
63+
## Panel Consumption Contract
64+
Overlay host builds provider snapshots and passes:
65+
66+
```js
67+
ctx.providers = {
68+
"system.frame": {...},
69+
"render.layers": {...}
70+
};
71+
```
72+
73+
Panels read from `ctx.providers[...]` only.
74+
75+
## Guardrails
76+
- no direct panel runtime reads
77+
- no provider-to-console calls
78+
- no overlay host special-case branches per panel
79+
- no mutations inside provider `collect`
80+
81+
## Validation Goals
82+
- deterministic provider snapshot availability per frame/update pass
83+
- graceful fallback when a provider is unavailable
84+
- panels render from providers without runtime reach-through
85+
- no engine core changes
86+
87+
## BUILD_PR Command
88+
`BUILD_PR_OVERLAY_DATA_PROVIDERS`
89+
90+
## Commit Comment
91+
`docs: define read-only overlay data provider contract for sample-level panel telemetry`
92+
93+
## Next Command
94+
`APPLY_PR_OVERLAY_DATA_PROVIDERS`

0 commit comments

Comments
 (0)