Refresh Workspace and V2 tools from normalized session data to preserve cross-tool changes - PR_26128_029-workspace-tool-session-refresh

Author: DavidQ

docs/dev/reports/playwright_workspace_tool_session_refresh.md

@@ -0,0 +1,26 @@
+# Playwright Workspace Tool Session Refresh
+
+## Commands
+- `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`
+
+## Results
+- Focused Workspace Manager V2 launch/session refresh flow: passed 1/1.
+- Workspace Manager V2 suite: passed 16/16.
+
+## Targeted Coverage
+- Verified Palette Manager V2 edit updates `workspace.tools.palette-manager-v2.data.swatches`.
+- Verified Palette Manager V2 edit marks `workspace.tools.palette-manager-v2.dirty.isDirty` true with `reason: "palette-updated"`.
+- Verified returning to Workspace Manager V2 refreshes the Palette Manager V2 tile to 12 swatches.
+- Verified Workspace Manager V2 reflects Palette Manager V2 dirty status from the normalized session.
+- Verified reopening Palette Manager V2 loads the edited palette swatch from session.
+- Verified Asset Manager V2 launches with 12 palette colors from `workspace.tools.palette-manager-v2.data`.
+- Verified Asset Manager V2 can add a color asset from the edited palette swatch.
+- Verified Asset Manager V2 writes the new asset to `workspace.tools.asset-manager-v2.data.assets`.
+- Verified Asset Manager V2 marks `workspace.tools.asset-manager-v2.dirty.isDirty` true with `reason: "asset-updated"`.
+- Verified returning to Workspace Manager V2 refreshes the Asset Manager V2 tile to 15 managed assets.
+- Verified Preview Generator V2 still launches and generates after refreshed tool sessions.
+- Verified Session Inspector V2 Delete All/reset behavior still clears shown session entries through the full suite.
+
+## Skipped
+- Full samples smoke test was skipped by request. The relevant refresh, launch, persistence, dirty tracking, and reset paths are covered by `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`.

docs/dev/reports/workspace_tool_session_refresh.md

@@ -0,0 +1,48 @@
+# Workspace Tool Session Refresh
+
+## Scope
+- Added Workspace Manager V2 refresh-from-session behavior after tool session hydration.
+- Workspace Manager V2 now refreshes active tool display data from normalized `workspace.tools.<tool-id>` session objects.
+- Palette Manager V2 return refresh updates the Palette Manager V2 tile from `workspace.tools.palette-manager-v2.data.swatches`.
+- Tool tiles expose normalized dirty status from each tool session.
+- Asset Manager V2 now reads both its asset payload and the active palette from normalized session keys on launch.
+- Asset Manager V2 writes asset changes back to `workspace.tools.asset-manager-v2`.
+
+## Session Rules
+- Workspace Manager V2 hydrates manifest defaults only when a normalized tool session is missing or invalid for the current game/context.
+- Valid dirty sessions are preserved when returning from a tool.
+- Workspace Manager V2 refreshes its active context from normalized session `data` before rendering tool counts and before later launches/exports.
+- Asset Manager V2 reads:
+  - `workspace.tools.asset-manager-v2.data.assets`
+  - `workspace.tools.palette-manager-v2.data.swatches`
+- Asset Manager V2 writes:
+  - `workspace.tools.asset-manager-v2.data.assets`
+  - `workspace.tools.asset-manager-v2.dirty`
+
+## Dirty Tracking
+- Palette Manager V2 dirty data continues to use `reason: "palette-updated"`.
+- Asset Manager V2 dirty data now uses `reason: "asset-updated"` when asset data changes.
+- Asset Manager V2 dirty updates include:
+  - `isDirty: true`
+  - `changedAt`: current ISO timestamp
+  - `changedKeys`: changed asset data paths.
+- Returning to Workspace Manager V2 without asset data changes does not create a new dirty timestamp.
+
+## Validation Notes
+- Palette edits update session data and dirty tracking.
+- Returning to Workspace Manager V2 updates the Palette Manager V2 tile from 11 to 12 swatches.
+- Workspace Manager V2 reflects Palette Manager V2 dirty status from the normalized session.
+- Reopening Palette Manager V2 reloads the edited swatch from session.
+- Asset Manager V2 loads the edited palette swatch from `workspace.tools.palette-manager-v2.data`.
+- Asset Manager V2 writes a new color asset to `workspace.tools.asset-manager-v2.data` and marks its dirty object.
+- Returning to Workspace Manager V2 updates Asset Manager V2 from 14 to 15 managed assets.
+
+## Guardrails
+- No `game.manifest.json` write path was added.
+- No direct cross-tool communication was added.
+- Session storage remains the integration boundary.
+- No sample JSON was modified.
+- No roadmap content was modified.
+
+## Skipped
+- Full samples smoke test was skipped by request. The affected Workspace Manager V2, Palette Manager V2, Asset Manager V2, Preview Generator V2, and Session Inspector V2 session paths are covered by `npm run test:workspace-v2`.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1728,6 +1728,9 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         isDirty: true,
         reason: "palette-updated"
       });
