Add overlay focus and input priority rules.

PR Details:
- Defines gameplay-first input priority
- Prevents overlay focus conflicts

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -2,14 +2,10 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Create BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS as the next smallest executable/testable PR.
+Implement overlay focus and input priority rules:
+- Gameplay input remains primary
+- Overlay controls scoped to explicit actions
+- No focus stealing
+- No Tab usage
 
-Requirements:
-- Add gameplay-safe interaction controls for overlays introduced by Level 19.2
-- Support show/hide and cycle behavior in gameplay runtime
-- Reuse the shared overlay/input mapping; do not reintroduce hardcoded Tab behavior
-- Preserve existing debug overlay behavior
-- Add or update focused tests proving overlay controls do not interfere with gameplay controls
-- Keep scope narrow and testable
-- Do not modify start_of_day folders
-- Package the repo-structured ZIP to <project folder>/tmp/BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS.zip
+Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,6 +1,5 @@
-Add gameplay-safe overlay interaction controls.
+Add overlay focus and input priority rules.
 
 PR Details:
-- Enables show/hide/cycle controls for gameplay overlays
-- Preserves shared non-Tab input mapping
-- Adds focused validation for non-interference with gameplay controls
+- Defines gameplay-first input priority
+- Prevents overlay focus conflicts

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -121,6 +121,9 @@ Commit Comment:
 - Preserve wording unless the PR explicitly requires rewriting.
 - Keep roadmap handling status-only unless explicitly requested otherwise.
 - Do not delete roadmap content during cleanup work.
+- Do not modify roadmap content during cleanup work.
+- Only update status [ ] [.] [x] in roadmap content during cleanup work.
+
 
 ## EXECUTION EFFICIENCY
 
@@ -132,4 +135,6 @@ Commit Comment:
   - Choose the correct path automatically
   - Reduce the number of options presented
   - Do the right thing and complete the task fully and correctly
+  - Don't ask if I want the next bundled PR, assume I want it.
+- Update Roadmap stutus every PR.
 

docs/dev/reports/BUILD_PR_LEVEL_19_4_OVERLAY_FOCUS_AND_INPUT_PRIORITY_report.md

@@ -0,0 +1,28 @@
+# BUILD_PR_LEVEL_19_4_OVERLAY_FOCUS_AND_INPUT_PRIORITY Report
+
+## Purpose
+Enforce gameplay-first input priority and explicit overlay runtime interaction controls with no focus stealing.
+
+## Scope Applied
+- Overlay runtime controls are now explicit-action only:
+  - show/hide: `Ctrl+G`
+  - runtime-cycle: `Ctrl+Shift+G`
+- Plain debug cycle input (`G` / `Shift+G`) remains unchanged for debug overlays.
+- Gameplay input remains primary; overlay runtime controls do not block movement/control flow.
+- No `Tab` usage introduced.
+
+## Files Changed
+- `samples/phase-17/shared/overlayCycleInput.js`
+- `samples/phase-17/shared/overlayGameplayRuntime.js`
+- `tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs`
+
+## Validation
+- `tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs` PASS
+- `tests/runtime/Phase17RealGameplaySample.test.mjs` PASS
+- `tests/runtime/Phase17Sample1712GameplayMetricsTelemetry.test.mjs` PASS
+- `tests/runtime/Phase17Sample1713FinalReferenceGame.test.mjs` PASS
+- `tests/runtime/Phase17TabDebugOverlayCycle1707Plus.test.mjs` PASS
+- `tests/runtime/Phase17DebugOverlayBottomRightPosition.test.mjs` PASS
+- `tests/runtime/Phase18RuntimeLayerScaffold.test.mjs` PASS
+- `tests/runtime/Phase18IntegrationFlowPass.test.mjs` PASS
+- `tests/runtime/Phase18CoreServicesSkeleton.test.mjs` PASS

docs/dev/reports/validation_checklist.txt

@@ -1,6 +1,4 @@
-[ ] Gameplay sample with overlays loads
-[ ] Overlay show/hide control works
-[ ] Overlay cycle control works
-[ ] Gameplay controls remain responsive while using overlay controls
-[ ] No Tab-based overlay interaction is introduced
-[ ] Debug overlay behavior remains unchanged
+[ ] Gameplay input unaffected
+[ ] Overlay controls work
+[ ] No focus conflicts
+[ ] No Tab usage

docs/pr/BUILD_PR.md

@@ -1,40 +1,19 @@
-# BUILD_PR_LEVEL_19_3_OVERLAY_INTERACTION_CONTROLS
+# BUILD_PR_LEVEL_19_4_OVERLAY_FOCUS_AND_INPUT_PRIORITY
 
 ## Purpose
