Add context-aware overlays.

PR Details:
- Enables dynamic overlay behavior

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,7 +2,7 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement advanced overlay feature:
-- Add one advanced capability
-- Maintain compatibility
+Implement context-aware overlays:
+- Detect gameplay state
+- Adapt overlay behavior
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,5 @@
-Add advanced overlay feature.
+Add context-aware overlays.
 
 PR Details:
-- Introduces Level 21 capabilities
+- Enables dynamic overlay behavior
+

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,4 @@
-[ ] Feature works
-[ ] No regressions
+[ ] Context detection works
+[ ] Overlay adapts
+[ ] No regression
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

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

docs/pr/BUILD_PR.md

@@ -1,20 +1,21 @@
-# BUILD_PR_LEVEL_21_1_ADVANCED_OVERLAY_FEATURES
+# BUILD_PR_LEVEL_21_2_CONTEXT_AWARE_OVERLAYS
 
 ## Purpose
-Introduce advanced overlay capabilities building on plugin system.
+Add context-aware overlays that respond to gameplay state.
 
 ## Roadmap Improvement
-Begins Level 21 advanced feature set.
+Advances Level 21 with dynamic overlay behavior.
 
 ## Scope
-- Add one advanced overlay capability (e.g. dynamic resizing or contextual display)
-- Ensure compatibility with plugin system
+- Detect gameplay context
+- Show/hide or modify overlays dynamically
+- Validate behavior
 
 ## Test Steps
-1. Activate advanced overlay
-2. Validate behavior
-3. Confirm no regression
+1. Change gameplay state
+2. Verify overlay adapts
+3. Confirm stability
 
 ## Expected
-- Advanced overlay works
-- System stable
+- Context-driven overlays
+- No regression

samples/phase-17/shared/overlayExpansionContracts.js