+      await expect(paletteTile).toContainText("12 palette swatches");
+      await expect(paletteTile).toHaveAttribute("data-workspace-tool-dirty", "true");
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Refreshed palette-manager-v2 from workspace\.tools\.palette-manager-v2\.data: 12 palette swatches; Dirty: true\./);
       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");
@@ -1739,6 +1742,53 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       await expectWorkspaceReturnRehydrated(page);
+      await expect(paletteTile).toContainText("12 palette swatches");
+      await expect(paletteTile).toHaveAttribute("data-workspace-tool-dirty", "true");
+
+      await assetTile.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 expect(page.locator("#statusLog")).toHaveValue(/Workspace Manager V2 loaded 12 palette colors from active palette context/);
+      await page.locator("#assetKindColor").check();
+      const sessionPurpleSwatch = page.locator('#assetColorSwatchList button[aria-label*="Workspace Session Purple"]');
+      await expect(sessionPurpleSwatch).toBeVisible();
+      await sessionPurpleSwatch.click();
+      await page.locator("#assetUsageInput").fill("session");
+      await expect(page.locator("#assetIdInput")).toHaveValue("assets.color.hud.session.workspace-session-purple");
+      await page.locator("#addAssetButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Added assets\.color\.hud\.session\.workspace-session-purple\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK workspace\.tools\.asset-manager-v2 now has 15 validated assets\./);
+      const editedAssetSession = await page.evaluate(() => JSON.parse(sessionStorage.getItem("workspace.tools.asset-manager-v2")));
+      expect(Object.keys(editedAssetSession.data.assets)).toHaveLength(15);
+      expect(editedAssetSession.data.assets["assets.color.hud.session.workspace-session-purple"]).toMatchObject({
+        color: {
+          hex: "#123456",
+          name: "Workspace Session Purple",
+          source: "User Added",
+          symbol: "@"
+        },
+        kind: "hex",
+        path: "palette://workspace/workspace-session-purple",
+        role: "hud",
+        type: "color"
+      });
+      expect(editedAssetSession.dirty).toMatchObject({
+        isDirty: true,
+        reason: "asset-updated"
+      });
+      expect(Date.parse(editedAssetSession.dirty.changedAt)).not.toBeNaN();
+      expect(editedAssetSession.dirty.changedKeys).toEqual(expect.arrayContaining([
+        "data.assets",
+        'data.assets["assets.color.hud.session.workspace-session-purple"]'
+      ]));
+      await page.locator("#returnToWorkspaceButton").click();
+      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
+      await expectWorkspaceReturnRehydrated(page);
+      await expect(assetTile).toContainText("15 managed assets");
+      await expect(assetTile).toHaveAttribute("data-workspace-tool-dirty", "true");
+      await expect(paletteTile).toContainText("12 palette swatches");
+      await expect(paletteTile).toHaveAttribute("data-workspace-tool-dirty", "true");
+      await expect(page.locator("#statusLog")).toHaveValue(/INFO Refreshed asset-manager-v2 from workspace\.tools\.asset-manager-v2\.data: 15 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('[data-launch-mode-nav="tool"]')).toBeHidden();

tools/asset-manager-v2/js/AssetManagerV2App.js

@@ -273,7 +273,12 @@ export class AssetManagerV2App {
     this.selectedAssetId = formValue.assetId;
     this.assetForm.clearEditableFields();
     this.statusLog.ok(`Added ${formValue.assetId}.`);
-    this.syncWorkspaceSessionManifest();
+    this.syncWorkspaceSessionManifest({
+      changedKeys: [
+        "data.assets",
+        `data.assets["${formValue.assetId}"]`
+      ]
+    });
     this.render();
     this.refreshActions();
   }
@@ -315,7 +320,12 @@ export class AssetManagerV2App {
     this.selectedAssetId = formValue.assetId;
     this.assetForm.loadAssetForEdit(formValue.assetId, entryResult.entry);
     this.statusLog.ok(`Updated ${formValue.assetId}.`);
-    this.syncWorkspaceSessionManifest();
+    this.syncWorkspaceSessionManifest({
+      changedKeys: [
+        "data.assets",
+        `data.assets["${this.selectedAssetId}"]`
+      ]
+    });
     this.render();
     this.refreshActions();
   }
@@ -341,7 +351,12 @@ export class AssetManagerV2App {
       this.assetForm.clearEditableFields();
     }
     this.statusLog.ok(`Deleted ${assetId}.`);
-    this.syncWorkspaceSessionManifest();
+    this.syncWorkspaceSessionManifest({
+      changedKeys: [
+        "data.assets",
+        `data.assets["${assetId}"]`
+      ]
+    });
     this.render();
     this.refreshActions();
   }
