Add event-driven overlay updates.

PR Details:
- Improves responsiveness and efficiency

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,7 +2,7 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement context-aware overlays:
-- Detect gameplay state
-- Adapt overlay behavior
+Implement overlay state synchronization:
+- Sync with gameplay state
+- Prevent desync
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,4 @@
-Add context-aware overlays.
+Add overlay state synchronization.
 
 PR Details:
-- Enables dynamic overlay behavior
-
+- Ensures consistent overlay behavior

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Context detection works
-[ ] Overlay adapts
-[ ] No regression
+[ ] State sync works
+[ ] No desync
+[ ] Stable behavior
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -826,5 +826,5 @@
 ### Track H — Final Stability Gate
 - [ ] full-repo validation sweep
 - [x] zero regression requirement
-- [.] contract freeze readiness
+- [x] contract freeze readiness
 - [.] readiness for long-term maintenance mode

docs/pr/BUILD_PR.md

@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_21_2_CONTEXT_AWARE_OVERLAYS
+# BUILD_PR_LEVEL_21_3_OVERLAY_STATE_SYNCHRONIZATION
 
 ## Purpose
-Add context-aware overlays that respond to gameplay state.
+Ensure overlay state is synchronized with gameplay systems.
 
 ## Roadmap Improvement
-Advances Level 21 with dynamic overlay behavior.
+Advances Level 21 with consistent state behavior across overlays.
 
 ## Scope
-- Detect gameplay context
-- Show/hide or modify overlays dynamically
-- Validate behavior
+- Sync overlay state with gameplay state
+- Prevent desync issues
+- Validate across multiple overlays
 
 ## Test Steps
-1. Change gameplay state
-2. Verify overlay adapts
-3. Confirm stability
+1. Change gameplay state rapidly
+2. Verify overlays stay in sync
+3. Confirm no desync artifacts
 
 ## Expected
-- Context-driven overlays
-- No regression
+- Consistent overlay state
+- No desync

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -91,6 +91,22 @@ function normalizeInteractionIndex(runtime) {
   return normalized;
 }
 
