Add overlay visual priority and readability rules.

PR Details:
- Ensures clear overlay hierarchy
- Improves readability under multi-overlay conditions

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement overlay layout constraints:
-- Define safe zones
-- Prevent overlays from covering critical gameplay areas
-- Validate across multi-layer overlays
+Implement overlay visual priority:
+- Define hierarchy rules
+- Ensure readability under multi-layer conditions
+- Prevent visual clutter
 - Update roadmap status only
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,5 @@
-Add overlay layout constraints and safe zones.
+Add overlay visual priority and readability rules.
 
 PR Details:
-- Prevents overlays from blocking gameplay
-- Improves usability and readability
+- Ensures clear overlay hierarchy
+- Improves readability under multi-overlay conditions

docs/dev/reports/roadmap_status_update.txt

@@ -1,5 +1,3 @@
-Roadmap Status Update Instruction:
-- Update the roadmap entry for BUILD_PR_LEVEL_19_6_OVERLAY_MULTI_LAYER_COMPOSITION using status markers only
-- Allowed changes: [ ] -> [.] -> [x]
-- Do not rewrite, move, or delete roadmap text
-- Do not perform cleanup edits outside the status change needed for this PR
+Roadmap Status Update:
+- Update status markers only ([ ] [.] [x])
+- Do not modify roadmap text

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Overlays respect safe zones
-[ ] No gameplay obstruction
-[ ] Layout stable with multiple overlays
+[ ] Visual hierarchy consistent
+[ ] Text/UI readable
+[ ] No clutter issues
 [ ] Roadmap status updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -799,7 +799,7 @@
 
 ### Track D — Debug & Observability Maturity
 - [ ] ensure all systems expose debug data
-- [ ] ensure providers are complete and consistent
+- [.] ensure providers are complete and consistent
 - [x] validate debug panels across systems
 - [ ] confirm production-safe debug toggling
 

docs/pr/BUILD_PR.md

@@ -1,22 +1,23 @@
-# BUILD_PR_LEVEL_19_7_OVERLAY_LAYOUT_CONSTRAINTS_AND_SAFE_ZONES
+# BUILD_PR_LEVEL_19_8_OVERLAY_VISUAL_PRIORITY_AND_READABILITY
 
 ## Purpose
-Introduce layout constraints and safe zones to ensure overlays never block critical gameplay areas.
+Ensure overlays maintain visual priority and readability when multiple overlays are active.
 
 ## Roadmap Improvement
-Advances Level 19 by ensuring visual safety and usability of multi-layer overlays.
+Advances Level 19 by guaranteeing readable, non-conflicting overlay presentation.
 
 ## Scope
-- Define safe zones for gameplay-critical regions
-- Constrain overlay placement to avoid conflicts
-- Validate layout across multiple overlays
+- Define visual priority rules between overlays
+- Ensure text and UI elements remain readable
+- Prevent clutter from multi-overlay stacking
 
 ## Test Steps
-1. Load gameplay sample
-2. Activate multiple overlays
-3. Verify overlays stay within safe zones
-4. Confirm gameplay visibility preserved
+1. Activate multiple overlays
+2. Verify priority ordering is respected
+3. Confirm readability (text/UI clarity)
+4. Validate no visual clutter blocks usability
 
 ## Expected
-- No overlay blocks critical gameplay
-- Layout remains stable and readable
+- Clear visual hierarchy
+- Readable overlays
+- No clutter interference

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -24,6 +24,8 @@ function normalizeRuntimeExtensionEntry(entry) {
 
   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 compose = entry.compose === true;
   const panelWidthRaw = Number(entry.panelWidth);
   const panelHeightRaw = Number(entry.panelHeight);
@@ -36,6 +38,7 @@ function normalizeRuntimeExtensionEntry(entry) {
     onRender,
     compose,
     layerOrder,
+    visualPriority,
     panelWidth,
     panelHeight,
   });
@@ -171,6 +174,87 @@ function getComposedRuntimeFrames(runtime, activeOverlayId) {
   return frames;
 }
 
