Persist Palette Manager V2 edits in normalized workspace session data across return and reopen - PR_26128_028-palette-manager-v2-session-persistence

Author: ToolboxAid

docs/dev/reports/palette_manager_v2_session_persistence.md

@@ -0,0 +1,37 @@
+# Palette Manager V2 Session Persistence
+
+## Scope
+- Updated Palette Manager V2 workspace launches to load palette data from the normalized session key `workspace.tools.palette-manager-v2`.
+- Palette edits now update `workspace.tools.palette-manager-v2.data.swatches`.
+- Palette edits now mark `workspace.tools.palette-manager-v2.dirty` as:
+  - `isDirty: true`
+  - `reason: "palette-updated"`
+  - `changedAt`: current ISO timestamp
+  - `changedKeys`: palette field/path list for the edit.
+- Updated Workspace Manager V2 hydration so valid existing tool sessions for the same selected game are preserved instead of overwritten with manifest defaults.
+
+## Session Boundary
+- Preserved the normalized per-tool shape:
+  - `schema`
+  - `workspace`
+  - `data`
+  - `dirty`
+- Preserved `workspace.repo.reference` as the repo session reference key.
+- Palette Manager V2 reads and writes only session storage for this handoff.
+- Workspace Manager V2 hydrates defaults only when a tool session key is missing or invalid for the current selected game/context.
+
+## Persistence Behavior
+- Launching Palette Manager V2 from Workspace Manager V2 loads `workspace.tools.palette-manager-v2.data`.
+- Adding, updating, removing, pinning, importing, undoing, or redoing palette swatches persists the edited swatch list into session storage.
+- Returning to Workspace Manager V2 preserves dirty palette session data.
+- Reopening Palette Manager V2 shows the prior unsaved session edits.
+- No `game.manifest.json` write path was added.
+
+## Guardrails
+- No cross-tool direct communication was added.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- No schema contract changes were made.
+
+## Skipped
+- Full samples smoke test was skipped by request. The changed surface is Workspace Manager V2 and Palette Manager V2 session launch/persistence behavior, covered by `npm run test:workspace-v2` and the targeted Palette Manager V2 launch persistence assertions.

docs/dev/reports/playwright_palette_manager_v2_session_persistence.md

