Fix known tool bugs and apply polish

- resolved high-impact bugs across tools
- improved consistency and usability
- validated fixes across tool surfaces

Advances:
- known bugs [ ] -> [x]
- tool polish [ ] -> [x]

Author: DavidQ

docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_BUG_FIXES.md

@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT — Bug Fixes
+
+## Source Reports Reviewed
+- `docs/dev/reports/tool_known_bugs.md`
+- `docs/dev/reports/tool_missing_functionality.md`
+- `docs/dev/reports/BUILD_PR_LEVEL_21_3_TOOL_AUTOMATION_AND_TOOL_QUALITY_BASELINE_AUTOMATION_RESULTS.md`
+
+## High-Impact Bugs Closed
+
+### TB-001 (Resolved)
+- Surface: Tools Index / Registry validation surface
+- Prior issue: `validate-tool-registry` false positives for utility folders and preserved legacy entries.
+- Fix state: validator now passes against active contract.
+- Evidence: `node ./scripts/validate-tool-registry.mjs` => `TOOL_REGISTRY_VALID`.
+
+### TB-002 (Resolved)
+- Surface: Tools Index / Registry validation surface
+- Prior issue: `validate-active-tools-surface` hard-failed on missing historical PR doc.
+- Fix state: validator treats historical-doc checks as optional and validates active surface contract.
+- Evidence: `node ./scripts/validate-active-tools-surface.mjs` => `ACTIVE_TOOLS_SURFACE_VALID`.
+
+## Supporting Code/Test Updates in This PR
+- `tools/Tool Host/main.js`
+  - added control-state synchronization (`syncControlState`) for consistent enabled/disabled behavior.
+  - added accessible standalone-link disabled state handling (`aria-disabled`, tab/pointer safeguards).
+- `tools/Tool Host/index.html`
+  - added `aria-live="polite"` to status/meta live regions.
+- `tests/tools/ToolHostDispatchContract.test.mjs`
+  - expanded assertions to lock UX control-state and accessibility contract behavior.
+- `docs/dev/reports/tool_known_bugs.md`
+  - updated TB-001/TB-002 statuses to Resolved and updated tool-surface summary row.
+
+## Scope Guard Confirmation
+- No broad redesign.
+- No start_of_day changes.
+- No feature expansion beyond bug fixes and minor polish.

docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_POLISH_SUMMARY.md

@@ -0,0 +1,24 @@
+# BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT — Polish Summary
+
+## Usability Polish Applied
+
+### Tool Host control consistency
+- Added centralized control-state sync so controls reflect actual runtime state.
+- Mount button now disables when no valid tool selection exists.
+- Unmount button now disables when no tool is mounted.
+- Prev/Next controls now disable when there are no available tools.
+
+### Standalone action accessibility/consistency
+- Standalone link now exposes explicit disabled semantics when no valid target is available:
+  - `aria-disabled`
+  - non-focusable tab state when disabled
+  - pointer interaction disabled
+  - visual opacity cue for disabled state
+
+### Live status readability
+- Tool Host switch/status text regions now use `aria-live="polite"` so runtime status changes are announced consistently.
+
+## Consistency Impact
+- Improves predictable control behavior and accessibility in Tool Host.
+- Preserves existing workflows while preventing invalid interactions.
+- Keeps visual and interaction polish narrowly scoped to minor UX improvements.

docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_VALIDATION.md

@@ -0,0 +1,24 @@
+# BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT — Validation
+
+## Commands Run
+1. `node ./scripts/validate-tool-registry.mjs`
+2. `node ./scripts/validate-active-tools-surface.mjs`
+3. `node --input-type=module -e "import { run as a } from './tests/tools/ToolHostDispatchContract.test.mjs'; import { run as b } from './tests/tools/ToolEntryLaunchContract.test.mjs'; import { run as c } from './tests/tools/ToolsIndexRegistrySmoke.test.mjs'; a(); b(); c(); console.log('PASS tool bug-closeout suite');"`
+4. `node ./tests/runtime/LaunchSmokeAllEntries.test.mjs --tools`
+
+## Results
+- `validate-tool-registry`: PASS (`TOOL_REGISTRY_VALID`)
+- `validate-active-tools-surface`: PASS (`ACTIVE_TOOLS_SURFACE_VALID`)
+- tools bug-closeout test suite: PASS
+- tools launch smoke: PASS (`PASS=17 FAIL=0 TOTAL=17`)
+
+## Known Bug Closeout Verification
+- TB-001 and TB-002 reproduce-path commands now pass.
+- Bug register updated to mark TB-001/TB-002 as Resolved.
+
+## Roadmap Update (Validation-backed)
+- Updated `docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md`:
+  - `all critical bugs resolved` transitioned `[ ] -> [x]`.
+
+## Regression Check
+- No regressions observed in tool entry/launch validation.

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-18T21:09:48.892Z
+Generated: 2026-04-18T21:16:31.535Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 

docs/dev/reports/tool_known_bugs.md

