Level 18.3 overlay state persistence.

Preserve selected overlay across reloads and navigation.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Consolidate input system for overlay cycling:
-- Introduce shared cycle key definition
-- Refactor runtime to use shared input mapping
-- Refactor tests to use shared mapping (remove hardcoded keys)
-- Do not change behavior
+Implement overlay state persistence:
+- Store current overlay index
+- Restore on sample load
+- Keep implementation lightweight
+- Do not change cycle behavior
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Level 18.2 input system consolidation.
-Unify runtime and test input mappings for overlay cycle key.
+Level 18.3 overlay state persistence.
+Preserve selected overlay across reloads and navigation.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Runtime uses shared input mapping
-[ ] Tests use shared mapping
-[ ] No hardcoded keys remain
-[ ] Cycle behavior unchanged
+[ ] Overlay index persists
+[ ] Restored on reload
+[ ] Works across samples
+[ ] No cycle regression

docs/pr/BUILD_PR.md

@@ -1,30 +1,31 @@
-# BUILD_PR_LEVEL_18_2_INPUT_SYSTEM_CONSOLIDATION
+# BUILD_PR_LEVEL_18_3_OVERLAY_STATE_PERSISTENCE
 
 ## PLAN
 
 ### Purpose
-Consolidate input handling for overlay cycling and test inputs to ensure a single authoritative key mapping across runtime and tests.
+Introduce overlay state persistence so selected overlay and cycle position are maintained across sample reloads and navigation.
 
 ### Goals
-- Eliminate duplicate key mappings
-- Ensure tests and runtime use same input source
-- Prevent future drift (like Tab issue)
+- Persist current overlay index
+- Restore state on reload
+- Maintain consistency across samples
 
 ---
 
 ## BUILD
 
 ### Scope
-- Centralize overlay cycle key definition
-- Update runtime references to use shared source
-- Update tests to reference shared input mapping
-- No behavior change
+- Store overlay state (in-memory or lightweight persistence)
+- Restore on sample load
+- No UI changes
+- No behavior change to cycle logic
 
 ### Test Steps
-1. Verify cycle key works in runtime
-2. Verify tests use shared mapping
-3. Confirm no hardcoded keys remain
+1. Select overlay
+2. Reload sample
+3. Confirm overlay restored
+4. Switch samples and return
 
 ### Expected
-- Single source of truth for cycle key
-- No drift between runtime and tests
+- Overlay state preserved
+- No regression in cycling

samples/phase-17/1708/RealGameplayMiniGameScene.js

@@ -26,6 +26,7 @@ import {
   isTabDebugOverlayActive,
   setTabDebugOverlayCycleKey,
   setTabDebugOverlayMap,
+  setTabDebugOverlayPersistenceKey,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
@@ -43,6 +44,7 @@ const READY_STATE = 'ready';
 const RUNNING_STATE = 'running';
 const WON_STATE = 'won';
 const LOST_STATE = 'lost';
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1708:overlay-index';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -91,6 +93,7 @@ export default class RealGameplayMiniGameScene extends Scene {
 
     this.tabDebugOverlays = createTabDebugOverlayController();
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
     this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
   }
 
@@ -183,6 +186,10 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, cycleKey);
   }
 
+  setDebugOverlayPersistenceKey(persistenceKey) {
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, persistenceKey);
+  }
+
   isDebugOverlayActive(overlayId) {
     return isTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
   }

samples/phase-17/1709/MovementModelsLabScene.js

@@ -12,6 +12,7 @@ import {
   getTabDebugOverlayStatusLabel,
   isTabDebugOverlayActive,
   setTabDebugOverlayCycleKey,
+  setTabDebugOverlayPersistenceKey,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
@@ -44,6 +45,7 @@ const MODE_ORDER = Object.freeze([
   MOVEMENT_MODES.TANK,
   MOVEMENT_MODES.WEIGHTED,
 ]);
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1709:overlay-index';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -105,6 +107,7 @@ export default class MovementModelsLabScene extends Scene {
       initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
     });
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, MOVEMENT_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
   }
 
   setCamera3D(camera3D) {

samples/phase-17/1710/RealGameplayMiniGameScene.js

@@ -26,6 +26,7 @@ import {
   isTabDebugOverlayActive,
   setTabDebugOverlayCycleKey,
   setTabDebugOverlayMap,
+  setTabDebugOverlayPersistenceKey,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
@@ -43,6 +44,7 @@ const READY_STATE = 'ready';
 const RUNNING_STATE = 'running';
 const WON_STATE = 'won';
 const LOST_STATE = 'lost';
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1710:overlay-index';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -91,6 +93,7 @@ export default class RealGameplayMiniGameScene extends Scene {
 
     this.tabDebugOverlays = createTabDebugOverlayController();
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
     this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
   }
 
@@ -183,6 +186,10 @@ export default class RealGameplayMiniGameScene extends Scene {
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, cycleKey);
   }
 
+  setDebugOverlayPersistenceKey(persistenceKey) {
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, persistenceKey);
+  }
+
   isDebugOverlayActive(overlayId) {
     return isTabDebugOverlayActive(this.tabDebugOverlays, overlayId);
   }

samples/phase-17/1711/MovementModelsLabScene.js

@@ -12,6 +12,7 @@ import {
   getTabDebugOverlayStatusLabel,
   isTabDebugOverlayActive,
   setTabDebugOverlayCycleKey,
+  setTabDebugOverlayPersistenceKey,
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
@@ -44,6 +45,7 @@ const MODE_ORDER = Object.freeze([
   MOVEMENT_MODES.TANK,
   MOVEMENT_MODES.WEIGHTED,
 ]);
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1711:overlay-index';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -105,6 +107,7 @@ export default class MovementModelsLabScene extends Scene {
       initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
     });
     setTabDebugOverlayCycleKey(this.tabDebugOverlays, MOVEMENT_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
   }
 
   setCamera3D(camera3D) {

samples/phase-17/1712/GameplayMetricsTelemetryScene.js

@@ -11,6 +11,7 @@ const OVERLAY_UI_LAYER = 'ui-layer';
 const OVERLAY_MISSION_FEED = 'mission-feed';
 const OVERLAY_MISSION_READY = 'mission-ready';
 const OVERLAY_TELEMETRY = 'telemetry';
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1712:overlay-index';
 
 function pushSample(history, value, limit = 48) {
   history.push(Number.isFinite(value) ? Number(value) : 0);
@@ -57,6 +58,7 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
       collisionHistory: [],
     };
     this.setDebugOverlayCycleKey(LEVEL17_OVERLAY_CYCLE_KEY);
+    this.setDebugOverlayPersistenceKey(DEBUG_OVERLAY_PERSISTENCE_KEY);
     this.setDebugOverlayCycleMap([
       { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
       { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },

samples/phase-17/1713/FinalReferenceGameScene.js

@@ -11,6 +11,7 @@ const OVERLAY_UI_LAYER = 'ui-layer';
 const OVERLAY_MISSION_FEED = 'mission-feed';
 const OVERLAY_MISSION_READY = 'mission-ready';
 const OVERLAY_FINAL_REFERENCE_RUNTIME = 'final-reference-runtime';
+const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1713:overlay-index';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -63,6 +64,7 @@ export default class FinalReferenceGameScene extends GameplayMetricsTelemetrySce
       phase: 'briefing',
     };
     this.setDebugOverlayCycleKey(LEVEL17_OVERLAY_CYCLE_KEY);
+    this.setDebugOverlayPersistenceKey(DEBUG_OVERLAY_PERSISTENCE_KEY);
     this.setDebugOverlayCycleMap([
       { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
       { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },