Level 18.5 overlay configuration externalization.

DavidQ · DavidQ · commit 287a3e3071a3 · 2026-04-16T16:57:21.000-04:00
Move stack definitions to config-driven model.
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,9 +2,9 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Optimize overlay performance:
-- Minimize redundant render calls
-- Ensure efficient cycling transitions
-- Maintain current behavior
+Externalize overlay configuration:
+- Create config for overlay stacks per sample
+- Refactor runtime to consume config
+- Ensure no behavior change
 
 Package ZIP to <project folder>/tmp/
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Level 18.4 overlay performance optimization.
-Improve rendering efficiency and cycle responsiveness.
+Level 18.5 overlay configuration externalization.
+Move stack definitions to config-driven model.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,4 @@
-[ ] No lag during rapid cycling
-[ ] Stable FPS
-[ ] No redundant renders observed
+[ ] Config file defines stacks
+[ ] Runtime reads config
 [ ] Behavior unchanged
+[ ] Per-sample mapping preserved
diff --git a/docs/pr/BUILD_PR.md b/docs/pr/BUILD_PR.md
@@ -1,31 +1,30 @@
-# BUILD_PR_LEVEL_18_4_OVERLAY_PERFORMANCE_OPTIMIZATION
+# BUILD_PR_LEVEL_18_5_OVERLAY_CONFIGURATION_EXTERNALIZATION
 
 ## PLAN
 
 ### Purpose
-Optimize overlay rendering and cycling performance under frequent updates and rapid input.
+Externalize overlay stack definitions and configuration to remove hardcoded mappings and improve maintainability.
 
 ### Goals
-- Reduce unnecessary re-renders
-- Ensure smooth cycling under load
-- Maintain stable FPS
+- Move overlay stack definitions to config
+- Allow per-sample configuration
+- Reduce hardcoded logic
 
 ---
 
 ## BUILD
 
 ### Scope
-- Optimize overlay render paths
-- Avoid redundant DOM/canvas updates
-- Ensure efficient cycle transitions
-- No behavior changes
+- Define external config structure for overlay stacks
+- Refactor runtime to read from config
+- Preserve existing behavior exactly
+- No UI or feature changes
 
 ### Test Steps
-1. Rapidly cycle overlays
-2. Monitor frame stability
-3. Switch samples quickly
-4. Confirm no lag or stutter
+1. Load samples
+2. Verify overlays match previous stacks
+3. Modify config and confirm behavior updates
 
 ### Expected
