Add Samples↔Tools return-path foundation

- added `Tool` filter to `samples/index.html`
- updated `samples/index.render.js` to filter by tool and preselect from `?tool=<toolId>`
- updated `tools/renderToolsIndex.js` to compute sample counts from metadata and render `Samples (x)` links
- tagged sample `1208` with `toolHints: ["parallax-editor"]`
- updated `MASTER_ROADMAP_SAMPLES2TOOLS.md` return-path checklist/status to reflect completed work

Author: DavidQ

docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md

@@ -47,11 +47,11 @@
 - render status indicating source sample
 
 ## Return Path (Tools -> Samples)
-- [ ] Add a `Tool` filter in Samples.
-- [ ] In Tools, add a link label pattern: `Samples (x)` where `x` is count for that tool.
-- [ ] Tools `Samples (x)` link passes tool argument back to Samples page.
-- [ ] Samples page prepopulates the `Tool` dropdown from query argument and applies filter automatically.
-- [ ] Samples return path filter uses `Tool` only (exclude `Workspace Manager` from this filter lane).
+- [x] Add a `Tool` filter in Samples.
+- [x] In Tools, add a link label pattern: `Samples (x)` where `x` is count for that tool.
+- [x] Tools `Samples (x)` link passes tool argument back to Samples page.
+- [x] Samples page prepopulates the `Tool` dropdown from query argument and applies filter automatically.
+- [x] Samples return path filter uses `Tool` only (exclude `Workspace Manager` from this filter lane).
 
 ## Rollout Plan
 
@@ -106,7 +106,10 @@
 - [ ] 3D Camera Path Editor (47 candidates; prioritize camera/path-centric samples)
 - [ ] Select precise, semantically aligned samples only (avoid broad keyword-only linkage).
 
-### Phase 5 - Phase 20 Decommission (After Parity)
+### Phase 5 - Games
+- [ ] Do the same thing for games.
+
+### Phase 6 - Phase 20 Decommission (After Parity)
 - [ ] Keep `Phase 20 - Tool Preset Integration` active until Samples2Tools parity is execution-validated.
 - [ ] Define parity gate:
 - sample-to-tool launch coverage equals or exceeds current Phase 20 matrix intent.
@@ -136,6 +139,6 @@
 - [ ] `docs/dev/reports/samples2tools_link_map_<n>.json`
 
 ## Current Snapshot (from tools_used.txt)
-- [x] Current tagged samples across active tools: `0` (excluding Phase 20)
+- [x] Current tagged samples across active tools: `1` (excluding Phase 20)
 - [x] Candidate coverage inventory exists for all active tools
 - [.] Convert candidates into curated, validated sample-to-tool links

samples/index.html

@@ -47,6 +47,12 @@ <h2>Filter Samples</h2>
             <option value="">All classes</option>
           </select>
         </div>
+        <div class="samples-filter-field">
+          <label for="samples-filter-tool">Tool</label>
+          <select id="samples-filter-tool">
+            <option value="">All tools</option>
+          </select>
+        </div>
         <div class="samples-filter-field">
           <label for="samples-filter-tag">Tag</label>
           <select id="samples-filter-tag">

samples/index.render.js

@@ -1,3 +1,5 @@
+import { getToolRegistry } from "../tools/toolRegistry.js";
+
 const METADATA_PATH = "./metadata/samples.index.metadata.json";
 const PINNED_KEY = "samples-index-pinned";
 
@@ -69,7 +71,18 @@ function buildClassTokens(classValues, engineClassesUsed) {
     .sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: "base" }));
 }
 
