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 overlay state synchronization:
-- Sync with gameplay state
-- Prevent desync
+Implement event-driven overlay updates:
+- Use events instead of polling
+- Improve responsiveness
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Add overlay state synchronization.
+Add event-driven overlay updates.
 
 PR Details:
-- Ensures consistent overlay behavior
+- Improves responsiveness and efficiency

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] State sync works
-[ ] No desync
-[ ] Stable behavior
+[ ] Events trigger updates
+[ ] No polling overhead
+[ ] Performance improved
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -827,4 +827,4 @@
 - [ ] full-repo validation sweep
 - [x] zero regression requirement
 - [x] contract freeze readiness
-- [.] readiness for long-term maintenance mode
+- [x] readiness for long-term maintenance mode

docs/pr/BUILD_PR.md

@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_21_3_OVERLAY_STATE_SYNCHRONIZATION
+# BUILD_PR_LEVEL_21_4_OVERLAY_EVENT_DRIVEN_UPDATES
 
 ## Purpose
-Ensure overlay state is synchronized with gameplay systems.
+Move overlay updates to an event-driven model.
 
 ## Roadmap Improvement
-Advances Level 21 with consistent state behavior across overlays.
+Improves efficiency and responsiveness of overlays.
 
 ## Scope
-- Sync overlay state with gameplay state
-- Prevent desync issues
-- Validate across multiple overlays
+- Trigger overlay updates via events
+- Reduce unnecessary polling
+- Validate responsiveness
 
 ## Test Steps
-1. Change gameplay state rapidly
-2. Verify overlays stay in sync
-3. Confirm no desync artifacts
+1. Trigger gameplay events
+2. Verify overlay updates instantly
+3. Confirm no extra processing
 
 ## Expected
-- Consistent overlay state
-- No desync
+- Event-driven updates working
+- Improved performance

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -254,6 +254,93 @@ function resolveOverlayRuntimeSyncStateContainer(context = {}, gameplayState = n
   return null;
 }
 
