Add overlay plugin registry.

DavidQ · DavidQ · commit 14cf4161fa7b · 2026-04-16T18:08:45.000-04:00
PR Details:
- Enables structured overlay registration
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,10 +2,8 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Create overlay expansion framework:
-- Define extension points
-- Ensure compatibility with existing overlay system
-- Add minimal testable example
+Implement overlay plugin registry:
+- Add registration system
+- Validate with one plugin
 - Update roadmap status only
-
-Package ZIP to <project folder>/tmp/
+- Package ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,5 +1,4 @@
-Introduce overlay system expansion framework.
+Add overlay plugin registry.
 
 PR Details:
-- Enables future overlay extensibility
-- Maintains compatibility with Level 19 baseline
+- Enables structured overlay registration
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,4 @@
-[ ] Extension works
-[ ] No regressions
-[ ] Gameplay unaffected
+[ ] Plugin registers
+[ ] Plugin activates
+[ ] Plugin removes cleanly
 [ ] Roadmap updated
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/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
+- [x] validate plugin/extension patterns
 - [ ] validate adding new systems is clean
 - [ ] validate external integration points
 - [ ] ensure future phases can build cleanly
diff --git a/docs/pr/BUILD_PR.md b/docs/pr/BUILD_PR.md
@@ -1,21 +1,20 @@
-# BUILD_PR_LEVEL_20_1_OVERLAY_SYSTEM_EXPANSION
+# BUILD_PR_LEVEL_20_2_OVERLAY_PLUGIN_REGISTRY
 
 ## Purpose
-Begin Level 20 by introducing a controlled expansion framework for new overlay types.
+Introduce a registry for managing overlay plugins.
 
 ## Roadmap Improvement
-Transitions from stable baseline (Level 19) to extensible overlay architecture.
+Enables structured registration and discovery of overlays.
 
 ## Scope
-- Define extension points for new overlays
-- Ensure compatibility with existing systems
-- Validate one sample extension
+- Define plugin registry
+- Allow registration/unregistration
+- Validate with one plugin
 
 ## Test Steps
-1. Load gameplay
-2. Register new overlay via extension
-3. Validate rendering + interaction
+1. Register plugin
+2. Activate overlay
+3. Remove plugin
 
 ## Expected