@@ -0,0 +1,21 @@
+# Playwright Palette Manager V2 Session Persistence
+
+## 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 launch persistence test: passed 1/1.
+- Workspace Manager V2 suite: passed 16/16.
+
+## Targeted Coverage
+- Verified Palette Manager V2 launches from Workspace Manager V2 and loads the Asteroids palette from `workspace.tools.palette-manager-v2.data`.
+- Verified a palette edit updates `workspace.tools.palette-manager-v2.data.swatches`.
+- Verified the same edit marks `dirty.isDirty` true with `reason: "palette-updated"`, an ISO `changedAt`, and palette `changedKeys`.
+- Verified returning to Workspace Manager V2 preserves the edited session data instead of overwriting it with manifest defaults.
+- Verified reopening Palette Manager V2 shows the unsaved edited swatch from session storage.
+- Verified Preview Generator V2 still launches and generates after the Palette Manager V2 persistence flow.
+- Verified Session Inspector V2 Delete All behavior still clears displayed session entries through the Workspace Manager V2 suite.
+
+## Skipped
+- Full samples smoke test was skipped by request. The relevant session persistence, Workspace Manager V2 return, Palette Manager V2 reopen, Preview Generator V2 launch, and Session Inspector V2 reset paths are covered by `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1689,12 +1689,56 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator('#userSwatchList [aria-label="Edit Space Black"]')).toBeVisible();
       await expect(page.locator('#userSwatchList [aria-label="Edit Space Black"]')).toHaveAttribute("title", /Name: Space Black/);
       await expect(page.locator("#paletteStatus")).toHaveText("Loaded active workspace palette Asteroids Palette.");
+      await page.locator("#swatchSymbolInput").fill("@");
+      await page.locator("#swatchHexInput").fill("#123456");
+      await page.locator("#swatchNameInput").fill("Workspace Session Purple");
+      await page.locator("#addSwatchButton").click();
+      await expect(page.locator("#userPaletteCount")).toHaveText("12 user swatches");
+      await expect(page.locator('#userSwatchList [aria-label="Edit Workspace Session Purple"]')).toBeVisible();
+      await expect(page.locator("#paletteStatus")).toHaveText("Added Workspace Session Purple.");
+      const editedPaletteSession = await page.evaluate(() => JSON.parse(sessionStorage.getItem("workspace.tools.palette-manager-v2")));
+      expect(editedPaletteSession.data.swatches).toHaveLength(12);
+      expect(editedPaletteSession.data.swatches.at(-1)).toMatchObject({
+        hex: "#123456",
+        name: "Workspace Session Purple",
+        source: "User Added",
+        symbol: "@"
+      });
+      expect(editedPaletteSession.dirty).toMatchObject({
+        isDirty: true,
+        reason: "palette-updated"
+      });
+      expect(Date.parse(editedPaletteSession.dirty.changedAt)).not.toBeNaN();
+      expect(editedPaletteSession.dirty.changedKeys).toEqual(expect.arrayContaining([
+        "data.swatches",
+        "data.swatches[11]"
+      ]));
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       await expectWorkspaceReturnRehydrated(page);
+      const returnedPaletteSession = await page.evaluate(() => JSON.parse(sessionStorage.getItem("workspace.tools.palette-manager-v2")));
+      expect(returnedPaletteSession.data.swatches).toHaveLength(12);
+      expect(returnedPaletteSession.data.swatches.at(-1)).toMatchObject({
+        hex: "#123456",
+        name: "Workspace Session Purple",
+        source: "User Added",
+        symbol: "@"
+      });
+      expect(returnedPaletteSession.dirty).toMatchObject({
+        isDirty: true,
+        reason: "palette-updated"
+      });
       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="palette-manager-v2"]').click();
+      await expect(page).toHaveURL(/palette-manager-v2\/index\.html.*launch=workspace/);
+      await expect(page.locator("#userPaletteCount")).toHaveText("12 user swatches");
+      await expect(page.locator('#userSwatchList [aria-label="Edit Workspace Session Purple"]')).toBeVisible();
+      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 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/palette-manager-v2/main.js

@@ -2,6 +2,12 @@ import { PaletteUsageService } from "../common/PaletteUsageService.js";
 import { PaletteSortService } from "../common/PaletteSortService.js";
 import { PaletteManagerApp } from "./modules/PaletteManagerApp.js";
 
+const PALETTE_MANAGER_V2_TOOL_SESSION_KEY = "workspace.tools.palette-manager-v2";
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function resolvePaletteSource() {
   const paletteSource = globalThis.paletteList;
   if (!paletteSource || !paletteSource.SOURCE_PALETTES) {
@@ -18,6 +24,70 @@ function reportBootstrapError(error) {
   console.error(error);
 }
 
+function readSessionJson(key) {
+  const rawValue = 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}` };
+  }
+}
+
+function readWorkspacePaletteToolSession() {
+  const result = readSessionJson(PALETTE_MANAGER_V2_TOOL_SESSION_KEY);
+  if (!result.ok) {
+    return result;
+  }
+  const session = result.value;
+  if (!isPlainObject(session.data) || !Array.isArray(session.data.swatches)) {
+    return { ok: false, message: `${PALETTE_MANAGER_V2_TOOL_SESSION_KEY}.data.swatches must contain the active workspace palette.` };
+  }
+  if (!isPlainObject(session.dirty)) {
+    return { ok: false, message: `${PALETTE_MANAGER_V2_TOOL_SESSION_KEY}.dirty must contain dirty tracking.` };
+  }
+  return { ok: true, session };
+}
+
+function createWorkspacePaletteSessionPersistence() {
+  const launchParams = getWorkspaceLaunchParams();
+  if (!launchParams.isWorkspaceLaunch) {
+    return null;
+  }
+  return {
+    save(paletteValue, changedKeys = []) {
+      const result = readWorkspacePaletteToolSession();
+      if (!result.ok) {
+        return result;
+      }
+      const session = result.session;
+      const uniqueChangedKeys = Array.from(new Set((Array.isArray(changedKeys) ? changedKeys : [])
+        .map((key) => String(key || "").trim())
+        .filter(Boolean)));
+      const nextSession = {
+        ...session,
+        data: {
+          ...session.data,
+          swatches: Array.isArray(paletteValue?.swatches) ? paletteValue.swatches : []
+        },
+        dirty: {
+          isDirty: true,
+          reason: "palette-updated",
+          changedAt: new Date().toISOString(),
+          changedKeys: uniqueChangedKeys.length ? uniqueChangedKeys : ["data.swatches"]
+        }
+      };
+      window.sessionStorage.setItem(PALETTE_MANAGER_V2_TOOL_SESSION_KEY, JSON.stringify(nextSession));
+      return { ok: true, key: PALETTE_MANAGER_V2_TOOL_SESSION_KEY, session: nextSession };
+    }
+  };
+}
+
 function normalizeSamplePresetPath(samplePresetPath) {
   const cleanPath = typeof samplePresetPath === "string"
     ? samplePresetPath.trim().replace(/\\/g, "/")
@@ -91,29 +161,19 @@ function loadWorkspacePalette(app) {
     app.rejectImport(["Workspace Manager V2 launch did not include hostContextId."], "Workspace palette load failed.");
     return;
   }
-  const rawValue = window.sessionStorage.getItem(launchParams.hostContextId);
-  if (!rawValue) {
-    app.rejectImport(["Workspace Manager V2 manifest was not found in sessionStorage."], "Workspace palette load failed.");
-    return;
-  }
-  let workspaceManifest;
-  try {
-    workspaceManifest = JSON.parse(rawValue);
-  } catch (error) {
-    app.rejectImport([`Workspace Manager V2 manifest JSON is invalid: ${error.message}`], "Workspace palette load failed.");
-    return;
-  }
-  const palettePayload = workspaceManifest?.tools?.["palette-manager-v2"];
-  if (!palettePayload || !Array.isArray(palettePayload.swatches)) {
-    app.rejectImport(["Workspace Manager V2 manifest is missing tools.palette-manager-v2.swatches."], "Workspace palette load failed.");
+  const sessionResult = readWorkspacePaletteToolSession();
+  if (!sessionResult.ok) {
+    app.rejectImport([sessionResult.message], "Workspace palette load failed.");
     return;
   }
+  const palettePayload = sessionResult.session.data;
   app.importPaletteDocument({
     name: palettePayload.name || "Workspace Palette",
     source: palettePayload.source || palettePayload.sourceId || palettePayload.name || "Workspace Manager V2",
     swatches: palettePayload.swatches
   }, {
     failureStatus: "Workspace palette load failed.",
+    persistWorkspaceSession: false,
     successStatus: `Loaded active workspace palette ${palettePayload.name || "Workspace Palette"}.`
   });
 }
@@ -164,7 +224,8 @@ try {
     documentRef: document,
     paletteSource: resolvePaletteSource(),
     sortService: new PaletteSortService(),
-    usageService: new PaletteUsageService()
+    usageService: new PaletteUsageService(),
+    workspaceSessionPersistence: createWorkspacePaletteSessionPersistence()
   });
   app.init();
   configureWorkspaceNav();

