Update tool status tooltips - PR_26160_086-tool-status-tooltip-update

Author: ToolboxAid

admin/tool-votes.html

@@ -92,7 +92,7 @@ <h2>Vote Inspector</h2>
                             <details class="vertical-accordion" open>
                                 <summary>Diagnostics</summary>
                                 <div class="accordion-body content-stack">
-                                    <p>State edits are limited to planned, wireframe, beta, and complete.</p>
+                                    <p data-toolbox-votes-state-help>State definitions load from shared Toolbox status metadata.</p>
                                     <p>Tool links open the current Toolbox route stored in shared metadata.</p>
                                 </div>
                             </details>

admin/tool-votes.js

@@ -10,13 +10,15 @@ const dragStatus = document.querySelector("[data-toolbox-votes-drag-status]");
 const body = document.querySelector("[data-toolbox-votes-body]");
 const sortButtons = Array.from(document.querySelectorAll("[data-toolbox-votes-sort]"));
 const sortHeaders = Array.from(document.querySelectorAll("[data-toolbox-votes-sort-header]"));
+const stateHelp = document.querySelector("[data-toolbox-votes-state-help]");
 const sortButtonLabels = new Map(sortButtons.map((button) => [
   button.dataset.toolboxVotesSort,
   button.textContent.trim(),
 ]));
 
 const toolboxContract = getToolboxContract();
 const releaseChannelLabels = toolboxContract.releaseChannelLabels || {};