+function resolveOverlayRuntimeEventQueue(context = {}, gameplayState = null, syncState = null) {
+  if (Array.isArray(context?.overlayRuntimeEvents)) {
+    return context.overlayRuntimeEvents;
+  }
+  if (Array.isArray(gameplayState?.overlayRuntimeEvents)) {
+    return gameplayState.overlayRuntimeEvents;
+  }
+  if (Array.isArray(syncState?.events)) {
+    return syncState.events;
+  }
+  return null;
+}
+
+export function enqueueOverlayGameplayRuntimeSyncEvent(target, event = {}) {
+  if (!target || typeof target !== 'object') {
+    return false;
+  }
+  if (!Array.isArray(target.overlayRuntimeEvents)) {
+    target.overlayRuntimeEvents = [];
+  }
+  if (!Array.isArray(target.overlayRuntimeEvents)) {
+    return false;
+  }
+  target.overlayRuntimeEvents.push({
+    type: String(event?.type || 'overlay-runtime-sync').trim() || 'overlay-runtime-sync',
+    ...(event || {}),
+  });
+  return true;
+}
+
+function normalizeOverlayRuntimeSyncEvent(event) {
+  if (!event || typeof event !== 'object') {
+    return null;
+  }
+  const normalizedType = String(event.type || 'overlay-runtime-sync').trim() || 'overlay-runtime-sync';
+  const hasVisible = event.visible === true || event.visible === false;
+  const hasInteractionIndex = Number.isFinite(Number(event.interactionIndex));
+  const hasActiveOverlayId = String(event.activeOverlayId || '').trim().length > 0;
+  if (!hasVisible && !hasInteractionIndex && !hasActiveOverlayId && normalizedType === 'overlay-runtime-sync') {
+    return null;
+  }
+  return {
+    type: normalizedType,
+    visible: hasVisible ? event.visible : undefined,
+    interactionIndex: hasInteractionIndex ? Number(event.interactionIndex) : undefined,
+    activeOverlayId: hasActiveOverlayId ? String(event.activeOverlayId || '').trim() : '',
+  };
+}
+
+function applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, patch = {}) {
+  const count = runtimeExtensions.length;
+  let desyncCorrected = false;
+  if (patch.visible === true || patch.visible === false) {
+    runtime.interactionVisible = patch.visible;
+  }
+
+  if (Number.isFinite(patch.interactionIndex) && count > 0) {
+    const incomingIndexRaw = Number(patch.interactionIndex);
+    const incomingIndex = Math.trunc(incomingIndexRaw);
+    if (incomingIndex < 0 || incomingIndex >= count || incomingIndex !== incomingIndexRaw) {
+      desyncCorrected = true;
+    }
+    runtime.interactionIndex = ((incomingIndex % count) + count) % count;
+  }
+
+  const requestedOverlayId = String(patch.activeOverlayId || '').trim();
+  const resolvedOverlayIndex = findRuntimeExtensionIndexByOverlayId(runtime, requestedOverlayId);
+  if (requestedOverlayId) {
+    if (resolvedOverlayIndex >= 0) {
+      if (runtime.interactionIndex !== resolvedOverlayIndex) {
+        runtime.interactionIndex = resolvedOverlayIndex;
+      }
+    } else {
+      desyncCorrected = true;
+    }
+  }
+
+  if (Number.isFinite(patch.interactionIndex) && requestedOverlayId && resolvedOverlayIndex >= 0 && count > 0) {
+    const incomingIndex = ((Math.trunc(Number(patch.interactionIndex)) % count) + count) % count;
+    if (incomingIndex !== resolvedOverlayIndex) {
+      desyncCorrected = true;
+    }
+  }
+
+  return desyncCorrected;
+}
+
 function writeOverlayRuntimeSyncSnapshot(container, snapshot) {
   if (!container || typeof container !== 'object' || !snapshot || typeof snapshot !== 'object') {
     return false;
@@ -265,6 +352,8 @@ function writeOverlayRuntimeSyncSnapshot(container, snapshot) {
     container.count = snapshot.count;
     container.cycleKey = snapshot.cycleKey;
     container.desyncCorrected = snapshot.desyncCorrected;
+    container.eventsProcessed = snapshot.eventsProcessed;
+    container.syncMode = snapshot.syncMode;
     return true;
   } catch {
     return false;
@@ -278,43 +367,32 @@ export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
 
   const gameplayState = resolveOverlayGameplayState(context);
   const syncState = resolveOverlayRuntimeSyncStateContainer(context, gameplayState);
+  const eventQueue = resolveOverlayRuntimeEventQueue(context, gameplayState, syncState);
   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;
+  let eventsProcessed = 0;
+
+  if (Array.isArray(eventQueue) && eventQueue.length > 0) {
+    const pending = eventQueue.splice(0, eventQueue.length);
+    for (let i = 0; i < pending.length; i += 1) {
+      const event = normalizeOverlayRuntimeSyncEvent(pending[i]);
+      if (!event) {
+        continue;
       }
-      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 (event.type !== 'overlay-runtime-sync' && event.type !== 'overlay-state-sync') {
+        continue;
       }
+      const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, event);
+      desyncCorrected = desyncCorrected || corrected;
+      eventsProcessed += 1;
     }
+  }
 
-    if (hasIncomingIndex && requestedOverlayId && resolvedOverlayIndex >= 0 && count > 0) {
-      const incomingIndex = ((Math.trunc(incomingIndexRaw) % count) + count) % count;
-      if (incomingIndex !== resolvedOverlayIndex) {
-        desyncCorrected = true;
-      }
-    }
+  // Compatibility fallback for pre-event producers.
+  if (eventsProcessed === 0 && syncState) {
+    const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, syncState);
+    desyncCorrected = desyncCorrected || corrected;
   }
 
   const interactionIndex = normalizeInteractionIndex(runtime);
@@ -326,6 +404,8 @@ export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
     count,
     cycleKey: String(runtime.interactionCycleKey || LEVEL17_OVERLAY_CYCLE_KEY),
     desyncCorrected,
+    eventsProcessed,
+    syncMode: eventsProcessed > 0 ? 'events' : 'compat',
   };
   writeOverlayRuntimeSyncSnapshot(syncState, snapshot);
   return snapshot;

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -7,6 +7,7 @@ Phase19OverlayExpansionFramework.test.mjs
 import assert from 'node:assert/strict';
 import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
 import {
+  enqueueOverlayGameplayRuntimeSyncEvent,
   getOverlayGameplayRuntimeCompositionSnapshot,
   getOverlayGameplayRuntimeInteractionSnapshot,
   renderOverlayGameplayRuntime,
@@ -257,18 +258,25 @@ function assertOverlayStateSynchronizationAndDesyncRecovery() {
 
   const runtime = framework.createRuntimeForExtension('phase19-overlay-sync');
   const gameplayState = {
-    overlayRuntimeState: {
-      visible: true,
-      interactionIndex: 99,
-      activeOverlayId: 'runtime-b',
-    },
+    overlayRuntimeState: {},
   };
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, {
+    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.');
+  assert.equal(gameplayState.overlayRuntimeState.syncMode, 'events', 'Sync should process queued gameplay events in event-driven mode.');
+  assert.equal(gameplayState.overlayRuntimeState.eventsProcessed, 1, 'Sync should process exactly one overlay event.');
+
+  const idleInteraction = getOverlayGameplayRuntimeInteractionSnapshot(runtime, { gameplayState });
+  assert.equal(idleInteraction.activeOverlayId, 'runtime-b', 'No-event sync should keep prior synchronized state stable.');
+  assert.equal(gameplayState.overlayRuntimeState.eventsProcessed, 0, 'No queued events should avoid extra event processing.');
 
   const renderRuntimeB = renderOverlayGameplayRuntime(runtime, {
     activeOverlayId: 'runtime-b',
@@ -277,16 +285,22 @@ function assertOverlayStateSynchronizationAndDesyncRecovery() {
   });
   assert.equal(renderRuntimeB, 1, 'Synced runtime should render requested gameplay overlay.');
 
-  gameplayState.overlayRuntimeState.visible = false;
-  gameplayState.overlayRuntimeState.activeOverlayId = 'runtime-a';
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, {
+    visible: false,
+    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.');
+  assert.equal(gameplayState.overlayRuntimeState.syncMode, 'events', 'Render sync should remain event-driven after hide event.');
 
-  gameplayState.overlayRuntimeState.visible = true;
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, {
+    visible: true,
+    activeOverlayId: 'runtime-a',
+  });
   const renderRuntimeA = renderOverlayGameplayRuntime(runtime, {
     activeOverlayId: 'runtime-a',
     renderer: createRendererProbe(),