-- New overlays plug in cleanly
-- No regression
+- Plugins managed cleanly
diff --git a/samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js b/samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js
@@ -0,0 +1,157 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19OverlayPluginRegistry.js
+*/
+import createPhase19OverlayExpansionFramework from '/samples/phase-19/shared/overlay/createPhase19OverlayExpansionFramework.js';
+
+function normalizePluginId(pluginId) {
+  return String(pluginId || '').trim();
+}
+
+function normalizePluginDefinition(plugin) {
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error('Overlay plugin registration requires a plugin object.');
+  }
+
+  const id = normalizePluginId(plugin.id);
+  if (!id) {
+    throw new Error('Overlay plugin requires a non-empty id.');
+  }
+
+  const createOverlayExtension = typeof plugin.createOverlayExtension === 'function'
+    ? plugin.createOverlayExtension
+    : null;
+  const extension = plugin.extension && typeof plugin.extension === 'object'
+    ? plugin.extension
+    : null;
+
+  if (!createOverlayExtension && !extension) {
+    throw new Error(`Overlay plugin "${id}" requires createOverlayExtension() or extension.`);
+  }
+
+  return Object.freeze({
+    id,
+    version: String(plugin.version || '').trim(),
+    metadata: Object.freeze({ ...(plugin.metadata || {}) }),
+    createOverlayExtension,
+    extension,
+  });
+}
+
+function normalizePluginExtension(plugin, candidateExtension) {
+  const extension = candidateExtension && typeof candidateExtension === 'object'
+    ? candidateExtension
+    : null;
+  if (!extension) {
+    throw new Error(`Overlay plugin "${plugin.id}" returned an invalid extension.`);
+  }
+  const extensionId = normalizePluginId(extension.id) || `${plugin.id}.extension`;
+  return {
+    ...extension,
+    id: extensionId,
+  };
+}
+
+export default function createPhase19OverlayPluginRegistry({
+  expansionFramework = createPhase19OverlayExpansionFramework(),
+  plugins = [],
+} = {}) {
+  const pluginMap = new Map();
+  const pluginExtensionMap = new Map();
+  let api = null;
+
+  function registerPlugin(plugin, context = {}) {
+    const normalizedPlugin = normalizePluginDefinition(plugin);
+    const pluginId = normalizedPlugin.id;
+
+    const resolvedExtension = normalizePluginExtension(
+      normalizedPlugin,
+      normalizedPlugin.createOverlayExtension
+        ? normalizedPlugin.createOverlayExtension({
+          pluginId,
+          registry: api,
+          expansionFramework,
+          ...context,
+        })
+        : normalizedPlugin.extension
+    );
+
+    const existingExtensionId = pluginExtensionMap.get(pluginId);
+    if (existingExtensionId) {
+      expansionFramework.unregisterExtension(existingExtensionId);
+    }
+
+    const registeredExtension = expansionFramework.registerExtension(resolvedExtension);
+    pluginMap.set(pluginId, normalizedPlugin);
+    pluginExtensionMap.set(pluginId, registeredExtension.id);
+
+    return Object.freeze({
+      pluginId,
+      extensionId: registeredExtension.id,
+    });
+  }
+
+  function unregisterPlugin(pluginId) {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    if (!normalizedPluginId || !pluginMap.has(normalizedPluginId)) {
+      return false;
+    }
+
+    const extensionId = pluginExtensionMap.get(normalizedPluginId);
+    if (extensionId) {
+      expansionFramework.unregisterExtension(extensionId);
+    }
+    pluginExtensionMap.delete(normalizedPluginId);
+    pluginMap.delete(normalizedPluginId);
+    return true;
+  }
+
+  function getPlugin(pluginId) {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    if (!normalizedPluginId) {
+      return null;
+    }
+    return pluginMap.get(normalizedPluginId) ?? null;
+  }
+
+  function getPluginExtensionId(pluginId) {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    if (!normalizedPluginId) {
+      return '';
+    }
+    return pluginExtensionMap.get(normalizedPluginId) || '';
+  }
+
+  function listPlugins() {
+    const entries = [];
+    for (const [pluginId, plugin] of pluginMap.entries()) {
+      entries.push({
+        id: pluginId,
+        version: plugin.version,
+        extensionId: pluginExtensionMap.get(pluginId) || '',
+      });
+    }
+    return Object.freeze(entries);
+  }
+
+  api = {
+    registerPlugin,
+    unregisterPlugin,
+    getPlugin,
+    getPluginExtensionId,
+    listPlugins,
+    getFramework() {
+      return expansionFramework;
+    },
+  };
+
+  if (Array.isArray(plugins)) {
+    for (let i = 0; i < plugins.length; i += 1) {
+      registerPlugin(plugins[i]);
+    }
+  }
+
+  return api;
+}
diff --git a/tests/runtime/Phase19OverlayPluginRegistry.test.mjs b/tests/runtime/Phase19OverlayPluginRegistry.test.mjs
@@ -0,0 +1,120 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase19OverlayPluginRegistry.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 { definePhase19OverlayExtension } from '../../samples/phase-19/shared/overlay/createPhase19OverlayExpansionFramework.js';
+import createPhase19OverlayPluginRegistry from '../../samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js';
+
+function createRendererProbe(width = 960, height = 540) {
+  return {
+    getCanvasSize() {
+      return { width, height };
+    },
+    clear() {},
+    drawRect() {},
+    strokeRect() {},
+    drawText() {},
+    drawLine() {},
+    drawPolygon() {},
+    drawImageFrame() {},
+  };
+}
+
+function assertPluginRegistrationAndRuntimeCompatibility() {
+  const counters = { step: 0, render: 0 };
+  const registry = createPhase19OverlayPluginRegistry();
+  const result = registry.registerPlugin({
+    id: 'phase19.runtime.plugin',
+    version: '1.0.0',
+    metadata: { owner: 'runtime-test' },
+    createOverlayExtension() {
+      return definePhase19OverlayExtension({
+        id: 'phase19.runtime.plugin.overlay',
+        overlays: [
+          { id: 'ui-layer', label: 'UI Layer' },
+          { id: 'plugin-runtime', label: 'Plugin Runtime' },
+        ],
+        initialOverlayId: 'ui-layer',
+        persistenceKey: 'phase19:plugin:overlay-index',
+        cycleKey: LEVEL17_OVERLAY_CYCLE_KEY,
+        runtimeExtensions: [
+          {
+            overlayId: 'plugin-runtime',
+            onStep() {
+              counters.step += 1;
+            },
+            onRender() {
+              counters.render += 1;
+            },
+          },
+        ],
+      });
+    },
+  });
+
+  assert.deepEqual(
+    result,
+    { pluginId: 'phase19.runtime.plugin', extensionId: 'phase19.runtime.plugin.overlay' },
+    'Plugin registry should return plugin id and resolved extension id.'
+  );
+  assert.equal(registry.listPlugins().length, 1, 'Plugin registry should track one registered plugin.');
+  assert.equal(
+    registry.getPluginExtensionId('phase19.runtime.plugin'),
+    'phase19.runtime.plugin.overlay',
+    'Plugin registry should expose extension id mapping.'
+  );
+
+  const framework = registry.getFramework();
+  assert.deepEqual(
+    framework.listExtensionIds(),
+    ['phase19.runtime.plugin.overlay'],
+    'Expansion framework should receive plugin overlay extension registration.'
+  );
+
+  const runtime = framework.createRuntimeForExtension('phase19.runtime.plugin.overlay');
+  assert.notEqual(runtime, null, 'Registered plugin extension should create overlay runtime.');
+  assert.equal(runtime.interactionCycleKey, LEVEL17_OVERLAY_CYCLE_KEY, 'Plugin runtime should preserve shared non-Tab cycle key.');
+  assert.equal(
+    stepOverlayGameplayRuntime(runtime, { activeOverlayId: 'plugin-runtime' }),
+    1,
+    'Plugin runtime extension should execute step hook through existing overlay runtime.'
+  );
+  assert.equal(
+    renderOverlayGameplayRuntime(runtime, {
+      activeOverlayId: 'plugin-runtime',
+      renderer: createRendererProbe(),
+    }),
+    1,
+    'Plugin runtime extension should execute render hook through existing overlay runtime.'
+  );
+  assert.equal(counters.step, 1, 'Plugin runtime step hook should run exactly once.');
+  assert.equal(counters.render, 1, 'Plugin runtime render hook should run exactly once.');
+}
+
+function assertPluginUnregisterCleansFramework() {
+  const registry = createPhase19OverlayPluginRegistry();
+  registry.registerPlugin({
+    id: 'phase19.cleanup.plugin',
+    extension: definePhase19OverlayExtension({
+      id: 'phase19.cleanup.overlay',
+      overlays: [{ id: 'ui-layer', label: 'UI Layer' }],
+    }),
+  });
+
+  assert.equal(registry.unregisterPlugin('phase19.cleanup.plugin'), true, 'Registered plugin should be removable.');
+  assert.equal(registry.unregisterPlugin('phase19.cleanup.plugin'), false, 'Repeated unregister should return false.');
+  assert.equal(registry.getFramework().getExtension('phase19.cleanup.overlay'), null, 'Plugin removal should remove extension from framework.');
+}
+
+export function run() {
+  assertPluginRegistrationAndRuntimeCompatibility();
+  assertPluginUnregisterCleansFramework();
+}
