Add advanced overlay feature.

PR Details:
- Introduces Level 21 capabilities

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,7 +1,8 @@
 MODEL: GPT-5.4
-REASONING: low
+REASONING: medium
 
 COMMAND:
-Promote Level 20 plugin system to baseline.
-Update roadmap status only.
-Package ZIP to <project folder>/tmp/
+Implement advanced overlay feature:
+- Add one advanced capability
+- Maintain compatibility
+- Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Promote Level 20 plugin system to baseline.
+Add advanced overlay feature.
 
 PR Details:
-- Marks completion of Level 20
+- Introduces Level 21 capabilities

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,3 @@
-[ ] Stable
+[ ] Feature works
 [ ] No regressions
 [ ] 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
+- [.] contract freeze readiness
 - [ ] readiness for long-term maintenance mode

docs/pr/BUILD_PR.md

@@ -1,18 +1,20 @@
-# BUILD_PR_LEVEL_20_10_OVERLAY_PLUGIN_PROMOTE_BASELINE
+# BUILD_PR_LEVEL_21_1_ADVANCED_OVERLAY_FEATURES
 
 ## Purpose
-Promote validated Level 20 plugin system to baseline.
+Introduce advanced overlay capabilities building on plugin system.
 
 ## Roadmap Improvement
-Marks Level 20 complete and production-ready.
+Begins Level 21 advanced feature set.
 
 ## Scope
-- Promote current plugin system
-- Ensure no regression
+- Add one advanced overlay capability (e.g. dynamic resizing or contextual display)
+- Ensure compatibility with plugin system
 
 ## Test Steps
-1. Run plugins
-2. Confirm stability
+1. Activate advanced overlay
+2. Validate behavior
+3. Confirm no regression
 
 ## Expected
-- Stable baseline
+- Advanced overlay works
+- System stable

samples/phase-17/shared/overlayExpansionContracts.js

