Standardize debug overlay behavior across samples 1707+ by introducing TAB-based cycling to prevent overlay stacking and improve usability.

PR: BUILD_PR_LEVEL_17_48_APPLY_TAB_DEBUG_TO_SAMPLES_1707_PLUS

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Implement Sample 1713 as the final reference game using existing engine/sample systems only. Register it in samples/index.html after the repaired 1707-1712 sequence, preserve existing work, keep logic bounded unless truly shared, and package the repo-structured result to <project folder>/tmp/BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME.zip
+COMMAND: Apply TAB-based debug overlay cycling to all samples from 1707 onward using shared debug infrastructure, ensuring only one overlay is visible at a time, preserving gameplay, and package to <project folder>/tmp/BUILD_PR_LEVEL_17_48_APPLY_TAB_DEBUG_TO_SAMPLES_1707_PLUS.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Implement Sample 1713 as the final reference gameplay sample for the repaired Level 17 sequence, with a complete playable loop, HUD, camera follow, and index integration.
+Standardize debug overlay behavior across samples 1707+ by introducing TAB-based cycling to prevent overlay stacking and improve usability.
 
-PR: BUILD_PR_LEVEL_17_45_SAMPLE_1713_FINAL_REFERENCE_GAME
+PR: BUILD_PR_LEVEL_17_48_APPLY_TAB_DEBUG_TO_SAMPLES_1707_PLUS

docs/pr/BUILD_PR_LEVEL_17_48_APPLY_TAB_DEBUG_TO_SAMPLES_1707_PLUS.md

@@ -0,0 +1,24 @@
+# BUILD
+
+## Instructions for Codex
+
+### Apply Behavior
+- Ensure all samples use shared debug overlay controller
+- Enable TAB / SHIFT+TAB cycling
+
+### Standardize
+- Only one overlay visible
+- Same ordering across samples
+
+### Update
+- samples/index.html (no structural change, ensure compatibility)
+
+### Constraints
+- Do not break gameplay
+- Do not duplicate logic per sample
+- Use shared debug layer
+
+### Validation
+- Open each sample 1707+
+- TAB cycles overlays
+- No stacking

docs/pr/PLAN_PR_LEVEL_17_48_APPLY_TAB_DEBUG_TO_SAMPLES_1707_PLUS.md

@@ -0,0 +1,12 @@
+# PLAN
+
+## Goal
+Apply TAB-based debug overlay cycling to all gameplay samples starting at 1707 through latest.
+
+## Why
+Samples currently stack debug overlays making them unusable.
+
+## Scope
+- Samples 1707 → latest
+- No engine rewrites
+- Hook into debug system only

samples/index.html

@@ -507,13 +507,13 @@ <h2>Phase 17 - Rendering Technique Expansion</h2>
         <a class="live" href="./phase-17/1704/index.html" title="Unreal-style textured surfaces with lightweight dynamic lighting cues." data-tags="camera3d, unreal-style, textures, lighting, image-backed, scene, themetokens" data-primary="unreal-texture-lighting">Sample 1704 - Unreal Texture + Lighting</a>
         <a class="live" href="./phase-17/1705/index.html" title="Unreal-style skinned character presentation with image-backed animation frames." data-tags="camera3d, unreal-style, image-skinned, animation, character, scene, themetokens" data-primary="unreal-skinned-mesh">Sample 1705 - Unreal Skinned Mesh Demo</a>
         <a class="live" href="./phase-17/1706/index.html" title="Minecraft-style filled voxel terrain blocks with visible height variation." data-tags="camera3d, minecraft-style, voxel, terrain, filled-render, scene, themetokens" data-primary="minecraft-voxel-terrain">Sample 1706 - Minecraft Voxel Terrain</a>