@@ -54,6 +54,9 @@ function normalizeRuntimeExtensionEntry(entry) {
   const onStep = typeof entry.onStep === 'function' ? entry.onStep : null;
   const onRender = typeof entry.onRender === 'function' ? entry.onRender : null;
   const resolvePanelSize = typeof entry.resolvePanelSize === 'function' ? entry.resolvePanelSize : null;
+  const resolveContextBehavior = typeof entry.resolveContextBehavior === 'function'
+    ? entry.resolveContextBehavior
+    : null;
   if (!onStep && !onRender) {
     return null;
   }
@@ -72,6 +75,7 @@ function normalizeRuntimeExtensionEntry(entry) {
     onStep,
     onRender,
     resolvePanelSize,
+    resolveContextBehavior,
     compose: entry.compose === true,
     layerOrder,
     visualPriority,

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -32,12 +32,16 @@ function normalizeRuntimeExtensionEntry(entry) {
   const panelWidth = Number.isFinite(panelWidthRaw) && panelWidthRaw > 0 ? panelWidthRaw : 260;
   const panelHeight = Number.isFinite(panelHeightRaw) && panelHeightRaw > 0 ? panelHeightRaw : 96;
   const resolvePanelSize = typeof entry.resolvePanelSize === 'function' ? entry.resolvePanelSize : null;
+  const resolveContextBehavior = typeof entry.resolveContextBehavior === 'function'
+    ? entry.resolveContextBehavior
+    : null;
 
   return Object.freeze({
     overlayId,
     onStep,
     onRender,
     resolvePanelSize,
+    resolveContextBehavior,
     compose,
     layerOrder,
     visualPriority,
@@ -140,7 +144,81 @@ function rectsOverlap(a, b) {
   return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }
 
-function getComposedRuntimeFrames(runtime, activeOverlayId) {
+function resolveOverlayGameplayState(context = {}) {
+  if (!context || typeof context !== 'object') {
+    return null;
+  }
+
+  if (context.gameplayState && typeof context.gameplayState === 'object') {
+    return context.gameplayState;
+  }
+
+  const scene = context.scene;
+  if (!scene || typeof scene !== 'object') {
+    return null;
+  }
+
+  if (typeof scene.getOverlayGameplayState === 'function') {
+    const value = scene.getOverlayGameplayState();
+    if (value && typeof value === 'object') {
+      return value;
+    }
+  }
+
+  if (typeof scene.getGameplayState === 'function') {
+    const value = scene.getGameplayState();
+    if (value && typeof value === 'object') {
+      return value;
+    }
+  }
+
+  if (scene.gameplayState && typeof scene.gameplayState === 'object') {
+    return scene.gameplayState;
+  }
+
+  if (scene.state && typeof scene.state === 'object') {
+    return scene.state;
+  }
+
+  return null;
+}
+
+function resolveRuntimeExtensionContextBehavior(extension, context = {}) {
+  const defaultBehavior = {
+    visible: true,
+    compose: extension?.compose === true,
+    panelWidth: Number(extension?.panelWidth) || 260,
+    panelHeight: Number(extension?.panelHeight) || 96,
+  };
+
+  if (!extension || typeof extension.resolveContextBehavior !== 'function') {
+    return defaultBehavior;
+  }
+
+  try {
+    const gameplayState = resolveOverlayGameplayState(context);
+    const resolved = extension.resolveContextBehavior({
+      ...context,
+      gameplayState,
+    });
+    return {
+      visible: resolved?.visible !== false,
+      compose: resolved?.compose === true || resolved?.compose === false
+        ? resolved.compose
+        : defaultBehavior.compose,
+      panelWidth: Number.isFinite(Number(resolved?.panelWidth))
+        ? Number(resolved.panelWidth)
+        : defaultBehavior.panelWidth,
+      panelHeight: Number.isFinite(Number(resolved?.panelHeight))
+        ? Number(resolved.panelHeight)
+        : defaultBehavior.panelHeight,
+    };
+  } catch {
+    return defaultBehavior;
+  }
+}
+
+function getComposedRuntimeFrames(runtime, activeOverlayId, context = {}) {
   if (!runtime || !Array.isArray(runtime.runtimeExtensions) || runtime.runtimeExtensions.length === 0) {
     return [];
   }
@@ -151,8 +229,12 @@ function getComposedRuntimeFrames(runtime, activeOverlayId) {
 
   for (let i = 0; i < runtime.runtimeExtensions.length; i += 1) {
     const extension = runtime.runtimeExtensions[i];
+    const contextBehavior = resolveRuntimeExtensionContextBehavior(extension, context);
+    if (contextBehavior.visible === false) {
+      continue;
+    }
     const isActive = i === activeIndex;
-    if (!isActive && extension.compose !== true) {
+    if (!isActive && contextBehavior.compose !== true) {
       continue;
     }
     if (!shouldRunRuntimeExtension(extension, normalizedActiveOverlayId)) {
@@ -163,6 +245,7 @@ function getComposedRuntimeFrames(runtime, activeOverlayId) {
       extension,
       registrationIndex: i,
       isActive,
+      contextBehavior,
     });
   }
 
@@ -362,12 +445,19 @@ function attachCompositionSlots(frames, renderer, safeZones = [], layoutContext
 
   for (let i = 0; i < frames.length; i += 1) {
     const frame = frames[i];
-    const fallbackWidth = Math.max(120, Number(frame.extension.panelWidth) || 260);
-    const fallbackHeight = Math.max(32, Number(frame.extension.panelHeight) || 96);
+    const fallbackWidth = Math.max(
+      120,
+      Number(frame.contextBehavior?.panelWidth) || Number(frame.extension.panelWidth) || 260
+    );
+    const fallbackHeight = Math.max(
+      32,
+      Number(frame.contextBehavior?.panelHeight) || Number(frame.extension.panelHeight) || 96
+    );
     const dynamicPanelSize = resolveDynamicPanelSize(frame.extension, {
       ...layoutContext,
       renderer,
       canvasSize: { width, height },
+      gameplayState: resolveOverlayGameplayState(layoutContext),
       frameIndex: i,
       frameCount: frames.length,
       safeZones,
@@ -499,7 +589,7 @@ export function getOverlayGameplayRuntimeCompositionSnapshot(runtime, context =
   const activeOverlayId = String(context?.activeOverlayId || '').trim();
   const safeZones = resolveLayoutSafeZones(context);
   const frames = deriveRenderHierarchy(attachCompositionSlots(
-    getComposedRuntimeFrames(runtime, activeOverlayId),
+    getComposedRuntimeFrames(runtime, activeOverlayId, context),
     context?.renderer,
     safeZones,
     context
@@ -517,7 +607,7 @@ export function getOverlayGameplayRuntimeCompositionSnapshot(runtime, context =
     visualTier: frame.visualTier,
     readabilityOpacity: frame.readabilityOpacity,
     hiddenByClutter: !visibleSet.has(frame),
-    compose: frame.extension.compose === true,
+    compose: frame.contextBehavior?.compose === true,
     isActive: frame.isActive === true,
     overlayId: frame.extension.overlayId,
     slot: frame.slot,
@@ -614,7 +704,7 @@ export function stepOverlayGameplayRuntime(runtime, context = {}) {
   }
 
   const activeOverlayId = String(context.activeOverlayId || '').trim();
-  const frames = getComposedRuntimeFrames(runtime, activeOverlayId);
+  const frames = getComposedRuntimeFrames(runtime, activeOverlayId, context);
   if (frames.length === 0) {
     return 0;
   }
@@ -633,7 +723,7 @@ export function stepOverlayGameplayRuntime(runtime, context = {}) {
           count: frames.length,
           registrationIndex: frame.registrationIndex,
           layerOrder: frame.extension.layerOrder,
-          compose: frame.extension.compose === true,
+          compose: frame.contextBehavior?.compose === true,
           isActive: frame.isActive === true,
           slot: frame.slot || null,
         },
@@ -661,7 +751,7 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
   const frames = applyCompositionReadabilityLimits(
     deriveRenderHierarchy(
       attachCompositionSlots(
-        getComposedRuntimeFrames(runtime, activeOverlayId),
+        getComposedRuntimeFrames(runtime, activeOverlayId, context),
         context.renderer,
         safeZones,
         context
@@ -692,7 +782,7 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
           visualTier: frame.visualTier,
           readabilityOpacity: frame.readabilityOpacity,
           hiddenByClutter: frame.hiddenByClutter === true,
-          compose: frame.extension.compose === true,
+          compose: frame.contextBehavior?.compose === true,
           isActive: frame.isActive === true,
           slot: frame.slot,
         },

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -182,8 +182,65 @@ function assertDynamicPanelSizingCapability() {
   assert.equal(fallbackSnapshot[0].slot.height, 98, 'Resolver failures should preserve compatibility via configured height fallback.');
 }
 
+function assertContextAwareOverlayBehavior() {
+  const framework = createPhase19OverlayExpansionFramework();
+  framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-context-aware',
+    overlays: [
+      { id: 'ui', label: 'UI' },
+      { id: 'runtime', label: 'Runtime' },
+    ],
+    initialOverlayId: 'ui',
+    runtimeExtensions: [
+      {
+        overlayId: 'runtime',
+        compose: true,
+        panelWidth: 220,
+        panelHeight: 90,
+        onRender() {},
+        resolveContextBehavior(context) {
+          const phase = String(context?.gameplayState?.phase || '').trim();
+          if (phase !== 'combat') {
+            return {
+              visible: false,
+            };
+          }
+          return {
+            visible: true,
+            compose: true,
+            panelWidth: 312,
+            panelHeight: 104,
+          };
+        },
+      },
+    ],
+  }));
+
+  const runtime = framework.createRuntimeForExtension('phase19-overlay-context-aware');
+  const hiddenSnapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
+    activeOverlayId: 'runtime',
+    renderer: createRendererProbe(960, 540),
+    gameplayState: { phase: 'menu' },
+  });
+  assert.equal(hiddenSnapshot.length, 0, 'Context-aware runtime should hide overlay when gameplay phase is not combat.');
+
+  const visibleSnapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
+    activeOverlayId: 'runtime',
+    renderer: createRendererProbe(960, 540),
+    scene: {
+      getGameplayState() {
+        return { phase: 'combat' };
+      },
+    },
+  });
+  assert.equal(visibleSnapshot.length, 1, 'Context-aware runtime should detect gameplay state from scene and show overlay.');
+  assert.equal(visibleSnapshot[0].slot.width, 312, 'Context-aware runtime should adapt panel width from gameplay state behavior.');
+  assert.equal(visibleSnapshot[0].slot.height, 104, 'Context-aware runtime should adapt panel height from gameplay state behavior.');
+}
+
 export function run() {
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
   assertDynamicPanelSizingCapability();
+  assertContextAwareOverlayBehavior();
 }