Hydrate only game-relevant workspace tools for selected games - PR_26128_021-workspace-hydrate-game-tools-only

Author: DavidQ

docs/dev/reports/playwright_workspace_hydrate_game_tools_only.md

@@ -0,0 +1,27 @@
+# Playwright Workspace Hydrate Game Tools Only
+
+## Command
+`npm run test:workspace-v2`
+
+## Result
+- Passed: 15/15
+- Runtime: about 1.4 minutes
+
+## Targeted Coverage
+- Verified initial Workspace Manager V2 load still has no hydrated tool sessions.
+- Verified selecting Asteroids hydrates:
+  - `workspace.tools.asset-manager-v2`
+  - `workspace.tools.palette-manager-v2`
+  - `workspace.tools.preview-generator-v2`
+  - `workspace.tools.session-inspector-v2`
+- Verified selecting Asteroids does not hydrate `workspace.tools.templates-v2`.
+- Verified the hydration report lists hydrated tools and skipped tools with skip reasons.
+- Verified the `templates-v2` tile is disabled after Asteroids opens because it is not enabled for the selected game.
+- Verified Asset Manager V2 and Palette Manager V2 retain manifest-backed data hydration.
+- Verified dirty defaults remain clean for hydrated tools.
+- Verified Session Inspector V2 does not show an unrelated `workspace.tools.templates-v2` entry after selecting Asteroids.
+- Verified Preview Generator V2 still opens from Workspace Manager V2 and reaches enabled image generation state.
+- Verified imported Asteroids game manifests also skip `workspace.tools.templates-v2`.
+
+## Skipped
+- Full samples smoke test was skipped by request. The relevant hydration, launch, Session Inspector V2, and Preview Generator V2 paths are covered by `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`.

docs/dev/reports/workspace_hydrate_game_tools_only.md

@@ -0,0 +1,45 @@
+# Workspace Hydrate Game Tools Only
+
+## Scope
+- Updated Workspace Manager V2 session hydration to hydrate only tools relevant to the selected game/workspace.
+- Preserved the normalized per-tool session object:
+  - `schema`
+  - `workspace`
+  - `data`
+  - `dirty`
+- Preserved the existing clean dirty defaults:
+  - `isDirty: false`
+  - `reason: null`
+  - `changedAt: null`
+  - `changedKeys: []`
+- Did not change repo reference hydration at `workspace.repo.reference`.
+
+## Hydration Rules
+- Hydrate a tool when its payload exists in the selected game workspace config.
+- Hydrate selected-game purpose launch-context tools that need the active game context.
+- Skip starter/dev-only tools when the selected game workspace does not explicitly provide tool data for them.
+- Disable skipped tool tiles after a game is opened so only hydrated tools are launchable.
+
+## Asteroids Hydration Report
+| Tool | Result | Reason |
+| --- | --- | --- |
+| `asset-manager-v2` | Hydrated | Tool data is present in selected game workspace config. |
+| `palette-manager-v2` | Hydrated | Tool data is present in selected game workspace config. |
+| `preview-generator-v2` | Hydrated | Tool has a selected-game workspace launch purpose. |
+| `session-inspector-v2` | Hydrated | Tool has a selected-game workspace launch purpose. |
+| `templates-v2` | Skipped | Starter/dev-only tool is not enabled by the selected game workspace config. |
+
+## Validation Notes
+- Selecting Asteroids does not create `workspace.tools.templates-v2`.
+- Asset Manager V2 and Palette Manager V2 hydrate with their manifest data when present.
+- Preview Generator V2 still opens from Workspace Manager V2 and can generate from hydrated repo/game session context.
+- Session Inspector V2 shows hydrated game-relevant `workspace.tools.*` entries and no unrelated `workspace.tools.templates-v2` entry.
+
+## Guardrails
+- No cross-tool communication was added.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- No schema/runtime contract changes were made.
+
+## Skipped
+- Full samples smoke test was skipped by request. The changed surface is Workspace Manager V2 session hydration and Workspace Manager V2 launch/session behavior, covered by `npm run test:workspace-v2`.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1134,16 +1134,29 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         "workspace.tools.asset-manager-v2",
         "workspace.tools.palette-manager-v2",
         "workspace.tools.preview-generator-v2",
