Normalize overlay stacks for samples 1708 and 1710.

DavidQ · DavidQ · commit 029d18bdaa06 · 2026-04-16T16:09:21.000-04:00
Standardize bottom-right placement and cycle behavior.
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,9 +1,9 @@
 MODEL: GPT-5.3-codex
 REASONING: medium
 COMMAND:
-Implement overlay stack mapping for sample 1713 using existing overlay system.
+Implement overlay normalization for samples 1708 and 1710.
+- Apply shared stack definition
 - Enforce bottom-right anchor
-- Remove any Tab bindings
-- Ensure cycle key matches prior PR (17_52)
-- Validate ordering and rendering
-Package output ZIP to <project folder>/tmp/
+- Remove Tab bindings
+- Ensure cycle order consistency
+Package ZIP to <project folder>/tmp/
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Align sample 1713 overlay stack to Final Reference Runtime.
-Enforce bottom-right placement and remove Tab key usage.
+Normalize overlay stacks for samples 1708 and 1710.
+Standardize bottom-right placement and cycle behavior.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,6 @@
-[ ] Sample 1713 loads
-[ ] Bottom-right overlay placement correct
+[ ] Sample 1708 loads
+[ ] Sample 1710 loads
+[ ] Bottom-right placement correct
 [ ] Cycle key works (non-Tab)
-[ ] Stack order matches spec
+[ ] Mini-Game Runtime renders
+[ ] Stack order consistent
diff --git a/docs/pr/BUILD_PR.md b/docs/pr/BUILD_PR.md
@@ -1,24 +1,25 @@
-# BUILD_PR_LEVEL_17_53_DEBUG_OVERLAY_SAMPLE_1713_FINAL_REFERENCE_ALIGNMENT
+# BUILD_PR_LEVEL_17_55_DEBUG_OVERLAY_SAMPLE_1708_1710_STACK_NORMALIZATION
 
 ## Purpose
-Align Sample 1713 overlay stack to Final Reference Runtime and validate bottom-right positioning + cycle behavior (non-Tab key).
+Normalize overlay stacks for samples 1708 and 1710 with consistent bottom-right placement and correct cycling order.
 
 ## Scope
-- Sample 1713 overlay stack:
+- Samples: 1708, 1710
+- Stack:
   - UI Layer
   - Mission Feed
   - <...ADY>
-  - Final Reference Runtime
-- Bottom-right anchor enforcement
-- Cycle key (non-Tab) verification
+  - Mini-Game Runtime
+- Bottom-right anchor
+- Non-Tab cycle key validation
 
 ## Test Steps
-1. Load sample 1713
-2. Verify overlays render bottom-right
-3. Press cycle key → confirm correct order
-4. Confirm no Tab usage
+1. Load 1708 and 1710
+2. Verify bottom-right placement
+3. Cycle overlays → confirm order
+4. Confirm Mini-Game Runtime visibility
 
 ## Expected
