Rehydrate Workspace Manager V2 repo and active game after returning from launched tools - PR_26128_027-workspace-return-repo-rehydrate

Author: DavidQ

docs/dev/reports/playwright_workspace_return_repo_rehydrate.md

@@ -0,0 +1,26 @@
+# Playwright Workspace Return Repo Rehydrate
+
+## Targeted Coverage
+- Verified return from Asset Manager V2 repopulates Repo Destination from `workspace.repo.reference`.
+- Verified return from Palette Manager V2 repopulates Repo Destination from `workspace.repo.reference`.
+- Verified return from Preview Generator V2 repopulates Repo Destination from `workspace.repo.reference`.
+- Verified Active Game remains selected after valid returns.
+- Verified tool buttons remain enabled after valid repo/game return hydration.
+- Verified missing repo session reference shows an actionable Workspace Manager V2 restore failure.
+- Verified malformed repo session reference also blocks restore and keeps controls disabled.
+
+## Commands
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `node --check tools/workspace-manager-v2/js/WorkspaceManagerV2App.js`
+- `node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "blocks Workspace Manager V2 return restore"`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "exports manifests and launches tools from fixed Workspace Manager V2 tiles"`
+- `npm run test:workspace-v2`
+
+## Result
+- Focused restore failure validation passed.
+- Focused return rehydration flow passed.
+- Full workspace-v2 Playwright validation passed: 16 tests.
+
+## Full Samples Smoke
+- Skipped per PR instructions because the requested change is scoped to Workspace Manager V2 return-from-tool session restoration.

docs/dev/reports/workspace_return_repo_rehydrate.md

@@ -0,0 +1,30 @@
+# PR_26128_027 Workspace Return Repo Rehydrate
+
+## Scope
+- Updated Workspace Manager V2 return-from-tool restore behavior.
+- Kept session storage as the integration boundary.
+- Preserved normalized `workspace.tools.<tool-id>` session keys.
+
+## Changes
+- Workspace Manager V2 now reads `workspace.repo.reference` before restoring a returned `hostContextId`.
+- Repo Destination display is repopulated from the session repo reference on valid returns.
+- Active Game and tool buttons remain restored only when both the session workspace context and repo reference are valid.
+- Missing or invalid repo session references now show an actionable restore failure and keep repo/game/tool controls disabled.
+- Added validation for repo reference JSON shape, `source`, `kind`, optional `storageKey`, display name, and manifest repo root compatibility.
+
+## Guardrails
+- No sample JSON files modified.
+- No roadmap files modified.
+- No cross-tool communication added.
+- No schema or normalized tool session key shape changes.
+
+## Validation
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs` passed.
+- `node --check tools/workspace-manager-v2/js/WorkspaceManagerV2App.js` passed.
+- `node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js` passed.
+- Focused missing/invalid repo reference restore test passed.
+- Focused Asset/Palette/Preview return flow test passed.
+- `npm run test:workspace-v2` passed: 16 tests.
+
+## Full Samples Smoke
+- Skipped per PR instructions. The change is limited to Workspace Manager V2 session return restore behavior and targeted Workspace Manager V2 Playwright coverage validates the affected flows.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -147,6 +147,16 @@ async function expectWorkspaceToolsDisabled(page) {
   expect(await page.locator("#workspaceToolTiles [data-workspace-tool-id]").evaluateAll((tiles) => tiles.every((tile) => tile.disabled))).toBe(true);
 }
 
