PLAN_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION

- Planned sample game integration for dev console and debug overlay
- Locked toggle-key driven behavior and last-stage overlay render
- Scoped implementation to sample-level wiring without engine pollution

Author: DavidQ

README.txt

@@ -1,3 +1,15 @@
-MODEL: GPT-5.3-codex
+Toolbox Aid
+David Quesenberry
+04/05/2026
+codex_commands.md
+
+MODEL: GPT-5.4-codex
 REASONING: high
-COMMAND: Apply dev console and debug overlay per PR.
+
+COMMAND:
+Implement dev console integration into one sample using tools/dev/devConsoleIntegration.js
+
+- follow BUILD PR
+- create file
+- wire sample
+- do not modify engine core

dev_console_test.js

@@ -1 +1,5 @@
-apply(debug): implement dev console and debug overlay contracts with deterministic ordering, validation isolation, and hot-reload-safe state handling
+BUILD_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION
+
+- Added dev console integration wrapper
+- Wired toggle keys (` and Shift+`)
+- Integrated into sample loop

docs/dev/CODEX_COMMANDS.md

@@ -1 +1 @@
-PLAN_PR_ASSET_PIPELINE_CACHING_AND_HASHING
+APPLY_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION

docs/dev/COMMIT_COMMENT.txt

@@ -1,61 +1 @@
-Toolbox Aid
-David Quesenberry
-04/05/2026
-change_summary.txt
-
-APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY summary
-
-Implemented focused dev console and debug overlay runtime contracts:
-- Added `tools/shared/devConsoleDebugOverlay.js`
-- Preserved architecture boundaries by keeping orchestration in shared runtime tooling above engine core
-- Did not introduce tool-specific quirks into engine systems
-
-Implemented diagnostics contract:
-- Added diagnostics envelope contract (`contractVersion`, deterministic `timestamp`, required/optional sections)
-- Added structured diagnostics error reporting (`level`, `stage`, `code`, `message`, `details`)
-- Added adapter failure isolation so one adapter failure does not break diagnostics collection
-
-Implemented command registry contract:
-- Added command definition validation and deterministic registration behavior
-- Added no-eval command execution pathway
-- Added deterministic conflict handling (core wins, extension collisions rejected)
-- Added required core command families from the approved contract
-
-Implemented overlay panel contract:
-- Added panel definition validation
-- Added deterministic panel ordering (priority then id)
-- Added panel-level render failure isolation
-- Added required core panel families from the approved contract
-
-Implemented deterministic render ordering:
-- Added canonical ordering function with debug surfaces last
-- Enforced ordering tail: `debug-overlay`, then `dev-console-surface`
-
-Implemented hot reload survival behavior:
-- Added reload application flow that preserves console history and panel registration state
-- Added structured fallback on reload failure (`RELOAD_REJECTED_KEEP_LAST_GOOD`)
-- Preserved last-known-good runtime state on reload rejection
-- Added repeated-reload stability behavior without duplicate command/panel registration
-
-Automated tests added:
-- Added `tests/tools/DevConsoleDebugOverlay.test.mjs`
-- Covers diagnostics contract shaping and adapter failure isolation
-- Covers command registry validation/conflict/unknown-command behavior
-- Covers panel contract ordering and panel render failure isolation
-- Covers deterministic render ordering with debug overlay last
-- Covers hot reload success, failure fallback, repeated reload stability, and disposal behavior
-
-Test harness integration:
-- Updated `tests/run-tests.mjs` with `DevConsoleDebugOverlay`
-
-Validation evidence:
-- `node --check tools/shared/devConsoleDebugOverlay.js`
-- `node --check tests/tools/DevConsoleDebugOverlay.test.mjs`
-- `node --check tests/run-tests.mjs`
-- Targeted test run passed (`DevConsoleDebugOverlay targeted check passed`)
-- Full suite passed (`113/113 explicit run() tests passed`)
-
-Scope guardrails honored:
-- No engine-core API rewrite
-- No unrelated sample/tool refactors
-- Changes kept surgical and contract-aligned
+Added dev console integration plan and execution instructions

docs/dev/NEXT_COMMAND.txt

@@ -1,12 +1 @@
-Toolbox Aid
-David Quesenberry
-04/05/2026
-file_tree.txt
-
-tools/shared/devConsoleDebugOverlay.js
-tests/tools/DevConsoleDebugOverlay.test.mjs
-tests/run-tests.mjs
-docs/dev/change_summary.txt
-docs/dev/file_tree.txt
-docs/dev/validation_checklist.txt
-docs/dev/commit_comment.txt
+docs/pr/... docs/dev/... tools/dev/devConsoleIntegration.js

docs/dev/change_summary.txt