-        "workspace.tools.session-inspector-v2",
-        "workspace.tools.templates-v2"
+        "workspace.tools.session-inspector-v2"
       ]);
+      expect(selectedGameHydration.toolKeys).not.toContain("workspace.tools.templates-v2");
       expect(selectedGameHydration.toolKeys.some((key) => key.endsWith(".schema") || key.endsWith(".state"))).toBe(false);
       expect(Object.keys(selectedGameHydration.toolSessions).sort()).toEqual([
         "asset-manager-v2",
         "palette-manager-v2",
         "preview-generator-v2",
-        "session-inspector-v2",
-        "templates-v2"
+        "session-inspector-v2"
+      ]);
+      const selectedGameHydrationReport = await page.evaluate(() => window.__workspaceManagerV2App.activeSessionHydration.report);
+      expect(selectedGameHydrationReport.hydratedTools.map((tool) => tool.toolId)).toEqual([
+        "asset-manager-v2",
+        "palette-manager-v2",
+        "preview-generator-v2",
+        "session-inspector-v2"
+      ]);
+      expect(selectedGameHydrationReport.skippedTools).toEqual([
+        {
+          reason: "starter/dev-only tool is not enabled by the selected game workspace config",
+          toolId: "templates-v2",
+          toolName: "Tool Starter V2"
+        }
       ]);
       expect(Object.values(selectedGameHydration.toolSessions).every((session) => (
         JSON.stringify(Object.keys(session).sort()) === JSON.stringify(["data", "dirty", "schema", "workspace"])
@@ -1172,12 +1185,11 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       });
       expect(selectedGameHydration.toolSessions["asset-manager-v2"].state).toBeUndefined();
       expect(Object.keys(selectedGameHydration.dataByTool["asset-manager-v2"].assets)).toHaveLength(14);
-      expect(selectedGameHydration.dataByTool["templates-v2"]).toBeNull();
+      expect(selectedGameHydration.toolSessions["templates-v2"]).toBeUndefined();
       expect(Object.values(selectedGameHydration.dirtyByTool)).toEqual([
         { isDirty: false, reason: null, changedAt: null, changedKeys: [] },
         { isDirty: false, reason: null, changedAt: null, changedKeys: [] },
         { isDirty: false, reason: null, changedAt: null, changedKeys: [] },
-        { isDirty: false, reason: null, changedAt: null, changedKeys: [] },
         { isDirty: false, reason: null, changedAt: null, changedKeys: [] }
       ]);
       await page.evaluate(() => {
@@ -1210,8 +1222,9 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       const paletteTile = page.locator('[data-workspace-tool-id="palette-manager-v2"]');
       const previewTile = page.locator('[data-workspace-tool-id="preview-generator-v2"]');
       const sessionInspectorTile = page.locator('[data-workspace-tool-id="session-inspector-v2"]');
-      await expect(templateTile).toBeEnabled();
+      await expect(templateTile).toBeDisabled();
       await expect(templateTile).toContainText("Tool Starter V2");
+      await expect(templateTile).toContainText("Not enabled for game");
       await expect(templateTile).toContainText("Canonical V2 template");
       await expect(assetTile).toBeEnabled();
       await expect(assetTile).toContainText("Asset Manager V2");
@@ -1234,9 +1247,20 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         { height: 142, width: 180 }
       ]);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Boundary contract: game\.gameData is runtime data; game\.workspace is editor\/tool state\. Runtime ignores game\.workspace; tools may read game\.gameData, write game\.workspace, and update game\.gameData only through explicit validated apply\/build\/export actions\./);
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Hydrated workspace session for templates-v2, asset-manager-v2, palette-manager-v2, preview-generator-v2, session-inspector-v2\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Hydrated workspace session for asset-manager-v2, palette-manager-v2, preview-generator-v2, session-inspector-v2\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Skipped workspace session hydration for templates-v2: starter\/dev-only tool is not enabled by the selected game workspace config\./);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded Asteroids from \/games\/Asteroids\/game\.manifest\.json with 11 active palette colors and 14 managed assets\./);
 