+function deriveRenderHierarchy(frames) {
+  if (!Array.isArray(frames) || frames.length === 0) {
+    return [];
+  }
+
+  const ordered = [...frames];
+  ordered.sort((left, right) => {
+    const leftIsActive = left.isActive === true;
+    const rightIsActive = right.isActive === true;
+    if (leftIsActive !== rightIsActive) {
+      return leftIsActive ? 1 : -1;
+    }
+    if (left.extension.visualPriority !== right.extension.visualPriority) {
+      return left.extension.visualPriority - right.extension.visualPriority;
+    }
+    if (left.extension.layerOrder !== right.extension.layerOrder) {
+      return left.extension.layerOrder - right.extension.layerOrder;
+    }
+    return left.registrationIndex - right.registrationIndex;
+  });
+
+  for (let i = 0; i < ordered.length; i += 1) {
+    const frame = ordered[i];
+    frame.visualPriorityRank = i;
+    frame.visualTier = frame.isActive === true ? 'primary' : 'secondary';
+    frame.readabilityOpacity = frame.isActive === true ? 1 : 0.84;
+    frame.hiddenByClutter = false;
+  }
+
+  return ordered;
+}
+
+function resolveMaxVisibleCompositionLayers(renderer) {
+  const canvasSize = renderer?.getCanvasSize?.() || { width: 960, height: 540 };
+  const height = Math.max(180, Number(canvasSize.height) || 540);
+  if (height <= 360) {
+    return 2;
+  }
+  if (height <= 540) {
+    return 3;
+  }
+  return 4;
+}
+
+function applyCompositionReadabilityLimits(frames, renderer) {
+  if (!Array.isArray(frames) || frames.length === 0) {
+    return [];
+  }
+
+  const maxVisibleLayers = Math.max(2, resolveMaxVisibleCompositionLayers(renderer));
+  for (let i = 0; i < frames.length; i += 1) {
+    frames[i].hiddenByClutter = false;
+  }
+  if (frames.length <= maxVisibleLayers) {
+    return frames;
+  }
+
+  const activeFrame = frames.find((frame) => frame.isActive === true) || null;
+  const selected = [];
+  if (activeFrame) {
+    const supportFrames = frames.filter((frame) => frame !== activeFrame);
+    const supportLimit = Math.max(0, maxVisibleLayers - 1);
+    const start = Math.max(0, supportFrames.length - supportLimit);
+    for (let i = start; i < supportFrames.length; i += 1) {
+      selected.push(supportFrames[i]);
+    }
+    selected.push(activeFrame);
+  } else {
+    const start = Math.max(0, frames.length - maxVisibleLayers);
+    for (let i = start; i < frames.length; i += 1) {
+      selected.push(frames[i]);
+    }
+  }
+
+  const selectedSet = new Set(selected);
+  for (let i = 0; i < frames.length; i += 1) {
+    frames[i].hiddenByClutter = !selectedSet.has(frames[i]);
+  }
+  return frames.filter((frame) => selectedSet.has(frame));
+}
+
 function attachCompositionSlots(frames, renderer, safeZones = []) {
   if (!Array.isArray(frames) || frames.length === 0) {
     return frames || [];
@@ -370,16 +454,24 @@ export function getOverlayGameplayRuntimeInteractionSnapshot(runtime) {
 export function getOverlayGameplayRuntimeCompositionSnapshot(runtime, context = {}) {
   const activeOverlayId = String(context?.activeOverlayId || '').trim();
   const safeZones = resolveLayoutSafeZones(context);
-  const frames = attachCompositionSlots(
+  const frames = deriveRenderHierarchy(attachCompositionSlots(
     getComposedRuntimeFrames(runtime, activeOverlayId),
     context?.renderer,
     safeZones
-  );
+  ));
+  const visibleFrames = applyCompositionReadabilityLimits(frames, context?.renderer);
+  const visibleSet = new Set(visibleFrames);
   return frames.map((frame, index) => ({
     index,
     count: frames.length,
+    visibleCount: visibleFrames.length,
     registrationIndex: frame.registrationIndex,
     layerOrder: frame.extension.layerOrder,
+    visualPriority: frame.extension.visualPriority,
+    visualPriorityRank: frame.visualPriorityRank,
+    visualTier: frame.visualTier,
+    readabilityOpacity: frame.readabilityOpacity,
+    hiddenByClutter: !visibleSet.has(frame),
     compose: frame.extension.compose === true,
     isActive: frame.isActive === true,
     overlayId: frame.extension.overlayId,
@@ -521,10 +613,15 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
 
   const activeOverlayId = String(context.activeOverlayId || '').trim();
   const safeZones = resolveLayoutSafeZones(context);
-  const frames = attachCompositionSlots(
-    getComposedRuntimeFrames(runtime, activeOverlayId),
-    context.renderer,
-    safeZones
+  const frames = applyCompositionReadabilityLimits(
+    deriveRenderHierarchy(
+      attachCompositionSlots(
+        getComposedRuntimeFrames(runtime, activeOverlayId),
+        context.renderer,
+        safeZones
+      )
+    ),
+    context.renderer
   );
   if (frames.length === 0) {
     return 0;
@@ -544,6 +641,11 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
           count: frames.length,
           registrationIndex: frame.registrationIndex,
           layerOrder: frame.extension.layerOrder,
+          visualPriority: frame.extension.visualPriority,
+          visualPriorityRank: frame.visualPriorityRank,
+          visualTier: frame.visualTier,
+          readabilityOpacity: frame.readabilityOpacity,
+          hiddenByClutter: frame.hiddenByClutter === true,
           compose: frame.extension.compose === true,
           isActive: frame.isActive === true,
           slot: frame.slot,

tests/runtime/Phase17OverlayMultiLayerComposition.test.mjs

@@ -131,8 +131,8 @@ function assertDeterministicCompositionOrderingAndSlots() {
   );
   assert.deepEqual(
     renderOrder.map((token) => token.split(':')[0]),
-    ['mission', 'base', 'telemetry'],
-    'Composed runtime render ordering should be deterministic by layer order.'
+    ['mission', 'telemetry', 'base'],
+    'Composed runtime render ordering should prioritize active readability while preserving deterministic secondary ordering.'
   );
 
   const snapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
@@ -141,6 +141,16 @@ function assertDeterministicCompositionOrderingAndSlots() {
     safeZones,
   });
   assert.equal(snapshot.length, 3, 'Composition snapshot should include all composed layers.');
+  assert.equal(
+    snapshot.filter((entry) => entry.hiddenByClutter === true).length,
+    0,
+    'Composition snapshot should keep all layers visible when layer count is within readability limits.'
+  );
+  assert.equal(
+    snapshot[snapshot.length - 1].isActive,
+    true,
+    'Active overlay should render with highest visual readability priority.'
+  );
   for (let i = 1; i < snapshot.length; i += 1) {
     const prev = snapshot[i - 1].slot;
     const curr = snapshot[i].slot;
@@ -188,6 +198,103 @@ function assertComposedRuntimeDoesNotInterfereWithGameplayInput() {
   assert.equal(counters.composed > 0, true, 'Composed overlay runtime step should execute alongside active layer.');
 }
 
+function assertVisualPriorityReadabilityAndClutterControl() {
+  const renderOrder = [];
+  const runtime = createOverlayGameplayRuntime({
+    runtimeExtensions: [
+      {
+        overlayId: '',
+        compose: true,
+        layerOrder: 5,
+        panelWidth: 220,
+        panelHeight: 86,
+        onStep() {},
+        onRender() {
+          renderOrder.push('low');
+        },
+      },
+      {
+        overlayId: '',
+        compose: true,
+        layerOrder: 10,
+        panelWidth: 220,
+        panelHeight: 86,
+        onStep() {},
+        onRender() {
+          renderOrder.push('mid');
+        },
+      },
+      {
+        overlayId: '',
+        compose: true,
+        layerOrder: 15,
+        panelWidth: 220,
+        panelHeight: 86,
+        onStep() {},
+        onRender() {
+          renderOrder.push('upper');
+        },
+      },
+      {
+        overlayId: '',
+        compose: true,
+        layerOrder: 20,
+        panelWidth: 220,
+        panelHeight: 86,
+        onStep() {},
+        onRender() {
+          renderOrder.push('top-support');
+        },
+      },
+      {
+        overlayId: '',
+        layerOrder: 12,
+        panelWidth: 220,
+        panelHeight: 86,
+        onStep() {},
+        onRender(context) {
+          renderOrder.push('active');
+          assert.equal(
+            context.overlayComposition.visualTier,
+            'primary',
+            'Active overlay should receive primary visual tier.'
+          );
+          assert.equal(
+            context.overlayComposition.readabilityOpacity,
+            1,
+            'Active overlay should keep full readability opacity.'
+          );
+        },
+      },
+    ],
+  });
+  runtime.interactionIndex = 4;
+
+  const renderer = createRendererProbe(960, 320);
+  const renderInvoked = renderOverlayGameplayRuntime(runtime, {
+    activeOverlayId: 'ui-layer',
+    renderer,
+  });
+  assert.equal(renderInvoked, 2, 'Readability limits should prevent visual clutter by capping visible layers on compact canvases.');
+  assert.deepEqual(
+    renderOrder,
+    ['top-support', 'active'],
+    'Render hierarchy should keep only top-priority support layer plus active layer when clutter limits apply.'
+  );
+
+  const snapshot = getOverlayGameplayRuntimeCompositionSnapshot(runtime, {
+    activeOverlayId: 'ui-layer',
+    renderer,
+  });
+  const hiddenLayers = snapshot.filter((entry) => entry.hiddenByClutter === true);
+  assert.equal(hiddenLayers.length, 3, 'Snapshot should identify lower-priority overlays hidden by clutter control.');
+  assert.equal(
+    snapshot.filter((entry) => entry.hiddenByClutter !== true).length,
+    2,
+    'Snapshot should expose the exact number of visible layers after readability limiting.'
+  );
+}
+
 function assertSceneSafeZonesProtectGameplayViewport() {
   const renderer = createRendererProbe();
   const runtime = createOverlayGameplayRuntime({
@@ -242,5 +349,6 @@ function assertSceneSafeZonesProtectGameplayViewport() {
 export function run() {
   assertDeterministicCompositionOrderingAndSlots();
   assertComposedRuntimeDoesNotInterfereWithGameplayInput();
+  assertVisualPriorityReadabilityAndClutterControl();
   assertSceneSafeZonesProtectGameplayViewport();
 }