docs: add BUILD_PR tool host multi-switch bundle

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,24 +2,16 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOL_HOST_FOUNDATION as the next follow-up to tool boot contract normalization.
+Create BUILD_PR_TOOL_HOST_MULTI_SWITCH
 
 Scope:
-- add a minimal Tool Host foundation
-- dynamic load path for normalized tools
-- mount/unmount lifecycle handling
-- lightweight registry/manifest
-- preserve standalone tool pages
-- no theme restyling
-- no editor-state refactors
-- no render-pipeline changes
-- do not touch templates/ cleanup in this PR
+- add multi-tool switching to host
+- enforce lifecycle correctness
+- minimal UI
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- verify host shell loads selected tool
-- verify standalone tool pages still launch
-- report exact files changed
+- verify switching works
 
 Output:
-<project folder>/tmp/BUILD_PR_TOOL_HOST_FOUNDATION_delta.zip
+<project>/tmp/BUILD_PR_TOOL_HOST_MULTI_SWITCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: add BUILD_PR bundle for minimal Tool Host foundation
+docs: add BUILD_PR tool host multi-switch bundle

docs/dev/reports/BUILD_PR_TOOL_HOST_MULTI_SWITCH_report.md

@@ -0,0 +1,30 @@
+# BUILD_PR_TOOL_HOST_MULTI_SWITCH Report
+
+## Scope Outcome
+- Added host multi-tool switching controls with minimal UI (`Previous Tool`, `Next Tool`, and switch position readout).
+- Enforced tighter lifecycle handling in host runtime:
+  - mount sequence guard to prevent stale load/error events from superseded mounts
+  - destroy contract invocation on unmount when available via tool boot contract registry
+  - explicit mount/unmount status for switch, reload, manual, and unload paths
+- Preserved standalone tool pages (iframe host only; no tool page rewrites).
+
+## Validation
+- `npm run test:launch-smoke -- --tools`
+  - PASS (`9/9` tools)
+- Multi-switch host verification (CDP):
+  - Loaded host with `?tool=asset-browser`
+  - Switched across:
+    - `asset-browser`
+    - `palette-browser`
+    - `tile-map-editor`
+    - `vector-map-editor`
+  - Verified one mounted frame at each step and matching selected tool id
+  - Verified explicit unmount clears mounted frame
+  - Console/runtime errors: none
+
+## Files Changed
+- `tools/shared/toolHostRuntime.js`
+- `tools/Tool Host/index.html`
+- `tools/Tool Host/main.js`
+- `docs/dev/reports/launch_smoke_report.md`
+- `docs/dev/reports/BUILD_PR_TOOL_HOST_MULTI_SWITCH_report.md`

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-11T23:41:41.835Z
+Generated: 2026-04-11T23:48:31.310Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 

docs/dev/reports/tool_host_multi_switch_targets.txt

@@ -0,0 +1,5 @@
+MULTI TOOL SWITCH TARGETS
+
+- tool selector
+- mount/unmount enforcement
+- lifecycle validation

docs/pr/BUILD_PR_TOOL_HOST_MULTI_SWITCH.md

@@ -0,0 +1,28 @@
+# BUILD_PR_TOOL_HOST_MULTI_SWITCH
+
+## Purpose
+Extend Tool Host foundation to support switching between multiple tools dynamically within the same session.
+
+## Goals
+- switch tools without page reload
+- clean mount/unmount lifecycle
+- preserve state isolation between tools
+
+## Scope
+- host switch controller
+- tool selection UI (minimal)
+- lifecycle enforcement
+
+## Out of Scope
+- styling/theme changes
+- editor state persistence between tools
+- deep UI redesign
+
+## Strategy
+- reuse host foundation
+- add tool selector
+- ensure destroy() always called before next init()
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- switch between at least 3 tools without errors

tools/Tool Host/index.html

@@ -21,9 +21,12 @@ <h2>Tool Host Foundation</h2>
       </div>
       <div class="meta">
         <button type="button" data-tool-host-mount>Load Selected Tool</button>
+        <button type="button" data-tool-host-prev>Previous Tool</button>
+        <button type="button" data-tool-host-next>Next Tool</button>
         <button type="button" data-tool-host-unmount>Unmount Tool</button>
         <a data-tool-host-standalone href="#" target="_blank" rel="noopener noreferrer">Open Standalone</a>
       </div>
