BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER

DavidQ · DavidQ · commit 8b0a860d79f5 · 2026-04-05T16:49:54.000-04:00
- Added canvas-based debug HUD renderer
- Wired HUD draw into sample-level dev console integration
- Rendered overlay after gameplay with existing combo-key controls
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -7,15 +7,29 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Update dev console integration to replace F-key bindings with combo-key bindings.
+Create BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER implementation.
 
-- Shift + ` => toggleConsole
-- Ctrl + Shift + ` => toggleOverlay
-- Ctrl + Shift + R => reload
-- Ctrl + Shift + ] => next panel
-- Ctrl + Shift + [ => previous panel
+Requirements:
+- Create tools/dev/canvasDebugHudRenderer.js
+- Update tools/dev/devConsoleIntegration.js to use the HUD renderer
+- Modify ONE sample/dev entry file only
+- Draw debug HUD on canvas after world rendering
+- Keep combo keys exactly as currently implemented:
+  - Shift + ` => toggle console
+  - Ctrl + Shift + ` => toggle overlay
+  - Ctrl + Shift + R => reload
+  - Ctrl + Shift + ] => next panel
+  - Ctrl + Shift + [ => previous panel
+- No engine core changes
+- No F-key bindings
+- Use save()/restore() around canvas mutations
+- Keep commit_comment.txt header-free
+- Run node --check on touched JS files
+- Package implementation output to:
+  <project folder>/tmp/BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER_delta.zip
 
-Remove all F-key bindings.
-
-Keep changes isolated to devConsoleIntegration.js
-Do not modify engine core
+Report back:
+- exact files changed
+- sample file selected
+- how HUD draw is invoked
+- validation command results
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,5 +1,5 @@
-BUILD_PR_DEBUG_COMBO_KEYS_PATCH
+BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER
 
-- Replaced F-key bindings with browser-safe combo keys
-- Added Shift+` and Ctrl+Shift+` toggles
-- Removed conflicting browser shortcuts
+- Added canvas-based debug HUD renderer
+- Wired HUD draw into sample-level dev console integration
+- Rendered overlay after gameplay with existing combo-key controls
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-APPLY_PR_DEBUG_COMBO_KEYS_PATCH
+APPLY_PR_CANVAS_DEBUG_OVERLAY_RENDERER
diff --git a/docs/dev/change_summary.txt b/docs/dev/change_summary.txt
@@ -1 +1,10 @@
-Replaced F-key debug bindings with combo keys for browser compatibility
+Toolbox Aid
+David Quesenberry
+04/05/2026
+change_summary.txt
+
+Summary
+- Added BUILD PR for a real on-canvas debug HUD
+- Scoped implementation to tools/dev plus one sample entry
+- Preserved combo-key debug controls
+- Preserved docs-first workflow and commit_comment no-header exception
diff --git a/docs/dev/file_tree.txt b/docs/dev/file_tree.txt
@@ -1 +1,12 @@
-docs/pr/... docs/dev/... tools/dev/devConsoleIntegration.js
+Toolbox Aid
+David Quesenberry
+04/05/2026
+file_tree.txt
+
+docs/pr/BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER.md
+docs/dev/codex_commands.md
+docs/dev/commit_comment.txt
+docs/dev/change_summary.txt
+docs/dev/validation_checklist.txt
+docs/dev/file_tree.txt
+docs/dev/next_command.txt
diff --git a/docs/dev/validation_checklist.txt b/docs/dev/validation_checklist.txt
@@ -1 +1,36 @@
-Combo keys work, no F-keys remain, no browser conflicts
+Toolbox Aid
+David Quesenberry
+04/05/2026
+validation_checklist.txt
+
+VALIDATION CHECKLIST
+
+Workflow
+- BUILD_PR created
+- One PR per purpose
+- Commit comment has no header
+
+Implementation Targets
+- tools/dev/canvasDebugHudRenderer.js created
+- tools/dev/devConsoleIntegration.js updated
+- one sample entry updated
+
+Functional
+- Shift + ` toggles console state
+- Ctrl + Shift + ` toggles HUD visibility
+- Ctrl + Shift + R triggers reload action
+- Ctrl + Shift + ] moves to next panel
+- Ctrl + Shift + [ moves to previous panel
+- HUD draws on canvas after gameplay/world rendering
+- HUD survives missing diagnostics safely
+
+Safety
+- No engine core files modified
+- No F-key bindings remain
+- Canvas save/restore used
+- No duplicate listeners/runtime instances after repeated init/reload
+
+Validation Commands
+- node --check tools/dev/canvasDebugHudRenderer.js
+- node --check tools/dev/devConsoleIntegration.js
+- node --check <selected sample file>
diff --git a/docs/pr/BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER.md b/docs/pr/BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER.md
@@ -0,0 +1,133 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER.md
+
+# BUILD PR
+Canvas Debug Overlay Renderer
+
+## Objective
+Build a real visual HUD for the existing dev console/debug overlay system and wire it into one sample so the overlay renders on-canvas inside the running game.
+
+## Scope
+- Create a dedicated canvas HUD renderer file
+- Wire the HUD renderer into the existing sample-level dev console integration
+- Render overlay content after gameplay/world rendering
+- Reuse existing overlay diagnostics and panel state from the current debug runtime
+- Keep implementation isolated to tool/dev + one sample integration target
+
+## Required Outputs
+Codex must produce implementation code and the implementation delta ZIP at:
+<project folder>/tmp/BUILD_PR_CANVAS_DEBUG_OVERLAY_RENDERER_delta.zip
+
+## File Targets
+Expected implementation focus:
+- tools/dev/canvasDebugHudRenderer.js
+- tools/dev/devConsoleIntegration.js
+- one sample entry file only
+- optional test file if needed for renderer validation
+
+## Implementation Requirements
+
+### 1. New HUD renderer
+Create:
+tools/dev/canvasDebugHudRenderer.js
+
+Responsibilities:
+- accept a 2D canvas context and overlay data
+- render a lightweight translucent HUD panel
+- draw title + section headers + line items
+- support current/active panel highlighting
+- support compact layout with predictable padding
+- render safely even when some diagnostics are missing
+- remain dependency-free
+
+### 2. Wire into existing integration
+Update:
+tools/dev/devConsoleIntegration.js
+
+Requirements:
+- import canvasDebugHudRenderer.js
+- keep combo-key bindings already implemented:
+  - Shift + ` => toggle console
+  - Ctrl + Shift + ` => toggle overlay
+  - Ctrl + Shift + R => reload
+  - Ctrl + Shift + ] => next panel
+  - Ctrl + Shift + [ => previous panel
+- expose a method that draws the HUD onto a provided canvas context
+- preserve sample-safe boundaries
+- do not move logic into engine core
+
+### 3. Sample wiring
+Modify ONE sample/dev entry file only.
+
+Requirements:
+- initialize integration once
+- collect diagnostics in the loop
+- draw world/game first
+- draw debug HUD last
+- ensure repeated toggles do not duplicate listeners or runtime instances
+
+## HUD Rendering Rules
+- Render last in frame order
+- Default position: top-left
+- Use readable mono or browser-safe default font
+- Use translucent dark background
+- Use contrasting text
+- Keep dimensions adaptive to content
+- Avoid touching gameplay transforms/camera transforms
+- Use save()/restore() around canvas state mutations
+- Do not assume fullscreen
+- Do not require HTML DOM overlay
+
+## Minimum Visible Content
+HUD should visibly support:
+- Runtime
+- Frame
+- Scene
+- Camera
+- Entities
+- Render
+- Tilemap
+- Input
+- Hot Reload
+- Validation
+
+## Non-Goals
+- No engine renderer rewrite
+- No DOM-based console window
+- No CSS/HTML overlay framework
+- No broad sample migrations
+- No debug system spread across engine modules
+
+## Acceptance Criteria
+- Sample still runs normally
+- Shift + ` toggles console state
+- Ctrl + Shift + ` toggles HUD visibility
+- HUD draws on canvas
+- HUD renders after gameplay content
+- Panel navigation works
+- Missing diagnostics do not crash rendering
+- No F-key bindings remain
+- No engine core files modified
+
+## Validation
+- node --check on all touched JS files
+- run sample manually
+- verify HUD visible on canvas
+- verify combo keys work
+- verify reload combo does not browser-refresh the page
+- verify panel cycling updates visible section focus
+- verify no duplicate event listeners after reload/reinit
+
+## Risks
+- Canvas state leakage
+- overlay drawn before game content
+- integration duplicates runtime
+- browser key conflict regressions
+
+## Rollback
+If instability appears:
+- disable HUD draw call in sample
+- keep runtime logic intact
+- preserve combo key system
diff --git a/samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js b/samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js
@@ -187,6 +187,9 @@ export default class MultiSystemDemoScene extends Scene {
     const worldStages = ['parallax', 'tilemap', 'entities', 'sprite-effects', 'vector-overlay'];
     const renderOrder = this.devConsoleIntegration?.getRuntime?.().getDeterministicRenderOrder(worldStages) || worldStages;
     this.lastResolvedRenderOrder = renderOrder.slice();
+    const shiftDown = engine.input.isDown('ShiftLeft') || engine.input.isDown('ShiftRight');
+    const ctrlDown = engine.input.isDown('ControlLeft') || engine.input.isDown('ControlRight');
+    const backquoteDown = engine.input.isDown('Backquote');
 
     return {
       runtime: {
@@ -214,8 +217,11 @@ export default class MultiSystemDemoScene extends Scene {
         left: engine.input.isDown('ArrowLeft'),
         right: engine.input.isDown('ArrowRight'),
         jump: engine.input.isDown('Space'),
-        consoleToggle: engine.input.isDown('Backquote'),
-        overlayToggle: engine.input.isDown('F3'),
+        consoleToggle: shiftDown && !ctrlDown && backquoteDown,
+        overlayToggle: ctrlDown && shiftDown && backquoteDown,
+        reload: ctrlDown && shiftDown && engine.input.isDown('KeyR'),
+        nextPanel: ctrlDown && shiftDown && engine.input.isDown('BracketRight'),
+        previousPanel: ctrlDown && shiftDown && engine.input.isDown('BracketLeft'),
       },
       hotReload: {
         enabled: false,
@@ -244,7 +250,8 @@ export default class MultiSystemDemoScene extends Scene {
       'Gameplay contract matches Demo 1204 with one added collectible counter layer.',
       'Collectibles disappear on touch and increment the counter.',
       'No enemies, trigger/switch systems, or broader game systems.',
-      'Debug: ` toggles console, F3 toggles overlay, F6/F7/F8/F9 run console commands.',
+      'Debug: Shift+` console, Ctrl+Shift+` overlay, Ctrl+Shift+R reload.',
+      'Debug Panels: Ctrl+Shift+] next panel, Ctrl+Shift+[ previous panel.',
     ]);
 
     renderer.strokeRect(this.screen.x, this.screen.y, this.camera.viewportWidth, this.camera.viewportHeight, '#d8d5ff', 2);
@@ -271,7 +278,7 @@ export default class MultiSystemDemoScene extends Scene {
       `Goal: ${complete}`,
       `Camera X: ${this.camera.x.toFixed(1)}`,
       `Parallax Far/Near: ${this.parallaxLayers[0].speed}/${this.parallaxLayers[2].speed}`,
-      'Controls: Left/Right + Space + ` + F3',
+      'Controls: Left/Right + Space + Shift+` + Ctrl+Shift+`',
     ]);
 
     if (this.devConsoleIntegration) {
diff --git a/tools/dev/canvasDebugHudRenderer.js b/tools/dev/canvasDebugHudRenderer.js
diff --git a/tools/dev/devConsoleIntegration.js b/tools/dev/devConsoleIntegration.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-APPLY_PR_DEBUG_COMBO_KEYS_PATCH`
	`1`	`+APPLY_PR_CANVAS_DEBUG_OVERLAY_RENDERER`