Phase 5 slice: route Games Hub launches through Workspace Manager via ?game=<id>, add Workspace game-host iframe mode, and mark first games roadmap item complete with batch-37 PASS validation.

DavidQ · DavidQ · commit 00efb1883ef4 · 2026-04-24T18:26:25.000-04:00
diff --git a/docs/dev/reports/samples2tools_batch_37_summary.txt b/docs/dev/reports/samples2tools_batch_37_summary.txt
@@ -0,0 +1,11 @@
+Samples2Tools batch 37 summary
+Generated: 2026-04-24T22:19:25.278Z
+Purpose: deliver first executable Phase 5 slice by making Games Hub launch through Workspace Manager.
+
+Completed this batch:
+- Added Workspace Manager game-host mode (`?game=<id>`) that resolves game href from games metadata
+- Updated Games Hub cards to route launchable games to Workspace Manager
+- Kept optional standalone game link available for side-by-side verification
+
+Primary validation artifact:
+- docs/dev/reports/samples2tools_batch_37_validation.txt (PASS)
diff --git a/docs/dev/reports/samples2tools_batch_37_validation.txt b/docs/dev/reports/samples2tools_batch_37_validation.txt
@@ -0,0 +1,14 @@
+Samples2Tools batch 37 validation
+Generated: 2026-04-24T22:19:25.278Z
+Scope: Phase 5 slice - launch games via Workspace Manager from Games Hub.
+
+- [PASS] Workspace Manager reads game query parameter :: tools/Workspace Manager/main.js
+- [PASS] Workspace Manager resolves game entry from games metadata :: tools/Workspace Manager/main.js
+- [PASS] Workspace Manager can mount game iframe mode :: tools/Workspace Manager/main.js
+- [PASS] Games index routes launchable games to Workspace Manager :: games/index.render.js
+- [PASS] Launchable games available for Workspace flow :: count=11
+- [PASS] Workspace game launch href construction sane :: issues=0
+
+Checks: 6
+Failures: 0
+Result: PASS
diff --git a/docs/dev/reports/samples2tools_batch_38_summary.txt b/docs/dev/reports/samples2tools_batch_38_summary.txt
@@ -0,0 +1,11 @@
+Samples2Tools batch 38 summary
+Generated: 2026-04-24T22:22:54.716Z
+Purpose: remove standalone game launch actions from the primary Games Hub surface.
+
+Completed this batch:
+- Removed standalone game launch link from game card actions
+- Kept Workspace Manager launch action as the only explicit game card launch action
+- Revalidated launchable game coverage for workspace launch path construction
+
+Primary validation artifact:
+- docs/dev/reports/samples2tools_batch_38_validation.txt (PASS)
diff --git a/docs/dev/reports/samples2tools_batch_38_validation.txt b/docs/dev/reports/samples2tools_batch_38_validation.txt
@@ -0,0 +1,11 @@
+Samples2Tools batch 38 validation
+Generated: 2026-04-24T22:22:54.716Z
+Scope: Phase 5 harden primary games surface to Workspace-only launch actions.
+
+- [PASS] Games card actions no longer render standalone game launch link :: games/index.render.js
+- [PASS] Games card actions keep Workspace Manager launch link :: games/index.render.js
+- [PASS] All launchable games have workspace launch path pattern :: launchable=11
+
+Checks: 3
+Failures: 0
+Result: PASS
diff --git a/docs/dev/reports/samples2tools_batch_39_summary.txt b/docs/dev/reports/samples2tools_batch_39_summary.txt
@@ -0,0 +1,12 @@
+Samples2Tools batch 39 summary
+Generated: 2026-04-24T22:25:29.424Z
+Purpose: harden games lane so Workspace Manager is the canonical launch surface.
+
+Completed this batch:
+- Added a shared game launch guard that redirects non-hosted direct game page opens to Workspace Manager
+- Applied guard to all launchable game index pages from games metadata
+- Ensured Games Hub card actions no longer advertise standalone game launch
+- Ensured Workspace Manager game-host iframe passes hosted context params
+
+Primary validation artifact:
+- docs/dev/reports/samples2tools_batch_39_validation.txt (PASS)
diff --git a/docs/dev/reports/samples2tools_batch_39_validation.txt b/docs/dev/reports/samples2tools_batch_39_validation.txt
@@ -0,0 +1,12 @@
+Samples2Tools batch 39 validation
+Generated: 2026-04-24T22:25:29.424Z
+Scope: Phase 5 hardening - enforce Workspace-first launches for game pages and Games Hub cards.
+
+- [PASS] Workspace game-host mode appends hosted params :: tools/Workspace Manager/main.js
+- [PASS] Games Hub card actions are Workspace-only (no standalone action) :: games/index.render.js
+- [PASS] Shared workspace game launch guard exists :: games/shared/workspaceGameLaunchGuard.js
+- [PASS] All launchable games include workspace launch guard :: launchable=11, guardIssues=0, missingFiles=0
+
+Checks: 4
+Failures: 0
+Result: PASS
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md b/docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md
@@ -121,7 +121,7 @@
 - [x] Select precise, semantically aligned samples only (avoid broad keyword-only linkage).
 
 ### Phase 5 - Games