+      await page.locator('[data-workspace-tool-id="session-inspector-v2"]').click();
+      await expect(page).toHaveURL(/session-inspector-v2\/index\.html.*launch=workspace/);
+      await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.asset-manager-v2']")).toHaveCount(1);
+      await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.palette-manager-v2']")).toHaveCount(1);
+      await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.preview-generator-v2']")).toHaveCount(1);
+      await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.session-inspector-v2']")).toHaveCount(1);
+      await expect(page.locator("#sessionInspectorV2EntryList [data-session-inspector-v2-entry-id='sessionStorage:workspace.tools.templates-v2']")).toHaveCount(0);
+      await page.locator("#returnToWorkspaceButton").click();
+      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+
       const downloadPromise = page.waitForEvent("download");
       await page.locator("#exportManifestButton").click();
       const download = await downloadPromise;
@@ -1436,13 +1460,6 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#exportManifestButton")).toBeEnabled();
       await expect(page.locator("#statusLog")).toHaveValue(/OK Restored Asteroids workspace from session context workspace-manager-v2-/);
 
-      await page.locator('[data-workspace-tool-id="templates-v2"]').click();
-      await expect(page).toHaveURL(/templates-v2\/index\.html.*launch=workspace/);
-      await expect(page.locator('[data-launch-mode-nav="tool"]')).toBeHidden();
-      await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeVisible();
-      await expect(page.locator('[data-launch-mode-nav="workspace"]').getByRole("button")).toHaveText(["Return to Workspace"]);
-      await page.locator("#returnToWorkspaceButton").click();
-      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       await page.locator('[data-workspace-tool-id="palette-manager-v2"]').click();
       await expect(page).toHaveURL(/palette-manager-v2\/index\.html.*launch=workspace/);
       await expect(page.locator('[data-launch-mode-nav="tool"]')).toBeHidden();
@@ -1543,9 +1560,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"id": "workspace-manager-v2-Asteroids-imported"/);
       await expect(page.locator("#activeAssetRegistrySummary")).toHaveCount(0);
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toBeEnabled();
-      expect((await readWorkspaceSessionHydration(page)).toolKeys).toContain("workspace.tools.asset-manager-v2");
+      const importedHydration = await readWorkspaceSessionHydration(page);
+      expect(importedHydration.toolKeys).toContain("workspace.tools.asset-manager-v2");
+      expect(importedHydration.toolKeys).not.toContain("workspace.tools.templates-v2");
       await expect(page.locator("#statusLog")).toHaveValue(/OK Boundary contract: game\.gameData is runtime data; game\.workspace is editor\/tool state\. Runtime ignores game\.workspace; tools may read game\.gameData, write game\.workspace, and update game\.gameData only through explicit validated apply\/build\/export actions\./);
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Hydrated workspace session for templates-v2, asset-manager-v2, palette-manager-v2, preview-generator-v2, session-inspector-v2\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Hydrated workspace session for asset-manager-v2, palette-manager-v2, preview-generator-v2, session-inspector-v2\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Skipped workspace session hydration for templates-v2: starter\/dev-only tool is not enabled by the selected game workspace config\./);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Imported schema-valid Workspace Manager V2 manifest workspace-manager-v2-Asteroids-imported\./);
 
       const downloadPromise = page.waitForEvent("download");

tools/workspace-manager-v2/js/WorkspaceManagerV2App.js