tools/palette-manager-v2/modules/PaletteManagerApp.js

@@ -156,11 +156,12 @@ function collectRefs(documentRef) {
 }
 
 export class PaletteManagerApp {
-  constructor({ documentRef, paletteSource, sortService, usageService }) {
+  constructor({ documentRef, paletteSource, sortService, usageService, workspaceSessionPersistence = null }) {
     this.document = documentRef;
     this.paletteSource = paletteSource;
     this.sortService = sortService;
     this.usageService = usageService;
+    this.workspaceSessionPersistence = workspaceSessionPersistence;
     this.globalPaletteToolKey = PALETTE_MANAGER_V2_TOOL_KEY;
     this.hexColorPattern = USER_HEX_COLOR_PATTERN;
     this.sourcePalettes = paletteSource.SOURCE_PALETTES;
@@ -268,6 +269,7 @@ export class PaletteManagerApp {
     this.renderSelectedSwatchState();
     this.setActionState([], status, false);
     this.render();
+    this.persistWorkspacePalette(["data.swatches"]);
   }
 
   renderSelectedSwatchState() {
@@ -541,6 +543,18 @@ export class PaletteManagerApp {
     }
   }
 
+  persistWorkspacePalette(changedKeys) {
+    if (!this.workspaceSessionPersistence || typeof this.workspaceSessionPersistence.save !== "function") {
+      return true;
+    }
+    const result = this.workspaceSessionPersistence.save(this.getPaletteValue(), changedKeys);
+    if (result?.ok) {
+      return true;
+    }
+    this.setActionState([result?.message || "Unable to update workspace palette session."], "Workspace palette session update failed.");
+    return false;
+  }
+
   setAvailableTags(tags) {
     this.state.availableTags = sortUniqueTags(tags);
   }
@@ -620,6 +634,10 @@ export class PaletteManagerApp {
     this.editorControl.showUserDefinedSwatch(cleanSwatch);
     this.recordHistorySnapshot();
     this.setActionState([], `Added ${cleanSwatch.name}.`);
+    this.persistWorkspacePalette([
+      "data.swatches",
+      `data.swatches[${this.state.selectedUserIndex}]`
+    ]);
   }
 
   updateSelectedSwatch(swatch) {
@@ -658,6 +676,12 @@ export class PaletteManagerApp {
     }
     this.recordHistorySnapshot();
     this.setActionState([], `Updated ${cleanSwatch.name}.`);
+    this.persistWorkspacePalette([
+      `data.swatches[${this.state.selectedUserIndex}]`,
+      `data.swatches[${this.state.selectedUserIndex}].symbol`,
+      `data.swatches[${this.state.selectedUserIndex}].hex`,
+      `data.swatches[${this.state.selectedUserIndex}].name`
+    ]);
   }
 
   addTagToSelectedSwatch(tag) {
@@ -697,6 +721,7 @@ export class PaletteManagerApp {
     }
     this.recordHistorySnapshot();
     this.setActionState([], `Added ${cleanTag} to ${cleanSwatch.name}.`);
+    this.persistWorkspacePalette([`data.swatches[${this.state.selectedUserIndex}].tags`]);
     return true;
   }
 
@@ -737,6 +762,7 @@ export class PaletteManagerApp {
     }
     this.recordHistorySnapshot();
     this.setActionState([], `Removed ${cleanTag} from ${cleanSwatch.name}.`);
+    this.persistWorkspacePalette([`data.swatches[${this.state.selectedUserIndex}].tags`]);
     return true;
   }
 
@@ -865,6 +891,7 @@ export class PaletteManagerApp {
     this.setActionState([], shouldAddTag
       ? `Added ${tag} to ${updates.length} selected swatches.`
       : `Removed ${tag} from ${updates.length} selected swatches.`);
+    this.persistWorkspacePalette(updates.map((update) => `data.swatches[${update.index}].tags`));
     return true;
   }
 
@@ -920,6 +947,10 @@ export class PaletteManagerApp {
     this.shiftCheckedUserSwatchIndexesAfterRemove(index);
     this.recordHistorySnapshot();
     this.setActionState([], `Removed ${swatch.name}.`);
+    this.persistWorkspacePalette([
+      "data.swatches",
+      `data.swatches[${index}]`
+    ]);
     return true;
   }
 
@@ -946,6 +977,10 @@ export class PaletteManagerApp {
     this.editorControl.clearUserDefinedSwatch();
     this.recordHistorySnapshot();
     this.setActionState([], `Pinned ${pinnedSwatch.name}.`);
+    this.persistWorkspacePalette([
+      "data.swatches",
+      `data.swatches[${this.state.selectedUserIndex}]`
+    ]);
   }
 
   pinVisibleSourceSwatches() {
@@ -988,6 +1023,9 @@ export class PaletteManagerApp {
 
     const status = `Pinned ${pinnedCount} source swatches. Skipped ${skippedCount} duplicate or invalid swatches.`;
     this.setActionState(Array.from(new Set(skipReasons)), status);
+    if (pinnedCount > 0) {
+      this.persistWorkspacePalette(["data.swatches"]);
+    }
   }
 
   findDuplicateUserSwatchIndex(swatch) {
@@ -1017,6 +1055,9 @@ export class PaletteManagerApp {
     this.editorControl.clearForm();
     this.resetHistorySnapshot();
     this.setActionState([], sanitizeText(options.successStatus) || `Imported ${this.state.userSwatches.length} user swatches.`);
+    if (options.persistWorkspaceSession !== false) {
+      this.persistWorkspacePalette(["data.swatches"]);
+    }
     return true;
   }