@@ -1,45 +1 @@
-Toolbox Aid
-David Quesenberry
-04/05/2026
-validation_checklist.txt
-
-APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY validation checklist
-
-Contracts
-[x] Diagnostics contract implemented with required envelope fields
-[x] Command registry contract implemented and validated
-[x] Overlay panel contract implemented and validated
-[x] Structured error format used for validation/collection/render failures
-
-Ordering and mappings
-[x] Deterministic render ordering implemented
-[x] Debug overlay renders after authored world stages
-[x] Dev console surface renders after debug overlay
-[x] Engine mapping constants defined through public adapter contract mapping
-
-Hot reload survival
-[x] Hot reload success preserves diagnostics shell state
-[x] Hot reload failure preserves last-known-good runtime state
-[x] Repeated reloads do not duplicate commands or panels
-[x] Structured reload rejection reporting implemented
-
-Automated tests
-[x] Diagnostics adapter failure isolation test passes
-[x] Command registry conflict/unknown command tests pass
-[x] Overlay panel ordering/failure isolation tests pass
-[x] Deterministic render ordering test passes
-[x] Hot reload success/failure/repeated-reload stability tests pass
-[x] Disposal behavior test passes
-[x] New test wired into `tests/run-tests.mjs`
-
-Execution evidence
-[x] `node --check tools/shared/devConsoleDebugOverlay.js`
-[x] `node --check tests/tools/DevConsoleDebugOverlay.test.mjs`
-[x] `node --check tests/run-tests.mjs`
-[x] Targeted test run passed
-[x] Full suite run passed (`113/113 explicit run() tests passed`)
-
-Scope safety
-[x] Orchestration remains above engine core
-[x] No destructive runtime-breaking changes introduced
-[x] No unrelated runtime/sample/tool areas modified
+Toggle keys work, overlay renders, sample runs

docs/dev/file_tree.txt

@@ -0,0 +1,38 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+BUILD_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION.md
+
+# BUILD PR
+Dev Console + Debug Overlay Sample Integration
+
+## Implementation Steps (Codex)
+
+1. Create file:
+tools/dev/devConsoleIntegration.js
+
+2. Implement:
+- import runtime from tools/shared/devConsoleDebugOverlay.js
+- key handling:
+  ` → toggleConsole()
+  Shift + ` → toggleOverlay()
+- expose:
+  init, dispose, updateDiagnostics, renderOverlay, executeCommand, getState
+
+3. Modify ONE sample file:
+- import integration
+- initialize once
+- call updateDiagnostics() in loop
+- call renderOverlay() after render
+
+## Constraints
+- no engine core changes
+- no duplicate runtime logic
+- sample-level only
+- overlay renders last
+
+## Validation
+- ` toggles console
+- Shift + ` toggles overlay
+- no crashes
+- sample still runs

docs/dev/validation_checklist.txt

@@ -0,0 +1,99 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+PLAN_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION.md
+
+# PLAN PR
+Sample Game Dev Console Toggle Integration
+
+## Objective
+Integrate the existing dev console and debug overlay runtime into one sample game with a keyboard toggle,
+while keeping engine core contracts clean and avoiding engine pollution.
+
+## Scope
+- Wire the existing `tools/shared/devConsoleDebugOverlay.js` runtime into a single sample/dev entry
+- Add a toggle key for console visibility
+- Add a toggle key for overlay visibility
+- Route collected diagnostics into the runtime once per frame
+- Render overlay text through the sample-facing surface only
+- Keep implementation isolated to sample/dev integration points and allowed debug surface hooks
+
+## Non-Goals
+- No engine-wide debug framework rewrite
+- No new tool contract changes
+- No replacement of renderer core APIs
+- No hotkey manager redesign
+- No global debug behavior forced into production samples
+
+## Required Constraints
+- Reuse the already-built runtime from `tools/shared/devConsoleDebugOverlay.js`
+- Do not duplicate console logic in the sample
+- Do not spread debug-specific conditionals across unrelated engine systems
+- Keep the feature disabled by default unless explicitly toggled
+- Preserve current render ordering; debug overlay renders last
+- Commit comment file must have NO header
+
+## Candidate Target
+Use one representative sample game or dev sample entry that already exercises scene loading and rendering.
+
+## Integration Design
+1. Import runtime from `tools/shared/devConsoleDebugOverlay.js`
+2. Create one runtime instance during sample init
+3. Register keyboard toggle(s):
+   - backquote / tilde for console surface
+   - F3 or similar for overlay visibility, if needed
+4. Per frame:
+   - gather diagnostics
+   - update runtime state
+   - render overlay after world render
+5. On command submit:
+   - execute console input through runtime
+   - log or surface output through the sample debug layer
+
+## Diagnostics Minimum Set
+- runtime summary
+- scene info
+- frame/fps
+- camera
+- entities
+- render stages
+- tilemap
+- input
+- hot reload
+- validation
+
+## Acceptance Criteria
+- Sample launches with no regression
+- Toggle key opens/closes console deterministically
+- Overlay can be shown/hidden
+- Existing world rendering still works
+- Overlay renders after gameplay content
+- `help` command works in the wired sample
+- `status` and `scene.info` return meaningful output
+- Invalid command does not crash the sample
+- Feature can be disabled cleanly
+
+## File Targets
+Expected implementation focus:
+- one sample entry file
+- optional sample-local debug helper
+- no broad engine churn
+
+## Validation
+- Run sample manually
+- Press toggle key repeatedly
+- Confirm overlay ordering
+- Execute `help`
+- Execute `status`
+- Execute `scene.info`
+- Confirm no duplicate runtime instances
+- Confirm no memory leak or double-render on repeated toggle
+
+## Risks
+- Input collision with existing sample controls
+- Overlay draw path mixed too deeply into renderer
+- Runtime instantiated more than once
+- Debug output coupled to production flow
+
+## Deliverable
+Create BUILD_PR_SAMPLE_GAME_DEV_CONSOLE_TOGGLE_INTEGRATION as a docs-only, repo-structured delta.