-        <a class="live" href="./phase-17/1707/index.html" title="Minecraft-style voxel chunk-window streaming around a movable camera anchor." data-tags="camera3d, minecraft-style, voxel, chunk-streaming, filled-render, scene, themetokens" data-primary="minecraft-chunk-streaming">Sample 1707 - Minecraft Chunk Streaming</a>
-        <a class="live" href="./phase-17/1708/index.html" title="Real 3D mini-game loop with movement, hazard interaction, objective scoring, camera follow, and standard 3D debug panels." data-tags="camera3d, gameplay, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game">Sample 1708 - Real Gameplay Mini-Game</a>
-        <a class="live" href="./phase-17/1709/index.html" title="Compares direct axis movement, tank rotation controls, and weighted movement with follow-camera framing." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab">Sample 1709 - Movement Models Lab</a>
-        <a class="live" href="./phase-17/1710/index.html" title="Polished gameplay loop variant with mission-state feedback, objective progression, and standard 3D debug panels." data-tags="camera3d, gameplay, polished-loop, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game-polished">Sample 1710 - Real Gameplay Mini-Game</a>
-        <a class="live" href="./phase-17/1711/index.html" title="Movement-models lab variant for sequence alignment with direct, tank, and weighted controls plus follow camera." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab-sequence">Sample 1711 - Movement Models Lab</a>
-        <a class="live" href="./phase-17/1712/index.html" title="Gameplay telemetry overlay for mini-game state, speed, collisions, actions, and live FPS trend." data-tags="camera3d, gameplay, telemetry, metrics, debug-overlay, scene, themetokens" data-primary="gameplay-metrics-telemetry">Sample 1712 - Gameplay Metrics & Telemetry</a>
-        <a class="live" href="./phase-17/1713/index.html" title="Final reference game sample that combines complete mission loop, camera/collision debug output, and runtime telemetry using existing systems only." data-tags="camera3d, gameplay, reference-game, telemetry, debug-panels, mission-loop, scene, themetokens" data-primary="final-reference-game">Sample 1713 - Final Reference Game</a>
+        <a class="live" href="./phase-17/1707/index.html" title="Minecraft-style voxel chunk-window streaming around a movable camera anchor with TAB-cycled debug runtime overlay." data-tags="camera3d, minecraft-style, voxel, chunk-streaming, filled-render, scene, themetokens" data-primary="minecraft-chunk-streaming">Sample 1707 - Minecraft Chunk Streaming</a>
+        <a class="live" href="./phase-17/1708/index.html" title="Real 3D mini-game loop with movement, hazard interaction, objective scoring, camera follow, and TAB-cycled debug overlays." data-tags="camera3d, gameplay, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game">Sample 1708 - Real Gameplay Mini-Game</a>
+        <a class="live" href="./phase-17/1709/index.html" title="Compares direct axis movement, tank rotation controls, and weighted movement with follow-camera framing and TAB-cycled overlays." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab">Sample 1709 - Movement Models Lab</a>
+        <a class="live" href="./phase-17/1710/index.html" title="Polished gameplay loop variant with mission-state feedback, objective progression, and TAB-cycled debug overlays." data-tags="camera3d, gameplay, polished-loop, objective, hazards, debug-panels, scene, themetokens" data-primary="real-gameplay-mini-game-polished">Sample 1710 - Real Gameplay Mini-Game</a>
+        <a class="live" href="./phase-17/1711/index.html" title="Movement-models lab variant for sequence alignment with direct, tank, and weighted controls plus TAB-cycled overlays." data-tags="camera3d, movement-models, direct-controls, tank-controls, weighted-motion, scene, themetokens" data-primary="movement-models-lab-sequence">Sample 1711 - Movement Models Lab</a>
+        <a class="live" href="./phase-17/1712/index.html" title="Gameplay telemetry overlay for mini-game state, speed, collisions, actions, and live FPS trend with TAB-cycled debug views." data-tags="camera3d, gameplay, telemetry, metrics, debug-overlay, scene, themetokens" data-primary="gameplay-metrics-telemetry">Sample 1712 - Gameplay Metrics & Telemetry</a>
+        <a class="live" href="./phase-17/1713/index.html" title="Final reference game sample that combines complete mission loop, camera/collision debug output, and runtime telemetry with TAB-cycled overlays." data-tags="camera3d, gameplay, reference-game, telemetry, debug-panels, mission-loop, scene, themetokens" data-primary="final-reference-game">Sample 1713 - Final Reference Game</a>
       </div>
     </section>
     <section>

samples/phase-17/1707/VoxelWorldDemoScene.js

@@ -7,10 +7,17 @@ VoxelWorldDemoScene.js
 import { Scene } from '/src/engine/scene/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
+import {
+  createTabDebugOverlayController,
+  getTabDebugOverlayStatusLabel,
+  isTabDebugOverlayActive,
+  stepTabDebugOverlayController,
+} from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 
 const theme = new Theme(ThemeTokens);
 const WORLD_SIZE = 16;
 const CHUNK_SIZE = 4;