+function findRuntimeExtensionIndexByOverlayId(runtime, overlayId) {
+  if (!runtime || !Array.isArray(runtime.runtimeExtensions)) {
+    return -1;
+  }
+  const requestedOverlayId = String(overlayId || '').trim();
+  if (!requestedOverlayId) {
+    return -1;
+  }
+  for (let i = 0; i < runtime.runtimeExtensions.length; i += 1) {
+    if (String(runtime.runtimeExtensions[i]?.overlayId || '').trim() === requestedOverlayId) {
+      return i;
+    }
+  }
+  return -1;
+}
+
 function normalizeSafeZoneEntry(entry) {
   if (!entry || typeof entry !== 'object') {
     return null;
@@ -218,6 +234,103 @@ function resolveRuntimeExtensionContextBehavior(extension, context = {}) {
   }
 }
 
+function resolveOverlayRuntimeSyncStateContainer(context = {}, gameplayState = null) {
+  if (context?.overlayRuntimeState && typeof context.overlayRuntimeState === 'object') {
+    return context.overlayRuntimeState;
+  }
+  if (gameplayState?.overlayRuntimeState && typeof gameplayState.overlayRuntimeState === 'object') {
+    return gameplayState.overlayRuntimeState;
+  }
+  if (gameplayState && typeof gameplayState === 'object') {
+    try {
+      gameplayState.overlayRuntimeState = {};
+      if (gameplayState.overlayRuntimeState && typeof gameplayState.overlayRuntimeState === 'object') {
+        return gameplayState.overlayRuntimeState;
+      }
+    } catch {
+      // Sync state creation is best effort only.
+    }
+  }
+  return null;
+}
+
+function writeOverlayRuntimeSyncSnapshot(container, snapshot) {
+  if (!container || typeof container !== 'object' || !snapshot || typeof snapshot !== 'object') {
+    return false;
+  }
+  try {
+    container.visible = snapshot.visible;
+    container.interactionIndex = snapshot.interactionIndex;
+    container.activeOverlayId = snapshot.activeOverlayId;
+    container.count = snapshot.count;
+    container.cycleKey = snapshot.cycleKey;
+    container.desyncCorrected = snapshot.desyncCorrected;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
+  if (!runtime) {
+    return null;
+  }
+
+  const gameplayState = resolveOverlayGameplayState(context);
+  const syncState = resolveOverlayRuntimeSyncStateContainer(context, gameplayState);
+  const runtimeExtensions = Array.isArray(runtime.runtimeExtensions) ? runtime.runtimeExtensions : [];
+  const count = runtimeExtensions.length;
+  let desyncCorrected = false;
+
+  if (syncState) {
+    if (syncState.visible === true || syncState.visible === false) {
+      runtime.interactionVisible = syncState.visible;
+    }
+
+    const incomingIndexRaw = Number(syncState.interactionIndex);
+    const hasIncomingIndex = Number.isFinite(incomingIndexRaw);
+    if (hasIncomingIndex && count > 0) {
+      const incomingIndex = Math.trunc(incomingIndexRaw);
+      if (incomingIndex < 0 || incomingIndex >= count || incomingIndex !== incomingIndexRaw) {
+        desyncCorrected = true;
+      }
+      runtime.interactionIndex = ((incomingIndex % count) + count) % count;
+    }
+
+    const requestedOverlayId = String(syncState.activeOverlayId || '').trim();
+    const resolvedOverlayIndex = findRuntimeExtensionIndexByOverlayId(runtime, requestedOverlayId);
+    if (requestedOverlayId) {
+      if (resolvedOverlayIndex >= 0) {
+        if (runtime.interactionIndex !== resolvedOverlayIndex) {
+          runtime.interactionIndex = resolvedOverlayIndex;
+        }
+      } else {
+        desyncCorrected = true;
+      }
+    }
+
+    if (hasIncomingIndex && requestedOverlayId && resolvedOverlayIndex >= 0 && count > 0) {
+      const incomingIndex = ((Math.trunc(incomingIndexRaw) % count) + count) % count;
+      if (incomingIndex !== resolvedOverlayIndex) {
+        desyncCorrected = true;
+      }
+    }
+  }
+
+  const interactionIndex = normalizeInteractionIndex(runtime);
+  const active = runtimeExtensions[interactionIndex] || null;
+  const snapshot = {
+    visible: runtime.interactionVisible !== false,
+    interactionIndex,
+    activeOverlayId: active?.overlayId || '',
+    count,
+    cycleKey: String(runtime.interactionCycleKey || LEVEL17_OVERLAY_CYCLE_KEY),
+    desyncCorrected,
+  };
+  writeOverlayRuntimeSyncSnapshot(syncState, snapshot);
+  return snapshot;
+}
+
 function getComposedRuntimeFrames(runtime, activeOverlayId, context = {}) {
   if (!runtime || !Array.isArray(runtime.runtimeExtensions) || runtime.runtimeExtensions.length === 0) {
     return [];
@@ -570,7 +683,8 @@ export function setOverlayGameplayRuntimeVisible(runtime, visible) {
   return true;
 }
 
-export function getOverlayGameplayRuntimeInteractionSnapshot(runtime) {
+export function getOverlayGameplayRuntimeInteractionSnapshot(runtime, context = {}) {
+  synchronizeOverlayGameplayRuntimeState(runtime, context);
   const extensions = Array.isArray(runtime?.runtimeExtensions) ? runtime.runtimeExtensions : [];
   const index = normalizeInteractionIndex(runtime);
   const active = extensions[index] || null;
@@ -586,6 +700,7 @@ export function getOverlayGameplayRuntimeInteractionSnapshot(runtime) {
 }
 
 export function getOverlayGameplayRuntimeCompositionSnapshot(runtime, context = {}) {
+  synchronizeOverlayGameplayRuntimeState(runtime, context);
   const activeOverlayId = String(context?.activeOverlayId || '').trim();
   const safeZones = resolveLayoutSafeZones(context);
   const frames = deriveRenderHierarchy(attachCompositionSlots(
@@ -618,6 +733,7 @@ export function stepOverlayGameplayRuntimeControls(runtime, input, options = {})
   if (!runtime) {
     return false;
   }
+  synchronizeOverlayGameplayRuntimeState(runtime, options);
 
   const dtSeconds = Math.max(0, Math.min(0.25, Number(options?.dtSeconds) || 0));
   if (runtime.interactionCooldownRemainingSeconds > 0 && dtSeconds > 0) {
@@ -694,6 +810,7 @@ export function stepOverlayGameplayRuntimeControls(runtime, input, options = {})
 }
 
 export function stepOverlayGameplayRuntime(runtime, context = {}) {
+  synchronizeOverlayGameplayRuntimeState(runtime, context);
   if (
     !runtime ||
     runtime.interactionVisible === false ||
@@ -737,6 +854,7 @@ export function stepOverlayGameplayRuntime(runtime, context = {}) {
 }
 
 export function renderOverlayGameplayRuntime(runtime, context = {}) {
+  synchronizeOverlayGameplayRuntimeState(runtime, context);
   if (
     !runtime ||
     runtime.interactionVisible === false ||

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -8,6 +8,7 @@ import assert from 'node:assert/strict';
 import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
 import {
   getOverlayGameplayRuntimeCompositionSnapshot,
+  getOverlayGameplayRuntimeInteractionSnapshot,
   renderOverlayGameplayRuntime,
   stepOverlayGameplayRuntime,
 } from '../../samples/phase-17/shared/overlayGameplayRuntime.js';
@@ -238,9 +239,66 @@ function assertContextAwareOverlayBehavior() {
   assert.equal(visibleSnapshot[0].slot.height, 104, 'Context-aware runtime should adapt panel height from gameplay state behavior.');
 }
 
+function assertOverlayStateSynchronizationAndDesyncRecovery() {
+  const framework = createPhase19OverlayExpansionFramework();
+  framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-sync',
+    overlays: [
+      { id: 'ui', label: 'UI' },
+      { id: 'runtime-a', label: 'Runtime A' },
+      { id: 'runtime-b', label: 'Runtime B' },
+    ],
+    initialOverlayId: 'ui',
+    runtimeExtensions: [
+      { overlayId: 'runtime-a', onRender() {} },
+      { overlayId: 'runtime-b', onRender() {} },
+    ],
+  }));
+
+  const runtime = framework.createRuntimeForExtension('phase19-overlay-sync');
+  const gameplayState = {
+    overlayRuntimeState: {
+      visible: true,
+      interactionIndex: 99,
+      activeOverlayId: 'runtime-b',
+    },
+  };
+
+  const initialInteraction = getOverlayGameplayRuntimeInteractionSnapshot(runtime, { gameplayState });
+  assert.equal(initialInteraction.index, 1, 'Sync should correct out-of-range index to the overlay requested by gameplay state.');
+  assert.equal(initialInteraction.activeOverlayId, 'runtime-b', 'Sync should align active overlay id with gameplay state request.');
+  assert.equal(gameplayState.overlayRuntimeState.desyncCorrected, true, 'Sync should flag corrected desync state.');
+  assert.equal(gameplayState.overlayRuntimeState.count, 2, 'Sync snapshot should expose runtime extension count.');
+
+  const renderRuntimeB = renderOverlayGameplayRuntime(runtime, {
+    activeOverlayId: 'runtime-b',
+    renderer: createRendererProbe(),
+    gameplayState,
+  });
+  assert.equal(renderRuntimeB, 1, 'Synced runtime should render requested gameplay overlay.');
+
+  gameplayState.overlayRuntimeState.visible = false;
+  gameplayState.overlayRuntimeState.activeOverlayId = 'runtime-a';
+  const renderHidden = renderOverlayGameplayRuntime(runtime, {
+    activeOverlayId: 'runtime-a',
+    renderer: createRendererProbe(),
+    gameplayState,
+  });
+  assert.equal(renderHidden, 0, 'Gameplay visibility sync should prevent overlay render while hidden.');
+
+  gameplayState.overlayRuntimeState.visible = true;
+  const renderRuntimeA = renderOverlayGameplayRuntime(runtime, {
+    activeOverlayId: 'runtime-a',
+    renderer: createRendererProbe(),
+    gameplayState,
+  });
+  assert.equal(renderRuntimeA, 1, 'Gameplay sync should recover to visible overlay rendering without desync.');
+}
+
 export function run() {
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
   assertDynamicPanelSizingCapability();
   assertContextAwareOverlayBehavior();
+  assertOverlayStateSynchronizationAndDesyncRecovery();
 }