Introduce overlay system expansion framework.

PR Details:
- Enables future overlay extensibility
- Maintains compatibility with Level 19 baseline

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,7 +1,11 @@
 MODEL: GPT-5.4
-REASONING: low
+REASONING: medium
 
 COMMAND:
-Promote Level 19 overlay system to baseline.
-Update roadmap status only.
+Create overlay expansion framework:
+- Define extension points
+- Ensure compatibility with existing overlay system
+- Add minimal testable example
+- Update roadmap status only
+
 Package ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,5 @@
-Promote Level 19 overlay system to baseline.
+Introduce overlay system expansion framework.
 
 PR Details:
-- Marks completion of Level 19
-- Locks validated state
+- Enables future overlay extensibility
+- Maintains compatibility with Level 19 baseline

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,4 @@
-[ ] System stable
+[ ] Extension works
 [ ] No regressions
+[ ] Gameplay unaffected
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -818,7 +818,7 @@
 - [ ] confirm no regression across phases
 
 ### Track G — Extensibility Readiness
-- [ ] validate plugin/extension patterns
+- [.] validate plugin/extension patterns
 - [ ] validate adding new systems is clean
 - [ ] validate external integration points
 - [ ] ensure future phases can build cleanly

docs/pr/BUILD_PR.md

@@ -1,19 +1,21 @@
-# BUILD_PR_LEVEL_19_10_OVERLAY_PROMOTE_BASELINE
+# BUILD_PR_LEVEL_20_1_OVERLAY_SYSTEM_EXPANSION
 
 ## Purpose
-Promote validated Level 19 overlay system to baseline.
+Begin Level 20 by introducing a controlled expansion framework for new overlay types.
 
 ## Roadmap Improvement
-Marks Level 19 complete and production-ready.
+Transitions from stable baseline (Level 19) to extensible overlay architecture.
 
 ## Scope
-- Promote current implementation as baseline
-- Ensure no regression from validation state
+- Define extension points for new overlays
+- Ensure compatibility with existing systems
+- Validate one sample extension
 
 ## Test Steps
-1. Run gameplay with overlays
-2. Confirm all systems stable
+1. Load gameplay
+2. Register new overlay via extension
+3. Validate rendering + interaction
 
 ## Expected
-- Stable baseline
-- Ready for next level
+- New overlays plug in cleanly
+- No regression

samples/phase-19/shared/overlay/createPhase19OverlayExpansionFramework.js

