Level 18.6 overlay diagnostics and debug tooling.

Add visibility into overlay state and cycle behavior.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,10 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Externalize overlay configuration:
-- Create config for overlay stacks per sample
-- Refactor runtime to consume config
-- Ensure no behavior change
+Add overlay diagnostics tooling:
+- Log overlay index and stack state
+- Add optional debug toggle
+- Ensure zero impact when disabled
+- Do not change overlay behavior
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Level 18.5 overlay configuration externalization.
-Move stack definitions to config-driven model.
+Level 18.6 overlay diagnostics and debug tooling.
+Add visibility into overlay state and cycle behavior.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Config file defines stacks
-[ ] Runtime reads config
-[ ] Behavior unchanged
-[ ] Per-sample mapping preserved
+[ ] Diagnostics output correct state
+[ ] Toggle enables/disables logs
+[ ] No performance impact when disabled
+[ ] No behavior change

docs/pr/BUILD_PR.md

@@ -1,30 +1,34 @@
-# BUILD_PR_LEVEL_18_5_OVERLAY_CONFIGURATION_EXTERNALIZATION
+# BUILD_PR_LEVEL_18_6_OVERLAY_DIAGNOSTICS_DEBUG_TOOLING
 
 ## PLAN
 
 ### Purpose
-Externalize overlay stack definitions and configuration to remove hardcoded mappings and improve maintainability.
+Introduce lightweight diagnostics and debug tooling for overlay system to aid validation and future debugging.
 
 ### Goals
-- Move overlay stack definitions to config
-- Allow per-sample configuration
-- Reduce hardcoded logic
+- Provide visibility into overlay state
+- Expose current stack + index
+- Enable debug logging toggle
 
 ---
 
 ## BUILD
 
 ### Scope
-- Define external config structure for overlay stacks
-- Refactor runtime to read from config
-- Preserve existing behavior exactly
-- No UI or feature changes
+- Add diagnostic hooks (non-invasive)
+- Add debug output for:
+  - Current overlay index
+  - Active stack
+  - Cycle key events
+- Optional debug toggle (no UI change required)
+- No behavior change
 
 ### Test Steps
-1. Load samples
-2. Verify overlays match previous stacks
-3. Modify config and confirm behavior updates
+1. Enable diagnostics
+2. Cycle overlays
+3. Verify logs show correct state transitions
+4. Disable diagnostics
 
 ### Expected
-- Same behavior as before
-- Config-driven overlay stacks
+- Clear debug visibility
+- No runtime impact when disabled

samples/phase-17/shared/tabDebugOverlayCycle.js

@@ -8,6 +8,40 @@ import { isOverlayCycleReverseModifierActive } from '/samples/phase-17/shared/ov
 
 const overlayIndexMemoryStore = new Map();
 const overlayPersistenceKeys = new Set();