-- [ ] Do the same thing for games, but use Workspace Manager.
+- [x] Do the same thing for games, but use Workspace Manager.
 - [ ] 100% of the game data needs to be generated from Workspace Manager
 - [ ] No Tool should be used independantly
 
diff --git a/games/AITargetDummy/index.html b/games/AITargetDummy/index.html
@@ -11,6 +11,10 @@
   <title>AI Target Dummy</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("AITargetDummy");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/Asteroids/index.html b/games/Asteroids/index.html
@@ -12,6 +12,10 @@
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="/games/shared/styles/vectorBattleFont.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("Asteroids");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/GravityWell/index.html b/games/GravityWell/index.html
@@ -11,6 +11,10 @@
   <title>Gravity Well</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("GravityWell");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/Pacman/index.html b/games/Pacman/index.html
@@ -11,6 +11,10 @@
   <title>Pacman</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("Pacman");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/SolarSystem/index.html b/games/SolarSystem/index.html
@@ -11,6 +11,10 @@
   <title>Solar System</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("SolarSystem");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/SpaceDuel/index.html b/games/SpaceDuel/index.html
@@ -11,6 +11,10 @@
   <title>Space Duel</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("SpaceDuel");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/SpaceInvaders/index.html b/games/SpaceInvaders/index.html
@@ -11,6 +11,10 @@
   <title>Space Invaders Next</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("SpaceInvaders");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/bouncing-ball/index.html b/games/bouncing-ball/index.html
@@ -11,6 +11,10 @@
   <title>Bouncing Ball</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("Bouncing-ball");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/breakout/index.html b/games/breakout/index.html
@@ -12,6 +12,10 @@
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="/samples/shared/debugShowcaseControls.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("Breakout");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/index.css b/games/index.css
@@ -112,6 +112,10 @@
   font-size: 0.9rem;
 }
 
+.game-launch-actions {
+  margin: 6px 0 8px;
+}
+
 .hub-page-games .pin-label {
   margin-right: 6px;
 }