@@ -0,0 +1,130 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19OverlayExpansionFramework.js
+*/
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '/samples/phase-17/shared/overlayCycleInput.js';
+import {
+  defineOverlayExtensionContract,
+  getOverlayControllerConfigFromContract,
+} from '/samples/phase-17/shared/overlayExpansionContracts.js';
+import { createOverlayGameplayRuntime } from '/samples/phase-17/shared/overlayGameplayRuntime.js';
+
+const DEFAULT_CHANNEL = 'gameplay';
+
+function normalizeContractId(contractId) {
+  return String(contractId || '').trim();
+}
+
+export function definePhase19OverlayExtension({
+  id = '',
+  overlays = [],
+  initialOverlayId = '',
+  cycleKey = LEVEL17_OVERLAY_CYCLE_KEY,
+  persistenceKey = '',
+  channel = DEFAULT_CHANNEL,
+  runtimeExtensions = [],
+  metadata = {},
+} = {}) {
+  return defineOverlayExtensionContract({
+    id,
+    overlays,
+    initialOverlayId,
+    cycleKey: String(cycleKey || LEVEL17_OVERLAY_CYCLE_KEY).trim() || LEVEL17_OVERLAY_CYCLE_KEY,
+    persistenceKey,
+    channel: String(channel || DEFAULT_CHANNEL).trim() || DEFAULT_CHANNEL,
+    runtimeExtensions,
+    metadata: {
+      phase: '19',
+      ...(metadata || {}),
+    },
+  });
+}
+
+function normalizeExtensionContract(candidate) {
+  if (!candidate || typeof candidate !== 'object') {
+    throw new Error('Overlay extension registration requires a contract-like object.');
+  }
+
+  const id = normalizeContractId(candidate.id);
+  if (!id || !Array.isArray(candidate.overlays)) {
+    throw new Error('Overlay extension registration requires contract id and overlays.');
+  }
+
+  if (Object.isFrozen(candidate) && typeof candidate.initialOverlayId === 'string') {
+    return candidate;
+  }
+
+  return definePhase19OverlayExtension(candidate);
+}
+
+export default function createPhase19OverlayExpansionFramework({ extensions = [] } = {}) {
+  const contractMap = new Map();
+
+  function registerExtension(extension) {
+    const contract = normalizeExtensionContract(extension);
+    contractMap.set(contract.id, contract);
+    return contract;
+  }
+
+  function unregisterExtension(id) {
+    const normalizedId = normalizeContractId(id);
+    if (!normalizedId) {
+      return false;
+    }
+    return contractMap.delete(normalizedId);
+  }
+
+  function getExtension(id) {
+    const normalizedId = normalizeContractId(id);
+    if (!normalizedId) {
+      return null;
+    }
+    return contractMap.get(normalizedId) ?? null;
+  }
+
+  function listExtensions() {
+    return Object.freeze(Array.from(contractMap.values()));
+  }
+
+  function listExtensionIds() {
+    return Object.freeze(Array.from(contractMap.keys()));
+  }
+
+  function getControllerConfig(id) {
+    const extension = getExtension(id);
+    if (!extension) {
+      return null;
+    }
+    return getOverlayControllerConfigFromContract(extension);
+  }
+
+  function createRuntimeForExtension(id) {
+    const extension = getExtension(id);
+    if (!extension) {
+      return null;
+    }
+    const runtime = createOverlayGameplayRuntime({
+      runtimeExtensions: extension.runtimeExtensions,
+    });
+    runtime.interactionCycleKey = String(extension.cycleKey || LEVEL17_OVERLAY_CYCLE_KEY);
+    return runtime;
+  }
+
+  if (Array.isArray(extensions)) {
+    for (let i = 0; i < extensions.length; i += 1) {
+      registerExtension(extensions[i]);
+    }
+  }
+
+  return {
+    registerExtension,
+    unregisterExtension,
+    getExtension,
+    listExtensions,
+    listExtensionIds,
+    getControllerConfig,
+    createRuntimeForExtension,
+  };
+}

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -0,0 +1,117 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase19OverlayExpansionFramework.test.mjs
+*/
+import assert from 'node:assert/strict';
+import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
+import {
+  renderOverlayGameplayRuntime,
+  stepOverlayGameplayRuntime,
+} from '../../samples/phase-17/shared/overlayGameplayRuntime.js';
+import createPhase19OverlayExpansionFramework, {
+  definePhase19OverlayExtension,
+} from '../../samples/phase-19/shared/overlay/createPhase19OverlayExpansionFramework.js';
+
+function createRendererProbe(width = 960, height = 540) {
+  return {
+    getCanvasSize() {
+      return { width, height };
+    },
+    clear() {},
+    drawRect() {},
+    strokeRect() {},
+    drawText() {},
+    drawLine() {},
+    drawPolygon() {},
+    drawImageFrame() {},
+  };
+}
+
+function assertExpansionRegistrationAndCompatibility() {
+  const counters = { step: 0, render: 0 };
+  const framework = createPhase19OverlayExpansionFramework();
+  const extension = framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-example',
+    overlays: [
+      { id: 'hud', label: 'HUD' },
+      { id: 'runtime', label: 'Runtime Diagnostics' },
+    ],
+    initialOverlayId: 'hud',
+    persistenceKey: 'phase19:example:overlay-index',
+    runtimeExtensions: [
+      {
+        overlayId: 'runtime',
+        compose: true,
+        layerOrder: 10,
+        panelWidth: 220,
+        panelHeight: 88,
+        onStep() {
+          counters.step += 1;
+        },
+        onRender() {
+          counters.render += 1;
+        },
+      },
+    ],
+    metadata: {
+      source: 'runtime-test',
+    },
+  }));
+
+  assert.equal(extension.channel, 'gameplay', 'Phase 19 overlay extension should default to gameplay channel.');
+  assert.equal(extension.cycleKey, LEVEL17_OVERLAY_CYCLE_KEY, 'Phase 19 extension should stay compatible with shared cycle key.');
+  assert.equal(extension.metadata.phase, '19', 'Phase 19 extension metadata should include phase identifier.');
+  assert.deepEqual(framework.listExtensionIds(), ['phase19-overlay-example'], 'Extension registration should expose exact extension id.');
+
+  const controllerConfig = framework.getControllerConfig('phase19-overlay-example');
+  assert.notEqual(controllerConfig, null, 'Controller config should resolve for registered extension.');
+  assert.equal(controllerConfig.initialOverlayId, 'hud', 'Controller config should preserve initial overlay id.');
+  assert.deepEqual(
+    controllerConfig.overlays.map((entry) => entry.id),
+    ['hud', 'runtime'],
+    'Controller config should expose expected overlay map.'
+  );
+
+  const runtime = framework.createRuntimeForExtension('phase19-overlay-example');
+  assert.notEqual(runtime, null, 'Runtime should be creatable from registered overlay extension.');
+  assert.equal(runtime.interactionCycleKey, LEVEL17_OVERLAY_CYCLE_KEY, 'Runtime cycle key should remain shared-key compatible.');
+  assert.equal(
+    stepOverlayGameplayRuntime(runtime, { activeOverlayId: 'runtime' }),
+    1,
+    'Runtime should execute registered step extension hook.'
+  );
+  assert.equal(
+    renderOverlayGameplayRuntime(runtime, {
+      activeOverlayId: 'runtime',
+      renderer: createRendererProbe(),
+    }),
+    1,
+    'Runtime should execute registered render extension hook.'
+  );
+  assert.equal(counters.step, 1, 'Runtime step hook should update test counter.');
+  assert.equal(counters.render, 1, 'Runtime render hook should update test counter.');
+}
+
+function assertExtensionLifecycleMutations() {
+  const framework = createPhase19OverlayExpansionFramework({
+    extensions: [
+      definePhase19OverlayExtension({
+        id: 'phase19-overlay-seed',
+        overlays: [{ id: 'seed', label: 'Seed' }],
+      }),
+    ],
+  });
+
+  assert.equal(framework.listExtensions().length, 1, 'Seed extension should be registered from constructor input.');
+  assert.equal(framework.unregisterExtension('phase19-overlay-seed'), true, 'Registered extension should be removable.');
+  assert.equal(framework.unregisterExtension('phase19-overlay-seed'), false, 'Removing missing extension should return false.');
+  assert.equal(framework.getControllerConfig('phase19-overlay-seed'), null, 'Removed extension should no longer resolve controller config.');
+  assert.equal(framework.createRuntimeForExtension('phase19-overlay-seed'), null, 'Removed extension should no longer create runtime.');
+}
+
+export function run() {
+  assertExpansionRegistrationAndCompatibility();
+  assertExtensionLifecycleMutations();
+}