+const OVERLAY_CHUNK_RUNTIME = 'chunk-runtime';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -35,6 +42,12 @@ export default class ChunkStreamingVoxelScene extends Scene {
     this.lastFilledFaces = 0;
     this.lastActiveChunks = 0;
     this.heights = this.buildHeights();
+    this.tabDebugOverlays = createTabDebugOverlayController({
+      overlays: [
+        { id: OVERLAY_CHUNK_RUNTIME, label: 'Chunk Runtime' },
+      ],
+      initialOverlayId: OVERLAY_CHUNK_RUNTIME,
+    });
   }
 
   buildHeights() {
@@ -100,6 +113,7 @@ export default class ChunkStreamingVoxelScene extends Scene {
 
   step3DPhysics(dt, engine) {
     const input = engine.input;
+    stepTabDebugOverlayController(this.tabDebugOverlays, input);
     const step = Math.min(dt, 1 / 30);
     const panSpeed = 3;
     if (input?.isDown('KeyA')) this.camera.x -= panSpeed * step;
@@ -119,7 +133,7 @@ export default class ChunkStreamingVoxelScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1707 - Minecraft Chunk Streaming',
       'Voxel chunk-window streaming keeps nearby terrain active around the camera anchor.',
-      'Controls: W/A/S/D pan | Up/Down or Q/E chunk radius',
+      `Controls: W/A/S/D pan | Up/Down or Q/E chunk radius | Debug: Tab/Shift+Tab (${getTabDebugOverlayStatusLabel(this.tabDebugOverlays)})`,
     ]);
 
     const viewport = this.viewport;
@@ -159,13 +173,15 @@ export default class ChunkStreamingVoxelScene extends Scene {
       this.drawBlock(renderer, block.x, block.y, block.z, block.baseRgb);
     }
 
-    drawPanel(renderer, 620, 34, 300, 188, 'Chunk Runtime', [
-      `World cells: ${WORLD_SIZE}x${WORLD_SIZE}`,
-      `Camera: x=${this.camera.x.toFixed(2)} z=${this.camera.z.toFixed(2)}`,
-      `Chunk radius: ${this.chunkRadius}`,
-      `Active chunks: ${this.lastActiveChunks}`,
-      `Blocks drawn: ${blocks.length}`,
-      `Filled faces: ${this.lastFilledFaces}`,
-    ]);
+    if (isTabDebugOverlayActive(this.tabDebugOverlays, OVERLAY_CHUNK_RUNTIME)) {
+      drawPanel(renderer, 620, 34, 300, 188, 'Chunk Runtime', [
+        `World cells: ${WORLD_SIZE}x${WORLD_SIZE}`,
+        `Camera: x=${this.camera.x.toFixed(2)} z=${this.camera.z.toFixed(2)}`,
+        `Chunk radius: ${this.chunkRadius}`,
+        `Active chunks: ${this.lastActiveChunks}`,
+        `Blocks drawn: ${blocks.length}`,
+        `Filled faces: ${this.lastFilledFaces}`,
+      ]);
+    }
   }
 }

samples/phase-17/1708/RealGameplayMiniGameScene.js

@@ -24,6 +24,14 @@ import {
   drawWireBox,
   stepPhase16ViewToggles,
 } from '/samples/phase-16/shared/threeDWireframe.js';
+import {
+  appendTabDebugOverlay,
+  createTabDebugOverlayController,
+  getTabDebugOverlayStatusLabel,
+  isTabDebugOverlayActive,
+  setTabDebugOverlayActive,
+  stepTabDebugOverlayController,
+} from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 
 const theme = new Theme(ThemeTokens);
 
@@ -32,6 +40,10 @@ const READY_STATE = 'ready';
 const RUNNING_STATE = 'running';
 const WON_STATE = 'won';
 const LOST_STATE = 'lost';
+const OVERLAY_RUNTIME = 'runtime';
+const OVERLAY_CAMERA = 'camera';
+const OVERLAY_COLLISION = 'collision';
+const OVERLAY_PHASE16 = 'phase16';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -111,6 +123,15 @@ export default class RealGameplayMiniGameScene extends Scene {
       providerMap,
       enabled: true,
     });
+    this.tabDebugOverlays = createTabDebugOverlayController({
+      overlays: [
+        { id: OVERLAY_RUNTIME, label: 'Mini-Game Runtime' },
+        { id: OVERLAY_CAMERA, label: '3D Camera Summary' },
+        { id: OVERLAY_COLLISION, label: '3D Collision Overlays' },
+        { id: OVERLAY_PHASE16, label: 'Phase16 Overlay' },
+      ],
+      initialOverlayId: OVERLAY_RUNTIME,
+    });
   }
 
   addEvent(text) {
@@ -191,6 +212,24 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.syncCamera();
   }
 