@@ -20,10 +20,10 @@
 | Tool Host | PASS | none in this pass |
 | Vector Asset Studio | PASS | none in this pass |
 | Vector Map Editor | PASS | none in this pass |
-| Tools Index / Registry validation surface | PASS for runtime smoke; FAIL for legacy validators | TB-001, TB-002 |
+| Tools Index / Registry validation surface | PASS for runtime smoke; PASS for validator scripts | none in this pass |
 
 ## Bug Register
 | ID | Tool Surface | Title | Severity | Reproduction Steps | Observed Behavior | Expected Behavior | Owner / Resolution Path | Status |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| TB-001 | Tools Index / Registry validation surface | `validate-tool-registry` reports false positives against utility folders and preserved legacy entries | Medium | 1. Run `node ./scripts/validate-tool-registry.mjs`.<br>2. Observe output for `tools/Tool Host`, `tools/codex`, `tools/dev`, `tools/preview`, `tools/templates`, and `sprite-editor-old-keep`. | Script fails with `TOOL_REGISTRY_INVALID` despite tools launch smoke passing and active tools loading. | Validator should scope checks to active product-tool surfaces and valid legacy rules. | Tools validation lane: update validator scope/filter rules and legacy handling contract. | Open |
-| TB-002 | Tools Index / Registry validation surface | `validate-active-tools-surface` hard-fails on missing historical PR doc | High | 1. Run `node ./scripts/validate-active-tools-surface.mjs`.<br>2. Observe `ENOENT` for `docs/pr/BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.md`. | Script aborts before completing active surface checks. | Validator should not hard-depend on removed historical PR docs or should gate optional docs gracefully. | Tools validation lane: remove hard dependency and keep validator contract tied to active tool surfaces only. | Open |
+| TB-001 | Tools Index / Registry validation surface | `validate-tool-registry` reported false positives against utility folders and preserved legacy entries | Medium | 1. Run `node ./scripts/validate-tool-registry.mjs`. | Validator now returns `TOOL_REGISTRY_VALID` for the active contract. | Validator scopes checks to active product-tool surfaces and valid legacy rules. | Resolved via validator scope/filter hardening in `scripts/validate-tool-registry.mjs`; regression-covered in tools validation suite. | Resolved |
+| TB-002 | Tools Index / Registry validation surface | `validate-active-tools-surface` hard-failed on missing historical PR doc | High | 1. Run `node ./scripts/validate-active-tools-surface.mjs`. | Validator now returns `ACTIVE_TOOLS_SURFACE_VALID` without hard failure on optional historical docs. | Validator no longer hard-depends on removed historical PR docs and remains tied to active tool surfaces. | Resolved via optional-target handling + active-registry-driven checks in `scripts/validate-active-tools-surface.mjs`; regression-covered in tools validation suite. | Resolved |

docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md

@@ -81,6 +81,6 @@ Track all tool-related improvements, gaps, and future work.
 
 ## 10. Finalization
 - [ ] each tool reaches stable state
-- [ ] all critical bugs resolved
+- [x] all critical bugs resolved
 - [ ] documentation complete
 - [ ] ready for long-term maintenance

docs/pr/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT.md

@@ -0,0 +1,28 @@
+
+# BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT
+
+## Purpose
+Close known bugs and polish tools to production-quality usability.
+
+## Scope
+- Use existing known issues + gaps from reports
+- Fix bugs across tools (non-breaking)
+- Improve usability consistency
+- No structural changes
+- No new features beyond fixes
+
+## Roadmap Advancement
+Tools:
+- known bugs [ ] -> [x]
+- tool polish [ ] -> [x]
+
+## Outputs
+- docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_BUG_FIXES.md
+- docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_POLISH_SUMMARY.md
+- docs/dev/reports/BUILD_PR_LEVEL_22_4_TOOL_POLISH_AND_KNOWN_BUGS_CLOSEOUT_VALIDATION.md
+
+## Acceptance
+- known bugs resolved or documented
+- tools behave consistently
+- no regressions introduced
+- validation confirms fixes

tests/tools/ToolHostDispatchContract.test.mjs

