Implemented. Games now mirrors the samples-style tool roundtrip flow.

### What changed
- Added **Tool filter** to Games hub UI:
  - [games/index.html](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\games\index.html)
  - [games/index.render.js](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\games\index.render.js)
- Added **per-game tool roundtrip links** (metadata-driven) that pass:
  - `gameId`, `gameTitle`, `gameHref`
  - `workspaceHref` (to Workspace Manager with `?game=...`)
  - `returnTo` (to Games hub with preselected tool filter)
- Added styling for game tool roundtrip section:
  - [games/index.css](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\games\index.css)
- Added **return line in tools header** when launched from a game:
  - Shows `Game Source`
  - `Return to Games`
  - `Open Game`
  - `Open in Workspace Manager`
  - [tools/shared/platformShell.js](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\tools\shared\platformShell.js)
  - [tools/shared/platformShell.css](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\tools\shared\platformShell.css)
- Added explicit game `toolHints` for all launchable games (11/11) so filter + links are metadata-driven:
  - [games/metadata/games.index.metadata.json](C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming\games\metadata\games.index.metadata.json)

### Validation run
- `node --check games/index.render.js` passed
- `node --check tools/shared/platformShell.js` passed
- JSON parse check for games metadata passed

Commit comment: `Games hub now has metadata-driven Tool filtering and game-to-tool roundtrip links with workspace + return context, and tools header renders a game return line when launched from games.`

Author: DavidQ

games/index.css

@@ -116,6 +116,30 @@
   margin: 6px 0 8px;
 }
 
+.game-tool-roundtrip {
+  margin: 10px 0 0;
+}
+
+.game-tool-roundtrip h4,
+.game-tool-roundtrip p,
+.game-tool-roundtrip li,
+.game-tool-roundtrip a {
+  color: #ffffff;
+}
+
+.game-tool-roundtrip h4 {
+  margin: 0 0 6px;
+}
+
+.game-tool-roundtrip p {
+  margin: 0 0 6px;
+}
+
+.game-tool-roundtrip ul {
+  margin: 0;
+  padding-left: 18px;
+}
+
 .hub-page-games .pin-label {
   margin-right: 6px;
 }

games/index.html

@@ -33,7 +33,7 @@ <h2>Pinned Games</h2>
 
     <section class="content-section">
       <h2>Filter Games</h2>
-      <p>Filter by level, class, tag, or free-text search.</p>
+      <p>Filter by level, class, tool, tag, or free-text search.</p>
       <div class="games-filter-grid">
         <div class="games-filter-field">
           <label for="games-filter-level">Level</label>
@@ -53,6 +53,12 @@ <h2>Filter Games</h2>
             <option value="">All tags</option>
           </select>
         </div>
+        <div class="games-filter-field">
+          <label for="games-filter-tool">Tool</label>
+          <select id="games-filter-tool">
+            <option value="">All tools</option>
+          </select>
+        </div>
         <div class="games-filter-field">
           <label for="games-filter-search">Search</label>
           <input id="games-filter-search" type="text" placeholder="arcade, physics, planned..." autocomplete="off" />

games/index.render.js

@@ -1,3 +1,5 @@
+import { getToolRegistry } from "../tools/toolRegistry.js";
+
 const METADATA_PATH = "./metadata/games.index.metadata.json";
 const GAMES_PINNED_KEY = "games-index-pinned";
 
@@ -50,6 +52,79 @@ function escapeHtml(value) {
     .replaceAll("'", "'");
 }
 