-function buildSampleRows(metadata, pinnedSet) {
+function buildToolTokens(toolHints, toolLabelMap) {
+  const deduped = [...new Set(asArray(toolHints).map((entry) => normalizeToken(entry)).filter(Boolean))];
+  return deduped
+    .filter((toolId) => toolId !== "workspace-manager")
+    .map((toolId) => ({
+      value: toolId,
+      label: toolLabelMap.get(toolId) || toolId
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: "base" }));
+}
+
+function buildSampleRows(metadata, pinnedSet, toolLabelMap) {
   const phaseInfoMap = new Map(
     asArray(metadata?.phases)
       .map((phase) => {
@@ -102,6 +115,7 @@ function buildSampleRows(metadata, pinnedSet) {
       const href = normalize(sample?.href) || `./phase-${phase}/${id}/index.html`;
       const tags = asArray(sample?.tags).map((tag) => normalizeTag(tag)).filter(Boolean);
       const classTokens = buildClassTokens(sample?.classValues, sample?.engineClassesUsed);
+      const toolTokens = buildToolTokens(sample?.toolHints, toolLabelMap);
       const previewSrc = normalize(sample?.thumbnail) || normalize(sample?.preview) || "";
       return {
         id,
@@ -113,6 +127,7 @@ function buildSampleRows(metadata, pinnedSet) {
         href,
         tags,
         classTokens,
+        toolTokens,
         previewSrc,
         pinned: pinnedSet.has(id)
       };
@@ -134,9 +149,14 @@ function buildSampleRows(metadata, pinnedSet) {
   ).entries()]
     .map(([value, label]) => ({ value, label }))
     .sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: "base" }));
+  const tools = [...new Map(
+    sampleRows.flatMap((sample) => sample.toolTokens).map((token) => [token.value, token.label])
+  ).entries()]
+    .map(([value, label]) => ({ value, label }))
+    .sort((a, b) => a.label.localeCompare(b.label, undefined, { sensitivity: "base" }));
   const tags = [...new Set(sampleRows.flatMap((sample) => sample.tags))].sort();
 
-  return { sampleRows, phases, phaseOptions, classes, tags, phaseInfoMap };
+  return { sampleRows, phases, phaseOptions, classes, tools, tags, phaseInfoMap };
 }
 
 function filterSampleRows(sampleRows, filterState) {
@@ -148,14 +168,18 @@ function filterSampleRows(sampleRows, filterState) {
     if (filterState.className && !sample.classTokens.some((token) => token.value === filterState.className)) {
       return false;
     }
+    if (filterState.toolId && !sample.toolTokens.some((token) => token.value === filterState.toolId)) {
+      return false;
+    }
     if (filterState.tag && !sample.tags.includes(filterState.tag)) {
       return false;
     }
     if (!query) {
       return true;
     }
     const classText = sample.classTokens.map((token) => `${token.label} ${token.value}`).join(" ");
-    const haystack = `${sample.phase} ${sample.phaseTitle} ${sample.id} ${sample.title} ${sample.description} ${sample.tags.join(" ")} ${classText}`.toLowerCase();
+    const toolText = sample.toolTokens.map((token) => `${token.label} ${token.value}`).join(" ");
+    const haystack = `${sample.phase} ${sample.phaseTitle} ${sample.id} ${sample.title} ${sample.description} ${sample.tags.join(" ")} ${classText} ${toolText}`.toLowerCase();
     return haystack.includes(query);
   });
 }
@@ -300,10 +324,11 @@ export async function initSamplesIndex() {
   const pinnedContainer = document.getElementById("samples-pinned-list");
   const phaseSelect = document.getElementById("samples-filter-phase");
   const classSelect = document.getElementById("samples-filter-class");
+  const toolSelect = document.getElementById("samples-filter-tool");
   const tagSelect = document.getElementById("samples-filter-tag");
   const searchInput = document.getElementById("samples-phase-filter-input");
   const statusNode = document.getElementById("samples-phase-filter-status");
-  if (!listContainer || !pinnedContainer || !phaseSelect || !classSelect || !tagSelect || !searchInput || !statusNode) {
+  if (!listContainer || !pinnedContainer || !phaseSelect || !classSelect || !toolSelect || !tagSelect || !searchInput || !statusNode) {
     return;
   }
 
@@ -314,8 +339,14 @@ export async function initSamplesIndex() {
   }
   const metadata = await response.json();
   let pinnedSet = readPinnedSet();
+  const toolLabelMap = new Map(
+    getToolRegistry()
+      .filter((tool) => tool.id !== "workspace-manager")
+      .map((tool) => [normalizeToken(tool.id), normalize(tool.displayName) || normalize(tool.name) || normalize(tool.id)])
+      .filter((entry) => entry[0] && entry[1])
+  );
 
-  const model = buildSampleRows(metadata, pinnedSet);
+  const model = buildSampleRows(metadata, pinnedSet, toolLabelMap);
   setSelectOptions(phaseSelect, model.phaseOptions.map((entry) => entry.value), (value) => {
     const found = model.phaseOptions.find((entry) => entry.value === value);
     return found?.label || `Phase ${value}`;
@@ -324,13 +355,22 @@ export async function initSamplesIndex() {
     const found = model.classes.find((entry) => entry.value === value);
     return found?.label || value.split("/").at(-1) || value;
   });
+  setSelectOptions(toolSelect, model.tools.map((entry) => entry.value), (value) => {
+    const found = model.tools.find((entry) => entry.value === value);
+    return found?.label || value;
+  });
   setSelectOptions(tagSelect, model.tags, (value) => value);
+  const toolQuery = normalizeToken(new URLSearchParams(window.location.search).get("tool"));
+  if (toolQuery && model.tools.some((entry) => entry.value === toolQuery)) {
+    toolSelect.value = toolQuery;
+  }
 
   const render = () => {
-    const nextModel = buildSampleRows(metadata, pinnedSet);
+    const nextModel = buildSampleRows(metadata, pinnedSet, toolLabelMap);
     const filterState = {
       phase: normalize(phaseSelect.value),
       className: normalize(classSelect.value),
+      toolId: normalizeToken(toolSelect.value),
       tag: normalize(tagSelect.value),
       query: normalize(searchInput.value)
     };
@@ -365,6 +405,7 @@ export async function initSamplesIndex() {
 
   phaseSelect.addEventListener("change", render);
   classSelect.addEventListener("change", render);
+  toolSelect.addEventListener("change", render);
   tagSelect.addEventListener("change", render);
   searchInput.addEventListener("input", render);
 

samples/metadata/samples.index.metadata.json

@@ -6382,6 +6382,9 @@
         "engine/tilemap/index/resolveRectVsTilemap",
         "engine/tilemap/index/Tilemap",
         "engine/utils/index/clamp"
+      ],
+      "toolHints": [
+        "parallax-editor"
       ]
     },
     {

tools/renderToolsIndex.js

@@ -1,6 +1,9 @@
 import { getToolRegistry } from "./toolRegistry.js";
 import { escapeHtml } from "../src/shared/string/stringUtil.js";
 
+const SAMPLES_INDEX_PATH = "/samples/index.html";
+const SAMPLES_METADATA_PATH = "/samples/metadata/samples.index.metadata.json";
+
 function toStandaloneHref(entryPoint) {
   const normalized = String(entryPoint || "").replace(/^\.?\/*/, "");
   return normalized ? `/tools/${normalized}` : "#";
@@ -17,10 +20,17 @@ function buildDocumentationLinks(tool) {
   ];
 }
 
-function buildCardLinks(tool) {
+function buildCardLinks(tool, sampleCount) {
   const docs = buildDocumentationLinks(tool);
+  const links = [...docs];
+  if (Number.isInteger(sampleCount) && sampleCount > 0) {
+    links.push({
+      label: `Samples (${sampleCount})`,
+      path: `${SAMPLES_INDEX_PATH}?tool=${encodeURIComponent(tool.id)}`
+    });
+  }
   const seen = new Set();
-  return docs.filter((entry) => {
+  return links.filter((entry) => {
     const label = String(entry?.label || "").trim();
     const path = String(entry?.path || "").trim();
     if (!label || !path) {
@@ -35,9 +45,10 @@ function buildCardLinks(tool) {
   });
 }
 
-function renderToolCard(tool) {
+function renderToolCard(tool, sampleCountByToolId) {
   const standaloneHref = toStandaloneHref(tool.entryPoint);
-  const cardLinks = buildCardLinks(tool);
+  const sampleCount = Number(sampleCountByToolId.get(tool.id) || 0);
+  const cardLinks = buildCardLinks(tool, sampleCount);
   const sampleLinks = cardLinks.length > 0
     ? `
       <div class="meta">
@@ -109,7 +120,35 @@ function renderWorkspaceManagerSection() {
   grid.innerHTML = renderWorkspaceManagerCard();
 }
 
-function renderActiveToolsList() {
+async function loadSampleCountByToolId() {
+  const counts = new Map();
+  try {
+    const response = await fetch(SAMPLES_METADATA_PATH, { cache: "no-store" });
+    if (!response.ok) {
+      return counts;
+    }
+    const metadata = await response.json();
+    const samples = Array.isArray(metadata?.samples) ? metadata.samples : [];
+    for (const sample of samples) {
+      if (String(sample?.phase || "").trim() === "20") {
+        continue;
+      }
+      const toolHints = Array.isArray(sample?.toolHints) ? sample.toolHints : [];
+      for (const rawToolId of toolHints) {
+        const toolId = String(rawToolId || "").trim().toLowerCase();
+        if (!toolId || toolId === "workspace-manager") {
+          continue;
+        }
+        counts.set(toolId, Number(counts.get(toolId) || 0) + 1);
+      }
+    }
+    return counts;
+  } catch {
+    return counts;
+  }
+}
+
+function renderActiveToolsList(sampleCountByToolId) {
   const editorsGrid = document.querySelector("[data-active-tools-editors-grid]");
   const utilitiesGrid = document.querySelector("[data-active-tools-utilities-grid]");
   const viewersGrid = document.querySelector("[data-active-tools-viewers-grid]");
@@ -122,9 +161,9 @@ function renderActiveToolsList() {
     .filter((entry) => entry.id !== "state-inspector")
     .sort((left, right) => String(left.displayName || "").localeCompare(String(right.displayName || "")));
 
-  const editors = tools.filter((tool) => classifyToolGroup(tool.id) === "editors").map((tool) => renderToolCard(tool));
-  const utilities = tools.filter((tool) => classifyToolGroup(tool.id) === "utilities").map((tool) => renderToolCard(tool));
-  const viewers = tools.filter((tool) => classifyToolGroup(tool.id) === "viewers").map((tool) => renderToolCard(tool));
+  const editors = tools.filter((tool) => classifyToolGroup(tool.id) === "editors").map((tool) => renderToolCard(tool, sampleCountByToolId));
+  const utilities = tools.filter((tool) => classifyToolGroup(tool.id) === "utilities").map((tool) => renderToolCard(tool, sampleCountByToolId));
+  const viewers = tools.filter((tool) => classifyToolGroup(tool.id) === "viewers").map((tool) => renderToolCard(tool, sampleCountByToolId));
 
   editorsGrid.innerHTML = editors.join("\n");
   utilitiesGrid.innerHTML = utilities.join("\n");
@@ -146,6 +185,11 @@ function sortPlannedCardsAlphabetically() {
     .forEach((card) => grid.appendChild(card));
 }
 
-renderWorkspaceManagerSection();
-renderActiveToolsList();
-sortPlannedCardsAlphabetically();
+async function initToolsIndex() {
+  const sampleCountByToolId = await loadSampleCountByToolId();
+  renderWorkspaceManagerSection();
+  renderActiveToolsList(sampleCountByToolId);
+  sortPlannedCardsAlphabetically();
+}
+
+void initToolsIndex();