diff --git a/games/index.render.js b/games/index.render.js
@@ -106,6 +106,7 @@ function buildRows(metadata, pinnedSet) {
         tags,
         preview: normalize(game?.preview),
         href: normalize(game?.href),
+        workspaceHref: normalize(game?.href) ? `/tools/Workspace%20Manager/index.html?game=${encodeURIComponent(id)}` : "",
         sampleTrack: game?.sampleTrack === true,
         debugShowcase: game?.debugShowcase === true,
         requiresService: game?.requiresService === true
@@ -163,13 +164,14 @@ function renderCard(row, instanceKey = "main") {
   article.className = "card-link game-card";
   article.dataset.gameId = row.id;
 
+  const launchHref = row.workspaceHref || row.href || "";
   const previewHtml = row.preview
-    ? `<a class="game-preview-link" href="${escapeHtml(row.href || "#")}" ${row.href ? "" : "aria-disabled=\"true\""}><img class="game-thumb" loading="lazy" decoding="async" alt="${escapeHtml(row.title)} thumbnail" src="${escapeHtml(row.preview)}"></a>`
+    ? `<a class="game-preview-link" href="${escapeHtml(launchHref || "#")}" ${launchHref ? "" : "aria-disabled=\"true\""}><img class="game-thumb" loading="lazy" decoding="async" alt="${escapeHtml(row.title)} thumbnail" src="${escapeHtml(row.preview)}"></a>`
     : `<span class="game-preview-link game-preview-missing">No Preview</span>`;
 
   const pinInputId = `game-pin-${escapeHtml(row.id)}-${escapeHtml(instanceKey)}`;
-  const titleLabel = row.href
-    ? `<a class="game-title-link" href="${escapeHtml(row.href)}">${escapeHtml(row.title)}</a>`
+  const titleLabel = launchHref
+    ? `<a class="game-title-link" href="${escapeHtml(launchHref)}">${escapeHtml(row.title)}</a>`
     : `${escapeHtml(row.title)}`;
   const titleHtml = `<h3 class="game-title-row"><input id="${pinInputId}" type="checkbox" class="pin-toggle" data-game-pin="${escapeHtml(row.id)}" ${row.pinned ? "checked" : ""}><label for="${pinInputId}" class="pin-label" title="${row.pinned ? "Unpin" : "Pin"}" aria-label="${row.pinned ? "Unpin game" : "Pin game"}"><span class="pin-icon" aria-hidden="true"></span></label>${titleLabel}</h3>`;
 
@@ -184,12 +186,16 @@ function renderCard(row, instanceKey = "main") {
   const asteroidDebugLink = row.id === "Asteroids"
     ? '<p><a class="game-title-link" href="/games/Asteroids/index.html?debug=1">Debug Mode</a></p>'
     : "";
+  const launchActions = row.workspaceHref
+    ? `<p class="game-launch-actions"><a class="game-title-link" href="${escapeHtml(row.workspaceHref)}">Open In Workspace Manager</a></p>`
+    : "";
 
   article.innerHTML = `
     ${titleHtml}
     <div class="game-badges">${badges}</div>
     ${previewHtml}
     <p>${escapeHtml(row.description)}</p>
+    ${launchActions}
     ${asteroidDebugLink}
     <p>Classes: ${escapeHtml(classText)}</p>
     <p>Tags: ${escapeHtml(tagText)}</p>
diff --git a/games/pong/index.html b/games/pong/index.html
@@ -11,6 +11,10 @@
   <title>Pong</title>
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("Pong");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/games/shared/workspaceGameLaunchGuard.js b/games/shared/workspaceGameLaunchGuard.js
@@ -0,0 +1,27 @@
+function normalizeGameId(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function enforceWorkspaceGameLaunch(gameId) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const normalizedGameId = normalizeGameId(gameId);
+  if (!normalizedGameId) {
+    return;
+  }
+
+  const url = new URL(window.location.href);
+  const params = url.searchParams;
+  const hosted = params.get("hosted") === "1";
+  const hostToolId = (params.get("hostToolId") || "").trim().toLowerCase();
+  const allowStandalone = params.get("allowStandalone") === "1";
+
+  if (allowStandalone || (hosted && hostToolId === "workspace-manager")) {
+    return;
+  }
+
+  const redirectUrl = new URL("/tools/Workspace%20Manager/index.html", window.location.origin);
+  redirectUrl.searchParams.set("game", normalizedGameId);
+  window.location.replace(redirectUrl.toString());
+}
diff --git a/games/vector-arcade-sample/index.html b/games/vector-arcade-sample/index.html
@@ -6,6 +6,10 @@
   <link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
   <link rel="stylesheet" href="/games/shared/styles/vectorBattleFont.css" />
   <link rel="stylesheet" href="../../src/engine/theme/main.css" />
+  <script type="module">
+    import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
+    enforceWorkspaceGameLaunch("vector-arcade-sample");
+  </script>
 </head>
 <body class="hub-page-games">
   <div id="shared-theme-header"></div>
diff --git a/tools/Workspace Manager/main.js b/tools/Workspace Manager/main.js
