Level 19.1 overlay system expansion framework.

Introduce extension points for future overlay types.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,10 +1,10 @@
 MODEL: GPT-5.4-codex
-REASONING: low
+REASONING: medium
 
 COMMAND:
-Promote Level 18 overlay system to baseline.
-- Update status markers only
-- Confirm no regressions
-- Do not change runtime behavior
+Implement overlay expansion framework:
+- Define extension interfaces/contracts
+- Ensure compatibility with config-driven overlays
+- Do not change existing behavior
 
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1,2 @@
-Promote Level 18 overlay system to baseline after final validation.
+Level 19.1 overlay system expansion framework.
+Introduce extension points for future overlay types.

docs/dev/reports/BUILD_PR_LEVEL_19_1_OVERLAY_SYSTEM_EXPANSION_FRAMEWORK_report.md

@@ -0,0 +1,40 @@
+# BUILD_PR_LEVEL_19_1_OVERLAY_SYSTEM_EXPANSION_FRAMEWORK Report
+
+## Purpose
+Establish a reusable overlay expansion framework with explicit contracts while keeping current runtime behavior unchanged.
+
+## Extension Contracts
+- `samples/phase-17/shared/overlayExpansionContracts.js`
+  - `defineOverlayExtensionContract(...)`
+  - `createOverlayExtensionContractMap(...)`
+  - `getOverlayControllerConfigFromContract(...)`
+
+Contract fields:
+- `id`
+- `channel`
+- `overlays` (`{ id, label }[]`)
+- `initialOverlayId`
+- `cycleKey`
+- `persistenceKey`
+- `metadata`
+
+## Integration Pattern (Config-Driven Compatibility)
+1. Define overlay contracts with `defineOverlayExtensionContract(...)`.
+2. Group contracts in a map with `createOverlayExtensionContractMap(...)`.
+3. Derive controller-ready configs through `getOverlayControllerConfigFromContract(...)`.
+4. Keep scene wiring unchanged by continuing to consume the existing stack-config shape:
+   - `overlays`
+   - `initialOverlayId`
+   - `cycleKey`
+   - `persistenceKey`
+
+## Level 17 Adoption
+- `samples/phase-17/shared/overlayStackBySampleConfig.js`
+  - now sources sample stack configs from the new contract definitions
+  - exports extension accessors:
+    - `getLevel17OverlayExtensionContract(sampleId)`
+    - `listLevel17OverlayExtensionContracts()`
+
+## Behavior Impact
+- No runtime behavior changes intended.
+- Overlay ordering, cycle key behavior, persistence, and panel rendering remain unchanged.

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Smoke test complete
-[ ] All integrations stable
-[ ] No regressions
-[ ] Baseline confirmed
+[ ] Existing overlays load
+[ ] Extension points defined
+[ ] No regression
+[ ] Config compatibility maintained

docs/pr/BUILD_PR.md

@@ -1,21 +1,30 @@
-# BUILD_PR_LEVEL_18_10_OVERLAY_PROMOTE_BASELINE
-
-## Purpose
-Promote Level 18 overlay system to baseline after successful validation.
-
-## Scope
-- Mark Level 18 as complete
-- Confirm baseline:
-  - Config-driven stacks
-  - Non-Tab cycle key
-  - Bottom-right placement
-  - Mission + telemetry integration
-  - Diagnostics and persistence
-
-## Test Steps
-1. Smoke test all samples
-2. Verify integrations remain stable
-3. Confirm no regressions
-
-## Expected
-- Stable production-ready baseline
+# BUILD_PR_LEVEL_19_1_OVERLAY_SYSTEM_EXPANSION_FRAMEWORK
+
+## PLAN
+
+### Purpose
+Establish a framework for expanding the overlay system beyond debug use into reusable gameplay and tool overlays.
+
+### Goals
+- Define extension points for new overlays
+- Ensure compatibility with existing config-driven system
+- Maintain strict separation between debug and gameplay overlays
+
+---
+
+## BUILD
+
+### Scope
+- Define overlay extension interface/contracts
+- Document integration pattern for new overlays
+- Ensure existing overlays conform to framework
+- No behavior change
+
+### Test Steps
+1. Validate existing overlays still load
+2. Confirm extension points available
+3. Verify no regression
+
+### Expected
+- Overlay system ready for expansion
+- No impact to existing behavior

samples/phase-17/shared/overlayExpansionContracts.js

