Level 18.1 overlay runtime hardening.

Improve stability for input, resize, and sample switching.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,9 +1,11 @@
-MODEL: GPT-5.3-codex
-REASONING: low
+MODEL: GPT-5.4-codex
+REASONING: medium
+
 COMMAND:
-Promote Level 17 overlay system to baseline.
-- Confirm no regressions
-- Update status markers only
-- Do not modify runtime behavior
+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
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1,2 @@
-Promote Level 17 debug overlay system to baseline after validation.
+Level 18.1 overlay runtime hardening.
+Improve stability for input, resize, and sample switching.

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,4 @@
-[x] Smoke test complete
-[x] No regressions found
-[x] Baseline confirmed
+[ ] Rapid cycle stable
+[ ] No flicker on sample switch
+[ ] Resize keeps bottom-right anchor
+[ ] No stack reorder issues

docs/pr/BUILD_PR.md

@@ -1,20 +1,33 @@
-# BUILD_PR_LEVEL_17_59_DEBUG_OVERLAY_PROMOTE_BASELINE
-
-## Purpose
-Promote Level 17 debug overlay system to baseline after successful validation sweep.
-
-## Scope
-- Mark Level 17 as complete
-- Confirm overlay system baseline:
-  - Bottom-right placement
-  - Non-Tab cycle key
-  - Sample-specific stack mappings
-
-## Test Steps
-1. Run smoke test across samples
-2. Confirm no regressions
-3. Validate baseline readiness
-
-## Expected
-- Stable baseline
-- Ready for next level integration
+# BUILD_PR_LEVEL_18_1_OVERLAY_RUNTIME_HARDENING
+
+## PLAN
+
+### Purpose
+Harden overlay runtime behavior after Level 17 baseline promotion to ensure stability under rapid input, resizing, and multi-sample switching.
+
+### 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
+
+---
+
+## BUILD
+
+### Scope
+- Overlay runtime stabilization (no feature expansion)
+- Input debounce/throttle validation
+- Resize handling validation
+- Sample switching consistency
+
+### Test Steps
+1. Rapidly cycle overlays
+2. Switch between samples quickly
+3. Resize viewport
+4. Validate overlays remain stable and anchored
+
+### Expected
+- No flicker
+- No misalignment
+- No cycle skips

samples/phase-17/shared/tabDebugOverlayCycle.js

