Level 18.2 input system consolidation.

Unify runtime and test input mappings for overlay cycle key.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Implement runtime hardening for overlay system:
-- Ensure stable cycling under rapid input
-- Validate bottom-right anchoring under resize
-- Prevent flicker during sample switching
-- Do not change feature behavior
+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
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Level 18.1 overlay runtime hardening.
-Improve stability for input, resize, and sample switching.
+Level 18.2 input system consolidation.
+Unify runtime and test input mappings for overlay cycle key.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Rapid cycle stable
-[ ] No flicker on sample switch
-[ ] Resize keeps bottom-right anchor
-[ ] No stack reorder issues
+[ ] Runtime uses shared input mapping
+[ ] Tests use shared mapping
+[ ] No hardcoded keys remain
+[ ] Cycle behavior unchanged

docs/pr/BUILD_PR.md

@@ -1,33 +1,30 @@
-# BUILD_PR_LEVEL_18_1_OVERLAY_RUNTIME_HARDENING
+# BUILD_PR_LEVEL_18_2_INPUT_SYSTEM_CONSOLIDATION
 
 ## PLAN
 
 ### Purpose
-Harden overlay runtime behavior after Level 17 baseline promotion to ensure stability under rapid input, resizing, and multi-sample switching.
+Consolidate input handling for overlay cycling and test inputs to ensure a single authoritative key mapping across runtime and tests.
 
 ### Goals
-- Ensure cycle key stability under rapid input
-- Prevent overlay flicker during sample switching
-- Lock bottom-right anchoring under resize
-- Validate overlay layering does not reorder unexpectedly
+- Eliminate duplicate key mappings
+- Ensure tests and runtime use same input source
+- Prevent future drift (like Tab issue)
 
 ---
 
 ## BUILD
 
 ### Scope
-- Overlay runtime stabilization (no feature expansion)
-- Input debounce/throttle validation
-- Resize handling validation
-- Sample switching consistency
+- Centralize overlay cycle key definition
+- Update runtime references to use shared source
+- Update tests to reference shared input mapping
+- No behavior change
 
 ### Test Steps
-1. Rapidly cycle overlays
-2. Switch between samples quickly
-3. Resize viewport
-4. Validate overlays remain stable and anchored
+1. Verify cycle key works in runtime
+2. Verify tests use shared mapping
+3. Confirm no hardcoded keys remain
 
 ### Expected
-- No flicker
-- No misalignment
-- No cycle skips
+- Single source of truth for cycle key
+- No drift between runtime and tests

samples/phase-17/1712/GameplayMetricsTelemetryScene.js

@@ -6,11 +6,11 @@ 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';
 const OVERLAY_UI_LAYER = 'ui-layer';
 const OVERLAY_MISSION_FEED = 'mission-feed';
 const OVERLAY_MISSION_READY = 'mission-ready';
 const OVERLAY_TELEMETRY = 'telemetry';
-const DEBUG_CYCLE_KEY = 'KeyG';
 
 function pushSample(history, value, limit = 48) {
   history.push(Number.isFinite(value) ? Number(value) : 0);
@@ -56,7 +56,7 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
       fpsHistory: [],
       collisionHistory: [],
     };
