Skip to content

Commit cee20b3

Browse files
author
DavidQ
committed
Define clean overlay panel registry contract with deterministic registration, approved panel context, and sample-level integration boundaries.
1 parent acceb2d commit cee20b3

9 files changed

Lines changed: 534 additions & 58 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

44
COMMAND:
5-
Follow PLAN_PR + BUILD_PR + APPLY_PR.
5+
Follow PLAN_PR -> BUILD_PR -> APPLY_PR.
66

7-
Create OVERLAY_BOUNDARY_delta.
7+
Create OVERLAY_PANEL_REGISTRY_delta focused on a clean contract for overlay panels.
88

99
Requirements:
10-
- Keep docs-first workflow for this bundle
10+
- Docs-first planning/bundle structure unless explicitly executing BUILD/APPLY implementation
11+
- One PR per purpose
1112
- No engine core changes
12-
- One PR purpose only: Dev Console vs Debug Overlay boundary
1313
- Keep integration sample-level
14+
- Preserve Dev Console vs Debug Overlay boundary
1415
- Use MultiSystemDemoScene.js as the integration reference
15-
- Preserve the distinction:
16-
- Dev Console = command/input surface
17-
- Debug Overlay = passive visual telemetry/HUD
18-
- Document allowed interactions, prohibited coupling, public contract candidates, ownership matrix, validation goals, and rollout notes
19-
- Write outputs under docs/pr and docs/dev
20-
- Write reports under docs/dev/reports
21-
- Package to <project folder>/tmp/OVERLAY_BOUNDARY_delta.zip
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

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Docs: define and lock Dev Console vs Debug Overlay boundary as a docs-only sample-level contract bundle.
1+
Define clean overlay panel registry contract with deterministic registration, approved panel context, and sample-level integration boundaries.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
APPLY_PR_OVERLAY_BOUNDARY
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.

‎docs/dev/reports/change_summary.txt‎

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

3-
Created a docs-only PLAN/BUILD/APPLY bundle for a single PR purpose:
4-
Dev Console vs Debug Overlay boundary.
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.
59

6-
Updated files:
7-
- docs/pr/PLAN_PR_OVERLAY_BOUNDARY.md
8-
- docs/pr/BUILD_PR_OVERLAY_BOUNDARY.md
9-
- docs/pr/APPLY_PR_OVERLAY_BOUNDARY.md
10-
- docs/dev/codex_commands.md
11-
- docs/dev/commit_comment.txt
12-
- docs/dev/next_command.txt
13-
- docs/dev/reports/change_summary.txt
14-
- docs/dev/reports/validation_checklist.txt
15-
- docs/dev/reports/file_tree.txt
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.
1614

17-
Boundary outcome:
18-
- Dev Console remains command/input surface.
19-
- Debug Overlay remains passive telemetry/HUD surface.
20-
- Shared interactions are limited to public selectors/events/adapters.
21-
- Integration stays sample-level with MultiSystemDemoScene.js as reference.
22-
- No engine core changes.
15+
Out of Scope
16+
- Engine core changes.
17+
- Runtime implementation changes.
18+
- Overlay preset/persistence expansion.
19+
- Console-overlay merger.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
HTML-JavaScript-Gaming/
22
|-- 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-
| |-- PLAN_PR_OVERLAY_BOUNDARY.md
13-
| |-- BUILD_PR_OVERLAY_BOUNDARY.md
14-
| `-- APPLY_PR_OVERLAY_BOUNDARY.md
3+
| |-- pr/
4+
| | |-- PLAN_PR_OVERLAY_PANEL_REGISTRY.md
5+
| | |-- BUILD_PR_OVERLAY_PANEL_REGISTRY.md
6+
| | `-- APPLY_PR_OVERLAY_PANEL_REGISTRY.md
7+
| `-- dev/
8+
| |-- codex_commands.md
9+
| |-- commit_comment.txt
10+
| |-- next_command.txt
11+
| `-- reports/
12+
| |-- change_summary.txt
13+
| |-- validation_checklist.txt
14+
| `-- file_tree.txt
1515
`-- tmp/
16-
`-- OVERLAY_BOUNDARY_delta.zip
16+
`-- OVERLAY_PANEL_REGISTRY_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,28 @@
1-
VALIDATION CHECKLIST
1+
OVERLAY_PANEL_REGISTRY_delta 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
8+
- [done] Docs-first bundle only
99

1010
Scope
1111
- [done] No engine core changes
12-
- [done] Sample-level integration reference documented
12+
- [done] Integration remains sample-level
1313
- [done] MultiSystemDemoScene.js referenced
14+
- [done] Dev Console vs Debug Overlay boundary preserved
1415

