Fix Preview Generator workspace launch repo root and preview file hydration - PR_26127_005-workspace-manager-v2-tool-tile-cleanup-preview-fix

Author: DavidQ

docs/dev/reports/PR_26127_006-preview-generator-v2-workspace-launch-hydration-fix.md

@@ -0,0 +1,43 @@
+# PR_26127_006-preview-generator-v2-workspace-launch-hydration-fix
+
+## Scope
+
+- Preview Generator V2 workspace-launch hydration from Workspace Manager V2.
+- Workspace Manager V2 Playwright coverage for the Preview Generator V2 launch path.
+- Deprecated `tools/workspace-v2` was not modified.
+- Sample JSON was not modified.
+- No fallback behavior was added.
+
+## Hydration Notes
+
+- Workspace Manager V2 launch no longer writes the workspace/game label into the Preview Generator V2 repo root field.
+- The repo root field remains `not selected` until the user selects an actual repo root folder.
+- The workspace/game label is shown separately as Workspace launch context.
+- Generate Image remains disabled during workspace launch until a valid repo root, target source, asset folder, and preview target file are all valid.
+- Repo root selection now validates that the chosen folder exposes repo-level `games` and `tools` directories.
+
+## Preview Target Notes
+
+- Preview Generator V2 now resolves the workspace preview target as the schema-backed bezel image asset from the manifest.
+- For Asteroids, the resolved preview target is `games/Asteroids/assets/images/bezel.png`.
+- The asset folder still hydrates as `assets/images`, but hydration also records and displays the full preview target file path.
+- Preview target validation checks that the resolved file exists and is image-like by response type or image filename extension.
+
+## Validation
+
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list` passed.
+- `npm run test:workspace-v2` passed.
+- Result: 24 passed.
+- Playwright impacted: Yes.
+- Full samples smoke test skipped because this PR is Workspace Manager V2 to Preview Generator V2 launch scoped.
+
+## Manual Validation Notes
+
+1. Open Workspace Manager V2.
+2. Load Asteroids.
+3. Launch Preview Generator V2 from the Preview Generator V2 tile.
+4. Confirm Repo selected remains `not selected`, while Workspace launch shows `Asteroids workspace (games/Asteroids)`.
+5. Confirm Preview target shows `games/Asteroids/assets/images/bezel.png`.
+6. Confirm Generate Image is disabled before selecting the repo root.
+7. Click Pick Repo Folder and choose the actual `HTML-JavaScript-Gaming` repo root.
+8. Confirm Repo selected shows the actual repo folder and Generate Image becomes enabled.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -24,6 +24,37 @@ async function openToolsIndex(page) {
   return server;
 }
 
+async function installPreviewGeneratorRepoRootPicker(page) {
+  await page.addInitScript(() => {
+    class FakeDirectoryHandle {
+      constructor(name) {
+        this.kind = "directory";
+        this.name = name;
+        this.children = new Map();
+      }
+
+      addDirectory(name) {
+        const directory = new FakeDirectoryHandle(name);
+        this.children.set(name, directory);
+        return directory;
+      }
+
+      async getDirectoryHandle(name) {
+        const child = this.children.get(name);
+        if (child?.kind === "directory") {
+          return child;
+        }
+        throw new Error(`Missing directory: ${name}`);
+      }
+    }
+
+    const repo = new FakeDirectoryHandle("HTML-JavaScript-Gaming");
+    repo.addDirectory("games");
+    repo.addDirectory("tools");
+    window.showDirectoryPicker = async () => repo;
+  });
+}
+
 test.describe("Workspace Manager V2 bootstrap", () => {
   test.afterAll(async () => {
     await coverageReporter.writeReport();
@@ -405,29 +436,30 @@ 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 page.route("**/games/Asteroids/assets/images/preview.svg", async (route) => {
-        await route.fulfill({
-          body: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect width="8" height="8"/></svg>',
-          contentType: "image/svg+xml",
-          status: 200
-        });
-      });
+      await installPreviewGeneratorRepoRootPicker(page);
       await page.locator('[data-workspace-tool-id="preview-generator-v2"]').click();
       await expect(page).toHaveURL(/preview-generator-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"] button')).toHaveText(["Generate Image", "Return to Workspace"]);
       await expect(page.locator("#executeBtn")).toBeVisible();
-      await expect(page.locator("#executeBtn")).toBeEnabled();
-      await expect(page.locator("#repoSelectedValue")).toHaveText("Asteroids workspace (games/Asteroids)");
+      await expect(page.locator("#executeBtn")).toBeDisabled();
+      await expect(page.locator("#repoSelectedValue")).toHaveText("not selected");
+      await expect(page.locator("#workspaceContextValue")).toHaveText("Asteroids workspace (games/Asteroids)");
       await expect(page.locator("#targetTypeGames")).toBeChecked();
       await expect(page.locator("#assetFolder")).toHaveValue("assets/images");
       await expect(page.locator("#sampleList")).toHaveValue("Asteroids");
+      await expect(page.locator("#previewTargetValue")).toHaveText("games/Asteroids/assets/images/bezel.png");
       await expect(page.locator("#lastGeneratedImagePreview")).toBeVisible();
-      await expect(page.locator("#lastGeneratedImageMeta")).toHaveText("Last generated: Asteroids preview.svg");
+      await expect(page.locator("#lastGeneratedImageMeta")).toHaveText("Preview target: games/Asteroids/assets/images/bezel.png");
       await expect(page.locator("#log")).toContainText("OK Workspace launch context hydrated for Asteroids.");
+      await expect(page.locator("#log")).toContainText("Repo selected: not selected; pick the actual repo root folder.");
       await expect(page.locator("#log")).toContainText("Asset folder: assets\\images");
-      await expect(page.locator("#log")).toContainText("OK Loaded existing preview image from /games/Asteroids/assets/images/preview.svg.");
+      await expect(page.locator("#log")).toContainText("Preview target: games/Asteroids/assets/images/bezel.png");
+      await expect(page.locator("#log")).toContainText("OK Workspace preview target is valid at games/Asteroids/assets/images/bezel.png.");
+      await page.locator("#pickRepoBtn").click();
+      await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
+      await expect(page.locator("#executeBtn")).toBeEnabled();
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       expect(pageErrors).toEqual([]);

tools/preview-generator-v2/PreviewGeneratorV2App.js

@@ -13,7 +13,10 @@ let repoDirHandle = null;
 let stopRequested = false;
 let repoDisplayName = "";
 let isGenerating = false;
-let workspaceLaunchReady = false;
+let workspacePreviewAssetFolder = "";
+let workspacePreviewFileValid = false;
+let workspacePreviewGameId = "";
+let workspacePreviewTargetPath = "";
 const ui = new PreviewGeneratorV2Ui();
 const logger = new PreviewGeneratorV2Logger({
   statusEl: ui.statusLog.getStatusElement(),
@@ -99,39 +102,62 @@ function workspaceAssetFolder(manifest) {
   return assetsPath.slice(gameRoot.length + 1);
 }
 
-function workspaceImageAssetFolder(manifest) {
+function workspacePreviewTarget(manifest) {
   const gameRoot = normalizeWorkspacePath(manifest.gameRoot);
   const assetFolder = workspaceAssetFolder(manifest);
   if (!assetFolder) {
-    return "";
+    return { ok: false, message: "assetsPath must be inside gameRoot." };
   }
   const imageAsset = Object.values(manifest.tools?.["asset-manager-v2"]?.assets || {})
-    .find((asset) => asset?.type === "image" && normalizeWorkspacePath(asset.path));
+    .find((asset) => asset?.type === "image" && asset?.role === "bezel" && normalizeWorkspacePath(asset.path));
+  if (!imageAsset) {
+    return { ok: false, message: "manifest must include a bezel image asset path under assetsPath." };
+  }
   const imagePath = normalizeWorkspacePath(imageAsset?.path);
   const imagePathFromGameRoot = imagePath.startsWith(`${gameRoot}/`)
     ? imagePath.slice(gameRoot.length + 1)
     : imagePath;
   if (!imagePathFromGameRoot.startsWith(`${assetFolder}/`)) {
-    return "";
+    return { ok: false, message: `${imagePath || "(empty)"} must resolve under ${assetFolder}.` };
   }
-  const imageFolder = imagePathFromGameRoot.split("/").slice(0, -1).join("/");
-  return imageFolder || "";
+  const previewAssetFolder = imagePathFromGameRoot.split("/").slice(0, -1).join("/");
+  if (!previewAssetFolder) {
+    return { ok: false, message: `${imagePath} does not include an asset folder.` };
+  }
+  return {
+    ok: true,
+    previewAssetFolder,
+    previewTargetPath: `${gameRoot}/${imagePathFromGameRoot}`
+  };
 }
 
-async function readWorkspacePreviewSvg(manifest, assetFolder) {
-  const gameRoot = normalizeWorkspacePath(manifest.gameRoot);
-  if (!gameRoot || !assetFolder) {
-    return { ok: false, message: "Workspace Manager V2 manifest preview path is incomplete." };
+async function validateWorkspacePreviewTarget(previewTargetPath) {
+  if (!previewTargetPath) {
+    return { ok: false, message: "Workspace Manager V2 manifest preview target path is empty." };
   }
-  const previewPath = `/${gameRoot}/${assetFolder}/preview.svg`;
   try {
-    const response = await fetch(previewPath, { cache: "no-store" });
+    const response = await fetch(`/${previewTargetPath}`, { cache: "no-store" });
     if (!response.ok) {
-      return { ok: false, missing: true, previewPath };
+      return { ok: false, message: `${previewTargetPath} returned ${response.status}.` };
+    }
+    const contentType = String(response.headers.get("content-type") || "");
+    const hasImageExtension = /\.(png|jpe?g|gif|webp|svg)$/i.test(previewTargetPath);
+    if (contentType && !contentType.startsWith("image/") && !hasImageExtension) {
+      return { ok: false, message: `${previewTargetPath} is not an image response.` };
     }
-    return { ok: true, previewPath, svgContent: await response.text() };
+    return { ok: true };
   } catch (error) {
-    return { ok: false, message: `Unable to read ${previewPath}: ${error.message}` };
+    return { ok: false, message: `Unable to read ${previewTargetPath}: ${error.message}` };
+  }
+}
+
+async function validateRepoRootHandle(handle) {
+  try {
+    await PreviewGeneratorV2RepoAccess.getDirectoryHandle(handle, "games");
+    await PreviewGeneratorV2RepoAccess.getDirectoryHandle(handle, "tools");
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: `Selected folder is not the repo root: ${error.message}` };
   }
 }
 
@@ -173,6 +199,10 @@ function updateWriteFolderSampleLabel() {
   }
 }
 
+function updatePreviewTargetLabel() {
+  ui.outputSummary.setPreviewTarget(workspacePreviewTargetPath || "not available yet");
+}
+
 async function updateWriteFolderActualLabelFromInput() {
   const lines = parseInputList(ui.pathsOrIds.getValue());
   if (!lines.length) {
@@ -195,6 +225,7 @@ async function updateWriteFolderActualLabelFromInput() {
 
 async function updatePathPreviewLabels() {
   updateWriteFolderSampleLabel();
+  updatePreviewTargetLabel();
   await updateWriteFolderActualLabelFromInput();
 }
 
@@ -552,13 +583,24 @@ function printSummary(results) {
 }
 
 class PreviewGeneratorV2App {
+  hasValidWorkspacePreviewTarget() {
+    if (!isWorkspaceManagerLaunch()) {
+      return true;
+    }
+    return workspacePreviewFileValid
+      && ui.getSelectedTargetType() === "games"
+      && getAssetFolderRelativePath() === workspacePreviewAssetFolder
+      && parseInputList(ui.pathsOrIds.getValue()).includes(workspacePreviewGameId);
+  }
+
   hasRequiredGenerateFields() {
-    return (Boolean(repoDirHandle) || workspaceLaunchReady)
+    return Boolean(repoDirHandle)
       && parseInputList(ui.pathsOrIds.getValue()).length > 0
       && ui.targetSource.hasBaseUrl()
       && ui.assetFolder.hasValue()
       && ui.targetSource.hasSelection()
-      && ui.captureMode.hasSelection();
+      && ui.captureMode.hasSelection()
+      && this.hasValidWorkspacePreviewTarget();
   }
 
   syncGeneratePreviewButton() {
@@ -567,9 +609,18 @@ class PreviewGeneratorV2App {
 
   async handlePickRepo() {
     try {
-      repoDirHandle = await window.showDirectoryPicker({ mode: "readwrite" });
-      workspaceLaunchReady = false;
-      repoDisplayName = PreviewGeneratorV2RepoAccess.getRepoDestinationDisplayName(repoDirHandle);
+      const selectedRepoHandle = await window.showDirectoryPicker({ mode: "readwrite" });
+      const repoValidation = await validateRepoRootHandle(selectedRepoHandle);
+      if (!repoValidation.ok) {
+        repoDirHandle = null;
+        repoDisplayName = "";
+        ui.setRepoDestinationDisplayName("not selected");
+        this.syncGeneratePreviewButton();
+        logger.log(`FAIL ${repoValidation.message}`);
+        return;
+      }
+      repoDirHandle = selectedRepoHandle;
+      repoDisplayName = PreviewGeneratorV2RepoAccess.getRepoDestinationDisplayName(selectedRepoHandle);
 
       ui.setRepoDestinationDisplayName(repoDisplayName);
       logger.clearStatus();
@@ -586,12 +637,12 @@ class PreviewGeneratorV2App {
   async handleExecute() {
     if (!this.hasRequiredGenerateFields()) {
       this.syncGeneratePreviewButton();
-      logger.log("Provide repo destination, base URL, asset folder, and at least one path or ID before generating.");
+      logger.log("Provide repo destination, base URL, asset folder, preview target, and at least one path or ID before generating.");
       return;
     }
 
     if (!repoDirHandle) {
-      logger.log("Workspace launch context is hydrated; Pick Repo Folder is required before writing preview output.");
+      logger.log("Pick the actual repo root folder before writing preview output.");
       return;
     }
 
@@ -678,41 +729,46 @@ class PreviewGeneratorV2App {
     }
     logger.log("Workspace launch context hydration started.");
     if (!contextResult.ok) {
-      workspaceLaunchReady = false;
+      workspacePreviewFileValid = false;
       logger.log(`FAIL Workspace launch context hydration: ${contextResult.message}`);
       this.syncGeneratePreviewButton();
       return;
     }
 
     const manifest = contextResult.manifest;
-    const assetFolder = workspaceImageAssetFolder(manifest);
-    if (!assetFolder) {
-      workspaceLaunchReady = false;
-      logger.log("FAIL Workspace launch context hydration: manifest must include an image asset path under assetsPath.");
+    const previewTarget = workspacePreviewTarget(manifest);
+    if (!previewTarget.ok) {
+      workspacePreviewFileValid = false;
+      logger.log(`FAIL Workspace launch context hydration: ${previewTarget.message}`);
       this.syncGeneratePreviewButton();
       return;
     }
 
-    repoDisplayName = `${manifest.gameId} workspace (${normalizeWorkspacePath(manifest.gameRoot)})`;
-    ui.setRepoDestinationDisplayName(repoDisplayName);
+    repoDisplayName = "";
+    repoDirHandle = null;
+    workspacePreviewAssetFolder = previewTarget.previewAssetFolder;
+    workspacePreviewGameId = manifest.gameId;
+    workspacePreviewTargetPath = previewTarget.previewTargetPath;
+    ui.setRepoDestinationDisplayName("not selected");
+    ui.repoDestination.setWorkspaceContextLabel(`${manifest.gameId} workspace (${normalizeWorkspacePath(manifest.gameRoot)})`);
     ui.targetSource.setSelectedTargetType("games");
-    ui.assetFolder.setValue(assetFolder);
+    ui.assetFolder.setValue(workspacePreviewAssetFolder);
     ui.pathsOrIds.setValue(manifest.gameId);
     await updatePathPreviewLabels();
-    workspaceLaunchReady = true;
     logger.log(`OK Workspace launch context hydrated for ${manifest.gameId}.`);
-    logger.log(`Repo selected: ${repoDisplayName}`);
+    logger.log("Repo selected: not selected; pick the actual repo root folder.");
     logger.log("Target source: games");
     logger.log(`Asset folder: ${getAssetFolderDisplayPath()}`);
+    logger.log(`Preview target: ${workspacePreviewTargetPath}`);
 
-    const previewResult = await readWorkspacePreviewSvg(manifest, assetFolder);
+    const previewResult = await validateWorkspacePreviewTarget(workspacePreviewTargetPath);
     if (previewResult.ok) {
-      ui.setLastGeneratedImage(previewResult.svgContent, `${manifest.gameId} preview.svg`);
-      logger.log(`OK Loaded existing preview image from ${previewResult.previewPath}.`);
-    } else if (previewResult.missing) {
-      logger.log(`SKIP No existing preview image at ${previewResult.previewPath}.`);
+      workspacePreviewFileValid = true;
+      ui.setPreviewTargetImage(workspacePreviewTargetPath);
+      logger.log(`OK Workspace preview target is valid at ${workspacePreviewTargetPath}.`);
     } else {
-      logger.log(`WARN ${previewResult.message}`);
+      workspacePreviewFileValid = false;
+      logger.log(`FAIL Workspace preview target validation: ${previewResult.message}`);
     }
     this.syncGeneratePreviewButton();
   }

tools/preview-generator-v2/PreviewGeneratorV2Ui.js

@@ -41,6 +41,10 @@ class PreviewGeneratorV2Ui {
     this.lastGeneratedImage.setLastGeneratedImage(svgContent, label);
   }
 
+  setPreviewTargetImage(imagePath) {
+    this.lastGeneratedImage.setPreviewTargetImage(imagePath);
+  }
+
   getSelectedCaptureMode() {
     return this.captureMode.getSelectedCaptureMode();
   }

tools/preview-generator-v2/controls/LastGeneratedImageControl.js

@@ -13,6 +13,7 @@ class LastGeneratedImageControl {
   setLastGeneratedImage(svgContent, label) {
     if (this.lastGeneratedImageObjectUrl) {
       URL.revokeObjectURL(this.lastGeneratedImageObjectUrl);
+      this.lastGeneratedImageObjectUrl = "";
     }
 
     const blob = new Blob([svgContent], { type: "image/svg+xml" });
@@ -22,6 +23,18 @@ class LastGeneratedImageControl {
     this.lastGeneratedImageEmptyEl.hidden = true;
     this.lastGeneratedImagePreviewEl.hidden = false;
   }
+
+  setPreviewTargetImage(imagePath) {
+    if (this.lastGeneratedImageObjectUrl) {
+      URL.revokeObjectURL(this.lastGeneratedImageObjectUrl);
+      this.lastGeneratedImageObjectUrl = "";
+    }
+
+    this.lastGeneratedImageEl.src = `/${imagePath}`;
+    this.lastGeneratedImageMetaEl.textContent = `Preview target: ${imagePath}`;
+    this.lastGeneratedImageEmptyEl.hidden = true;
+    this.lastGeneratedImagePreviewEl.hidden = false;
+  }
 }
 
 export { LastGeneratedImageControl };