-    this.setDebugOverlayCycleKey(DEBUG_CYCLE_KEY);
+    this.setDebugOverlayCycleKey(LEVEL17_OVERLAY_CYCLE_KEY);
     this.setDebugOverlayCycleMap([
       { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
       { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },

samples/phase-17/1713/FinalReferenceGameScene.js

@@ -6,11 +6,11 @@ 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';
 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_CYCLE_KEY = 'KeyG';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -62,7 +62,7 @@ export default class FinalReferenceGameScene extends GameplayMetricsTelemetrySce
       completionBonus: 0,
       phase: 'briefing',
     };
-    this.setDebugOverlayCycleKey(DEBUG_CYCLE_KEY);
+    this.setDebugOverlayCycleKey(LEVEL17_OVERLAY_CYCLE_KEY);
     this.setDebugOverlayCycleMap([
       { id: OVERLAY_UI_LAYER, label: 'UI Layer' },
       { id: OVERLAY_MISSION_FEED, label: 'Mission Feed' },

samples/phase-17/shared/miniGameOverlayStack.js

@@ -4,7 +4,9 @@ David Quesenberry
 04/16/2026
 miniGameOverlayStack.js
 */
-export const MINI_GAME_DEBUG_CYCLE_KEY = 'KeyG';
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+
+export const MINI_GAME_DEBUG_CYCLE_KEY = LEVEL17_OVERLAY_CYCLE_KEY;
 export const OVERLAY_UI_LAYER = 'ui-layer';
 export const OVERLAY_MISSION_FEED = 'mission-feed';
 export const OVERLAY_MISSION_READY = 'mission-ready';

samples/phase-17/shared/movementOverlayStack.js

@@ -4,7 +4,9 @@ David Quesenberry
 04/16/2026
 movementOverlayStack.js
 */
-export const MOVEMENT_DEBUG_CYCLE_KEY = 'KeyG';
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+
+export const MOVEMENT_DEBUG_CYCLE_KEY = LEVEL17_OVERLAY_CYCLE_KEY;
 export const OVERLAY_MOVEMENT_RUNTIME = 'movement-runtime';
 export const OVERLAY_MOVEMENT_HUD = 'movement-lab-hud';
 

samples/phase-17/shared/overlayCycleInput.js

@@ -0,0 +1,25 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+overlayCycleInput.js
+*/
+export const LEVEL17_OVERLAY_CYCLE_KEY = 'KeyG';
+export const LEVEL17_OVERLAY_REVERSE_MODIFIERS = Object.freeze(['ShiftLeft', 'ShiftRight']);
+export const LEVEL17_OVERLAY_CYCLE_LABEL = 'G/Shift+G';
+
+export function isOverlayCycleReverseModifierActive(input) {
+  for (let i = 0; i < LEVEL17_OVERLAY_REVERSE_MODIFIERS.length; i += 1) {
+    if (input?.isDown(LEVEL17_OVERLAY_REVERSE_MODIFIERS[i]) === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function getOverlayCycleInputCodes({ reverse = false } = {}) {
+  if (!reverse) {
+    return [LEVEL17_OVERLAY_CYCLE_KEY];
+  }
+  return [LEVEL17_OVERLAY_CYCLE_KEY, LEVEL17_OVERLAY_REVERSE_MODIFIERS[0]];
+}

samples/phase-17/shared/tabDebugOverlayCycle.js

@@ -4,6 +4,8 @@ David Quesenberry
 04/16/2026
 tabDebugOverlayCycle.js
 */
+import { isOverlayCycleReverseModifierActive } from '/samples/phase-17/shared/overlayCycleInput.js';
+
 function normalizeOverlayEntry(entry) {
   const id = String(entry?.id ?? '').trim();
   if (!id) {
@@ -13,10 +15,6 @@ function normalizeOverlayEntry(entry) {
   return { id, label };
 }
 
-function hasShiftModifier(input) {
-  return input?.isDown('ShiftLeft') === true || input?.isDown('ShiftRight') === true;
-}
-
 function normalizeActiveIndex(controller) {
   if (!controller || !Array.isArray(controller.overlays) || controller.overlays.length === 0) {
     if (controller) {
@@ -144,7 +142,7 @@ export function stepTabDebugOverlayController(controller, input) {
   const cyclePressed = input?.isDown(cycleKey) === true;
   normalizeActiveIndex(controller);
   if (cyclePressed && controller.cycleLatch === false && controller.overlays.length > 1) {
-    const delta = hasShiftModifier(input) ? -1 : 1;
+    const delta = isOverlayCycleReverseModifierActive(input) ? -1 : 1;
     const count = controller.overlays.length;
     controller.activeIndex = (controller.activeIndex + delta + count) % count;
   }