@@ -215,6 +215,7 @@ export class WorkspaceManagerV2App {
     this.toolTiles.render({
       assetCount: result.assetCount,
       canLaunch: hydration.ok,
+      enabledToolIds: hydration.ok ? hydration.hydratedToolIds : [],
       manifestStatus: "Schema-valid manifest",
       paletteSwatchCount: result.paletteSwatches.length
     });
@@ -230,6 +231,9 @@ export class WorkspaceManagerV2App {
       return;
     }
     this.statusLog.ok(`Hydrated workspace session for ${this.activeSessionHydration.hydratedToolIds.join(", ")}.`);
+    (this.activeSessionHydration.skippedTools || []).forEach((tool) => {
+      this.statusLog.info(`Skipped workspace session hydration for ${tool.toolId}: ${tool.reason}.`);
+    });
   }
 
   hasLaunchReadyContext() {
@@ -244,6 +248,10 @@ export class WorkspaceManagerV2App {
       this.statusLog.fail("Launch blocked: active game context and palette are required.");
       return;
     }
+    if (!this.activeSessionHydration.hydratedToolIds.includes(toolId)) {
+      this.statusLog.fail(`Launch blocked: ${toolId} is not enabled for ${this.activeGame.name}.`);
+      return;
+    }
     const validation = await this.contextService.validateGeneratedManifest(this.activeContext);
     if (!validation.ok) {
       this.statusLog.fail(`Launch blocked: ${validation.message}`);

tools/workspace-manager-v2/js/controls/ToolTilesControl.js

@@ -25,12 +25,15 @@ export class ToolTilesControl {
   render({
     assetCount = 0,
     canLaunch = false,
+    enabledToolIds = [],
     manifestStatus = "Waiting for manifest",
     paletteSwatchCount = 0
   } = {}) {
+    const enabledToolIdSet = new Set(enabledToolIds);
     this.container.replaceChildren(...TOOL_GROUPS.map((group) => this.groupSection({
       assetCount,
       canLaunch,
+      enabledToolIdSet,
       group,
       manifestStatus,
       paletteSwatchCount
@@ -53,7 +56,7 @@ export class ToolTilesControl {
     return manifestStatus;
   }
 
-  groupSection({ assetCount, canLaunch, group, manifestStatus, paletteSwatchCount }) {
+  groupSection({ assetCount, canLaunch, enabledToolIdSet, group, manifestStatus, paletteSwatchCount }) {
     const section = document.createElement("section");
     section.className = "workspace-manager-v2__tool-group";
     section.setAttribute("aria-label", `${group} tools`);
@@ -70,6 +73,7 @@ export class ToolTilesControl {
         grid.append(this.tile({
           assetCount,
           canLaunch,
+          enabledToolIdSet,
           manifestStatus,
           paletteSwatchCount,
           tool
@@ -80,12 +84,13 @@ export class ToolTilesControl {
     return section;
   }
 
-  tile({ assetCount, canLaunch, manifestStatus, paletteSwatchCount, tool }) {
+  tile({ assetCount, canLaunch, enabledToolIdSet, manifestStatus, paletteSwatchCount, tool }) {
+    const isEnabledForGame = canLaunch && enabledToolIdSet.has(tool.id);
     const button = document.createElement("button");
     button.type = "button";
     button.className = "workspace-manager-v2__tool-tile";
     button.dataset.workspaceToolId = tool.id;
-    button.disabled = !canLaunch;
+    button.disabled = !isEnabledForGame;
     button.addEventListener("click", () => {
       this.onLaunchTool(tool.id);
     });
@@ -96,7 +101,7 @@ export class ToolTilesControl {
 
     const state = document.createElement("span");
     state.className = "workspace-manager-v2__tool-tile-state";
-    state.textContent = canLaunch ? "Ready to launch" : "Waiting for manifest";
+    state.textContent = isEnabledForGame ? "Ready to launch" : (canLaunch ? "Not enabled for game" : "Waiting for manifest");
 
     const detailText = this.detailForTool(tool, { assetCount, manifestStatus, paletteSwatchCount });