+async function expectWorkspaceReturnRehydrated(page, { gameId = "Asteroids", repoName = "HTML-JavaScript-Gaming" } = {}) {
+  await expect(page.locator("#repoSelectedValue")).toHaveText(repoName);
+  await expect(page.locator("#activeGameSelect")).toHaveValue(gameId);
+  await expect(page.locator("#exportManifestButton")).toBeEnabled();
+  await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toBeEnabled();
+  await expect(page.locator('[data-workspace-tool-id="palette-manager-v2"]')).toBeEnabled();
+  await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toBeEnabled();
+  await expect(page.locator('[data-workspace-tool-id="session-inspector-v2"]')).toBeEnabled();
+}
+
 async function readWorkspaceSessionHydration(page) {
   return await page.evaluate(() => {
     const parseJson = (key) => {
@@ -1662,10 +1672,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(JSON.stringify(storedContext)).not.toMatch(/samples\//i);
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await expectWorkspaceReturnRehydrated(page);
       await expect(page.locator("#activeGameSelect")).toHaveValue("Asteroids");
       await expect(page.locator("#activeAssetRegistrySummary")).toHaveCount(0);
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toBeEnabled();
       await expect(page.locator("#exportManifestButton")).toBeEnabled();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Restored repo destination from workspace\.repo\.reference for HTML-JavaScript-Gaming\./);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Restored Asteroids workspace from session context workspace-manager-v2-/);
 
       await page.locator('[data-workspace-tool-id="palette-manager-v2"]').click();
@@ -1679,6 +1691,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#paletteStatus")).toHaveText("Loaded active workspace palette Asteroids Palette.");
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await expectWorkspaceReturnRehydrated(page);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Restored repo destination from workspace\.repo\.reference for HTML-JavaScript-Gaming\./);
       await expect(previewTile).toBeEnabled();
       await expect(previewTile).toContainText("Schema-valid manifest");
       await page.locator('[data-workspace-tool-id="preview-generator-v2"]').click();
@@ -1740,6 +1754,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(previewWrites[0].contents).not.toContain("Capture timeout");
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await expectWorkspaceReturnRehydrated(page);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Restored repo destination from workspace\.repo\.reference for HTML-JavaScript-Gaming\./);
       expect(pageErrors).toEqual([]);
     } finally {
       await coverageReporter.stop(page);
@@ -1790,6 +1806,50 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("blocks Workspace Manager V2 return restore when repo session reference is missing or invalid", async ({ page }) => {
+    const pageErrors = [];
+    const hostContextId = "workspace-manager-v2-missing-return-repo-reference";
+    const gameManifest = JSON.parse(await readFile("games/Asteroids/game.manifest.json", "utf8"));
+    const manifest = gameManifest.game.workspace;
+    await page.addInitScript(({ contextId, workspaceManifest }) => {
+      window.sessionStorage.setItem(contextId, JSON.stringify(workspaceManifest));
+    }, { contextId: hostContextId, workspaceManifest: manifest });
+    const server = await openWorkspaceManagerV2(page, `?hostContextId=${hostContextId}`);
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    try {
+      await expect(page.locator("#repoSelectedValue")).toHaveText("not selected");
+      await expect(page.locator("#activeGameSelect")).toBeDisabled();
+      await expect(page.locator("#activeGameSelect option")).toHaveCount(0);
+      await expect(page.locator("#exportManifestButton")).toBeDisabled();
+      await expect(page.locator("#workspaceContextOutput")).toHaveValue("{}");
+      await expectWorkspaceToolsDisabled(page);
+      await expect(page.locator("#activeGameSummary")).toHaveText("workspace.repo.reference was not found in sessionStorage. Pick Repo Folder to reselect repo before launching tools.");
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Workspace restore failed: workspace\.repo\.reference was not found in sessionStorage\. Pick Repo Folder to reselect repo before launching tools\./);
+      expect(await readWorkspaceSessionHydration(page)).toMatchObject({
+        repoReference: null,
+        toolKeys: []
+      });
+
+      await page.evaluate(({ contextId, workspaceManifest }) => {
+        window.sessionStorage.setItem(contextId, JSON.stringify(workspaceManifest));
+        window.sessionStorage.setItem("workspace.repo.reference", "not-json");
+      }, { contextId: hostContextId, workspaceManifest: manifest });
+      await page.goto(`${server.baseUrl}/tools/workspace-manager-v2/index.html?hostContextId=${hostContextId}`, { waitUntil: "networkidle" });
+      await expect(page.locator("#repoSelectedValue")).toHaveText("not selected");
+      await expect(page.locator("#activeGameSelect")).toBeDisabled();
+      await expectWorkspaceToolsDisabled(page);
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Workspace restore failed: workspace\.repo\.reference contains invalid JSON:/);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("opens Preview Generator V2 workspace launch with actionable missing repo session status", async ({ page }) => {
     const server = await startRepoServer();
     const pageErrors = [];

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

@@ -190,12 +190,24 @@ export class WorkspaceManagerV2App {
       this.statusLog.fail(`Workspace restore failed: ${result.message}`);
       return;
     }
+    const repoReferenceResult = this.contextService.readWorkspaceRepoReference({
+      expectedRepoRoot: result.context.repoRoot || result.game.repoRoot || ""
+    });
+    if (!repoReferenceResult.ok) {
+      const message = `${repoReferenceResult.message} Pick Repo Folder to reselect repo before launching tools.`;
+      this.repoDestination.setRepoDestinationDisplayName("not selected");
+      this.clearActiveWorkspace(message);
+      this.statusLog.fail(`Workspace restore failed: ${message}`);
+      return;
+    }
+    this.repoDestination.setRepoDestinationDisplayName(repoReferenceResult.reference.displayName);
     this.gameSelector.setValue(result.game.id, result.game.name);
     this.applyContextResult(result);
     if (result.assetWarning) {
       this.statusLog.info(`Warning: ${result.assetWarning}`);
     }
     this.reportSessionHydration();
+    this.statusLog.ok(`Restored repo destination from workspace.repo.reference for ${repoReferenceResult.reference.displayName}.`);
     this.statusLog.ok(`Restored ${result.game.name} workspace from session context ${result.hostContextId}.`);
   }
 

tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js

@@ -65,6 +65,22 @@ function makeHostContextId() {
   return `workspace-manager-v2-${Date.now().toString(36)}`;
 }
 
+function repoRootNameMatches(selectedRepoName, expectedRepoRoot) {
+  const expected = String(expectedRepoRoot || "").trim();
+  if (!expected) {
+    return true;
+  }
+  if (selectedRepoName === expected) {
+    return true;
+  }
+  const expectedFolderName = expected
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter(Boolean)
+    .at(-1);
+  return selectedRepoName === expectedFolderName;
+}
+
 function toolSessionKey(toolId) {
   return `${WORKSPACE_TOOL_SESSION_KEY_PREFIX}${toolId}`;
 }
@@ -368,6 +384,49 @@ export class WorkspaceManagerV2ContextService {
     this.sessionStorage.removeItem(WORKSPACE_REPO_REFERENCE_SESSION_KEY);
   }
 
+  readSessionJson(key) {
+    const rawValue = this.sessionStorage.getItem(key);
+    if (!rawValue) {
+      return { ok: false, message: `${key} was not found in sessionStorage.` };
+    }
+    try {
+      const value = JSON.parse(rawValue);
+      return isPlainObject(value)
+        ? { ok: true, value }
+        : { ok: false, message: `${key} must contain a JSON object.` };
+    } catch (error) {
+      return { ok: false, message: `${key} contains invalid JSON: ${error.message}` };
+    }
+  }
+
+  readWorkspaceRepoReference({ expectedRepoRoot = "" } = {}) {
+    const result = this.readSessionJson(WORKSPACE_REPO_REFERENCE_SESSION_KEY);
+    if (!result.ok) {
+      return result;
+    }
+    const reference = result.value;
+    if (reference.source !== "workspace-manager-v2") {
+      return { ok: false, message: `${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.source must be workspace-manager-v2.` };
+    }
+    if (reference.kind !== "file-system-directory-handle-reference") {
+      return { ok: false, message: `${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.kind must be file-system-directory-handle-reference.` };
+    }
+    if (reference.storageKey && reference.storageKey !== WORKSPACE_REPO_REFERENCE_SESSION_KEY) {
+      return { ok: false, message: `${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.storageKey must be ${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.` };
+    }
+    const displayName = String(reference.displayName || reference.handleName || "").trim();
+    if (!displayName) {
+      return { ok: false, message: `${WORKSPACE_REPO_REFERENCE_SESSION_KEY} must include displayName or handleName.` };
+    }
+    if (!repoRootNameMatches(displayName, expectedRepoRoot)) {
+      return {
+        ok: false,
+        message: `${WORKSPACE_REPO_REFERENCE_SESSION_KEY}.displayName ${displayName} does not match manifest repoRoot ${expectedRepoRoot}.`
+      };
+    }
+    return { ok: true, reference: { ...reference, displayName } };
+  }
+
   hydrateRepoReference(repoHandle, displayName = "") {
     const repoName = String(displayName || repoHandle?.name || "selected").trim() || "selected";
     const reference = {