Retain Preview Generator V2 repo writer context and fix stale preview skip detection - PR_26128_032-preview-generator-repo-writer-retention

Author: DavidQ

docs/dev/reports/playwright_preview_generator_repo_writer_retention.md

@@ -0,0 +1,31 @@
+# Playwright Preview Generator V2 Repo Writer Retention
+
+## Commands
+- `node --check tools/preview-generator-v2/PreviewGeneratorV2App.js`
+- `node --check tools/preview-generator-v2/controls/StatusLogControl.js`
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `node --check tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs`
+- `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|keeps Preview Generator V2 repo writer after Asset Manager V2 deletes the preview asset entry|loads Gravity Well and Pong manifests|logs actionable Preview Generator V2 output path resolution failures"`
+- `npx playwright test tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs --project=playwright --workers=1 --reporter=list -g "exercises controls, required-field gating, accordions, paths layout, and status clear"`
+- `npm run test:workspace-v2`
+- `git diff --check`
+
+## Results
+- JavaScript syntax checks: passed.
+- Focused Workspace Manager V2 / Preview Generator V2 coverage: passed 4/4.
+- Focused Preview Generator V2 baseline status-control coverage: passed 1/1.
+- Workspace Manager V2 suite: passed 18/18.
+- Diff whitespace check: passed.
+
+## Targeted Coverage
+- Verified `Copy` appears left of `Clear` in Preview Generator V2 Status controls.
+- Verified `Copy` copies the full current status log.
+- Verified Copy logs success and missing-Clipboard failure states.
+- Verified Preview Generator V2 rehydrates repo selected/file writer context after returning from Asset Manager V2.
+- Verified deleting the preview asset entry in Asset Manager V2 does not leave Preview Generator V2 with `Repo selected: not selected`.
+- Verified Generate remains enabled when valid repo/game session context exists.
+- Verified missing `preview.svg` logs `CHK` with the full absolute path, logs `MISSING`, and generates instead of stale-skipping.
+- Verified `OK WRITE` appears after write verification and `Written: 1` follows the verified write path.
+
+## Skipped
+- Full samples smoke test was skipped by request. The requested behavior is covered by targeted Playwright flows plus `npm run test:workspace-v2`.

docs/dev/reports/preview_generator_repo_writer_retention.md

@@ -0,0 +1,34 @@
+# Preview Generator V2 Repo Writer Retention
+
+## Scope
+- Added a `Copy` button to the Preview Generator V2 Status header, positioned to the left of `Clear`.
+- Copy reads the full current Preview Generator V2 status log and logs an `OK`, `WARN`, or `FAIL` result.
+- Kept integration through session storage only.
+- No direct cross-tool communication was added.
+
+## Repo Writer Retention
+- Preview Generator V2 continues to rehydrate repo context from:
+  - `workspace.repo.reference`
+  - `workspace.tools.preview-generator-v2`
+- Workspace launch no longer blocks generation when Asset Manager V2 session data no longer contains a preview-role asset entry.
+- If the preview asset entry is missing, Preview Generator V2 now falls back to the generated target:
+  - `games/<game>/assets/images/preview.svg`
+- Valid repo sessions keep `Repo selected` populated instead of showing `not selected`.
+- Missing or invalid repo session data still logs a visible `FAIL` and keeps generation disabled.
+
+## Skip And Write Verification
+- Force rewrite behavior and verified-write logging are preserved.
+- With Force rewrite disabled, Preview Generator V2 now checks the live target file handle for `preview.svg`.
+- `CHK` logs the full absolute path being checked.
+- If the checked file is missing, the log includes `MISSING` and generation proceeds.
+- If the checked file exists but cannot be verified, generation proceeds instead of using a stale skip.
+- `OK WRITE` and `Written` counts are still emitted only after write verification succeeds.
+
+## Guardrails
+- No hidden fallback output paths were added.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- No schema/runtime contracts were modified.
+
+## Skipped
+- Full samples smoke test was skipped by request. The targeted Workspace V2 coverage exercises the Asset Manager return flow, missing preview target behavior, status copy behavior, and verified write path.

tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs

@@ -384,7 +384,8 @@ test.describe("Preview Generator V2 baseline", () => {
       const statusHeader = page.locator('#statusAccordion .accordion-v2__header[aria-controls="statusAccordionContent"]');
       const statusContent = page.locator("#statusAccordionContent");
       const statusHeaderOrder = await statusHeader.evaluate((header) => Array.from(header.querySelectorAll(":scope > span, :scope > div > span, :scope > div > button"), (element) => element.textContent.trim()));
-      expect(statusHeaderOrder).toEqual(["Status", "+", "Clear"]);
+      expect(statusHeaderOrder).toEqual(["Status", "+", "Copy", "Clear"]);
+      await expect(statusHeader.locator("#copyLogBtn")).toBeVisible();
       await expect(statusHeader.locator("#clearLogBtn")).toBeVisible();
       await expect(statusHeader).toHaveAttribute("aria-expanded", "true");
       await expect(statusContent).toBeVisible();
@@ -406,6 +407,7 @@ test.describe("Preview Generator V2 baseline", () => {
         await expectAccordionToggles(page, contentId);
       }
       await expect(page.locator("#clearLogBtn")).toBeVisible();
+      await expect(statusHeader.locator(".preview-generator-v2__status-header-actions #copyLogBtn")).toBeVisible();
       await expect(statusHeader.locator(".preview-generator-v2__status-header-actions #clearLogBtn")).toBeVisible();
       await page.locator("#captureModeFullScreen").check();
       await expect(page.locator("#log")).toContainText("Capture mode: Full Screen");

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1899,10 +1899,36 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#log")).not.toContainText("FAIL Workspace background hydration");
       await expect(page.locator("#log")).toContainText("OK Workspace manifest preview source is valid at games/Asteroids/assets/images/preview.png.");
       const previewStatusHeaderOrder = await page.locator(".preview-generator-v2__status-accordion-header").evaluate((header) => Array.from(header.querySelectorAll(":scope > span, :scope > div > span, :scope > div > button"), (element) => element.textContent.trim()));
-      expect(previewStatusHeaderOrder).toEqual(["Status", "+", "Clear"]);
+      expect(previewStatusHeaderOrder).toEqual(["Status", "+", "Copy", "Clear"]);
+      await expect(page.locator(".preview-generator-v2__status-header-actions #copyLogBtn")).toBeVisible();
+      await expect(page.locator(".preview-generator-v2__status-header-actions #clearLogBtn")).toBeVisible();
+      await page.evaluate(() => {
+        Object.defineProperty(navigator, "clipboard", {
+          configurable: true,
+          value: {
+            writeText: async (text) => {
+              window.__previewGeneratorV2CopiedLog = text;
+            }
+          }
+        });
+      });
+      const previewLogBeforeCopy = await page.locator("#log").textContent();
+      await page.locator("#copyLogBtn").click();
+      expect(await page.evaluate(() => window.__previewGeneratorV2CopiedLog)).toBe(previewLogBeforeCopy);
+      await expect(page.locator("#log")).toContainText("OK Copied Preview Generator V2 status log to clipboard");
+      await page.evaluate(() => {
+        Object.defineProperty(navigator, "clipboard", {
+          configurable: true,
+          value: undefined
+        });
+      });
+      await page.locator("#copyLogBtn").click();
+      await expect(page.locator("#log")).toContainText("FAIL Copy status log failed: Clipboard API is unavailable.");
       await page.locator("#executeBtn").click();
       await expect(page.locator("#log")).toContainText("Starting execution...", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText(`Repo root: ${displayRepoRootPath(server)}`, { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText(`CHK  ${displayAbsoluteOutputPath(server, "games/Asteroids/assets/images/preview.svg")}`, { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText(`MISSING ${displayAbsoluteOutputPath(server, "games/Asteroids/assets/images/preview.svg")}`, { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("RUN  Asteroids", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("OUT  games\\Asteroids\\assets\\images\\preview.svg", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("OK WRITE Asteroids", { timeout: 20000 });
@@ -1930,6 +1956,72 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("keeps Preview Generator V2 repo writer after Asset Manager V2 deletes the preview asset entry", async ({ page }) => {
+    const server = await openWorkspaceManagerV2(page);
+    const pageErrors = [];
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    try {
+      await selectMockRepo(page);
+      await page.locator("#activeGameSelect").selectOption("Asteroids");
+      await expectWorkspaceReturnRehydrated(page);
+      await page.locator('[data-workspace-tool-id="asset-manager-v2"]').click();
+      await expect(page).toHaveURL(/asset-manager-v2\/index\.html.*launch=workspace/);
+      await expect(page.locator("#statusLog")).toHaveValue(/Workspace Manager V2 loaded 14 validated assets from tools\.asset-manager-v2\.assets/);
+      await page.locator('[data-delete-asset-id="assets.image.preview.preview"]').click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Deleted assets\.image\.preview\.preview\./);
+      const editedAssetSession = await page.evaluate(() => JSON.parse(sessionStorage.getItem("workspace.tools.asset-manager-v2")));
+      expect(editedAssetSession.data.assets["assets.image.preview.preview"]).toBeUndefined();
+      expect(Object.keys(editedAssetSession.data.assets)).toHaveLength(13);
+      expect(editedAssetSession.dirty).toMatchObject({
+        isDirty: true,
+        reason: "asset-updated"
+      });
+      await page.evaluate(() => {
+        sessionStorage.setItem("workspace.repo.writes", JSON.stringify([{
+          contents: "<svg>stale cached prior preview</svg>",
+          path: "HTML-JavaScript-Gaming/games/Asteroids/assets/images/preview.svg"
+        }]));
+      });
+      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('[data-workspace-tool-id="asset-manager-v2"]')).toContainText("13 managed assets");
+      await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toHaveAttribute("data-workspace-tool-dirty", "true");
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Refreshed asset-manager-v2 from workspace\.tools\.asset-manager-v2\.data: 13 managed assets; Dirty: true\./);
+      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("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
+      await expect(page.locator("#executeBtn")).toBeEnabled();
+      await expect(page.locator("#previewTargetValue")).toHaveText("games/Asteroids/assets/images/preview.svg");
+      await expect(page.locator("#log")).toContainText("WARN Workspace manifest preview asset is missing from Asset Manager V2 data; generated preview output will target games/Asteroids/assets/images/preview.svg.");
+      await expect(page.locator("#log")).toContainText("OK Workspace repo session reference loaded from workspace.repo.reference for HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).not.toContainText("Repo selected: not selected");
+      await page.locator("#executeBtn").click();
+      const log = page.locator("#log");
+      await expect(log).toContainText(`CHK  ${displayAbsoluteOutputPath(server, "games/Asteroids/assets/images/preview.svg")}`, { timeout: 20000 });
+      await expect(log).toContainText(`MISSING ${displayAbsoluteOutputPath(server, "games/Asteroids/assets/images/preview.svg")}`, { timeout: 20000 });
+      await expect(log).toContainText("RUN  Asteroids", { timeout: 20000 });
+      await expect(log).toContainText("OK WRITE Asteroids", { timeout: 20000 });
+      await expect(log).toContainText(`Write verification passed: file exists at ${displayAbsoluteOutputPath(server, "games/Asteroids/assets/images/preview.svg")}.`, { timeout: 20000 });
+      await expect(log).toContainText("Written: 1", { timeout: 20000 });
+      await expect(log).toContainText("Failed: 0", { timeout: 20000 });
+      await expect(log).not.toContainText("SKIP Asteroids");
+      const previewWrites = await page.evaluate(() => JSON.parse(sessionStorage.getItem("workspace.repo.writes") || "[]"));
+      expect(previewWrites).toHaveLength(2);
+      expect(previewWrites.at(-1).path).toBe("HTML-JavaScript-Gaming/games/Asteroids/assets/images/preview.svg");
+      expect(previewWrites.at(-1).contents).toContain("<svg");
+      expect(previewWrites.at(-1).contents).not.toContain("stale cached prior preview");
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("imports a schema-valid manifest and exports the imported session manifest", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page);
     const pageErrors = [];