@@ -0,0 +1,109 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+overlayExpansionContracts.js
+*/
+
+const DEFAULT_CHANNEL = 'debug';
+
+function normalizeOverlayEntry(entry) {
+  const id = String(entry?.id ?? '').trim();
+  if (!id) {
+    return null;
+  }
+  const label = String(entry?.label ?? id).trim() || id;
+  return { id, label };
+}
+
+function normalizeOverlayStack(overlays) {
+  const normalized = [];
+  for (let i = 0; i < overlays.length; i += 1) {
+    const candidate = normalizeOverlayEntry(overlays[i]);
+    if (!candidate) {
+      continue;
+    }
+    if (normalized.some((overlay) => overlay.id === candidate.id)) {
+      continue;
+    }
+    normalized.push(candidate);
+  }
+  return normalized;
+}
+
+function resolveInitialOverlayId(overlays, initialOverlayId) {
+  if (overlays.length === 0) {
+    return '';
+  }
+
+  const requestedId = String(initialOverlayId || '').trim();
+  if (!requestedId) {
+    return overlays[0].id;
+  }
+
+  const exists = overlays.some((overlay) => overlay.id === requestedId);
+  return exists ? requestedId : overlays[0].id;
+}
+
+export function defineOverlayExtensionContract({
+  id = '',
+  overlays = [],
+  initialOverlayId = '',
+  cycleKey = '',
+  persistenceKey = '',
+  channel = DEFAULT_CHANNEL,
+  metadata = {},
+} = {}) {
+  const normalizedId = String(id || '').trim();
+  if (!normalizedId) {
+    throw new Error('Overlay extension contract requires a non-empty id.');
+  }
+
+  const normalizedOverlays = normalizeOverlayStack(Array.isArray(overlays) ? overlays : []);
+  if (normalizedOverlays.length === 0) {
+    throw new Error(`Overlay extension contract "${normalizedId}" requires at least one overlay entry.`);
+  }
+
+  const normalizedCycleKey = String(cycleKey || '').trim();
+  const normalizedPersistenceKey = String(persistenceKey || '').trim();
+  const normalizedChannel = String(channel || DEFAULT_CHANNEL).trim() || DEFAULT_CHANNEL;
+  const normalizedInitialOverlayId = resolveInitialOverlayId(normalizedOverlays, initialOverlayId);
+
+  return Object.freeze({
+    id: normalizedId,
+    channel: normalizedChannel,
+    overlays: Object.freeze(normalizedOverlays),
+    initialOverlayId: normalizedInitialOverlayId,
+    cycleKey: normalizedCycleKey,
+    persistenceKey: normalizedPersistenceKey,
+    metadata: Object.freeze({ ...(metadata || {}) }),
+  });
+}
+
+export function createOverlayExtensionContractMap(contracts = []) {
+  const map = new Map();
+  for (let i = 0; i < contracts.length; i += 1) {
+    const contract = contracts[i];
+    if (!contract || typeof contract !== 'object') {
+      continue;
+    }
+    const id = String(contract.id || '').trim();
+    if (!id) {
+      continue;
+    }
+    map.set(id, contract);
+  }
+  return map;
+}
+
+export function getOverlayControllerConfigFromContract(contract) {
+  if (!contract || typeof contract !== 'object') {
+    throw new Error('Overlay contract is required to resolve overlay controller config.');
+  }
+  return Object.freeze({
+    overlays: contract.overlays,
+    initialOverlayId: contract.initialOverlayId,
+    cycleKey: contract.cycleKey,
+    persistenceKey: contract.persistenceKey,
+  });
+}

samples/phase-17/shared/overlayStackBySampleConfig.js

@@ -13,33 +13,48 @@ import {
   OVERLAY_MOVEMENT_RUNTIME,
   createMovementOverlayCycleMap,
 } from '/samples/phase-17/shared/movementOverlayStack.js';
+import {
+  createOverlayExtensionContractMap,
+  defineOverlayExtensionContract,
+  getOverlayControllerConfigFromContract,
+} from '/samples/phase-17/shared/overlayExpansionContracts.js';
 
