Skip to content

Commit acceb2d

Browse files
author
DavidQ
committed
Docs: define Dev Console vs Debug Overlay boundary and package OVERLAY_BOUNDARY_delta
1 parent 680ff17 commit acceb2d

10 files changed

Lines changed: 268 additions & 72 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

44
COMMAND:
5-
Add TAB autocomplete to dev console.
5+
Follow PLAN_PR + BUILD_PR + APPLY_PR.
66

7-
Modify:
8-
tools/dev/devConsoleIntegration.js
7+
Create OVERLAY_BOUNDARY_delta.
98

109
Requirements:
11-
- Tab triggers autocomplete
12-
- Autocomplete uses command registry (if available)
13-
- If multiple matches → cycle suggestions
14-
- If one match → complete command
15-
- Do not break existing input/cursor logic
16-
- Prevent default tab behavior
17-
18-
Behavior:
19-
- Partial input "sce" → Tab → "scene."
20-
- "scene.r" → Tab → "scene.reload"
21-
- Multiple matches → cycle each Tab press
22-
23-
Constraints:
10+
- Keep docs-first workflow for this bundle
2411
- No engine core changes
25-
- Keep logic isolated to this file
26-
- Preserve combo keys
27-
28-
Validation:
29-
- Tab completes commands
30-
- No browser focus change
31-
- Cursor remains correct
12+
- One PR purpose only: Dev Console vs Debug Overlay boundary
13+
- Keep integration sample-level
14+
- 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

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1 @@
1-
DEV_CONSOLE_AUTOCOMPLETE_TAB_PATCH
2-
3-
- Added Tab autocomplete
4-
- Supports cycling suggestions
5-
- Integrated with cursor-based input
1+
Docs: define and lock Dev Console vs Debug Overlay boundary as a docs-only sample-level contract bundle.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
NONE
1+
APPLY_PR_OVERLAY_BOUNDARY

‎docs/dev/reports/change_summary.txt‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,22 @@
1-
Toolbox Aid
2-
David Quesenberry
3-
04/05/2026
4-
change_summary.txt
1+
CHANGE SUMMARY
52