15-
Boundary Content
16-
- [done] Allowed interactions documented
17-
- [done] Prohibited coupling documented
18-
- [done] Public contract candidates documented
19-
- [done] Ownership matrix documented
20-
- [done] Validation goals documented
21-
- [done] Rollout notes documented
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
2223

2324
Packaging
24-
- [done] Outputs under docs/pr and docs/dev
25-
- [done] Reports under docs/dev/reports
26-
- [done] Delta zip generated at <project folder>/tmp/OVERLAY_BOUNDARY_delta.zip
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

‎docs/pr/APPLY_PR_OVERLAY_PANEL_REGISTRY.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
APPLY_PR_OVERLAY_PANEL_REGISTRY.md
5+
6+
# APPLY PR
7+
## Overlay Panel Registry
8+
9+
## Apply Objective
10+
Provide the execution checklist for implementing the overlay panel registry contract in a way that preserves the Dev Console / Debug Overlay boundary and keeps all integration sample-level.
11+
12+
## Apply Checklist
13+
### Pre-Apply
14+
- confirm overlay boundary PR docs are accepted
15+
- confirm registry scope remains limited to overlay panels
16+
- confirm no engine-core API changes are required
17+
- confirm sample integration target remains `MultiSystemDemoScene.js`
18+
19+
### Implementation
20+
- add or formalize overlay panel registry module
21+
- add descriptor validation on registration
22+
- update overlay host to consume registry snapshots only
23+
- introduce narrow panel context adapter
24+
- register initial sample panels through approved bootstrap path
25+
- add optional public console commands only through registry contract if already aligned with existing command system
26+
27+
### Validation
28+
- validate registration success for known-good descriptors
29+
- validate duplicate rejection
30+
- validate deterministic panel ordering
31+
- validate enable/disable behavior
32+
- validate conditional visibility
33+
- validate no direct panel-to-console coupling
34+
- validate no overlay host hardcoded sample branches
35+
- validate `node --check` or equivalent on touched JS files
36+
37+
### Docs / Reporting
38+
- update `docs/dev/reports/change_summary.txt`
39+
- update `docs/dev/reports/validation_checklist.txt`
40+
- update `docs/dev/reports/file_tree.txt`
41+
- keep all BUILD/APPLY notes scoped to this PR purpose only
42+
43+
## Commit Comment Guidance
44+
Use a commit comment centered on:
45+
`Add clean overlay panel registry contract and sample-level panel registration path`
46+
47+
## Expected Outcome
48+
After apply:
49+
- overlay panels are registered through a stable public contract
50+
- panel ordering is deterministic
51+
- console remains an optional caller, not a co-renderer
52+
- sample-level panels can be added or removed without changing overlay host internals
53+
54+
## Exit Criteria
55+
This PR is complete when:
56+
- a minimal panel set renders through the registry
57+
- the overlay host has no panel-specific special cases for those panels
58+
- the contract is documented and validated
59+
- no engine-core breakage is introduced
60+
61+
## Not In This Apply PR
62+
- overlay presets
63+
- layout themes
64+
- graph widgets
65+
- cross-session persistence
66+
- broad debug framework redesign
67+
68+
## Recommended Next Command
69+
Move to:
70+
`BUILD_PR_OVERLAY_PANEL_PRESETS_AND_TOGGLES`
71+
only after registry validation is stable.