-const SAMPLE_OVERLAY_STACKS = Object.freeze({
-  '1708': Object.freeze({
+const LEVEL17_OVERLAY_EXTENSION_CONTRACTS = Object.freeze([
+  defineOverlayExtensionContract({
+    id: '1708',
+    channel: 'debug',
     overlays: Object.freeze(createMiniGameOverlayCycleMap()),
     initialOverlayId: OVERLAY_UI_LAYER,
     persistenceKey: 'phase17:1708:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-  '1709': Object.freeze({
+  defineOverlayExtensionContract({
+    id: '1709',
+    channel: 'debug',
     overlays: Object.freeze(createMovementOverlayCycleMap()),
     initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
     persistenceKey: 'phase17:1709:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-  '1710': Object.freeze({
+  defineOverlayExtensionContract({
+    id: '1710',
+    channel: 'debug',
     overlays: Object.freeze(createMiniGameOverlayCycleMap()),
     initialOverlayId: OVERLAY_UI_LAYER,
     persistenceKey: 'phase17:1710:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-  '1711': Object.freeze({
+  defineOverlayExtensionContract({
+    id: '1711',
+    channel: 'debug',
     overlays: Object.freeze(createMovementOverlayCycleMap()),
     initialOverlayId: OVERLAY_MOVEMENT_RUNTIME,
     persistenceKey: 'phase17:1711:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-  '1712': Object.freeze({
+  defineOverlayExtensionContract({
+    id: '1712',
+    channel: 'debug',
     overlays: Object.freeze([
       { id: 'ui-layer', label: 'UI Layer' },
       { id: 'mission-feed', label: 'Mission Feed' },
@@ -50,7 +65,9 @@ const SAMPLE_OVERLAY_STACKS = Object.freeze({
     persistenceKey: 'phase17:1712:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-  '1713': Object.freeze({
+  defineOverlayExtensionContract({
+    id: '1713',
+    channel: 'debug',
     overlays: Object.freeze([
       { id: 'ui-layer', label: 'UI Layer' },
       { id: 'mission-feed', label: 'Mission Feed' },
@@ -61,7 +78,30 @@ const SAMPLE_OVERLAY_STACKS = Object.freeze({
     persistenceKey: 'phase17:1713:overlay-index',
     cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
   }),
-});
+]);
+
+const LEVEL17_OVERLAY_EXTENSION_CONTRACT_MAP = createOverlayExtensionContractMap(LEVEL17_OVERLAY_EXTENSION_CONTRACTS);
+
+const SAMPLE_OVERLAY_STACKS = Object.freeze(
+  Object.fromEntries(
+    Array.from(LEVEL17_OVERLAY_EXTENSION_CONTRACT_MAP.entries(), ([sampleId, contract]) => [
+      sampleId,
+      getOverlayControllerConfigFromContract(contract),
+    ])
+  )
+);
+
+export function getLevel17OverlayExtensionContract(sampleId) {
+  const id = String(sampleId || '').trim();
+  if (!id) {
+    return null;
+  }
+  return LEVEL17_OVERLAY_EXTENSION_CONTRACT_MAP.get(id) ?? null;
+}
+
+export function listLevel17OverlayExtensionContracts() {
+  return LEVEL17_OVERLAY_EXTENSION_CONTRACTS;
+}
 
 export function getLevel17OverlayStackConfig(sampleId) {
   return SAMPLE_OVERLAY_STACKS[String(sampleId || '').trim()] ?? null;

tests/runtime/Phase17OverlayExpansionFramework.test.mjs

@@ -0,0 +1,61 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase17OverlayExpansionFramework.test.mjs
+*/
+import assert from 'node:assert/strict';
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
+import {
+  defineOverlayExtensionContract,
+  getOverlayControllerConfigFromContract,
+} from '../../samples/phase-17/shared/overlayExpansionContracts.js';
+import {
+  getLevel17OverlayExtensionContract,
+  getLevel17OverlayStackConfig,
+  listLevel17OverlayExtensionContracts,
+} from '../../samples/phase-17/shared/overlayStackBySampleConfig.js';
+
+function assertLevel17ContractsMatchControllerConfigs() {
+  const contracts = listLevel17OverlayExtensionContracts();
+  assert.equal(contracts.length, 6, 'Level 17 overlay extension contracts should be defined for samples 1708-1713.');
+
+  for (let sampleId = 1708; sampleId <= 1713; sampleId += 1) {
+    const key = String(sampleId);
+    const contract = getLevel17OverlayExtensionContract(key);
+    const config = getLevel17OverlayStackConfig(key);
+    assert.equal(Boolean(contract), true, `Overlay extension contract should exist for sample ${key}.`);
+    assert.equal(Boolean(config), true, `Overlay controller config should exist for sample ${key}.`);
+
+    const resolved = getOverlayControllerConfigFromContract(contract);
+    assert.deepEqual(resolved, config, `Overlay controller config for sample ${key} should be derived from extension contract.`);
+    assert.equal(contract.cycleKey, LEVEL17_OVERLAY_CYCLE_KEY, `Overlay contract for sample ${key} should use shared cycle key.`);
+  }
+}
+
+function assertContractNormalizationForExpansionPath() {
+  const contract = defineOverlayExtensionContract({
+    id: 'future-sample',
+    overlays: [
+      { id: 'runtime', label: 'Runtime' },
+      { id: 'runtime', label: 'Duplicate Runtime' },
+      { id: 'hud', label: 'HUD' },
+    ],
+    initialOverlayId: 'missing-id',
+    cycleKey: 'KeyG',
+    persistenceKey: 'phaseX:future:overlay-index',
+    channel: 'gameplay',
+    metadata: { family: 'future-track' },
+  });
+
+  assert.equal(contract.id, 'future-sample', 'Contract id should be preserved.');
+  assert.equal(contract.channel, 'gameplay', 'Contract channel should be preserved.');
+  assert.equal(contract.overlays.length, 2, 'Contract normalization should dedupe duplicate overlay ids.');
+  assert.equal(contract.initialOverlayId, 'runtime', 'Missing initial overlay id should fall back to first normalized overlay.');
+  assert.equal(contract.metadata.family, 'future-track', 'Contract metadata should be retained.');
+}
+
+export function run() {
+  assertLevel17ContractsMatchControllerConfigs();
+  assertContractNormalizationForExpansionPath();
+}