+      <p data-tool-host-switch-meta>Switching disabled until tools are loaded.</p>
       <p data-tool-host-status>Tool host idle.</p>
     </section>
 

tools/Tool Host/main.js

@@ -4,14 +4,18 @@ import { createToolHostRuntime } from "../shared/toolHostRuntime.js";
 const refs = {
   toolSelect: document.querySelector("[data-tool-host-select]"),
   mountButton: document.querySelector("[data-tool-host-mount]"),
+  prevButton: document.querySelector("[data-tool-host-prev]"),
+  nextButton: document.querySelector("[data-tool-host-next]"),
   unmountButton: document.querySelector("[data-tool-host-unmount]"),
   standaloneLink: document.querySelector("[data-tool-host-standalone]"),
+  switchMetaText: document.querySelector("[data-tool-host-switch-meta]"),
   statusText: document.querySelector("[data-tool-host-status]"),
   currentLabel: document.querySelector("[data-tool-host-current-label]"),
   mountContainer: document.querySelector("[data-tool-host-mount-container]")
 };
 
 const manifest = createToolHostManifest();
+const toolIds = manifest.tools.map((tool) => tool.id);
 
 function readSelectedToolId() {
   return refs.toolSelect instanceof HTMLSelectElement ? refs.toolSelect.value : "";
@@ -29,6 +33,39 @@ function setCurrentLabel(text) {
   }
 }
 