-Add testable interaction controls for gameplay-safe overlays introduced in Level 19.2 so overlays can be shown, hidden, and cycled without interfering with gameplay input.
+Define and enforce focus + input priority rules so gameplay and overlays coexist without conflicts.
 
 ## Scope
-- Define gameplay-safe overlay interaction controls
-- Keep debug-overlay behavior intact
-- Ensure overlay interaction does not steal or block primary gameplay controls
-- Validate control behavior in at least one gameplay-active sample
-
-## Included
-- Interaction control contract for gameplay overlays
-- Runtime hookup for overlay show/hide/cycle actions in gameplay context
-- Tests covering non-interference with gameplay controls
-- Validation notes for control behavior
-
-## Excluded
-- New overlay types
-- Overlay visual redesign
-- Mission or telemetry feature expansion
-- Repo-wide input cleanup
-
-## Execution Notes
-- Use the shared input mapping established by prior overlay/input consolidation work
-- Preserve current non-Tab overlay cycle behavior
-- Keep scope to the smallest executable/testable change
-- Do not modify start_of_day folders
+- Establish input priority: gameplay > overlay (except explicit overlay controls)
+- Define focus model (no hard focus steal by overlays)
+- Ensure overlay controls are scoped and non-invasive
 
 ## Test Steps
-1. Load a gameplay-active sample with overlays enabled
-2. Trigger overlay show/hide control
-3. Trigger overlay cycle control
-4. Confirm gameplay movement/actions still work while overlay controls are used
-5. Confirm debug overlay behavior remains unchanged where applicable
+1. Run gameplay sample
+2. Trigger overlay controls
+3. Verify gameplay input remains primary
+4. Confirm overlay controls only act when invoked
 
-## Expected Result
-- Gameplay overlays can be interacted with safely
-- Overlay controls do not interfere with core gameplay input
-- Existing debug overlay behavior remains stable
+## Expected
+- No input conflicts
+- Predictable priority behavior

samples/phase-17/shared/overlayCycleInput.js

@@ -7,6 +7,7 @@ overlayCycleInput.js
 export const LEVEL17_OVERLAY_CYCLE_KEY = 'KeyG';
 export const LEVEL17_OVERLAY_REVERSE_MODIFIERS = Object.freeze(['ShiftLeft', 'ShiftRight']);
 export const LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS = Object.freeze(['ControlLeft', 'ControlRight']);
