Optimize overlay performance.

PR Details:
- Improves efficiency and scalability

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,7 +2,7 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement event-driven overlay updates:
-- Use events instead of polling
-- Improve responsiveness
+Optimize overlay performance:
+- Reduce overhead
+- Improve event efficiency
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Add event-driven overlay updates.
+Optimize overlay performance.
 
 PR Details:
-- Improves responsiveness and efficiency
+- Improves efficiency and scalability

docs/dev/reports/validation_checklist.txt

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

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -824,7 +824,7 @@
 - [x] ensure future phases can build cleanly
 
 ### Track H — Final Stability Gate
-- [ ] full-repo validation sweep
+- [.] full-repo validation sweep
 - [x] zero regression requirement
 - [x] contract freeze readiness
 - [x] readiness for long-term maintenance mode

docs/pr/BUILD_PR.md

@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_21_4_OVERLAY_EVENT_DRIVEN_UPDATES
+# BUILD_PR_LEVEL_21_5_OVERLAY_PERFORMANCE_OPTIMIZATION
 
 ## Purpose
-Move overlay updates to an event-driven model.
+Optimize overlay system performance under advanced usage.
 
 ## Roadmap Improvement
-Improves efficiency and responsiveness of overlays.
+Enhances efficiency and scalability of Level 21 overlays.
 
 ## Scope
-- Trigger overlay updates via events
-- Reduce unnecessary polling
-- Validate responsiveness
+- Reduce render overhead
+- Optimize event handling
+- Validate performance gains
 
 ## Test Steps
-1. Trigger gameplay events
-2. Verify overlay updates instantly
-3. Confirm no extra processing
+1. Run multiple overlays
+2. Measure performance
+3. Compare before/after
 
 ## Expected
-- Event-driven updates working
 - Improved performance
+- No regressions

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -267,6 +267,30 @@ function resolveOverlayRuntimeEventQueue(context = {}, gameplayState = null, syn
   return null;
 }
 
+function hasOverlayRuntimeSyncPatch(syncPatch) {
+  if (!syncPatch || typeof syncPatch !== 'object') {
+    return false;
+  }
+  if (syncPatch.visible === true || syncPatch.visible === false) {
+    return true;
+  }
+  if (Number.isFinite(Number(syncPatch.interactionIndex))) {
+    return true;
+  }
+  return String(syncPatch.activeOverlayId || '').trim().length > 0;
+}
+
+function computeOverlayRuntimeCompatSignature(syncPatch, count) {
+  if (!hasOverlayRuntimeSyncPatch(syncPatch)) {
+    return '';
+  }
+  const visibleToken = syncPatch.visible === true ? '1' : (syncPatch.visible === false ? '0' : 'x');
+  const hasInteractionIndex = Number.isFinite(Number(syncPatch.interactionIndex));
+  const interactionToken = hasInteractionIndex ? String(Math.trunc(Number(syncPatch.interactionIndex))) : 'x';
+  const activeOverlayId = String(syncPatch.activeOverlayId || '').trim();
+  return `${visibleToken}|${interactionToken}|${activeOverlayId}|${Math.max(0, Number(count) || 0)}`;
+}
+
 export function enqueueOverlayGameplayRuntimeSyncEvent(target, event = {}) {
   if (!target || typeof target !== 'object') {
     return false;
@@ -303,6 +327,43 @@ function normalizeOverlayRuntimeSyncEvent(event) {
   };
 }
 
+function consumeOverlayRuntimeSyncEvents(eventQueue = []) {
+  if (!Array.isArray(eventQueue) || eventQueue.length === 0) {
+    return {
+      eventsProcessed: 0,
+      patch: {},
+    };
+  }
+
+  const patch = {};
+  let eventsProcessed = 0;
+  for (let i = 0; i < eventQueue.length; i += 1) {
+    const event = normalizeOverlayRuntimeSyncEvent(eventQueue[i]);
+    if (!event) {
+      continue;
+    }
+    if (event.type !== 'overlay-runtime-sync' && event.type !== 'overlay-state-sync') {
+      continue;
+    }
+    eventsProcessed += 1;
+    if (event.visible === true || event.visible === false) {
+      patch.visible = event.visible;
+    }
+    if (Number.isFinite(event.interactionIndex)) {
+      patch.interactionIndex = event.interactionIndex;
+    }
+    if (event.activeOverlayId) {
+      patch.activeOverlayId = event.activeOverlayId;
+    }
+  }
+  eventQueue.length = 0;
+
+  return {
+    eventsProcessed,
+    patch,
+  };
+}
+
 function applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, patch = {}) {
   const count = runtimeExtensions.length;
   let desyncCorrected = false;
@@ -372,27 +433,29 @@ export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
   const count = runtimeExtensions.length;
   let desyncCorrected = false;
   let eventsProcessed = 0;
+  let syncMode = 'cached';
 
   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;
-      }
-      if (event.type !== 'overlay-runtime-sync' && event.type !== 'overlay-state-sync') {
-        continue;
-      }
-      const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, event);
+    const consumedEvents = consumeOverlayRuntimeSyncEvents(eventQueue);
+    eventsProcessed = consumedEvents.eventsProcessed;
+    if (hasOverlayRuntimeSyncPatch(consumedEvents.patch)) {
+      const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, consumedEvents.patch);
       desyncCorrected = desyncCorrected || corrected;