+function writeSwitchMeta(text) {
+  if (refs.switchMetaText instanceof HTMLElement) {
+    refs.switchMetaText.textContent = text;
+  }
+}
+
+function getSelectedToolIndex() {
+  const selectedToolId = readSelectedToolId();
+  return toolIds.findIndex((toolId) => toolId === selectedToolId);
+}
+
+function updateSwitchMeta() {
+  if (toolIds.length === 0) {
+    writeSwitchMeta("No active tools are available in host manifest.");
+    return;
+  }
+  const selectedIndex = getSelectedToolIndex();
+  const oneBased = selectedIndex >= 0 ? selectedIndex + 1 : 1;
+  writeSwitchMeta(`Switch target ${oneBased}/${toolIds.length}.`);
+}
+
+function selectToolByOffset(offset) {
+  if (!(refs.toolSelect instanceof HTMLSelectElement) || toolIds.length === 0) {
+    return false;
+  }
+
+  const currentIndex = Math.max(0, getSelectedToolIndex());
+  const nextIndex = (currentIndex + offset + toolIds.length) % toolIds.length;
+  refs.toolSelect.value = toolIds[nextIndex];
+  updateSwitchMeta();
+  return true;
+}
+
 function updateStandaloneHref(toolId) {
   if (!(refs.standaloneLink instanceof HTMLAnchorElement)) {
     return;
@@ -66,6 +103,7 @@ function populateToolSelect(initialToolId) {
     .map((tool) => `<option value="${tool.id}">${tool.displayName}</option>`)
     .join("");
   refs.toolSelect.value = getToolHostEntryById(manifest, initialToolId) ? initialToolId : (manifest.tools[0]?.id || "");
+  updateSwitchMeta();
 }
 
 const runtime = createToolHostRuntime({
@@ -88,6 +126,7 @@ function mountSelectedTool(source = "manual") {
     writeStatus("Select a tool to mount.");
     return;
   }
+  updateSwitchMeta();
   updateStandaloneHref(toolId);
   writeQueryToolId(toolId, source === "init");
   runtime.mountTool(toolId, {
@@ -103,6 +142,24 @@ function bindEvents() {
     });
   }
 
+  if (refs.prevButton instanceof HTMLButtonElement) {
+    refs.prevButton.addEventListener("click", () => {
+      if (!selectToolByOffset(-1)) {
+        return;
+      }
+      mountSelectedTool("prev");
+    });
+  }
+
+  if (refs.nextButton instanceof HTMLButtonElement) {
+    refs.nextButton.addEventListener("click", () => {
+      if (!selectToolByOffset(1)) {
+        return;
+      }
+      mountSelectedTool("next");
+    });
+  }
+
   if (refs.unmountButton instanceof HTMLButtonElement) {
     refs.unmountButton.addEventListener("click", () => {
       runtime.unmountCurrentTool("manual");
@@ -111,6 +168,7 @@ function bindEvents() {
 
   if (refs.toolSelect instanceof HTMLSelectElement) {
     refs.toolSelect.addEventListener("change", () => {
+      updateSwitchMeta();
       updateStandaloneHref(readSelectedToolId());
       mountSelectedTool("select");
     });
@@ -121,6 +179,7 @@ function bindEvents() {
     if (refs.toolSelect instanceof HTMLSelectElement) {
       refs.toolSelect.value = toolId;
     }
+    updateSwitchMeta();
     updateStandaloneHref(toolId);
     mountSelectedTool("popstate");
   });

tools/shared/toolHostRuntime.js

@@ -34,6 +34,21 @@ function createHostFrame(toolEntry, sourceUrl) {
   return frame;
 }
 
+function readToolDestroyContract(frameWindow, toolId) {
+  if (!frameWindow || typeof frameWindow !== "object") {
+    return null;
+  }
+  const registry = frameWindow.__TOOLS_BOOT_CONTRACT_REGISTRY__;
+  if (!registry || typeof registry !== "object") {
+    return null;
+  }
+  const contract = registry[toolId];
+  if (!contract || typeof contract.destroy !== "function") {
+    return null;
+  }
+  return contract.destroy.bind(contract);
+}
+
 export function createToolHostRuntime(options = {}) {
   const manifest = options.manifest;
   const mountContainer = options.mountContainer instanceof HTMLElement ? options.mountContainer : null;
@@ -42,6 +57,7 @@ export function createToolHostRuntime(options = {}) {
   const onUnmounted = typeof options.onUnmounted === "function" ? options.onUnmounted : (() => {});
 
   let currentMount = null;
+  let mountSequence = 0;
 
   function getCurrentMount() {
     return currentMount ? { ...currentMount } : null;
@@ -54,13 +70,30 @@ export function createToolHostRuntime(options = {}) {
     }
 
     const previous = currentMount;
+    currentMount = null;
+
+    let destroyStatus = "not-available";
+    try {
+      const frameWindow = previous.frame?.contentWindow ?? null;
+      const destroyFn = readToolDestroyContract(frameWindow, previous.tool.id);
+      if (destroyFn) {
+        const destroyResult = destroyFn({
+          reason,
+          hosted: true,
+          source: "tool-host-runtime"
+        });
+        destroyStatus = destroyResult === false ? "failed" : "ok";
+      }
+    } catch {
+      destroyStatus = "failed";
+    }
+
     if (previous.frame && previous.frame.parentElement === mountContainer) {
       previous.frame.removeAttribute("src");
       mountContainer.removeChild(previous.frame);
     }
-    currentMount = null;
-    onStatus(`Unmounted ${previous.tool.displayName} (${reason}).`);
-    onUnmounted(previous.tool, reason);
+    onStatus(`Unmounted ${previous.tool.displayName} (${reason}, destroy=${destroyStatus}).`);
+    onUnmounted(previous.tool, reason, destroyStatus);
     return true;
   }
 
@@ -83,12 +116,22 @@ export function createToolHostRuntime(options = {}) {
       unmountCurrentTool("reload");
     }
 
+    mountSequence += 1;
+    const sequenceId = mountSequence;
     const sourceUrl = buildHostLaunchUrl(toolEntry, config);
     const frame = createHostFrame(toolEntry, sourceUrl);
     frame.addEventListener("load", () => {
+      if (!currentMount || currentMount.mountSequence !== sequenceId) {
+        return;
+      }
+      currentMount.loadedAt = new Date().toISOString();
       onStatus(`Mounted ${toolEntry.displayName}.`);
     }, { once: true });
     frame.addEventListener("error", () => {
+      if (!currentMount || currentMount.mountSequence !== sequenceId) {
+        return;
+      }
+      currentMount.failedAt = new Date().toISOString();
       onStatus(`Failed to load ${toolEntry.displayName}.`);
     }, { once: true });
 
@@ -97,9 +140,11 @@ export function createToolHostRuntime(options = {}) {
       tool: toolEntry,
       frame,
       sourceUrl,
-      mountedAt: new Date().toISOString()
+      mountedAt: new Date().toISOString(),
+      mountSequence: sequenceId
     };
 
+    onStatus(`Mounting ${toolEntry.displayName}...`);
     onMounted(toolEntry, currentMount);
     return getCurrentMount();
   }