‎docs/pr/BUILD_PR_OVERLAY_PANEL_REGISTRY.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_OVERLAY_PANEL_REGISTRY.md
5+
6+
# BUILD PR
7+
## Overlay Panel Registry
8+
9+
## Build Objective
10+
Translate the approved panel registry plan into an execution-ready build package that Codex can implement without widening scope beyond sample-level overlay integration.
11+
12+
## Build Summary
13+
This BUILD_PR defines the implementation path for:
14+
- `OverlayPanelRegistry`
15+
- panel descriptor validation
16+
- overlay host consumption of registry snapshots
17+
- sample-level panel registration in `MultiSystemDemoScene.js`
18+
- optional console-facing visibility commands through approved public calls only
19+
20+
No implementation code is included in this docs bundle.
21+
22+
## Build Constraints
23+
- follow PLAN_PR -> BUILD_PR -> APPLY_PR
24+
- docs-first package only
25+
- no engine-core breakage
26+
- no console/overlay merger
27+
- sample-level integration only
28+
- public contract driven
29+
30+
## Proposed File Touch Targets
31+
Expected implementation touch points should stay as small and surgical as possible. Final file names may vary slightly if Codex finds existing equivalent locations.
32+
33+
Likely targets:
34+
- `engine/debug/` overlay registry module
35+
- `engine/debug/` overlay host / panel consumption module
36+
- `tools/dev/devConsoleIntegration.js` only if public registry commands already belong there and can remain isolated
37+
- `samples/.../MultiSystemDemoScene.js` for sample registration and validation wiring
38+
- docs under `docs/pr/` and `docs/dev/reports/`
39+
40+
## Build Workstreams
41+
### 1. Registry Module
42+
Codex should implement a lightweight registry with:
43+
- register
44+
- unregister if already approved by current debug lifecycle, otherwise defer
45+
- get ordered list
46+
- get by id
47+
- set enabled state
48+
- snapshot export
49+
50+
Acceptance goals:
51+
- stable deterministic ordering
52+
- duplicate rejection
53+
- no overlay host mutation leaks
54+
55+
### 2. Descriptor Validation
56+
Codex should validate required descriptor fields at registration time.
57+
58+
Validation checks:
59+
- `id` exists and is string
60+
- `title` exists and is string
61+
- `order` is finite numeric value
62+
- `readModel` is function
63+
- `render` is function
64+
- optional hooks are type-checked when present
65+
66+
Failure mode:
67+
- reject invalid descriptor
68+
- preserve existing registry state
69+
- emit clear debug error
70+
71+
### 3. Overlay Host Consumption
72+
Codex should update the overlay host so that it:
73+
- requests a registry snapshot each frame or approved update point
74+
- filters visible/enabled panels
75+
- reads model first, then renders
76+
- lays out panels in deterministic order
77+
- does not know about panel-specific runtime internals
78+
79+
### 4. Approved Context Adapter
80+
Codex should introduce or formalize a narrow panel context object.
81+
82+
Suggested contents:
83+
- frame timing snapshot
84+
- scene summary
85+
- approved debug selectors
86+
- draw helpers
87+
- feature flags
88+
- panel bounds/layout helpers
89+
90+
Suggested exclusions:
91+
- unrestricted engine mutation methods
92+
- raw console state/history
93+
- arbitrary scene object mutation handles
94+
95+
### 5. Sample Registration Path
96+
Codex should register a minimal first-pass panel set in `MultiSystemDemoScene.js` or approved sample bootstrap helper.
97+
98+
Suggested initial sample panels:
99+
- FPS/runtime frame panel
100+
- scene identity/status panel
101+
- render layers/status panel
102+
- entity count panel
103+
104+
### 6. Console Surface Integration
105+
Only if already aligned with existing command architecture, Codex may add public command hooks that:
106+
- list panel ids
107+
- toggle a panel by id
108+
- show current enabled state
109+
110+
The console must remain a caller of the registry contract, not a co-owner of panel rendering.
111+
112+
## Build Validation Matrix
113+
### Contract Validation
114+
- valid panel descriptor registers successfully
115+
- invalid descriptor is rejected cleanly
116+
- duplicate id is rejected
117+
118+
### Behavior Validation
119+
- ordered snapshot is stable
120+
- disabled panels do not render
121+
- conditional visibility works independently of enabled state
122+
- render call order matches contract sort rules
123+
124+
### Isolation Validation
125+
- panel renderers do not access console internals
126+
- overlay host does not contain panel-specific logic branches
127+
- sample-specific panel removal does not break host
128+
129+
### Sample Validation
130+
- `MultiSystemDemoScene.js` demonstrates registry-based panel registration
131+
- overlay still draws with no registered sample panel failures
132+
- console autocomplete/interaction remains intact
133+
134+
## Contract Test Suggestions
135+
Codex should include lightweight tests or validations for:
136+
- registration order
137+
- duplicate rejection
138+
- enable/disable state transition
139+
- visibility gate behavior
140+
- snapshot immutability expectations if implemented
141+
142+
## Risks
143+
- leaking runtime internals through panel context
144+
- allowing console-specific logic into panel descriptors
145+
- tying ordering to registration sequence
146+
- over-designing the registry before minimal validation
147+
148+
## Risk Controls
149+
- keep context narrow
150+
- reject descriptors that violate contract shape
151+
- validate through sample integration only first
152+
- favor immutable or read-only snapshots where practical
153+
154+
## Rollback Strategy
155+
If implementation becomes noisy or starts expanding scope:
156+
- keep registry internal behind one public module
157+
- disable console toggle hooks first
158+
- retain sample registration only
159+
- leave presets and persistence for later PRs
160+
161+
## Deliverables
162+
Codex should produce:
163+
- updated docs in `docs/pr/`
164+
- `docs/dev/codex_commands.md`
165+
- `docs/dev/commit_comment.txt`
166+
- `docs/dev/next_command.txt`
167+
- `docs/dev/reports/change_summary.txt`
168+
- `docs/dev/reports/validation_checklist.txt`
169+
- `docs/dev/reports/file_tree.txt`
170+
- implementation changes only if this BUILD_PR is executed outside the docs-only planning workflow

0 commit comments

Comments
 (0)