+function toStandaloneToolHref(entryPoint) {
+  const normalized = String(entryPoint || "").replace(/^\.?\/*/, "");
+  return normalized ? `/tools/${encodeURI(normalized)}` : "";
+}
+
+function normalizeGameHref(value) {
+  const href = normalize(value).replace(/\\/g, "/");
+  if (!href || href.includes("..") || !href.startsWith("/games/")) {
+    return "";
+  }
+  return href;
+}
+
+function buildWorkspaceManagerHref(gameId) {
+  const normalizedGameId = normalize(gameId);
+  return normalizedGameId
+    ? `/tools/Workspace%20Manager/index.html?game=${encodeURIComponent(normalizedGameId)}`
+    : "/tools/Workspace%20Manager/index.html";
+}
+
+function buildReturnHref(toolId) {
+  const normalizedToolId = normalizeToken(toolId);
+  return normalizedToolId
+    ? `/games/index.html?tool=${encodeURIComponent(normalizedToolId)}`
+    : "/games/index.html";
+}
+
+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 buildRoundtripLinks(game, toolRegistryMap) {
+  const orderedToolHints = asArray(game?.toolHints)
+    .map((entry) => normalizeToken(entry))
+    .filter(Boolean)
+    .filter((toolId) => toolId !== "workspace-manager");
+  const dedupedToolHints = [...new Set(orderedToolHints)];
+  const links = [];
+
+  dedupedToolHints.forEach((toolId) => {
+    const tool = toolRegistryMap.get(toolId);
+    if (!tool) {
+      return;
+    }
+    const baseHref = toStandaloneToolHref(tool.entryPoint);
+    if (!baseHref) {
+      return;
+    }
+    const query = new URLSearchParams();
+    query.set("gameId", game.id);
+    if (game.title) {
+      query.set("gameTitle", game.title);
+    }
+    if (game.href) {
+      query.set("gameHref", game.href);
+    }
+    query.set("workspaceHref", buildWorkspaceManagerHref(game.id));
+    query.set("returnTo", buildReturnHref(tool.id));
+    const href = `${baseHref}?${query.toString()}`;
+    const label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
+    links.push({ toolId, href, label });
+  });
+
+  return links;
+}
+
 function statusLabel(status) {
   switch (status) {
     case "playable":
@@ -83,7 +158,7 @@ function writePinnedSet(pinnedSet) {
   window.localStorage.setItem(GAMES_PINNED_KEY, JSON.stringify([...pinnedSet].sort()));
 }
 
-function buildRows(metadata, pinnedSet) {
+function buildRows(metadata, pinnedSet, toolLabelMap, toolRegistryMap) {
   const rows = asArray(metadata?.games)
     .map((game) => {
       const id = normalize(game?.id);
@@ -96,17 +171,27 @@ function buildRows(metadata, pinnedSet) {
         .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
       const tags = [...new Set(asArray(game?.tags).map((value) => normalizeTag(value)).filter(Boolean))]
         .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+      const href = normalizeGameHref(game?.href);
+      const toolTokens = buildToolTokens(game?.toolHints, toolLabelMap);
+      const roundtripLinks = buildRoundtripLinks({
+        id,
+        title,
+        href,
+        toolHints: game?.toolHints
+      }, toolRegistryMap);
       return {
         id,
         title,
         description: normalize(game?.description) || "No description available.",
         level,
         status: normalize(game?.status) || "planned",
         classValues,
+        toolTokens,
+        roundtripLinks,
         tags,
         preview: normalize(game?.preview),
-        href: normalize(game?.href),
-        workspaceHref: normalize(game?.href) ? `/tools/Workspace%20Manager/index.html?game=${encodeURIComponent(id)}` : "",
+        href,
+        workspaceHref: href ? buildWorkspaceManagerHref(id) : "",
         sampleTrack: game?.sampleTrack === true,
         debugShowcase: game?.debugShowcase === true,
         requiresService: game?.requiresService === true
@@ -118,8 +203,13 @@ function buildRows(metadata, pinnedSet) {
 
   const levels = [...new Set(rows.map((row) => row.level))].sort(sortLevels);
   const classes = [...new Set(rows.flatMap((row) => row.classValues))].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+  const tools = [...new Map(
+    rows.flatMap((row) => row.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(rows.flatMap((row) => row.tags))].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
-  return { rows, levels, classes, tags };
+  return { rows, levels, classes, tools, tags };
 }
 
 function filterRows(rows, state) {
@@ -131,13 +221,17 @@ function filterRows(rows, state) {
     if (state.classValue && !row.classValues.includes(state.classValue)) {
       return false;
     }
+    if (state.toolId && !row.toolTokens.some((token) => token.value === state.toolId)) {
+      return false;
+    }
     if (state.tag && !row.tags.includes(state.tag)) {
       return false;
     }
     if (!query) {
       return true;
     }
-    const haystack = `${row.level} ${row.title} ${row.description} ${row.classValues.join(" ")} ${row.tags.join(" ")}`.toLowerCase();
+    const toolText = row.toolTokens.map((token) => `${token.label} ${token.value}`).join(" ");
+    const haystack = `${row.level} ${row.title} ${row.description} ${row.classValues.join(" ")} ${toolText} ${row.tags.join(" ")}`.toLowerCase();
     return haystack.includes(query);
   });
 }
@@ -186,13 +280,25 @@ function renderCard(row, instanceKey = "main") {
   const launchActions = row.workspaceHref
     ? `<p class="game-launch-actions"><a class="game-title-link" href="${escapeHtml(row.workspaceHref)}">Open In Workspace Manager</a></p>`
     : "";
+  const roundtripSection = Array.isArray(row.roundtripLinks) && row.roundtripLinks.length > 0
+    ? `
+      <section class="game-tool-roundtrip">
+        <h4>Tool Roundtrip Links</h4>
+        <p>Open game-related tools with workspace context and a return path back to Games.</p>
+        <ul>
+          ${row.roundtripLinks.map((entry) => `<li><a href="${escapeHtml(entry.href)}">${escapeHtml(entry.label)}</a></li>`).join("")}
+        </ul>
+      </section>
+    `
+    : "";
 
   article.innerHTML = `
     ${titleHtml}
     <div class="game-badges">${badges}</div>
     ${previewHtml}
     <p>${escapeHtml(row.description)}</p>
     ${launchActions}
+    ${roundtripSection}
     <p>Classes: ${escapeHtml(classText)}</p>
     <p>Tags: ${escapeHtml(tagText)}</p>
     ${row.requiresService ? '<p class="game-service-note">Requires background service.</p>' : ""}
@@ -262,9 +368,10 @@ export async function initGamesIndex() {
   const statusNode = document.getElementById("games-filter-status");
   const levelSelect = document.getElementById("games-filter-level");
   const classSelect = document.getElementById("games-filter-class");
+  const toolSelect = document.getElementById("games-filter-tool");
   const tagSelect = document.getElementById("games-filter-tag");
   const searchInput = document.getElementById("games-filter-search");
-  if (!container || !pinnedContainer || !statusNode || !levelSelect || !classSelect || !tagSelect || !searchInput) {
+  if (!container || !pinnedContainer || !statusNode || !levelSelect || !classSelect || !toolSelect || !tagSelect || !searchInput) {
     return;
   }
 
@@ -274,17 +381,39 @@ export async function initGamesIndex() {
     return;
   }
   const metadata = await response.json();
+  const toolRegistry = getToolRegistry();
+  const toolLabelMap = new Map(
+    toolRegistry
+      .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 toolRegistryMap = new Map(
+    toolRegistry
+      .filter((tool) => tool.id !== "workspace-manager")
+      .map((tool) => [normalizeToken(tool.id), tool])
+      .filter((entry) => entry[0] && entry[1])
+  );
   let pinnedSet = readPinnedSet();
-  let model = buildRows(metadata, pinnedSet);
+  let model = buildRows(metadata, pinnedSet, toolLabelMap, toolRegistryMap);
   setSelect(levelSelect, model.levels, (value) => value);
   setSelect(classSelect, model.classes, (value) => value.split("/").at(-1) || value);
+  setSelect(toolSelect, model.tools.map((entry) => entry.value), (value) => {
+    const found = model.tools.find((entry) => entry.value === value);
+    return found?.label || value;
+  });
   setSelect(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 apply = () => {
-    model = buildRows(metadata, pinnedSet);
+    model = buildRows(metadata, pinnedSet, toolLabelMap, toolRegistryMap);
     const state = {
       level: normalize(levelSelect.value),
       classValue: normalize(classSelect.value),
+      toolId: normalizeToken(toolSelect.value),
       tag: normalize(tagSelect.value),
       query: normalize(searchInput.value)
     };
@@ -312,6 +441,7 @@ export async function initGamesIndex() {
 
   levelSelect.addEventListener("change", apply);
   classSelect.addEventListener("change", apply);
+  toolSelect.addEventListener("change", apply);
   tagSelect.addEventListener("change", apply);
   searchInput.addEventListener("input", apply);
   container.addEventListener("change", handlePin);