Level 18.8 overlay integration with telemetry system.

Enable Telemetry Overlay to reflect live system metrics.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,9 @@ MODEL: GPT-5.4-codex
 REASONING: medium
 
 COMMAND:
-Integrate overlay system with mission system:
-- Connect Mission Feed overlay to mission state updates
-- Ensure live updates reflect correctly
-- Preserve existing overlay behavior
+Integrate overlay system with telemetry system:
+- Connect Telemetry Overlay to telemetry data
+- Ensure real-time updates
+- Preserve overlay behavior and performance
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Level 18.7 overlay integration with mission system.
-Enable Mission Feed overlay to reflect live mission state.
+Level 18.8 overlay integration with telemetry system.
+Enable Telemetry Overlay to reflect live system metrics.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Mission Feed updates with state
+[ ] Telemetry Overlay updates with data
 [ ] Overlay cycle unaffected
 [ ] No regression in other overlays
-[ ] Stable behavior
+[ ] Stable performance

docs/pr/BUILD_PR.md

@@ -1,31 +1,30 @@
-# BUILD_PR_LEVEL_18_7_OVERLAY_MISSION_SYSTEM_INTEGRATION
+# BUILD_PR_LEVEL_18_8_OVERLAY_TELEMETRY_SYSTEM_INTEGRATION
 
 ## PLAN
 
 ### Purpose
-Integrate overlay system with mission system so Mission Feed and related overlays respond to mission state changes.
+Integrate overlay system with telemetry system so Telemetry Overlay reflects live system metrics and state.
 
 ### Goals
-- Sync Mission Feed overlay with mission state
-- Ensure overlay updates reflect live mission progress
-- Maintain overlay cycle behavior
+- Sync Telemetry Overlay with telemetry data
+- Ensure real-time updates
+- Maintain overlay stability and performance
 
 ---
 
 ## BUILD
 
 ### Scope
-- Hook overlay system into mission state updates
-- Ensure Mission Feed overlay reflects current mission data
-- No changes to overlay positioning or cycling
-- No UI redesign
+- Connect overlay system to telemetry data sources
+- Ensure Telemetry Overlay updates in real time
+- No changes to overlay cycle behavior or positioning
 
 ### Test Steps
-1. Trigger mission updates
-2. Verify Mission Feed overlay updates
+1. Generate telemetry data
+2. Verify Telemetry Overlay updates
 3. Cycle overlays and confirm consistency
 4. Confirm no regression in other overlays
 
 ### Expected
-- Mission Feed reflects live state
+- Telemetry Overlay reflects live data
 - Overlay system remains stable

samples/phase-17/1712/GameplayMetricsTelemetryScene.js

@@ -7,6 +7,7 @@ GameplayMetricsTelemetryScene.js
 import { createBottomRightDebugPanelStack, drawStackedDebugPanel } from '/src/engine/debug/index.js';
 import RealGameplayMiniGameScene from '/samples/phase-17/1708/RealGameplayMiniGameScene.js';
 import { getRequiredLevel17OverlayStackConfig } from '/samples/phase-17/shared/overlayStackBySampleConfig.js';
+import { getTabDebugOverlayTelemetrySnapshot } from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 const OVERLAY_UI_LAYER = 'ui-layer';
 const OVERLAY_MISSION_FEED = 'mission-feed';
 const OVERLAY_MISSION_READY = 'mission-ready';
@@ -56,10 +57,22 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
       speedHistory: [],
       fpsHistory: [],
       collisionHistory: [],
+      overlay: {
+        activeId: '',
+        activeIndex: 0,
+        stackSize: 0,
+        cycleKey: '',
+        statusLabel: 'none',
+      },
     };
     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);