@@ -17,6 +17,21 @@ 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) {
+      controller.activeIndex = 0;
+    }
+    return 0;
+  }
+
+  const count = controller.overlays.length;
+  const current = Number.isInteger(controller.activeIndex) ? controller.activeIndex : 0;
+  const normalized = ((current % count) + count) % count;
+  controller.activeIndex = normalized;
+  return normalized;
+}
+
 export function createTabDebugOverlayController({ overlays = [], initialOverlayId = '' } = {}) {
   const normalized = [];
   for (let i = 0; i < overlays.length; i += 1) {
@@ -40,7 +55,7 @@ export function createTabDebugOverlayController({ overlays = [], initialOverlayI
 
   return {
     overlays: normalized,
-    activeIndex,
+    activeIndex: normalized.length > 0 ? Math.max(0, Math.min(activeIndex, normalized.length - 1)) : 0,
     cycleKey: 'Tab',
     cycleLatch: false,
   };
@@ -71,6 +86,7 @@ export function setTabDebugOverlayMap(controller, { overlays = [], initialOverla
       controller.activeIndex = lookupIndex;
     }
   }
+  normalizeActiveIndex(controller);
   controller.cycleLatch = false;
   return true;
 }
@@ -115,6 +131,7 @@ export function setTabDebugOverlayActive(controller, overlayId) {
     return false;
   }
   controller.activeIndex = nextIndex;
+  normalizeActiveIndex(controller);
   return true;
 }
 
@@ -125,6 +142,7 @@ export function stepTabDebugOverlayController(controller, input) {
 
   const cycleKey = String(controller.cycleKey || 'Tab');
   const cyclePressed = input?.isDown(cycleKey) === true;
+  normalizeActiveIndex(controller);
   if (cyclePressed && controller.cycleLatch === false && controller.overlays.length > 1) {
     const delta = hasShiftModifier(input) ? -1 : 1;
     const count = controller.overlays.length;
@@ -137,6 +155,7 @@ export function isTabDebugOverlayActive(controller, overlayId) {
   if (!controller || !Array.isArray(controller.overlays) || controller.overlays.length === 0) {
     return false;
   }
+  normalizeActiveIndex(controller);
   const active = controller.overlays[controller.activeIndex];
   return active?.id === overlayId;
 }
@@ -145,7 +164,7 @@ export function getTabDebugOverlayStatusLabel(controller) {
   if (!controller || !Array.isArray(controller.overlays) || controller.overlays.length === 0) {
     return 'none';
   }
-  const index = Math.max(0, Math.min(controller.activeIndex, controller.overlays.length - 1));
+  const index = normalizeActiveIndex(controller);
   const active = controller.overlays[index];
   return `${active.label} (${index + 1}/${controller.overlays.length})`;
 }

src/engine/debug/DebugOverlayLayout.js

@@ -10,17 +10,38 @@ function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
 
+function readCanvasSize(renderer) {
+  const canvasSize = renderer?.getCanvasSize?.() || { width: 960, height: 540 };
+  return {
+    width: Math.max(1, Number(canvasSize.width) || 960),
+    height: Math.max(1, Number(canvasSize.height) || 540),
+  };
+}
+
+function syncStackCanvasSize(stack) {
+  if (!stack) {
+    return;
+  }
+  const canvas = readCanvasSize(stack.renderer);
+  stack.canvasWidth = canvas.width;
+  stack.canvasHeight = canvas.height;
+  if (!Number.isFinite(stack.usedHeight) || stack.usedHeight < 0) {
+    stack.usedHeight = 0;
+  }
+}
+
 export function createBottomRightDebugPanelStack(renderer, {
   right = 10,
   bottom = 10,
   spacing = 10,
   minX = 8,
   minY = 8,
 } = {}) {
-  const canvasSize = renderer?.getCanvasSize?.() || { width: 960, height: 540 };
+  const canvas = readCanvasSize(renderer);
   return {
-    canvasWidth: Math.max(1, Number(canvasSize.width) || 960),
-    canvasHeight: Math.max(1, Number(canvasSize.height) || 540),
+    renderer,
+    canvasWidth: canvas.width,
+    canvasHeight: canvas.height,
     right: Math.max(0, Number(right) || 0),
     bottom: Math.max(0, Number(bottom) || 0),
     spacing: Math.max(0, Number(spacing) || 0),
@@ -40,6 +61,7 @@ export function getNextBottomRightDebugPanelRect(stack, width, height) {
     };
   }
 
+  syncStackCanvasSize(stack);
   const panelWidth = Math.max(1, Number(width) || 1);
   const panelHeight = Math.max(1, Number(height) || 1);
   const x = clamp(

tests/runtime/Phase17DebugOverlayBottomRightPosition.test.mjs

@@ -54,11 +54,17 @@ function pressCycleKey(scene) {
 }
 
 function createRendererProbe(width = 960, height = 540) {
+  let canvasWidth = width;
+  let canvasHeight = height;
   const texts = [];
   return {
     texts,
     getCanvasSize() {
-      return { width, height };
+      return { width: canvasWidth, height: canvasHeight };
+    },
+    setCanvasSize(nextWidth, nextHeight) {
+      canvasWidth = Math.max(1, Number(nextWidth) || canvasWidth);
+      canvasHeight = Math.max(1, Number(nextHeight) || canvasHeight);
     },
     clear() {},
     drawRect() {},
@@ -94,8 +100,11 @@ function assertSharedStackMath() {
   const stack = createBottomRightDebugPanelStack(renderer, { right: 10, bottom: 10, spacing: 10 });
   const first = getNextBottomRightDebugPanelRect(stack, 300, 170);
   const second = getNextBottomRightDebugPanelRect(stack, 300, 120);
+  renderer.setCanvasSize(1280, 720);
+  const resized = getNextBottomRightDebugPanelRect(stack, 300, 170);
   assert.deepEqual(first, { x: 650, y: 360, width: 300, height: 170 });
   assert.deepEqual(second, { x: 650, y: 230, width: 300, height: 120 });
+  assert.deepEqual(resized, { x: 970, y: 230, width: 300, height: 170 });
 }
 
 function assertSample1701RuntimePanelPlacement() {
@@ -215,6 +224,39 @@ function assertSample1713FinalRuntimePlacement() {
   assertBottomRightFromTitle(runtimeTitle, 228, 248, 722, 282, 'Sample 1713 final runtime overlay');
 }
 
+function assertNoFlickerDuringSampleSwitching() {
+  const scenes = [
+    [new RealGameplayMiniGameScene(), 'UI Layer'],
+    [new MovementModelsLab1709Scene(), 'Movement Runtime'],
+    [new RealGameplayMiniGame1710Scene(), 'UI Layer'],
+    [new MovementModelsLab1711Scene(), 'Movement Runtime'],
+    [new GameplayMetricsTelemetryScene(), 'UI Layer'],
+    [new FinalReferenceGameScene(), 'UI Layer'],
+  ];
+  const overlayTitles = [
+    'UI Layer',
+    'Mission Feed',
+    'MISSION READY',
+    'Mini-Game Runtime',
+    'Movement Runtime',
+    'Movement Lab HUD',
+    'Telemetry Overlay',
+    'Final Reference Runtime',
+  ];
+  const sharedCamera = createCameraStub();
+  for (let i = 0; i < scenes.length; i += 1) {
+    const [scene, expectedTitle] = scenes[i];
+    scene.setCamera3D?.(sharedCamera);
+    for (let pass = 0; pass < 2; pass += 1) {
+      const renderer = createRendererProbe();
+      scene.render(renderer);
+      const visibleOverlays = overlayTitles.filter((title) => Boolean(findExactText(renderer, title)));
+      assert.equal(visibleOverlays.length, 1, `Sample switch pass ${i + 1}.${pass + 1} should render exactly one active overlay panel title.`);
+      assert.equal(visibleOverlays[0], expectedTitle, `Sample switch pass ${i + 1}.${pass + 1} should render expected default overlay without flicker.`);
+    }
+  }
+}
+
 export function run() {
   assertSharedStackMath();
   assertSample1701RuntimePanelPlacement();
@@ -225,4 +267,5 @@ export function run() {
   assertSample1711MovementOverlayPlacement();
   assertSample1712TelemetryPlacement();
   assertSample1713FinalRuntimePlacement();
+  assertNoFlickerDuringSampleSwitching();
 }

tests/runtime/Phase17TabDebugOverlayCycle1707Plus.test.mjs

@@ -48,6 +48,14 @@ function pressCycleKey(scene, { reverse = false } = {}) {
   scene.step3DPhysics(0.02, { input: makeInput([]) });
 }
 
+function holdCycleKey(scene, { reverse = false, frames = 4 } = {}) {
+  const keys = reverse ? ['KeyG', 'ShiftLeft'] : ['KeyG'];
+  for (let i = 0; i < Math.max(1, frames); i += 1) {
+    scene.step3DPhysics(0.01, { input: makeInput(keys) });
+  }
+  scene.step3DPhysics(0.01, { input: makeInput([]) });
+}
+
 function createRendererProbe(width = 960, height = 540) {
   const texts = [];
   return {
@@ -77,6 +85,25 @@ function assertMapOrderAndKeyBehavior(label, sceneFactory, expectedLabels, expec
   const labels = scene.tabDebugOverlays.overlays.map((entry) => entry.label);
   assert.deepEqual(labels, expectedLabels, `${label} should use exact required overlay map ordering.`);
 
+  if (scene.tabDebugOverlays.overlays.length > 1) {
+    const count = scene.tabDebugOverlays.overlays.length;
+    const beforeHoldForward = scene.tabDebugOverlays.activeIndex;
+    holdCycleKey(scene);
+    assert.equal(
+      scene.tabDebugOverlays.activeIndex,
+      (beforeHoldForward + 1) % count,
+      `${label} should cycle exactly once while cycle key is held across rapid frames.`
+    );
+
+    const beforeHoldReverse = scene.tabDebugOverlays.activeIndex;
+    holdCycleKey(scene, { reverse: true });
+    assert.equal(
+      scene.tabDebugOverlays.activeIndex,
+      (beforeHoldReverse - 1 + count) % count,
+      `${label} should cycle exactly once in reverse while reverse cycle key is held across rapid frames.`
+    );
+  }
+
   for (let i = 0; i < expectedTokens.length; i += 1) {
     const renderer = createRendererProbe();
     scene.render(renderer);