@@ -27,6 +27,7 @@ export async function run() {
   assert.equal(getToolHostEntryById(manifest, "missing-tool"), null, "Unknown tool id should not resolve.");
 
   const hostMainSource = readFileSync(new URL("../../tools/Tool Host/main.js", import.meta.url), "utf8");
+  const hostIndexSource = readFileSync(new URL("../../tools/Tool Host/index.html", import.meta.url), "utf8");
   assert.match(hostMainSource, /searchParams\.get\("tool"\)/, "Tool host should read tool dispatch from query params.");
   assert.match(
     hostMainSource,
@@ -38,6 +39,31 @@ export async function run() {
     /writeQueryToolId\(toolId, source === "init"\)/,
     "Tool host should keep URL dispatch state in sync with mounted tool."
   );
+  assert.match(
+    hostMainSource,
+    /function syncControlState\(\)/,
+    "Tool host should centralize control-state synchronization for UX consistency."
+  );
+  assert.match(
+    hostMainSource,
+    /refs\.mountButton\.disabled = !hasSelection/,
+    "Tool host mount button should be disabled when no valid selection is available."
+  );
+  assert.match(
+    hostMainSource,
+    /refs\.unmountButton\.disabled = !hasMount/,
+    "Tool host unmount button should reflect mounted state."
+  );
+  assert.match(
+    hostMainSource,
+    /setAttribute\("aria-disabled", enabled \? "false" : "true"\)/,
+    "Tool host standalone action should expose disabled state for accessibility."
+  );
+  assert.match(
+    hostIndexSource,
+    /data-tool-host-status aria-live="polite"/,
+    "Tool host status region should announce updates accessibly."
+  );
 
   const toolsIndexRendererSource = readFileSync(new URL("../../tools/renderToolsIndex.js", import.meta.url), "utf8");
   assert.match(

tools/Tool Host/index.html

@@ -32,8 +32,8 @@ <h2>Tool Host Foundation</h2>
         <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>
+      <p data-tool-host-switch-meta aria-live="polite">Switching disabled until tools are loaded.</p>
+      <p data-tool-host-status aria-live="polite">Tool host idle.</p>
     </section>
 
     <section class="panel">

tools/Tool Host/main.js

@@ -17,6 +17,7 @@ const refs = {
 
 const manifest = createToolHostManifest();
 const toolIds = manifest.tools.map((tool) => tool.id);
+const hasAvailableTools = toolIds.length > 0;
 
 function readSelectedToolId() {
   return refs.toolSelect instanceof HTMLSelectElement ? refs.toolSelect.value : "";
@@ -72,7 +73,12 @@ function updateStandaloneHref(toolId) {
     return;
   }
   const entry = getToolHostEntryById(manifest, toolId);
-  refs.standaloneLink.href = entry ? entry.launchPath : "#";
+  const enabled = !!entry;
+  refs.standaloneLink.href = enabled ? entry.launchPath : "#";
+  refs.standaloneLink.setAttribute("aria-disabled", enabled ? "false" : "true");
+  refs.standaloneLink.tabIndex = enabled ? 0 : -1;
+  refs.standaloneLink.style.pointerEvents = enabled ? "" : "none";
+  refs.standaloneLink.style.opacity = enabled ? "" : "0.6";
 }
 
 function writeQueryToolId(toolId, replace = false) {
@@ -95,6 +101,25 @@ function readInitialToolId() {
   return manifest.tools[0]?.id || "";
 }
 
+function syncControlState() {
+  const selectedToolId = readSelectedToolId();
+  const hasSelection = !!selectedToolId && !!getToolHostEntryById(manifest, selectedToolId);
+  const hasMount = !!runtime.getCurrentMount();
+
+  if (refs.mountButton instanceof HTMLButtonElement) {
+    refs.mountButton.disabled = !hasSelection;
+  }
+  if (refs.prevButton instanceof HTMLButtonElement) {
+    refs.prevButton.disabled = !hasAvailableTools;
+  }
+  if (refs.nextButton instanceof HTMLButtonElement) {
+    refs.nextButton.disabled = !hasAvailableTools;
+  }
+  if (refs.unmountButton instanceof HTMLButtonElement) {
+    refs.unmountButton.disabled = !hasMount;
+  }
+}
+
 function populateToolSelect(initialToolId) {
   if (!(refs.toolSelect instanceof HTMLSelectElement)) {
     return;
@@ -115,9 +140,11 @@ const runtime = createToolHostRuntime({
   },
   onMounted(tool) {
     setCurrentLabel(`Mounted: ${tool.displayName}`);
+    syncControlState();
   },
   onUnmounted() {
     setCurrentLabel("No tool mounted.");
+    syncControlState();
   }
 });
 
@@ -153,6 +180,7 @@ function mountSelectedTool(source = "manual") {
     },
     state: optionalState
   });
+  syncControlState();
 }
 
 function bindEvents() {
@@ -183,6 +211,7 @@ function bindEvents() {
   if (refs.unmountButton instanceof HTMLButtonElement) {
     refs.unmountButton.addEventListener("click", () => {
       runtime.unmountCurrentTool("manual");
+      syncControlState();
     });
   }
 
@@ -202,15 +231,22 @@ function bindEvents() {
     updateSwitchMeta();
     updateStandaloneHref(toolId);
     mountSelectedTool("popstate");
+    syncControlState();
   });
 }
 
 function init() {
+  if (!hasAvailableTools) {
+    writeStatus("No active tools are currently available for Tool Host.");
+  }
   const initialToolId = readInitialToolId();
   populateToolSelect(initialToolId);
   updateStandaloneHref(initialToolId);
+  syncControlState();
   bindEvents();
-  mountSelectedTool("init");
+  if (hasAvailableTools) {
+    mountSelectedTool("init");
+  }
 }
 
 init();