+let overlayDiagnosticsEnabled = false;
+
+function getOverlayStackSnapshot(controller) {
+  if (!controller || !Array.isArray(controller.overlays)) {
+    return [];
+  }
+  return controller.overlays.map((overlay) => ({
+    id: overlay.id,
+    label: overlay.label,
+  }));
+}
+
+function getOverlayDiagnosticsSnapshot(controller) {
+  const stack = getOverlayStackSnapshot(controller);
+  const activeIndex = normalizeActiveIndex(controller);
+  const activeEntry = stack[activeIndex] || null;
+  return {
+    activeIndex,
+    activeId: activeEntry?.id || '',
+    stack,
+    cycleKey: String(controller?.cycleKey || ''),
+    persistenceKey: String(controller?.persistenceKey || ''),
+  };
+}
+
+function logOverlayDiagnostics(eventName, controller) {
+  if (!overlayDiagnosticsEnabled) {
+    return;
+  }
+  if (typeof console === 'undefined' || typeof console.debug !== 'function') {
+    return;
+  }
+  console.debug(`[overlay-diagnostics] ${eventName}`, getOverlayDiagnosticsSnapshot(controller));
+}
 
 function normalizeOverlayEntry(entry) {
   const id = String(entry?.id ?? '').trim();
@@ -180,6 +214,7 @@ export function setTabDebugOverlayMap(controller, { overlays = [], initialOverla
   applyPersistedActiveIndex(controller);
   normalizeActiveIndex(controller);
   controller.cycleLatch = false;
+  logOverlayDiagnostics('set-map', controller);
   return true;
 }
 
@@ -190,6 +225,7 @@ export function setTabDebugOverlayCycleKey(controller, cycleKey) {
   const normalized = String(cycleKey || '').trim();
   controller.cycleKey = normalized || 'Tab';
   controller.cycleLatch = false;
+  logOverlayDiagnostics('set-cycle-key', controller);
   return true;
 }
 
@@ -206,6 +242,7 @@ export function setTabDebugOverlayPersistenceKey(controller, persistenceKey) {
   overlayPersistenceKeys.add(controller.persistenceKey);
   applyPersistedActiveIndex(controller);
   normalizeActiveIndex(controller);
+  logOverlayDiagnostics('set-persistence-key', controller);
   return true;
 }
 
@@ -241,6 +278,7 @@ export function setTabDebugOverlayActive(controller, overlayId) {
   controller.activeIndex = nextIndex;
   normalizeActiveIndex(controller);
   persistActiveIndex(controller);
+  logOverlayDiagnostics('set-active', controller);
   return true;
 }
 
@@ -269,6 +307,7 @@ export function stepTabDebugOverlayController(controller, input) {
   const count = controller.overlays.length;
   controller.activeIndex = (controller.activeIndex + delta + count) % count;
   persistActiveIndex(controller);
+  logOverlayDiagnostics('step-cycle', controller);
 }
 
 export function isTabDebugOverlayActive(controller, overlayId) {
@@ -297,3 +336,12 @@ export function resetTabDebugOverlayPersistenceForTests() {
   overlayPersistenceKeys.clear();
   overlayIndexMemoryStore.clear();
 }
+
+export function setTabDebugOverlayDiagnosticsEnabled(enabled) {
+  overlayDiagnosticsEnabled = enabled === true;
+  return overlayDiagnosticsEnabled;
+}
+
+export function isTabDebugOverlayDiagnosticsEnabled() {
+  return overlayDiagnosticsEnabled;
+}

tests/runtime/Phase17OverlayDiagnosticsTooling.test.mjs

@@ -0,0 +1,81 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase17OverlayDiagnosticsTooling.test.mjs
+*/
+import assert from 'node:assert/strict';
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
+import {
+  createTabDebugOverlayController,
+  isTabDebugOverlayDiagnosticsEnabled,
+  resetTabDebugOverlayPersistenceForTests,
+  setTabDebugOverlayCycleKey,
+  setTabDebugOverlayDiagnosticsEnabled,
+  setTabDebugOverlayMap,
+  stepTabDebugOverlayController,
+} from '../../samples/phase-17/shared/tabDebugOverlayCycle.js';
+
+function makeInput(keys = []) {
+  const down = new Set(keys);
+  return {
+    isDown(code) {
+      return down.has(code);
+    },
+  };
+}
+
+function assertDiagnosticsAreOptionalAndNonBlocking() {
+  const controller = createTabDebugOverlayController({
+    overlays: [
+      { id: 'ui-layer', label: 'UI Layer' },
+      { id: 'mission-feed', label: 'Mission Feed' },
+    ],
+    initialOverlayId: 'ui-layer',
+  });
+  setTabDebugOverlayCycleKey(controller, LEVEL17_OVERLAY_CYCLE_KEY);
+
+  const calls = [];
+  const originalConsoleDebug = console.debug;
+  console.debug = (...args) => {
+    calls.push(args);
+  };
+
+  try {
+    setTabDebugOverlayDiagnosticsEnabled(false);
+    assert.equal(isTabDebugOverlayDiagnosticsEnabled(), false, 'Diagnostics should default to disabled state.');
+
+    stepTabDebugOverlayController(controller, makeInput([LEVEL17_OVERLAY_CYCLE_KEY]));
+    stepTabDebugOverlayController(controller, makeInput([]));
+    assert.equal(controller.activeIndex, 1, 'Overlay cycling behavior should work when diagnostics are disabled.');
+    assert.equal(calls.length, 0, 'No diagnostics logs should emit when diagnostics are disabled.');
+
+    setTabDebugOverlayDiagnosticsEnabled(true);
+    assert.equal(isTabDebugOverlayDiagnosticsEnabled(), true, 'Diagnostics toggle should enable logging.');
+
+    setTabDebugOverlayMap(controller, {
+      overlays: [
+        { id: 'ui-layer', label: 'UI Layer' },
+        { id: 'mission-feed', label: 'Mission Feed' },
+      ],
+      initialOverlayId: 'ui-layer',
+    });
+    stepTabDebugOverlayController(controller, makeInput([LEVEL17_OVERLAY_CYCLE_KEY]));
+
+    assert.equal(calls.length >= 2, true, 'Diagnostics should log stack state when enabled.');
+    const [firstMessage, firstPayload] = calls[0];
+    assert.equal(String(firstMessage).includes('[overlay-diagnostics]'), true, 'Diagnostics prefix should be emitted.');
+    assert.equal(typeof firstPayload.activeIndex, 'number', 'Diagnostics payload should include activeIndex.');
+    assert.equal(Array.isArray(firstPayload.stack), true, 'Diagnostics payload should include stack state.');
+    assert.equal(firstPayload.stack.length, 2, 'Diagnostics payload should include all overlay entries.');
+  } finally {
+    console.debug = originalConsoleDebug;
+    setTabDebugOverlayDiagnosticsEnabled(false);
+  }
+}
+
+export function run() {
+  resetTabDebugOverlayPersistenceForTests();
+  setTabDebugOverlayDiagnosticsEnabled(false);
+  assertDiagnosticsAreOptionalAndNonBlocking();
+}