-- Correct stack order
-- No overlay overlap issues
-- Stable cycling behavior
+- Identical stack behavior across both samples
+- Stable cycling
+- No Tab usage
diff --git a/samples/phase-17/1708/RealGameplayMiniGameScene.js b/samples/phase-17/1708/RealGameplayMiniGameScene.js
@@ -28,18 +28,21 @@ import {
   setTabDebugOverlayMap,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
+import {
+  MINI_GAME_DEBUG_CYCLE_KEY,
+  OVERLAY_MINI_GAME_RUNTIME,
+  OVERLAY_MISSION_FEED,
+  OVERLAY_MISSION_READY,
+  OVERLAY_UI_LAYER,
+  createMiniGameOverlayCycleMap,
+} from '/samples/phase-17/shared/miniGameOverlayStack.js';
 
 const theme = new Theme(ThemeTokens);
 
 const READY_STATE = 'ready';
 const RUNNING_STATE = 'running';
 const WON_STATE = 'won';
 const LOST_STATE = 'lost';
-const DEBUG_CYCLE_KEY = 'KeyG';
-const OVERLAY_UI_LAYER = 'ui-layer';
-const OVERLAY_MISSION_FEED = 'mission-feed';
-const OVERLAY_MISSION_READY = 'mission-ready';
-const OVERLAY_MINI_GAME_RUNTIME = 'mini-game-runtime';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -87,13 +90,8 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.resetMatch({ toReady: true });
 
     this.tabDebugOverlays = createTabDebugOverlayController();
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_CYCLE_KEY);
-    this.setDebugOverlayCycleMap([
-      { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
-      { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },
-      { id: OVERLAY_MISSION_READY, label: 'MISSION READY' },
-      { id: OVERLAY_MINI_GAME_RUNTIME, label: 'Mini-Game Runtime' },
-    ], OVERLAY_UI_LAYER);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
+    this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
   }
 
   addEvent(text) {
diff --git a/samples/phase-17/1710/RealGameplayMiniGameScene.js b/samples/phase-17/1710/RealGameplayMiniGameScene.js
@@ -28,18 +28,21 @@ import {
   setTabDebugOverlayMap,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
+import {
+  MINI_GAME_DEBUG_CYCLE_KEY,
+  OVERLAY_MINI_GAME_RUNTIME,
+  OVERLAY_MISSION_FEED,
+  OVERLAY_MISSION_READY,
+  OVERLAY_UI_LAYER,
+  createMiniGameOverlayCycleMap,
+} from '/samples/phase-17/shared/miniGameOverlayStack.js';
 
 const theme = new Theme(ThemeTokens);
 
 const READY_STATE = 'ready';
 const RUNNING_STATE = 'running';
 const WON_STATE = 'won';
 const LOST_STATE = 'lost';
-const DEBUG_CYCLE_KEY = 'KeyG';
-const OVERLAY_UI_LAYER = 'ui-layer';
-const OVERLAY_MISSION_FEED = 'mission-feed';
-const OVERLAY_MISSION_READY = 'mission-ready';
-const OVERLAY_MINI_GAME_RUNTIME = 'mini-game-runtime';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -87,13 +90,8 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.resetMatch({ toReady: true });
 
     this.tabDebugOverlays = createTabDebugOverlayController();
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_CYCLE_KEY);
-    this.setDebugOverlayCycleMap([
-      { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
-      { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },
-      { id: OVERLAY_MISSION_READY, label: 'MISSION READY' },
-      { id: OVERLAY_MINI_GAME_RUNTIME, label: 'Mini-Game Runtime' },
-    ], OVERLAY_UI_LAYER);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
+    this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
   }
 
   addEvent(text) {
diff --git a/samples/phase-17/shared/miniGameOverlayStack.js b/samples/phase-17/shared/miniGameOverlayStack.js
@@ -0,0 +1,20 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+miniGameOverlayStack.js
+*/
+export const MINI_GAME_DEBUG_CYCLE_KEY = 'KeyG';
+export const OVERLAY_UI_LAYER = 'ui-layer';
+export const OVERLAY_MISSION_FEED = 'mission-feed';
+export const OVERLAY_MISSION_READY = 'mission-ready';
+export const OVERLAY_MINI_GAME_RUNTIME = 'mini-game-runtime';
+
+export function createMiniGameOverlayCycleMap() {
+  return [
+    { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
+    { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },
+    { id: OVERLAY_MISSION_READY, label: 'MISSION READY' },
+    { id: OVERLAY_MINI_GAME_RUNTIME, label: 'Mini-Game Runtime' },
+  ];
+}
diff --git a/tests/runtime/Phase17DebugOverlayBottomRightPosition.test.mjs b/tests/runtime/Phase17DebugOverlayBottomRightPosition.test.mjs
@@ -12,6 +12,7 @@ import {
 import DoomRaycastSpritesScene from '../../samples/phase-17/1701/RaycastDemoScene.js';
 import TextureMaterialDemoScene from '../../samples/phase-17/1704/TextureMaterialDemoScene.js';
 import RealGameplayMiniGameScene from '../../samples/phase-17/1708/RealGameplayMiniGameScene.js';
+import RealGameplayMiniGame1710Scene from '../../samples/phase-17/1710/RealGameplayMiniGameScene.js';
 import GameplayMetricsTelemetryScene from '../../samples/phase-17/1712/GameplayMetricsTelemetryScene.js';
 import FinalReferenceGameScene from '../../samples/phase-17/1713/FinalReferenceGameScene.js';
 
@@ -145,6 +146,31 @@ function assertSample1708CyclePlacement() {
   assertBottomRightFromTitle(runtimeTitle, 300, 120, 650, 410, 'Sample 1708 runtime overlay');
 }
 
+function assertSample1710CyclePlacement() {
+  const scene = new RealGameplayMiniGame1710Scene();
+  scene.setCamera3D(createCameraStub());
+
+  const renderer = createRendererProbe();
+  scene.render(renderer);
+  const uiLayerTitle = findExactText(renderer, 'UI Layer');
+  assertBottomRightFromTitle(uiLayerTitle, 326, 174, 624, 356, 'Sample 1710 UI Layer overlay');
+
+  scene.step3DPhysics(0.02, { input: makeInput(['Tab']) });
+  scene.step3DPhysics(0.02, { input: makeInput([]) });
+  const tabRenderer = createRendererProbe();
+  scene.render(tabRenderer);
+  const tabUiLayerTitle = findExactText(tabRenderer, 'UI Layer');
+  assertBottomRightFromTitle(tabUiLayerTitle, 326, 174, 624, 356, 'Sample 1710 should ignore Tab and keep UI Layer overlay');
+
+  pressCycleKey(scene);
+  pressCycleKey(scene);
+  pressCycleKey(scene);
+  const runtimeRenderer = createRendererProbe();
+  scene.render(runtimeRenderer);
+  const runtimeTitle = findExactText(runtimeRenderer, 'Mini-Game Runtime');
+  assertBottomRightFromTitle(runtimeTitle, 300, 120, 650, 410, 'Sample 1710 runtime overlay');
+}
+
 function assertSample1712TelemetryPlacement() {
   const scene = new GameplayMetricsTelemetryScene();
   scene.setCamera3D(createCameraStub());
@@ -174,6 +200,7 @@ export function run() {
   assertSample1701RuntimePanelPlacement();
   assertSample1704StackedPanelPlacement();
   assertSample1708CyclePlacement();
+  assertSample1710CyclePlacement();
   assertSample1712TelemetryPlacement();
   assertSample1713FinalRuntimePlacement();
 }