+  registerDebugOverlay(overlayId, label, { makeActive = false } = {}) {
+    appendTabDebugOverlay(this.tabDebugOverlays, {
+      id: overlayId,
+      label,
+    });
+    if (makeActive) {
+      setTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
+    }
+  }
+
+  isDebugOverlayActive(overlayId) {
+    return isTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
+  }
+
+  getDebugOverlayStatusLabel() {
+    return getTabDebugOverlayStatusLabel(this.tabDebugOverlays);
+  }
+
   pushCollisionRow(overlayId, kind, state, enabled = true) {
     this.debugCollisionRows.push({
       overlayId,
@@ -413,6 +452,7 @@ export default class RealGameplayMiniGameScene extends Scene {
     const dt = Math.max(0, Math.min(0.05, Number(dtSeconds) || 0));
     this.elapsed += dt;
     const input = engine?.input;
+    stepTabDebugOverlayController(this.tabDebugOverlays, input);
 
     stepPhase16ViewToggles(this.viewState, input);
 
@@ -465,7 +505,7 @@ export default class RealGameplayMiniGameScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1708 - Real Gameplay Mini-Game (Polished)',
       'Deploy, collect data cores, survive sentry patrols, and complete mission objectives.',
-      'Start: Space/Enter | Move: W A S D | Camera yaw: Q/E or Left/Right | Restart after match: R | Camera mode: C',
+      `Start: Space/Enter | Move: W A S D | Camera yaw: Q/E or Left/Right | Restart: R | Overlay: Tab/Shift+Tab (${this.getDebugOverlayStatusLabel()})`,
     ]);
 
     const viewport = this.viewport;
@@ -599,7 +639,10 @@ export default class RealGameplayMiniGameScene extends Scene {
       max: this.roundSeconds,
       barColor: '#38bdf8',
     });
-    renderer.drawText('Camera mode: C | Debug overlay: V', 64, 166, { color: '#e2e8f0', font: '11px monospace' });
+    renderer.drawText(`Camera mode: C | Overlay cycle: Tab/Shift+Tab (${this.getDebugOverlayStatusLabel()})`, 64, 166, {
+      color: '#e2e8f0',
+      font: '11px monospace',
+    });
     renderer.drawText('Move: W A S D | Yaw: Q/E or Left/Right', 64, 182, { color: '#e2e8f0', font: '11px monospace' });
 
     const statePulse = 0.5 + Math.sin(this.statePulse * 3.2) * 0.5;
@@ -637,20 +680,28 @@ export default class RealGameplayMiniGameScene extends Scene {
           : `Status: ${this.gameState}.`,
     ]);
 
-    drawPanel(renderer, 620, 414, 300, 120, 'Mini-Game Runtime', [
-      `Entities: obstacles=${this.obstacles.length} sentries=${this.enemies.length}`,
-      `Remaining cores: ${this.cores.filter((core) => !core.collected).length}`,
-      `Player: x=${this.player.x.toFixed(2)} z=${this.player.z.toFixed(2)}`,
-      `Collision overlays: ${this.lastCollisionCount}`,
-      `Camera mode: ${this.viewState.cameraMode}`,
-    ]);
+    if (this.isDebugOverlayActive(OVERLAY_RUNTIME)) {
+      drawPanel(renderer, 620, 414, 300, 120, 'Mini-Game Runtime', [
+        `Entities: obstacles=${this.obstacles.length} sentries=${this.enemies.length}`,
+        `Remaining cores: ${this.cores.filter((core) => !core.collected).length}`,
+        `Player: x=${this.player.x.toFixed(2)} z=${this.player.z.toFixed(2)}`,
+        `Collision overlays: ${this.lastCollisionCount}`,
+        `Camera mode: ${this.viewState.cameraMode}`,
+      ]);
+    }
 
-    this.renderStandardDebugPanel(renderer, PANEL_3D_CAMERA, 620, 34, 300, 150, 7);
-    this.renderStandardDebugPanel(renderer, PANEL_3D_COLLISION, 620, 194, 300, 210, 9);
+    if (this.isDebugOverlayActive(OVERLAY_CAMERA)) {
+      this.renderStandardDebugPanel(renderer, PANEL_3D_CAMERA, 620, 34, 300, 150, 7);
+    }
+    if (this.isDebugOverlayActive(OVERLAY_COLLISION)) {
+      this.renderStandardDebugPanel(renderer, PANEL_3D_COLLISION, 620, 194, 300, 210, 9);
+    }
 
-    drawPhase16DebugOverlay(renderer, viewport, this.viewState, [
-      `Match state: ${this.gameState}`,
-      'Standard 3D camera/collision debug panels rendered from provider snapshots',
-    ]);
+    if (this.isDebugOverlayActive(OVERLAY_PHASE16)) {
+      drawPhase16DebugOverlay(renderer, viewport, this.viewState, [
+        `Match state: ${this.gameState}`,
+        'Standard 3D camera/collision debug panels rendered from provider snapshots',
+      ]);
+    }
   }
 }