-- Smooth overlay transitions
-- No visible performance degradation
+- Same behavior as before
+- Config-driven overlay stacks
diff --git a/samples/phase-17/1708/RealGameplayMiniGameScene.js b/samples/phase-17/1708/RealGameplayMiniGameScene.js
@@ -36,16 +36,16 @@ import {
   OVERLAY_MISSION_FEED,
   OVERLAY_MISSION_READY,
   OVERLAY_UI_LAYER,
-  createMiniGameOverlayCycleMap,
 } from '/samples/phase-17/shared/miniGameOverlayStack.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 
 const theme = new Theme(ThemeTokens);
 
 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';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1708');
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -93,9 +93,9 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.resetMatch({ toReady: true });
 
     this.tabDebugOverlays = createTabDebugOverlayController();
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
-    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
-    this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MINI_GAME_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
+    this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId);
   }
 
   addEvent(text) {
diff --git a/samples/phase-17/1709/MovementModelsLabScene.js b/samples/phase-17/1709/MovementModelsLabScene.js
@@ -16,11 +16,11 @@ import {
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
-  createMovementOverlayCycleMap,
   MOVEMENT_DEBUG_CYCLE_KEY,
   OVERLAY_MOVEMENT_HUD,
   OVERLAY_MOVEMENT_RUNTIME,
 } from '/samples/phase-17/shared/movementOverlayStack.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 import {
   applyPhase16CameraMode,
   createPhase16ViewState,
@@ -45,7 +45,7 @@ const MODE_ORDER = Object.freeze([
   MOVEMENT_MODES.TANK,
   MOVEMENT_MODES.WEIGHTED,
 ]);
-const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1709:overlay-index';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1709');
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -103,11 +103,11 @@ export default class MovementModelsLabScene extends Scene {
     this.lastInputSummary = '';
     this.lastSpeed = 0;
     this.tabDebugOverlays = createTabDebugOverlayController({
-      overlays: createMovementOverlayCycleMap(),
-      initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
+      overlays: DEBUG_OVERLAY_CONFIG.overlays,
+      initialOverlayId: DEBUG_OVERLAY_CONFIG.initialOverlayId || OVERLAY_MOVEMENT_RUNTIME,
     });
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MOVEMENT_DEBUG_CYCLE_KEY);
-    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MOVEMENT_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
   }
 
   setCamera3D(camera3D) {
diff --git a/samples/phase-17/1710/RealGameplayMiniGameScene.js b/samples/phase-17/1710/RealGameplayMiniGameScene.js
@@ -36,16 +36,16 @@ import {
   OVERLAY_MISSION_FEED,
   OVERLAY_MISSION_READY,
   OVERLAY_UI_LAYER,
-  createMiniGameOverlayCycleMap,
 } from '/samples/phase-17/shared/miniGameOverlayStack.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 
 const theme = new Theme(ThemeTokens);
 
 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';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1710');
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -93,9 +93,9 @@ export default class RealGameplayMiniGameScene extends Scene {
     this.resetMatch({ toReady: true });
 
     this.tabDebugOverlays = createTabDebugOverlayController();
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MINI_GAME_DEBUG_CYCLE_KEY);
-    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
-    this.setDebugOverlayCycleMap(createMiniGameOverlayCycleMap(), OVERLAY_UI_LAYER);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MINI_GAME_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
+    this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId);
   }
 
   addEvent(text) {
diff --git a/samples/phase-17/1711/MovementModelsLabScene.js b/samples/phase-17/1711/MovementModelsLabScene.js
@@ -16,11 +16,11 @@ import {
   stepTabDebugOverlayController,
 } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 import {
-  createMovementOverlayCycleMap,
   MOVEMENT_DEBUG_CYCLE_KEY,
   OVERLAY_MOVEMENT_HUD,
   OVERLAY_MOVEMENT_RUNTIME,
 } from '/samples/phase-17/shared/movementOverlayStack.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 import {
   applyPhase16CameraMode,
   createPhase16ViewState,
@@ -45,7 +45,7 @@ const MODE_ORDER = Object.freeze([
   MOVEMENT_MODES.TANK,
   MOVEMENT_MODES.WEIGHTED,
 ]);
-const DEBUG_OVERLAY_PERSISTENCE_KEY = 'phase17:1711:overlay-index';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1711');
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -103,11 +103,11 @@ export default class MovementModelsLabScene extends Scene {
     this.lastInputSummary = '';
     this.lastSpeed = 0;
     this.tabDebugOverlays = createTabDebugOverlayController({
-      overlays: createMovementOverlayCycleMap(),
-      initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
+      overlays: DEBUG_OVERLAY_CONFIG.overlays,
+      initialOverlayId: DEBUG_OVERLAY_CONFIG.initialOverlayId || OVERLAY_MOVEMENT_RUNTIME,
     });
-    setTabDebugOverlayCycleKey(this.tabDebugOverlays, MOVEMENT_DEBUG_CYCLE_KEY);
-    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_PERSISTENCE_KEY);
+    setTabDebugOverlayCycleKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.cycleKey || MOVEMENT_DEBUG_CYCLE_KEY);
+    setTabDebugOverlayPersistenceKey(this.tabDebugOverlays, DEBUG_OVERLAY_CONFIG.persistenceKey);
   }
 
   setCamera3D(camera3D) {
diff --git a/samples/phase-17/1712/GameplayMetricsTelemetryScene.js b/samples/phase-17/1712/GameplayMetricsTelemetryScene.js
@@ -6,12 +6,12 @@ GameplayMetricsTelemetryScene.js
 */
 import { createBottomRightDebugPanelStack, drawStackedDebugPanel } from '/src/engine/debug/index.js';
 import RealGameplayMiniGameScene from '/samples/phase-17/1708/RealGameplayMiniGameScene.js';
-import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 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';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1712');
 
 function pushSample(history, value, limit = 48) {
   history.push(Number.isFinite(value) ? Number(value) : 0);
@@ -57,14 +57,9 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
       fpsHistory: [],
       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' },
-      { id: OVERLAY_MISSION_READY, label: 'MISSION READY' },
-      { id: OVERLAY_TELEMETRY, label: 'Telemetry Overlay' },
-    ], OVERLAY_UI_LAYER);
+    this.setDebugOverlayCycleKey(DEBUG_OVERLAY_CONFIG.cycleKey);
+    this.setDebugOverlayPersistenceKey(DEBUG_OVERLAY_CONFIG.persistenceKey);
+    this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId || OVERLAY_UI_LAYER);
   }
 
   step3DPhysics(dtSeconds, engine) {
diff --git a/samples/phase-17/1713/FinalReferenceGameScene.js b/samples/phase-17/1713/FinalReferenceGameScene.js
@@ -6,12 +6,12 @@ FinalReferenceGameScene.js
 */
 import { createBottomRightDebugPanelStack, drawStackedDebugPanel } from '/src/engine/debug/index.js';
 import GameplayMetricsTelemetryScene from '/samples/phase-17/1712/GameplayMetricsTelemetryScene.js';
-import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
 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';
+const DEBUG_OVERLAY_CONFIG = getRequiredLevel17OverlayStackConfig('1713');
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -63,14 +63,9 @@ export default class FinalReferenceGameScene extends GameplayMetricsTelemetrySce
       completionBonus: 0,
       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' },
-      { id: OVERLAY_MISSION_READY, label: 'MISSION READY' },
-      { id: OVERLAY_FINAL_REFERENCE_RUNTIME, label: 'Final Reference Runtime' },
-    ], OVERLAY_UI_LAYER);
+    this.setDebugOverlayCycleKey(DEBUG_OVERLAY_CONFIG.cycleKey);
+    this.setDebugOverlayPersistenceKey(DEBUG_OVERLAY_CONFIG.persistenceKey);
+    this.setDebugOverlayCycleMap(DEBUG_OVERLAY_CONFIG.overlays, DEBUG_OVERLAY_CONFIG.initialOverlayId || OVERLAY_UI_LAYER);
   }
 
   step3DPhysics(dtSeconds, engine) {
diff --git a/samples/phase-17/shared/overlayStackBySampleConfig.js b/samples/phase-17/shared/overlayStackBySampleConfig.js
@@ -0,0 +1,76 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+overlayStackBySampleConfig.js
+*/
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+import {
+  OVERLAY_UI_LAYER,
+  createMiniGameOverlayCycleMap,
+} from '/samples/phase-17/shared/miniGameOverlayStack.js';
+import {
+  OVERLAY_MOVEMENT_RUNTIME,
+  createMovementOverlayCycleMap,
+} from '/samples/phase-17/shared/movementOverlayStack.js';
+
+const SAMPLE_OVERLAY_STACKS = Object.freeze({
+  '1708': Object.freeze({
+    overlays: Object.freeze(createMiniGameOverlayCycleMap()),
+    initialOverlayId: OVERLAY_UI_LAYER,
+    persistenceKey: 'phase17:1708:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+  '1709': Object.freeze({
+    overlays: Object.freeze(createMovementOverlayCycleMap()),
+    initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
+    persistenceKey: 'phase17:1709:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+  '1710': Object.freeze({
+    overlays: Object.freeze(createMiniGameOverlayCycleMap()),
+    initialOverlayId: OVERLAY_UI_LAYER,
+    persistenceKey: 'phase17:1710:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+  '1711': Object.freeze({
+    overlays: Object.freeze(createMovementOverlayCycleMap()),
+    initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
+    persistenceKey: 'phase17:1711:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+  '1712': Object.freeze({
+    overlays: Object.freeze([
+      { id: 'ui-layer', label: 'UI Layer' },
+      { id: 'mission-feed', label: 'Mission Feed' },
+      { id: 'mission-ready', label: 'MISSION READY' },
+      { id: 'telemetry', label: 'Telemetry Overlay' },
+    ]),
+    initialOverlayId: 'ui-layer',
+    persistenceKey: 'phase17:1712:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+  '1713': Object.freeze({
+    overlays: Object.freeze([
+      { id: 'ui-layer', label: 'UI Layer' },
+      { id: 'mission-feed', label: 'Mission Feed' },
+      { id: 'mission-ready', label: 'MISSION READY' },
+      { id: 'final-reference-runtime', label: 'Final Reference Runtime' },
+    ]),
+    initialOverlayId: 'ui-layer',
+    persistenceKey: 'phase17:1713:overlay-index',
+    cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+  }),
+});
+
+export function getLevel17OverlayStackConfig(sampleId) {
+  return SAMPLE_OVERLAY_STACKS[String(sampleId || '').trim()] ?? null;
+}
+
+export function getRequiredLevel17OverlayStackConfig(sampleId) {
+  const config = getLevel17OverlayStackConfig(sampleId);
+  if (config) {
+    return config;
+  }
+  throw new Error(`Missing overlay stack config for sample "${sampleId}".`);
+}