6-
Summary
7-
- Added docs-only BUILD PR contract for namespaced dev-console command packs.
8-
- Defined command registry and command-pack schema.
9-
- Defined help behavior for global, pack, and command-level discovery.
10-
- Defined normalized output contract and validation/error conventions.
11-
- Constrained future implementation scope to `tools/dev` and optional `tests/tools` only.
3+
Created a docs-only PLAN/BUILD/APPLY bundle for a single PR purpose:
4+
Dev Console vs Debug Overlay boundary.
5+
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
16+
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.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1-
Toolbox Aid
2-
David Quesenberry
3-
04/05/2026
4-
file_tree.txt
5-
6-
docs/pr/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS.md
7-
docs/dev/codex_commands.md
8-
docs/dev/commit_comment.txt
9-
docs/dev/next_command.txt
10-
docs/dev/reports/change_summary.txt
11-
docs/dev/reports/file_tree.txt
12-
docs/dev/reports/validation_checklist.txt
1+
HTML-JavaScript-Gaming/
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+
| |-- PLAN_PR_OVERLAY_BOUNDARY.md
13+
| |-- BUILD_PR_OVERLAY_BOUNDARY.md
14+
| `-- APPLY_PR_OVERLAY_BOUNDARY.md
15+
`-- tmp/
16+
`-- OVERLAY_BOUNDARY_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 19 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,26 @@
1-
Toolbox Aid
2-
David Quesenberry
3-
04/05/2026
4-
validation_checklist.txt
5-
61
VALIDATION CHECKLIST
72

83
Workflow
9-
- PLAN_PR source exists: `docs/pr/PLAN_PR_DEV_CONSOLE_COMMAND_PACKS.md`
10-
- BUILD_PR created as docs-only delta
11-
- No implementation/runtime code included
4+
- [done] PLAN_PR documented
5+
- [done] BUILD_PR documented
6+
- [done] APPLY_PR documented
7+
- [done] One PR purpose only
8+
- [done] Docs-first bundle
129

13-
Contract Coverage
14-
- Command-pack registry shape defined
15-
- Namespaced command definition shape defined
16-
- Help behavior defined for `help`, `help <pack>`, `help <command>`
17-
- Output contract standardized
18-
- Validation/error conventions and codes defined
10+
Scope
11+
- [done] No engine core changes
12+
- [done] Sample-level integration reference documented
13+
- [done] MultiSystemDemoScene.js referenced
1914

20-
Scope Safety
21-
- Future implementation constrained to `tools/dev` and optional `tests/tools`
22-
- No engine core modifications required by contract
23-
- `docs/dev/commit_comment.txt` remains header-free
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
2422

2523
Packaging
26-
- Delta ZIP output path set to:
27-
`<project folder>/tmp/BUILD_PR_DEV_CONSOLE_COMMAND_PACKS_delta.zip`
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

‎docs/dev/start_of_day/CODEX_SESSION_PROMPT.md‎

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

77
- Docs-first unless BUILD/APPLY
88
- No engine core changes

‎docs/pr/APPLY_PR_OVERLAY_BOUNDARY.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
APPLY_PR_OVERLAY_BOUNDARY.md
5+
6+
# APPLY_PR_OVERLAY_BOUNDARY
7+
8+
## Objective
9+
Apply only the approved boundary contract at sample integration touchpoints while preserving architecture safety.
10+
11+
## Approved Input
12+
- `PLAN_PR_OVERLAY_BOUNDARY`
13+
- `BUILD_PR_OVERLAY_BOUNDARY`
14+
15+
## Apply Scope
16+
- Documentation alignment and sample-level integration guidance only.
17+
- Reference sample: `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`.
18+
19+
## Guardrails
20+
1. No engine core changes.
21+
2. No expansion to unrelated tools/samples.
22+
3. No private cross-calls between console and overlay.
23+
4. Preserve Dev Console as command/input owner.
24+
5. Preserve Debug Overlay as passive telemetry/HUD owner.
25+
26+
## Apply Checklist
27+
1. Confirm all console command/input features stay in console path.
28+
2. Confirm all overlay visual telemetry features stay in overlay path.
29+
3. Confirm shared interactions go through public selectors/events/adapters only.
30+
4. Confirm no docs or guidance introduce prohibited coupling.
31+
32+
## Validation Checklist
33+
- Boundary rules are unchanged and explicit.
34+
- Allowed and prohibited interaction rules are consistent across PLAN/BUILD/APPLY.
35+
- Ownership matrix remains intact.
36+
- Rollout notes remain sample-level.
37+
- No implementation code included in this docs bundle.
38+
39+
## Rollback Guidance
40+
If apply review detects scope drift:
41+
1. Revert non-doc additions.
42+
2. Keep only boundary docs/reports.
43+
3. Re-run checklist before repackaging.
44+
45+
## Expected Outcome
46+
A clean, docs-only APPLY bundle that is ready for a later focused implementation PR without coupling drift.

‎docs/pr/BUILD_PR_OVERLAY_BOUNDARY.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_OVERLAY_BOUNDARY.md
5+
6+
# BUILD_PR_OVERLAY_BOUNDARY
7+
8+
## Objective
9+
Build a docs-only PR bundle that operationalizes the approved Dev Console vs Debug Overlay boundary with explicit rules and acceptance targets.
10+
11+
## Workflow
12+
PLAN_PR -> BUILD_PR -> APPLY_PR
13+
14+
## Deliverables In This Bundle
15+
- `docs/pr/PLAN_PR_OVERLAY_BOUNDARY.md`
16+
- `docs/pr/BUILD_PR_OVERLAY_BOUNDARY.md`
17+
- `docs/pr/APPLY_PR_OVERLAY_BOUNDARY.md`
18+
- `docs/dev/codex_commands.md`
19+
- `docs/dev/commit_comment.txt`
20+
- `docs/dev/next_command.txt`
21+
- `docs/dev/reports/change_summary.txt`
22+
- `docs/dev/reports/validation_checklist.txt`
23+
- `docs/dev/reports/file_tree.txt`
24+
25+
## Integration Boundary (Sample-Level)
26+
Reference sample only:
27+
- `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`
28+
29+
No engine core changes are part of this BUILD bundle.
30+
31+
## Required Boundary Contract
32+
1. Dev Console is the only command/input surface.
33+
2. Debug Overlay is the only passive telemetry/HUD surface.
34+
3. Any shared data must flow through public selectors/events/adapters.
35+
4. Private internal state from either surface is not a contract.
36+
37+
## Allowed Interaction Contract
38+
- Console command execution may update runtime state.
39+
- Overlay telemetry may read runtime/debug snapshots.
40+
- Overlay may show command outcomes only if present in shared public snapshot/state.
41+
42+
## Prohibited Coupling Contract
43+
- Overlay parsing/executing commands.
44+
- Console controlling overlay layout internals.
45+
- Hidden two-way dependency on private implementation details.
46+
- Engine-level coupling added only for console-overlay wiring.
47+
48+
## Ownership Matrix
49+
| Area | Owner | Notes |
50+
|---|---|---|
51+
| Command input, caret, history, autocomplete | Dev Console | Overlay cannot depend on this |
52+
| Command registry execution | Dev Console | Through public command gateway |
53+
| Visual diagnostics panels | Debug Overlay | Console cannot own panel layout |
54+
| HUD drawing and ordering | Debug Overlay | Overlay rendered as passive telemetry |
55+
| Shared snapshot access | Shared public adapter | Read-only, stable contract |
56+
57+
## Validation Goals
58+
- Distinction is explicit in docs and actionable.
59+
- Console-only behavior remains in console path.
60+
- Overlay-only behavior remains in overlay path.
61+
- Sample-level reference is documented and sufficient.
62+
- Bundle contains docs only.
63+
64+
## Acceptance Criteria
65+
- Required sections are present: allowed interactions, prohibited coupling, public contracts, ownership matrix, validation goals, rollout notes.
66+
- Docs define one PR purpose only.
67+
- No implementation files are included.
68+
69+
## Rollout Notes
70+
- This BUILD bundle is docs-first and non-destructive.
71+
- APPLY phase should only enforce boundary usage at sample-level integration points.
72+
- If an engine-level need appears, stop and open a separate PR purpose.

‎docs/pr/PLAN_PR_OVERLAY_BOUNDARY.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
PLAN_PR_OVERLAY_BOUNDARY.md
5+
6+
# PLAN_PR_OVERLAY_BOUNDARY
7+
8+
## Goal
9+
Define one clear architectural boundary between Dev Console and Debug Overlay while keeping integration sample-level and non-destructive.
10+
11+
## Single PR Purpose
12+
Dev Console vs Debug Overlay boundary only.
13+
14+
## In Scope
15+
- Role separation for Dev Console and Debug Overlay
16+
- Allowed interactions and prohibited coupling
17+
- Public contract candidates for shared state access
18+
- Ownership matrix for responsibilities
19+
- Validation goals and rollout notes
20+
- Sample-level reference using `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`
21+
22+
## Out of Scope
23+
- Engine core API changes
24+
- Runtime renderer redesign
25+
- Cross-tool refactors outside the sample-level boundary guidance
26+
- New debug feature implementation code
27+
28+
## Boundary Definition
29+
- Dev Console: command and input surface
30+
- Debug Overlay: passive visual telemetry and HUD surface
31+
32+
## Allowed Interactions
33+
1. Console commands may update runtime/debug state through public command pathways.
34+
2. Overlay may read shared diagnostics state through approved selectors/adapters only.
35+
3. Overlay may reflect command outcomes only from shared/public state, never from console-private internals.
36+
4. Sample integration may wire both surfaces to the same runtime snapshot provider.
37+
38+
## Prohibited Coupling
39+
1. Overlay cannot parse or execute console input.
40+
2. Console cannot directly mutate overlay panel internals.
41+
3. No direct cross-calls into private state, private UI buffers, or private render internals.
42+
4. No engine-core additions that exist only to bridge console and overlay.
43+
44+
## Public Contract Candidates
45+
- `getDebugSnapshot()` selector contract
46+
- `runDebugCommand(commandText, context)` command gateway contract
47+
- `debugSnapshotUpdated` event contract (optional)
48+
- `overlayPanelDescriptor` read contract for panel metadata
49+
- structured execution result contract:
50+
- `status`
51+
- `title`
52+
- `lines`
53+
- `code`
54+
- `details`
55+
56+
## Ownership Matrix
57+
| Concern | Dev Console | Debug Overlay |
58+
|---|---|---|
59+
| Text input | Owns | Prohibited |
60+
| Command parsing | Owns | Prohibited |
61+
| Command history/autocomplete | Owns | Prohibited |
62+
| Runtime telemetry display | Reads only | Owns |
63+
| HUD panel layout | Prohibited | Owns |
64+
| Panel cycling/visual focus | No | Owns |
65+
| Explicit command actions | Owns | No |
66+
| Passive diagnostics view | Optional | Owns |
67+
68+
## Validation Goals
69+
- Console remains fully usable without overlay visibility.
70+
- Overlay remains fully usable without console focus.
71+
- Shared state flow is explainable through public boundaries only.
72+
- No engine-core changes required.
73+
- Sample-level integration reference remains `MultiSystemDemoScene.js`.
74+
75+
## Rollout Notes
76+
1. Land docs first (this bundle).
77+
2. If needed later, run a focused APPLY PR to replace any private cross-calls with approved selectors/events at sample integration points only.
78+
3. Keep command/input changes in console code and telemetry/HUD changes in overlay code.

0 commit comments

Comments
 (0)