+export const LEVEL19_OVERLAY_RUNTIME_CYCLE_MODIFIERS = LEVEL17_OVERLAY_REVERSE_MODIFIERS;
 export const LEVEL17_OVERLAY_CYCLE_LABEL = 'G/Shift+G';
 
 export function isOverlayCycleReverseModifierActive(input) {
@@ -37,3 +38,20 @@ export function isOverlayRuntimeToggleModifierActive(input) {
 export function getOverlayRuntimeToggleInputCodes() {
   return [LEVEL17_OVERLAY_CYCLE_KEY, LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS[0]];
 }
+
+export function isOverlayRuntimeCycleModifierActive(input) {
+  for (let i = 0; i < LEVEL19_OVERLAY_RUNTIME_CYCLE_MODIFIERS.length; i += 1) {
+    if (input?.isDown(LEVEL19_OVERLAY_RUNTIME_CYCLE_MODIFIERS[i]) === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function getOverlayRuntimeCycleInputCodes() {
+  return [
+    LEVEL17_OVERLAY_CYCLE_KEY,
+    LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS[0],
+    LEVEL19_OVERLAY_RUNTIME_CYCLE_MODIFIERS[0],
+  ];
+}

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -5,7 +5,7 @@ David Quesenberry
 overlayGameplayRuntime.js
 */
 import {
-  isOverlayCycleReverseModifierActive,
+  isOverlayRuntimeCycleModifierActive,
   isOverlayRuntimeToggleModifierActive,
   LEVEL17_OVERLAY_CYCLE_KEY,
 } from '/samples/phase-17/shared/overlayCycleInput.js';
@@ -123,11 +123,15 @@ export function stepOverlayGameplayRuntimeControls(runtime, input) {
   const cycleKey = String(runtime.interactionCycleKey || LEVEL17_OVERLAY_CYCLE_KEY);
   const cyclePressed = input?.isDown(cycleKey) === true;
   const toggleModifierActive = isOverlayRuntimeToggleModifierActive(input);
-  const togglePressed = cyclePressed && toggleModifierActive;
-  const reverseActive = isOverlayCycleReverseModifierActive(input);
+  const cycleModifierActive = isOverlayRuntimeCycleModifierActive(input);
+  const explicitActionPressed = cyclePressed && toggleModifierActive;
+  const togglePressed = explicitActionPressed && !cycleModifierActive;
+  const runtimeCyclePressed = explicitActionPressed && cycleModifierActive;
 
-  if (!togglePressed) {
+  if (!explicitActionPressed) {
     runtime.interactionToggleLatch = false;
+    runtime.interactionCycleLatch = false;
+    return false;
   }
 
   if (togglePressed && runtime.interactionToggleLatch === false) {
@@ -137,8 +141,10 @@ export function stepOverlayGameplayRuntimeControls(runtime, input) {
     return true;
   }
 
-  if (!cyclePressed || toggleModifierActive) {
-    runtime.interactionCycleLatch = false;
+  if (!runtimeCyclePressed) {
+    if (!togglePressed) {
+      runtime.interactionCycleLatch = false;
+    }
     return false;
   }
 
@@ -153,8 +159,7 @@ export function stepOverlayGameplayRuntimeControls(runtime, input) {
 
   normalizeInteractionIndex(runtime);
   const count = runtime.runtimeExtensions.length;
-  const delta = reverseActive ? -1 : 1;
-  runtime.interactionIndex = (runtime.interactionIndex + delta + count) % count;
+  runtime.interactionIndex = (runtime.interactionIndex + 1 + count) % count;
   return true;
 }
 

tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs

@@ -8,6 +8,7 @@ import assert from 'node:assert/strict';
 import RealGameplayMiniGameScene from '../../samples/phase-17/1708/RealGameplayMiniGameScene.js';
 import {
   getOverlayCycleInputCodes,
+  getOverlayRuntimeCycleInputCodes,
   getOverlayRuntimeToggleInputCodes,
 } from '../../samples/phase-17/shared/overlayCycleInput.js';
 import { resetTabDebugOverlayPersistenceForTests } from '../../samples/phase-17/shared/tabDebugOverlayCycle.js';
@@ -71,7 +72,15 @@ function pressOverlayRuntimeToggle(scene) {
   scene.step3DPhysics(0.02, { input: makeInput([]) });
 }
 
+function pressOverlayRuntimeCycle(scene) {
+  scene.step3DPhysics(0.02, { input: makeInput(getOverlayRuntimeCycleInputCodes()) });
+  scene.step3DPhysics(0.02, { input: makeInput([]) });
+}
+
 function assertGameplayOverlayRuntimeHooksAreNonBlocking() {
+  assert.equal(getOverlayRuntimeToggleInputCodes().includes('Tab'), false, 'Runtime overlay toggle mapping must not use Tab.');
+  assert.equal(getOverlayRuntimeCycleInputCodes().includes('Tab'), false, 'Runtime overlay cycle mapping must not use Tab.');
+
   const scene = new RealGameplayMiniGameScene();
   scene.setCamera3D(createCameraStub());
 
@@ -123,7 +132,11 @@ function assertGameplayOverlayRuntimeHooksAreNonBlocking() {
   scene.render(missionFeedRenderer);
   assert.equal(missionFeedRenderer.texts.some((text) => text.includes('Mission Feed')), true, 'Debug overlay cycle behavior should remain unchanged.');
   scene.step3DPhysics(0.05, { input: makeInput([]) });
-  assert.equal(counters.bStep > beforeCycleBStep, true, 'Gameplay overlay runtime cycle control should switch active runtime extension.');
+  assert.equal(counters.bStep, beforeCycleBStep, 'Plain debug overlay cycle should not switch gameplay runtime overlay extension.');
+
+  pressOverlayRuntimeCycle(scene);
+  scene.step3DPhysics(0.05, { input: makeInput([]) });
+  assert.equal(counters.bStep > beforeCycleBStep, true, 'Explicit runtime overlay cycle control should switch active runtime extension.');
 
   const beforeHideStep = counters.aStep + counters.bStep;
   pressOverlayRuntimeToggle(scene);
@@ -134,6 +147,10 @@ function assertGameplayOverlayRuntimeHooksAreNonBlocking() {
   scene.step3DPhysics(0.05, { input: makeInput([]) });
   assert.equal(counters.aStep + counters.bStep > beforeHideStep, true, 'Runtime overlay toggle should restore runtime overlay execution.');
 
+  const beforeMoveWithRuntimeControl = scene.player.x;
+  scene.step3DPhysics(0.2, { input: makeInput(['KeyD', ...getOverlayRuntimeCycleInputCodes()]) });
+  assert.equal(scene.player.x > beforeMoveWithRuntimeControl, true, 'Gameplay movement input should remain primary during explicit runtime overlay control actions.');
+
   scene.setOverlayGameplayRuntimeExtensions([
     {
       overlayId: 'mission-feed',