+const releaseChannelHelpText = toolboxContract.releaseChannelHelpText || {};
 const RELEASE_CHANNEL_OPTIONS = Object.freeze((toolboxContract.releaseChannels || []).map((channel) => [
   channel,
   releaseChannelLabels[channel] || channel,
@@ -166,6 +168,33 @@ function releaseChannelLabel(value) {
   return RELEASE_CHANNEL_LABELS.get(value) || RELEASE_CHANNEL_LABELS.get(DEFAULT_RELEASE_CHANNEL) || value || DEFAULT_RELEASE_CHANNEL;
 }
 
+function releaseChannelHelp(value) {
+  return releaseChannelHelpText[value] || releaseChannelHelpText[DEFAULT_RELEASE_CHANNEL] || "";
+}
+
+function compactHelpText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function statusHelpSummary() {
+  return RELEASE_CHANNEL_OPTIONS.map(([value, label]) => {
+    const help = compactHelpText(releaseChannelHelp(value));
+    return help ? `${label}: ${help}` : label;
+  }).join(" ");
+}
+
+function renderStatusHelp() {
+  const summary = statusHelpSummary();
+  if (stateHelp) {
+    stateHelp.textContent = `State definitions: ${summary}`;
+    stateHelp.title = summary;
+  }
+  const stateSortButton = sortButtons.find((button) => button.dataset.toolboxVotesSort === "releaseChannelLabel");
+  if (stateSortButton) {
+    stateSortButton.title = summary;
+  }
+}
+
 function rowReleaseChannel(voteRow) {
   const value = String(voteRow.status || voteRow.releaseChannel || "").trim().toLowerCase();
   return RELEASE_CHANNEL_LABELS.has(value) ? value : DEFAULT_RELEASE_CHANNEL;
@@ -177,11 +206,13 @@ function stateCell(voteRow) {
   const currentState = rowReleaseChannel(voteRow);
   select.dataset.toolboxVotesState = voteRow.toolId;
   select.setAttribute("aria-label", `State for ${voteRow.toolName}`);
+  select.title = `${releaseChannelLabel(currentState)}: ${compactHelpText(releaseChannelHelp(currentState))}`;
   const options = RELEASE_CHANNEL_OPTIONS.length ? RELEASE_CHANNEL_OPTIONS : [[currentState, currentState]];
   options.forEach(([value, label]) => {
     const option = document.createElement("option");
     option.value = value;
     option.textContent = label;
+    option.title = `${label}: ${compactHelpText(releaseChannelHelp(value))}`;
     select.append(option);
   });
   select.value = currentState;
@@ -410,4 +441,5 @@ sortButtons.forEach((button) => {
   });
 });
 
+renderStatusHelp();
 renderToolboxVotes();

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -6,25 +6,11 @@ Missing changed runtime JS files are WARN, not FAIL.
 Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 Changed runtime JS files considered:
-(0%) assets/theme-v2/js/account-achievements.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-design-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-catalog-config.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-workspace-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-journey/project-journey-api-client.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-journey/project-journey.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-workspace/project-workspace.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(89%) toolbox/colors/colors.js - executed lines 1848/1848; executed functions 189/212
-(100%) toolbox/colors/palette-api-client.js - executed lines 28/28; executed functions 4/4
+(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(78%) admin/tool-votes.js - executed lines 406/406; executed functions 43/55
+(84%) toolbox/tools-page-accordions.js - executed lines 960/960; executed functions 92/109
 
 Guardrail warnings:
-(0%) assets/theme-v2/js/account-achievements.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-design-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-catalog-config.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-journey-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-workspace-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/project-journey/project-journey-api-client.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/project-journey/project-journey.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/project-workspace/project-workspace.js - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -12,55 +12,34 @@ Note: entry percentages use function coverage when available, otherwise line cov
 Note: coverage entries are aggregated across every page/tool where coverageReporter.start(page) and coverageReporter.stop(page) ran.
 
 Exercised tool entry points detected:
-(88%) Toolbox Index - exercised 3 runtime JS files
+(81%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(77%) Theme V2 Shared JS - exercised 3 runtime JS files
+(74%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
-(0%) assets/theme-v2/js/account-achievements.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-design-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-catalog-config.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-workspace-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-journey/project-journey-api-client.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-journey/project-journey.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/project-workspace/project-workspace.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(89%) toolbox/colors/colors.js - executed lines 1848/1848; executed functions 189/212
-(100%) toolbox/colors/palette-api-client.js - executed lines 28/28; executed functions 4/4
+(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(78%) admin/tool-votes.js - executed lines 406/406; executed functions 43/55
+(84%) toolbox/tools-page-accordions.js - executed lines 960/960; executed functions 92/109
 
 Files with executed line/function counts where available:
-(58%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 11/19
+(38%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 3/8
+(50%) src/engine/api/toolbox-votes-api-client.js - executed lines 46/46; executed functions 3/6
+(53%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 10/19
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 209/209; executed functions 9/14
-(75%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 21/28
+(64%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 16/25
 (77%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 603/603; executed functions 43/56
-(89%) toolbox/colors/colors.js - executed lines 1848/1848; executed functions 189/212
-(92%) assets/theme-v2/js/account-controls.js - executed lines 47/47; executed functions 12/13
-(100%) toolbox/colors/palette-api-client.js - executed lines 28/28; executed functions 4/4
+(78%) admin/tool-votes.js - executed lines 406/406; executed functions 43/55
+(84%) toolbox/tools-page-accordions.js - executed lines 960/960; executed functions 92/109
+(100%) toolbox/project-workspace/project-workspace-api-client.js - executed lines 12/12; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
-(0%) assets/theme-v2/js/account-achievements.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/game-design-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-catalog-config.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-journey-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/project-workspace-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
-(0%) toolbox/project-journey/project-journey-api-client.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) toolbox/project-journey/project-journey.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) toolbox/project-workspace/project-workspace.js - WARNING: uncovered changed runtime JS file; advisory only
+(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: uncovered changed runtime JS file; advisory only
+(0%) toolbox/toolRegistry.js - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
-(0%) assets/theme-v2/js/account-achievements.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/game-design-mock-repository.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/palette-catalog-config.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/project-journey-mock-repository.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/project-workspace-mock-repository.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/server/mock-api-router.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ProjectJourneyTool.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ProjectWorkspaceMockRepository.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ToolboxRoutePages.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) toolbox/project-journey/project-journey-api-client.js - changed JS file not collected as browser runtime coverage
-(0%) toolbox/project-journey/project-journey.js - changed JS file not collected as browser runtime coverage
-(0%) toolbox/project-workspace/project-workspace.js - changed JS file not collected as browser runtime coverage
-(89%) toolbox/colors/colors.js - changed JS file with browser V8 coverage
-(100%) toolbox/colors/palette-api-client.js - changed JS file with browser V8 coverage
+(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - changed JS file not collected as browser runtime coverage
+(0%) tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs - changed JS file not collected as browser runtime coverage
+(0%) toolbox/toolRegistry.js - changed JS file not collected as browser runtime coverage
+(78%) admin/tool-votes.js - changed JS file with browser V8 coverage
+(84%) toolbox/tools-page-accordions.js - changed JS file with browser V8 coverage

docs_build/dev/reports/tool-status-tooltip-update-report.md

@@ -0,0 +1,51 @@
+# PR_26160_086 Tool Status Tooltip Update Report
+
+## Branch Validation
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| Current branch is `main` | PASS | `git branch --show-current` returned `main` before changes. |
+
+## Requirement Checklist
+
+| Requirement | Result | Evidence |
+| --- | --- | --- |
+| Update Toolbox/Admin status tooltip hover text to use the new governance definitions | PASS | `src/dev-runtime/guest-seeds/tool-metadata-inventory.js` now exports the PR085 definitions through `TOOL_RELEASE_CHANNEL_HELP_TEXT`. |
+| Tooltip text explains `planned`, `wireframe`, `beta`, and `complete` | PASS | API contract assertion verifies all four help strings in `tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs`. |
+| Tooltip appears in Toolbox Build Path | PASS | `toolbox/tools-page-accordions.js` adds shared-definition title text to Build Path status cells and existing status filter buttons use the same contract help text. |
+| Tooltip appears in Admin Tool Votes | PASS | `admin/tool-votes.js` applies shared-definition title text to State selects/options and renders a shared-definition diagnostics line. |
+| Do not hardcode duplicate definitions in multiple places when shared metadata exists | PASS | Active UI reads help text from the Toolbox API contract. The compatibility `toolbox/toolRegistry.js` stub was updated only to prevent stale definitions for legacy scripts/tests. |
+| Use DB/API/service-backed or shared metadata where already available | PASS | Active Toolbox/Admin surfaces consume `getToolboxContract()` from `/api/toolbox/registry/snapshot`. |
+| Do not use inline script/style/event handlers | PASS | Focused `rg` audit found no inline handlers/styles in changed HTML/JS. |
+
+## Tooltip Coverage
+
+| Surface | Coverage |
+| --- | --- |
+| Toolbox status filter controls | Existing `data-toolbox-status-filter` buttons use `releaseChannelHelp(channel)` from the API contract for `title`; Playwright asserts Beta contains "Can be used in a real game." |
+| Toolbox Build Path status cells | New `data-build-path-status-help` cells show `<Status>: <definition>` in `title`; Playwright asserts Complete contains "Ready for long-term support." |
+| Toolbox tiles/status kickers | Existing `data-toolbox-kicker` badges continue using contract-backed `tool.releaseChannelHelpText`. |
+| Admin Tool Votes State select | New select/option titles use shared `releaseChannelHelpText`; Playwright asserts Colors State title contains the Complete definition. |
+| Admin Tool Votes Diagnostics | New `data-toolbox-votes-state-help` line renders all shared definitions; Playwright asserts the Beta definition is visible. |
+
+## Validation
+
+| Lane | Result | Notes |
+| --- | --- | --- |
+| Branch guard | PASS | Current branch was `main`. |
+| Changed-file syntax | PASS | `node --check` passed for changed JS and test files. |
+| Inline HTML/JS audit | PASS | `rg` found no inline scripts, styles, or event handlers in changed files. |
+| Diff hygiene | PASS | `git diff --check` completed with line-ending normalization warnings only. |
+| Targeted Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` passed 4/4. |
+
+## Impacted Lanes
+
+- Impacted lane: Toolbox/Admin Tool Votes metadata SSoT.
+- Playwright impacted: Yes.
+- Samples skipped: Safe to skip because the change only updates Toolbox/Admin status metadata and hover/help display.
+- Full samples validation: Not run per request.
+
+## Manual Test Notes
+
+- Open `/toolbox/index.html`, switch to Build Path, hover status filter buttons and status cells.
+- Open `/admin/tool-votes.html`, hover State dropdowns and confirm the Diagnostics panel lists the same four status meanings.

src/dev-runtime/guest-seeds/tool-metadata-inventory.js

@@ -24,10 +24,10 @@ export const TOOL_RELEASE_CHANNEL_LABELS = Object.freeze({
 });
 
 export const TOOL_RELEASE_CHANNEL_HELP_TEXT = Object.freeze({
-  planned: "Idea exists.\nNot yet available.",
-  wireframe: "Preview the planned workflow and layout.\nHelp shape the design before development begins.",
-  beta: "Ready to try.\nFeatures, layout, and workflows may change based on feedback.",
-  complete: "Production ready and fully supported."
+  planned: "Not designed yet.\nNo meaningful UI.\nNo ownership defined.",
+  wireframe: "Tool exists.\nUser can understand workflow.\nData ownership is defined.\nNot functionally usable.",
+  beta: "Functionally usable.\nCan be used in a real game.\nMay still contain incomplete workflows, placeholder data, UI cleanup issues, unused fields, missing validation, or incomplete code review.",
+  complete: "Functionally usable.\nCode reviewed.\nDead code removed.\nInvalid fields removed.\nUI cleaned up.\nNo known placeholder data.\nNo known invalid controls.\nReady for long-term support."
 });
 
 export const TOOL_REGISTRY_REQUIRED_METADATA_FIELDS = Object.freeze([