@@ -373,7 +388,7 @@ export class AssetManagerV2App {
     } else {
       this.assetForm.clearEditableFields();
     }
-    this.syncWorkspaceSessionManifest();
+    this.syncWorkspaceSessionManifest({ changedKeys: ["data.assets"] });
     this.render();
     this.refreshActions();
   }
@@ -501,7 +516,7 @@ export class AssetManagerV2App {
       this.redoStack = [];
       this.statusLog.ok(`Imported JSON with ${Object.keys(this.assets).length} validated assets.`);
       this.missingFileAssetIds = await this.logMissingReferencedFiles(this.assets);
-      this.syncWorkspaceSessionManifest();
+      this.syncWorkspaceSessionManifest({ changedKeys: ["data.assets"] });
       this.render();
       this.refreshActions();
     } catch (error) {
@@ -565,22 +580,22 @@ export class AssetManagerV2App {
     this.window.location.href = this.workspaceBridge.workspaceManagerUrl();
   }
 
-  syncWorkspaceSessionManifest({ quiet = false } = {}) {
+  syncWorkspaceSessionManifest({ changedKeys = ["data.assets"], quiet = false } = {}) {
     if (!this.workspaceBridge.isWorkspaceMode()) {
       return { ok: true, skipped: true };
     }
     const validation = this.validateCurrentPayload({ showInspector: false });
     if (!validation.ok) {
       return validation;
     }
-    const result = this.workspaceBridge.writeAssetsPayload(validation.payload);
+    const result = this.workspaceBridge.writeAssetsPayload(validation.payload, changedKeys);
     if (!result.ok) {
-      this.statusLog.fail(`Workspace session manifest update failed: ${result.message}`);
+      this.statusLog.fail(`Workspace tool session update failed: ${result.message}`);
       return result;
     }
     this.lastWorkspaceManifest = result.workspaceManifest;
     if (!quiet) {
-      this.statusLog.ok(`Workspace Manager V2 session manifest now has ${Object.keys(validation.payload.assets).length} validated assets.`);
+      this.statusLog.ok(`workspace.tools.asset-manager-v2 now has ${Object.keys(validation.payload.assets).length} validated assets.`);
     }
     return result;
   }

tools/asset-manager-v2/js/services/WorkspaceBridge.js

@@ -33,6 +33,16 @@ function isWorkspaceManifest(value) {
 }
 
 const PALETTE_MANAGER_V2_TOOL_KEY = "palette-manager-v2";
+const ASSET_MANAGER_V2_TOOL_KEY = "asset-manager-v2";
+const WORKSPACE_TOOL_SESSION_KEY_PREFIX = "workspace.tools.";
+
+function toolSessionKey(toolId) {
+  return `${WORKSPACE_TOOL_SESSION_KEY_PREFIX}${toolId}`;
+}
+
+function normalizedToolSessionError(key) {
+  return `${key} must use the normalized schema/workspace/data/dirty object shape.`;
+}
 
 export class WorkspaceBridge {
   constructor({ windowRef = window }) {
@@ -135,6 +145,53 @@ export class WorkspaceBridge {
     }
   }
 
+  readSessionJson(key) {
+    const rawValue = this.window.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}` };
+    }
+  }
+
+  readWorkspaceToolSession(toolId, contextResult = null) {
+    const context = contextResult || this.readContext();
+    if (!context.ok) {
+      return context;
+    }
+    const key = toolSessionKey(toolId);
+    const sessionResult = this.readSessionJson(key);
+    if (!sessionResult.ok) {
+      return sessionResult;
+    }
+    const session = sessionResult.value;
+    if (!isPlainObject(session.schema)
+      || !isPlainObject(session.workspace)
+      || !Object.prototype.hasOwnProperty.call(session, "data")
+      || !isPlainObject(session.dirty)) {
+      return { ok: false, message: normalizedToolSessionError(key) };
+    }
+    if (session.workspace.source !== "workspace-manager-v2") {
+      return { ok: false, message: `${key}.workspace.source must be workspace-manager-v2.` };
+    }
+    if (session.workspace.toolId !== toolId) {
+      return { ok: false, message: `${key}.workspace.toolId must match ${toolId}.` };
+    }
+    if (session.workspace.workspaceManifestId !== context.context.id) {
+      return { ok: false, message: `${key}.workspace.workspaceManifestId must match ${context.context.id}.` };
+    }
+    if (session.workspace.gameId !== context.gameId) {
+      return { ok: false, message: `${key}.workspace.gameId must match ${context.gameId}.` };
+    }
+    return { ok: true, context, key, session };
+  }
+
   workspaceManifestFromContext(context) {
     if (isWorkspaceManifest(context)) {
       return context;
@@ -147,13 +204,13 @@ export class WorkspaceBridge {
     if (!contextResult.ok) {
       return contextResult;
     }
-    const workspaceManifest = this.workspaceManifestFromContext(contextResult.context);
-    if (!isPlainObject(workspaceManifest)) {
-      return { ok: false, message: "Workspace Manager V2 manifest context is invalid." };
+    const sessionResult = this.readWorkspaceToolSession(ASSET_MANAGER_V2_TOOL_KEY, contextResult);
+    if (!sessionResult.ok) {
+      return sessionResult;
     }
-    const assetPayload = workspaceManifest.tools?.["asset-manager-v2"];
+    const assetPayload = sessionResult.session.data;
     if (!isPlainObject(assetPayload) || !isPlainObject(assetPayload.assets)) {
-      return { ok: false, message: "Workspace Manager V2 manifest is missing tools.asset-manager-v2.assets." };
+      return { ok: false, message: `${sessionResult.key}.data.assets must contain the active workspace assets.` };
     }
     return {
       ok: true,
@@ -168,9 +225,13 @@ export class WorkspaceBridge {
     if (!contextResult.ok) {
       return contextResult;
     }
-    const activePalette = contextResult.activePalette;
+    const sessionResult = this.readWorkspaceToolSession(PALETTE_MANAGER_V2_TOOL_KEY, contextResult);
+    if (!sessionResult.ok) {
+      return sessionResult;
+    }
+    const activePalette = sessionResult.session.data;
     if (!isPlainObject(activePalette) || !Array.isArray(activePalette.swatches)) {
-      return { ok: false, message: "Workspace Manager V2 session context is missing active palette swatches." };
+      return { ok: false, message: `${sessionResult.key}.data.swatches must contain the active workspace palette.` };
     }
     return { ok: true, swatches: clone(activePalette.swatches) };
   }
@@ -201,27 +262,57 @@ export class WorkspaceBridge {
     };
   }
 
-  writeAssetsPayload(payload) {
+  writeAssetsPayload(payload, changedKeys = ["data.assets"]) {
     if (!this.isWorkspaceMode()) {
       return { ok: false, message: "Asset insertion is only available when launched from Workspace Manager V2." };
     }
     const contextResult = this.readContext();
     if (!contextResult.ok) {
       return contextResult;
     }
+    const sessionResult = this.readWorkspaceToolSession(ASSET_MANAGER_V2_TOOL_KEY, contextResult);
+    if (!sessionResult.ok) {
+      return sessionResult;
+    }
     const workspaceManifest = clone(contextResult.context);
     if (!isPlainObject(workspaceManifest)) {
       return { ok: false, message: "Workspace Manager V2 manifest context is invalid." };
     }
     if (!isPlainObject(workspaceManifest.tools)) {
       return { ok: false, message: "Workspace Manager V2 session context is missing tools." };
     }
-    if (!isPlainObject(workspaceManifest.tools["asset-manager-v2"]) || !isPlainObject(workspaceManifest.tools["asset-manager-v2"].assets)) {
-      return { ok: false, message: "Workspace Manager V2 manifest is missing tools.asset-manager-v2.assets." };
+    if (!isPlainObject(payload?.assets)) {
+      return { ok: false, message: "Asset Manager V2 payload must include assets." };
     }
 
-    workspaceManifest.tools["asset-manager-v2"].assets = clone(payload.assets);
-    this.window.sessionStorage.setItem(contextResult.hostContextId, JSON.stringify(workspaceManifest));
-    return { ok: true, workspaceManifest: clone(workspaceManifest) };
+    const session = sessionResult.session;
+    const currentAssets = isPlainObject(session.data?.assets) ? session.data.assets : {};
+    const nextData = {
+      ...(isPlainObject(session.data) ? session.data : {}),
+      assets: clone(payload.assets)
+    };
+    const assetsChanged = JSON.stringify(currentAssets) !== JSON.stringify(nextData.assets);
+    const nextSession = {
+      ...session,
+      data: nextData,
+      dirty: assetsChanged
+        ? {
+            isDirty: true,
+            reason: "asset-updated",
+            changedAt: new Date().toISOString(),
+            changedKeys: Array.from(new Set((Array.isArray(changedKeys) ? changedKeys : ["data.assets"])
+              .map((key) => String(key || "").trim())
+              .filter(Boolean)))
+          }
+        : session.dirty
+    };
+    this.window.sessionStorage.setItem(sessionResult.key, JSON.stringify(nextSession));
+    workspaceManifest.tools[ASSET_MANAGER_V2_TOOL_KEY] = clone(nextData);
+    return {
+      ok: true,
+      changed: assetsChanged,
+      session: clone(nextSession),
+      workspaceManifest: clone(workspaceManifest)
+    };
   }
 }