+    this.refreshOverlayTelemetrySnapshot();
+  }
+
+  refreshOverlayTelemetrySnapshot() {
+    this.telemetry.overlay = getTabDebugOverlayTelemetrySnapshot(this.tabDebugOverlays);
   }
 
   step3DPhysics(dtSeconds, engine) {
@@ -93,6 +106,7 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
     pushSample(this.telemetry.speedHistory, speed);
     pushSample(this.telemetry.fpsHistory, this.telemetry.avgFps);
     pushSample(this.telemetry.collisionHistory, this.lastCollisionCount);
+    this.refreshOverlayTelemetrySnapshot();
   }
 
   render(renderer) {
@@ -113,8 +127,8 @@ export default class GameplayMetricsTelemetryScene extends RealGameplayMiniGameS
       `maxSpeed=${this.telemetry.maxPlayerSpeed.toFixed(2)}`,
       `objects=${objectCount} coresRemaining=${remainingCores}`,
       `collisions=${this.telemetry.collisionsTotal}`,
-      `actions=${this.telemetry.actionEvents}`,
-      `stateTransitions=${this.telemetry.stateTransitions}`,
+      `actions=${this.telemetry.actionEvents} transitions=${this.telemetry.stateTransitions}`,
+      `overlay=${this.telemetry.overlay.statusLabel} key=${this.telemetry.overlay.cycleKey}`,
     ]);
 
     drawTelemetrySparkline(

samples/phase-17/shared/tabDebugOverlayCycle.js

@@ -323,6 +323,28 @@ export function getTabDebugOverlayStatusLabel(controller) {
   return `${active.label} (${index + 1}/${controller.overlays.length})`;
 }
 
+export function getTabDebugOverlayTelemetrySnapshot(controller) {
+  if (!controller || !Array.isArray(controller.overlays) || controller.overlays.length === 0) {
+    return {
+      activeId: '',
+      activeIndex: 0,
+      stackSize: 0,
+      cycleKey: String(controller?.cycleKey || ''),
+      statusLabel: 'none',
+    };
+  }
+
+  const activeIndex = normalizeActiveIndex(controller);
+  const activeEntry = controller.overlays[activeIndex] || null;
+  return {
+    activeId: activeEntry?.id || '',
+    activeIndex,
+    stackSize: controller.overlays.length,
+    cycleKey: String(controller.cycleKey || ''),
+    statusLabel: getTabDebugOverlayStatusLabel(controller),
+  };
+}
+
 export function resetTabDebugOverlayPersistenceForTests() {
   for (const key of overlayPersistenceKeys.values()) {
     if (typeof localStorage !== 'undefined') {

tests/runtime/Phase17Sample1712GameplayMetricsTelemetry.test.mjs

@@ -105,6 +105,8 @@ function assertTelemetryOverlayAndCounters() {
   scene.step3DPhysics(0.2, { input: makeInput(['KeyD']) });
   assert.equal(scene.telemetry.playerSpeed > 0, true, 'Telemetry should report positive player speed after movement.');
   assert.equal(scene.telemetry.avgFps > 0, true, 'Telemetry should report FPS.');
+  assert.equal(scene.telemetry.overlay.stackSize, 4, 'Telemetry should include overlay stack telemetry details.');
+  assert.equal(scene.telemetry.overlay.activeId, 'ui-layer', 'Telemetry should report active overlay id in real time.');
 
   const firstCore = scene.cores.find((core) => core.collected === false);
   positionPlayerOnCore(scene, firstCore);
@@ -126,6 +128,7 @@ function assertTelemetryOverlayAndCounters() {
   assert.equal(renderer.texts.some((text) => text.includes('Telemetry Overlay')), false, 'Telemetry panel should not render by default.');
 
   pressOverlayCycle(scene);
+  assert.equal(scene.telemetry.overlay.activeId, 'mission-feed', 'Telemetry should update active overlay id after overlay cycling.');
   const missionFeedRenderer = createRendererProbe();
   scene.render(missionFeedRenderer);
   assert.equal(missionFeedRenderer.texts.some((text) => text.includes('Mission Feed')), true, 'First G press should cycle to Mission Feed.');
@@ -140,6 +143,7 @@ function assertTelemetryOverlayAndCounters() {
   scene.render(telemetryRenderer);
   assert.equal(telemetryRenderer.texts.some((text) => text.includes('Telemetry Overlay')), true, 'Third G press should cycle to Telemetry Overlay.');
   assert.equal(telemetryRenderer.texts.some((text) => text.includes('playerSpeed=')), true, 'Telemetry overlay should render player-speed metrics.');
+  assert.equal(telemetryRenderer.texts.some((text) => text.includes('overlay=Telemetry Overlay')), true, 'Telemetry overlay should render live overlay telemetry state.');
   assert.equal(telemetryRenderer.texts.some((text) => text.includes('UI Layer')), false, 'Only one debug overlay should be visible at a time.');
 }