@@ -53,14 +53,30 @@ function normalizeRuntimeExtensionEntry(entry) {
   const overlayId = String(entry.overlayId || '').trim();
   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;
   if (!onStep && !onRender) {
     return null;
   }
 
+  const layerOrderRaw = Number(entry.layerOrder);
+  const layerOrder = Number.isFinite(layerOrderRaw) ? layerOrderRaw : 0;
+  const visualPriorityRaw = Number(entry.visualPriority);
+  const visualPriority = Number.isFinite(visualPriorityRaw) ? visualPriorityRaw : layerOrder;
+  const panelWidthRaw = Number(entry.panelWidth);
+  const panelHeightRaw = Number(entry.panelHeight);
+  const panelWidth = Number.isFinite(panelWidthRaw) && panelWidthRaw > 0 ? panelWidthRaw : 260;
+  const panelHeight = Number.isFinite(panelHeightRaw) && panelHeightRaw > 0 ? panelHeightRaw : 96;
+
   return Object.freeze({
     overlayId,
     onStep,
     onRender,
+    resolvePanelSize,
+    compose: entry.compose === true,
+    layerOrder,
+    visualPriority,
+    panelWidth,
+    panelHeight,
   });
 }
 

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -31,11 +31,13 @@ function normalizeRuntimeExtensionEntry(entry) {
   const panelHeightRaw = Number(entry.panelHeight);
   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;
 
   return Object.freeze({
     overlayId,
     onStep,
     onRender,
+    resolvePanelSize,
     compose,
     layerOrder,
     visualPriority,
@@ -255,7 +257,37 @@ function applyCompositionReadabilityLimits(frames, renderer) {
   return frames.filter((frame) => selectedSet.has(frame));
 }
 
-function attachCompositionSlots(frames, renderer, safeZones = []) {
+function normalizePanelDimension(value, fallback, minimum) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return Math.max(minimum, fallback);
+  }
+  return Math.max(minimum, numeric);
+}
+
+function resolveDynamicPanelSize(extension, layoutContext, fallbackWidth, fallbackHeight) {
+  if (!extension || typeof extension.resolvePanelSize !== 'function') {
+    return {
+      width: fallbackWidth,
+      height: fallbackHeight,
+    };
+  }
+
+  try {
+    const computed = extension.resolvePanelSize(layoutContext || {});
+    return {
+      width: normalizePanelDimension(computed?.width, fallbackWidth, 120),
+      height: normalizePanelDimension(computed?.height, fallbackHeight, 32),
+    };
+  } catch {
+    return {
+      width: fallbackWidth,
+      height: fallbackHeight,
+    };
+  }
+}
+
+function attachCompositionSlots(frames, renderer, safeZones = [], layoutContext = {}) {
   if (!Array.isArray(frames) || frames.length === 0) {
     return frames || [];
   }
@@ -330,8 +362,20 @@ function attachCompositionSlots(frames, renderer, safeZones = []) {
 
   for (let i = 0; i < frames.length; i += 1) {
     const frame = frames[i];
-    const slotWidth = Math.max(120, Number(frame.extension.panelWidth) || 260);
-    const slotHeight = Math.max(32, Number(frame.extension.panelHeight) || 96);
+    const fallbackWidth = Math.max(120, Number(frame.extension.panelWidth) || 260);
+    const fallbackHeight = Math.max(32, Number(frame.extension.panelHeight) || 96);
+    const dynamicPanelSize = resolveDynamicPanelSize(frame.extension, {
+      ...layoutContext,
+      renderer,
+      canvasSize: { width, height },
+      frameIndex: i,
+      frameCount: frames.length,
+      safeZones,
+    }, fallbackWidth, fallbackHeight);
+    const maxPanelWidth = Math.max(120, width - margin * 2);
+    const maxPanelHeight = Math.max(32, height - margin * 2);
+    const slotWidth = Math.min(maxPanelWidth, Math.max(120, Number(dynamicPanelSize.width) || fallbackWidth));
+    const slotHeight = Math.min(maxPanelHeight, Math.max(32, Number(dynamicPanelSize.height) || fallbackHeight));
     const anchorOrder = ['bottom-right', 'top-right', 'bottom-left', 'top-left'];
 
     let slot = null;
@@ -457,7 +501,8 @@ export function getOverlayGameplayRuntimeCompositionSnapshot(runtime, context =
   const frames = deriveRenderHierarchy(attachCompositionSlots(
     getComposedRuntimeFrames(runtime, activeOverlayId),
     context?.renderer,
-    safeZones
+    safeZones,
+    context
   ));
   const visibleFrames = applyCompositionReadabilityLimits(frames, context?.renderer);
   const visibleSet = new Set(visibleFrames);
@@ -618,7 +663,8 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
       attachCompositionSlots(
         getComposedRuntimeFrames(runtime, activeOverlayId),
         context.renderer,
-        safeZones
+        safeZones,
+        context
       )
     ),
     context.renderer

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 {
+  getOverlayGameplayRuntimeCompositionSnapshot,
   renderOverlayGameplayRuntime,
   stepOverlayGameplayRuntime,
 } from '../../samples/phase-17/shared/overlayGameplayRuntime.js';
@@ -111,7 +112,78 @@ function assertExtensionLifecycleMutations() {
   assert.equal(framework.createRuntimeForExtension('phase19-overlay-seed'), null, 'Removed extension should no longer create runtime.');
 }
 
+function assertDynamicPanelSizingCapability() {
+  const framework = createPhase19OverlayExpansionFramework();
+  framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-dynamic-size',
+    overlays: [
+      { id: 'ui', label: 'UI' },
+      { id: 'runtime', label: 'Runtime' },
+    ],
+    initialOverlayId: 'ui',
+    runtimeExtensions: [
+      {
+        overlayId: 'runtime',
+        panelWidth: 220,
+        panelHeight: 90,
+        onRender() {},
+        resolvePanelSize(layoutContext) {
+          const canvasWidth = Number(layoutContext?.canvasSize?.width) || 0;
+          const canvasHeight = Number(layoutContext?.canvasSize?.height) || 0;
+          return {
+            width: Math.round(canvasWidth * 0.5),
+            height: Math.round(canvasHeight * 0.2),
+          };
+        },
+      },
+    ],
+  }));
+
+  const runtime = framework.createRuntimeForExtension('phase19-overlay-dynamic-size');
+  const wideSnapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
+    activeOverlayId: 'runtime',
+    renderer: createRendererProbe(1000, 600),
+  });
+  assert.equal(wideSnapshot.length, 1, 'Dynamic panel sizing runtime should emit a composed frame snapshot.');
+  assert.equal(wideSnapshot[0].slot.width, 500, 'Dynamic sizing should scale panel width from canvas size.');
+  assert.equal(wideSnapshot[0].slot.height, 120, 'Dynamic sizing should scale panel height from canvas size.');
+
+  const compactSnapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
+    activeOverlayId: 'runtime',
+    renderer: createRendererProbe(600, 400),
+  });
+  assert.equal(compactSnapshot[0].slot.width, 300, 'Dynamic sizing should recompute width for smaller canvases.');
+  assert.equal(compactSnapshot[0].slot.height, 80, 'Dynamic sizing should recompute height for smaller canvases.');
+
+  const fallbackFramework = createPhase19OverlayExpansionFramework();
+  fallbackFramework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-dynamic-size-fallback',
+    overlays: [{ id: 'runtime', label: 'Runtime' }],
+    initialOverlayId: 'runtime',
+    runtimeExtensions: [
+      {
+        overlayId: 'runtime',
+        panelWidth: 234,
+        panelHeight: 98,
+        onRender() {},
+        resolvePanelSize() {
+          throw new Error('resolver failed');
+        },
+      },
+    ],
+  }));
+
+  const fallbackRuntime = fallbackFramework.createRuntimeForExtension('phase19-overlay-dynamic-size-fallback');
+  const fallbackSnapshot = getOverlayGameplayRuntimeCompositionSnapshot(fallbackRuntime, {
+    activeOverlayId: 'runtime',
+    renderer: createRendererProbe(960, 540),
+  });
+  assert.equal(fallbackSnapshot[0].slot.width, 234, 'Resolver failures should preserve compatibility via configured width fallback.');
+  assert.equal(fallbackSnapshot[0].slot.height, 98, 'Resolver failures should preserve compatibility via configured height fallback.');
+}
+
 export function run() {
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
+  assertDynamicPanelSizingCapability();
 }