-      eventsProcessed += 1;
+    }
+    if (eventsProcessed > 0) {
+      syncMode = 'events';
     }
   }
 
-  // Compatibility fallback for pre-event producers.
+  // Compatibility fallback for pre-event producers with change detection to avoid repeated polling overhead.
   if (eventsProcessed === 0 && syncState) {
-    const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, syncState);
-    desyncCorrected = desyncCorrected || corrected;
+    const compatSignature = computeOverlayRuntimeCompatSignature(syncState, count);
+    if (compatSignature && runtime.interactionCompatSyncSignature !== compatSignature) {
+      const corrected = applyOverlayRuntimeSyncPatch(runtime, runtimeExtensions, syncState);
+      desyncCorrected = desyncCorrected || corrected;
+      syncMode = 'compat';
+      runtime.interactionCompatSyncSignature = compatSignature;
+    }
   }
 
   const interactionIndex = normalizeInteractionIndex(runtime);
@@ -405,9 +468,10 @@ export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
     cycleKey: String(runtime.interactionCycleKey || LEVEL17_OVERLAY_CYCLE_KEY),
     desyncCorrected,
     eventsProcessed,
-    syncMode: eventsProcessed > 0 ? 'events' : 'compat',
+    syncMode,
   };
   writeOverlayRuntimeSyncSnapshot(syncState, snapshot);
+  runtime.interactionCompatSyncSignature = computeOverlayRuntimeCompatSignature(syncState, count);
   return snapshot;
 }
 

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -277,6 +277,7 @@ function assertOverlayStateSynchronizationAndDesyncRecovery() {
   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.');
+  assert.equal(gameplayState.overlayRuntimeState.syncMode, 'cached', 'No-event sync should use cached state and avoid fallback re-apply.');
 
   const renderRuntimeB = renderOverlayGameplayRuntime(runtime, {
     activeOverlayId: 'runtime-b',
@@ -309,10 +310,40 @@ function assertOverlayStateSynchronizationAndDesyncRecovery() {
   assert.equal(renderRuntimeA, 1, 'Gameplay sync should recover to visible overlay rendering without desync.');
 }
 
+function assertOverlayEventCoalescingEfficiency() {
+  const framework = createPhase19OverlayExpansionFramework();
+  framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-event-coalesce',
+    overlays: [
+      { id: 'runtime-a', label: 'Runtime A' },
+      { id: 'runtime-b', label: 'Runtime B' },
+    ],
+    initialOverlayId: 'runtime-a',
+    runtimeExtensions: [
+      { overlayId: 'runtime-a', onRender() {} },
+      { overlayId: 'runtime-b', onRender() {} },
+    ],
+  }));
+
+  const runtime = framework.createRuntimeForExtension('phase19-overlay-event-coalesce');
+  const gameplayState = { overlayRuntimeState: {} };
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, { visible: true, interactionIndex: 0, activeOverlayId: 'runtime-a' });
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, { visible: false });
+  enqueueOverlayGameplayRuntimeSyncEvent(gameplayState, { visible: true, interactionIndex: 999, activeOverlayId: 'runtime-b' });
+
+  const interaction = getOverlayGameplayRuntimeInteractionSnapshot(runtime, { gameplayState });
+  assert.equal(interaction.activeOverlayId, 'runtime-b', 'Coalesced event processing should keep the final overlay selection.');
+  assert.equal(interaction.visible, true, 'Coalesced event processing should keep the final visibility state.');
+  assert.equal(gameplayState.overlayRuntimeState.eventsProcessed, 3, 'Event efficiency path should consume all queued events in one synchronization pass.');
+  assert.equal(gameplayState.overlayRuntimeState.desyncCorrected, true, 'Event coalescing should preserve desync correction behavior.');
+  assert.equal(gameplayState.overlayRuntimeEvents.length, 0, 'Event queue should be drained after synchronization.');
+}
+
 export function run() {
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
   assertDynamicPanelSizingCapability();
   assertContextAwareOverlayBehavior();
   assertOverlayStateSynchronizationAndDesyncRecovery();
+  assertOverlayEventCoalescingEfficiency();
 }