Enforce single active workspace palette during Workspace V2 export - PR_11_304

Author: DavidQ

docs/dev/reports/PR_11_304_report.md

@@ -1,55 +1,70 @@
-# PR_11_304 Report - Workspace V2 Import/Export Continuation Fix (Saved Session Payload Guard)
+# PR_11_304 Report - Workspace V2 Import/Export Continuation (Single Active Palette Ownership)
 
 ## Purpose
-Continue/fix PR_11_304 in `tools/workspace-v2/index.js` for Workspace V2 import/export/save/load session handling.
+Continue/fix PR_11_304 in `tools/workspace-v2/index.js` to enforce manifest-only export with single active palette ownership at `workspace.tools.palettes`.
 
 ## Scope
-- `tools/workspace-v2/index.js` only
-- No schema changes
-
-## Issues Fixed
-1. Save Session payload source/shape
-- Updated `readSessionPayloadForSaveAction(sessionId)` to prioritize current active workspace payload only.
-- Removed session-name lookup fallback that could pull unrelated stale payloads.
-- Added save-time shape validation using `validateWorkspaceToolSessionPayload(...)` before writing to library.
-- Result: new saved Palette Manager sessions are saved as `{ version, toolId, paletteJson }`, not `{ payloadJson }`.
-
-2. Export invalid saved palette sessions with actionable block message
-- Added targeted guard in `exportWorkspaceSessionJson()`:
-  - Detects any saved `palette-manager-v2` session containing `payloadJson`.
-  - Blocks export with explicit message:
-    - `Saved session 'session_2' is invalid for palette-manager-v2. Load a valid session and overwrite it, or delete it.`
-- No silent conversion/fix during export.
-
-3. Manifest-only textarea after fixture/init/reset
-- `loadSelectedFixture()` now normalizes palette fixture session context and syncs manifest textarea via `syncWorkspaceManifestTextarea()`.
-- `initializeWorkspaceProducerSession()` creates valid default payload and syncs manifest textarea.
-- `fullReset()` now re-initializes producer and writes manifest baseline instead of leaving empty/raw payload state.
-- Reset status updated to reflect manifest baseline restoration.
-
-4. Session ID validation UX
-- Invalid Session ID message remains exact and visible:
-  - `Invalid session ID. Use letters, numbers, hyphen, or underscore only.`
-- Save remains disabled for invalid IDs via state model.
+- `tools/workspace-v2/index.js`
+- `docs/dev/reports/PR_11_304_report.md`
+- No schema file changes
+
+## Changes Implemented
+1. Added strict active palette ownership for export:
+- Export now resolves one active palette from the current active `palette-manager-v2` session only.
+- Export writes the active palette at:
+  - `tools.palettes.activePalette`
+- Export blocks when active palette is not available with clear error messaging.
+- Export blocks ambiguous palette context (multiple palette sessions present with no active palette selected).
+
+2. Kept manifest-only export contract and removed silent no-op behavior:
+- Export still validates before download.
+- Export continues to reject legacy wrapper shape:
+  - `workspaceSession`
+  - `workspaceV2Session`
+  - `toolSessions`
+  - `savedSessions` at root
+  - `exportedAt`
+- Export status now surfaces build-time failures using explicit `lastWorkspaceExportBuildErrorMessage`.
+
+3. Tightened palette payload validation paths:
+- `palette-manager-v2` payloads continue to require:
+  - `paletteJson.swatches`
+- `paletteJson.colors` remains rejected.
+- `payloadJson` remains rejected for `palette-manager-v2`.
+- Swatches are validated as lowercase strict fields:
+  - `symbol`
+  - `hex`
+  - `name`
+- Extra swatch fields are rejected.
+
+4. Validator now enforces palette tool manifest entry:
+- `tools.palettes` is required.
+- `tools.palettes.activePalette` is required.
+- `tools.palettes.activePalette.swatches` is validated before export/import acceptance.
+
+## Required Rule Coverage
+- No `workspaceSession`: enforced
+- No `games[]`: enforced in export document shape
+- No `palette-manager-v2.payloadJson`: enforced
+- Export validates before download: enforced
+- Exactly one active exported palette at `workspace.tools.palettes`: enforced
 
 ## Validation Commands Run
 1. `node --check tools/workspace-v2/index.js`
-2. Inline Node targeted continuation check script (writes `tmp/pr_11_304_continue_checks.json`)
-3. Inline Node saved-session validation scenario check script
+2. `node --check tests/runtime/V2CurrentSessionExport.test.mjs`
+3. `node tests/runtime/V2CurrentSessionExport.test.mjs`
+4. Inline targeted executable check script:
+   - writes `tmp/pr_11_304_palette_ownership_checks.json`
+   - validates presence of single-active-palette export and guard strings in `tools/workspace-v2/index.js`
 
 ## Validation Results
 - Command 1: PASS
-- Command 2: PASS (`PR_11_304 continuation checks: ok`)
-- Command 3: PASS (`saved session validation scenario check: ok`)
-
-## Acceptance Mapping
-- Load Fixture -> manifest textarea contains `tools.workspace-v2.activeSession.paletteJson.swatches`: PASS
-- Export blocks stale invalid saved palette session `session_2` with actionable message: PASS
-- After deleting/overwriting invalid saved session, export path is unblocked: PASS (guard behavior validated)
-- New saved palette sessions use `paletteJson`, not `payloadJson`: PASS
-- Export never emits `workspaceSession` and never emits `games[]`: PASS (manifest builder/validator path)
-- Invalid New Session ID message is actionable and Save stays disabled: PASS
+- Command 2: PASS
+- Command 3: FAIL (existing legacy expectation unrelated to this scoped change):
+  - test asserts `workspace.schema.json` root `workspaceSession`, which conflicts with current manifest-only direction
+- Command 4: PASS
 
 ## Full Samples Smoke Decision
 - Full samples smoke test skipped.
-- Reason: change is scoped to one file and validated via targeted syntax + executable continuation checks.
+- Reason: change is scoped to one tool JS file with targeted syntax/executable checks only; no shared sample framework changes.
+

tools/workspace-v2/index.js

@@ -85,6 +85,7 @@ class WorkspaceV2SessionProducer {
     this.currentSessionPayload = null;
     this.currentSessionSource = "";
     this.currentHostContextId = "";
+    this.lastWorkspaceExportBuildErrorMessage = "";
     this.workspaceTransitionState = "idle";
     this.pendingMergePreview = null;
     this.lastMergedSessionResult = null;
@@ -905,6 +906,90 @@ class WorkspaceV2SessionProducer {
     return "";
   }
 
+  validatePaletteSwatchesForWorkspaceExport(swatches, swatchesPath) {
+    if (!Array.isArray(swatches)) {
+      return { ok: false, message: `${swatchesPath} must be an array.` };
+    }
+    for (let index = 0; index < swatches.length; index += 1) {
+      const swatchPath = `${swatchesPath}[${index}]`;
+      const swatch = swatches[index];
+      if (!swatch || typeof swatch !== "object" || Array.isArray(swatch)) {
+        return { ok: false, message: `${swatchPath} must be an object.` };
+      }
+      const swatchKeys = Object.keys(swatch);
+      const allowedSwatchKeys = new Set(["symbol", "hex", "name"]);
+      for (const swatchKey of swatchKeys) {
+        if (!allowedSwatchKeys.has(swatchKey)) {
+          return { ok: false, message: `${swatchPath}.${swatchKey} is not allowed.` };
+        }
+      }
+      if (typeof swatch.symbol !== "string" || swatch.symbol.length !== 1) {
+        return { ok: false, message: `${swatchPath}.symbol must be exactly one character.` };
+      }
+      if (typeof swatch.hex !== "string" || !/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(swatch.hex)) {
+        return { ok: false, message: `${swatchPath}.hex must be #RRGGBB or #RRGGBBAA.` };
+      }
+      if (typeof swatch.name !== "string" || !swatch.name.trim()) {
+        return { ok: false, message: `${swatchPath}.name is required.` };
+      }
+    }
+    return { ok: true, message: "" };
+  }
+
+  resolveActivePaletteForWorkspaceExport(activePayload, library) {
+    let savedPaletteCount = 0;
+    if (library && typeof library === "object" && !Array.isArray(library)) {
+      for (const sessionId of Object.keys(library)) {
+        const savedPayload = library[sessionId];
+        if (!savedPayload || typeof savedPayload !== "object" || Array.isArray(savedPayload)) {
+          continue;
+        }
+        if (savedPayload.toolId !== "palette-manager-v2") {
+          continue;
+        }
+        if (!savedPayload.paletteJson || typeof savedPayload.paletteJson !== "object" || Array.isArray(savedPayload.paletteJson)) {
+          continue;
+        }
+        if (!Array.isArray(savedPayload.paletteJson.swatches)) {
+          continue;
+        }
+        savedPaletteCount += 1;
+      }
+    }
+    if (!activePayload || typeof activePayload !== "object" || Array.isArray(activePayload)) {
+      return { ok: false, message: "Active session payload could not be resolved for export." };
+    }
+    if (activePayload.toolId !== "palette-manager-v2") {
+      if (savedPaletteCount > 1) {
+        return {
+          ok: false,
+          message: "Multiple palettes are present. Select one active palette session before export."
+        };
+      }
+      return {
+        ok: false,
+        message: "Workspace export requires one active palette in the current palette-manager-v2 session."
+      };
+    }
+    const activePaletteValidation = this.validateWorkspaceToolSessionPayload(activePayload, "tools.workspace-v2.activeSession");
+    if (!activePaletteValidation.ok) {
+      return { ok: false, message: activePaletteValidation.message };
+    }
+    const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(
+      activePayload.paletteJson.swatches,
+      "tools.workspace-v2.activeSession.paletteJson.swatches"
+    );
+    if (!swatchValidation.ok) {
+      return { ok: false, message: swatchValidation.message };
+    }
+    return {
+      ok: true,
+      activePalette: {
+        swatches: this.cloneSessionValue(activePayload.paletteJson.swatches)
+      }
+    };
+  }
+
   selectedMergedSessionId() {
     return typeof this.mergedSessionIdNode.value === "string" ? this.mergedSessionIdNode.value.trim() : "";
   }
@@ -3048,16 +3133,25 @@ class WorkspaceV2SessionProducer {
   }
 
   buildWorkspaceSchemaDocument() {
+    this.lastWorkspaceExportBuildErrorMessage = "";
     const activePayload = this.resolveActiveSessionPayloadForWorkspaceManifest();
     if (!this.isValidSessionPayload(activePayload)) {
+      this.lastWorkspaceExportBuildErrorMessage = "Export error: No active Workspace V2 session is available to export.";
       return null;
     }
     const library = this.readSessionLibrary();
     if (library === null) {
+      this.lastWorkspaceExportBuildErrorMessage = "Export error: Session library could not be read.";
+      return null;
+    }
+    const activePaletteResolution = this.resolveActivePaletteForWorkspaceExport(activePayload, library);
+    if (!activePaletteResolution.ok) {
+      this.lastWorkspaceExportBuildErrorMessage = `Export error: ${activePaletteResolution.message}`;
       return null;
     }
     const activeToolId = typeof activePayload.toolId === "string" && activePayload.toolId.trim() ? activePayload.toolId.trim() : "";
     if (!activeToolId) {
+      this.lastWorkspaceExportBuildErrorMessage = "Export error: Active session toolId is missing.";
       return null;
     }
     let activeHostContextId = typeof this.currentHostContextId === "string" ? this.currentHostContextId.trim() : "";
@@ -3086,6 +3180,9 @@ class WorkspaceV2SessionProducer {
       id: `workspace-v2-${activeHostContextId}`,
       name: `Workspace V2 Session ${activeToolId}`,
       tools: {
+        palettes: {
+          activePalette: this.cloneSessionValue(activePaletteResolution.activePalette)
+        },
         "workspace-v2": {
         schema: "html-js-gaming.workspace-v2-session/1",
           game: workspaceGame,
@@ -3104,7 +3201,7 @@ class WorkspaceV2SessionProducer {
     this.setImportExportStatus("Export clicked");
     const workspaceSchemaDocument = this.buildWorkspaceSchemaDocument();
     if (!workspaceSchemaDocument) {
-      this.setImportExportStatus("Export error: No active Workspace V2 session is available to export.");
+      this.setImportExportStatus(this.lastWorkspaceExportBuildErrorMessage || "Export error: No active Workspace V2 session is available to export.");
       return;
     }
     const invalidSavedSessionId = this.readInvalidPaletteSavedSessionId(workspaceSchemaDocument.tools["workspace-v2"].savedSessions);
@@ -3159,6 +3256,13 @@ class WorkspaceV2SessionProducer {
       if (!Array.isArray(sessionPayload.paletteJson.swatches)) {
         return { ok: false, message: `${sessionPath}.paletteJson.swatches must be an array.` };
       }
+      const swatchValidation = this.validatePaletteSwatchesForWorkspaceExport(
+        sessionPayload.paletteJson.swatches,
+        `${sessionPath}.paletteJson.swatches`
+      );
+      if (!swatchValidation.ok) {
+        return swatchValidation;
+      }
       if (Object.prototype.hasOwnProperty.call(sessionPayload.paletteJson, "colors")) {
         return { ok: false, message: `${sessionPath}.paletteJson.colors is not supported. Use paletteJson.swatches.` };
       }
@@ -3205,12 +3309,46 @@ class WorkspaceV2SessionProducer {
       return { ok: false, message: "tools must be an object." };
     }
     const toolsKeys = Object.keys(workspaceDocument.tools);
-    const allowedToolsKeys = new Set(["workspace-v2"]);
+    const allowedToolsKeys = new Set(["palettes", "workspace-v2"]);
     for (const key of toolsKeys) {
       if (!allowedToolsKeys.has(key)) {
         return { ok: false, message: `tools.${key} is not allowed.` };
       }
     }
+    if (!Object.prototype.hasOwnProperty.call(workspaceDocument.tools, "palettes")) {
+      return { ok: false, message: "tools.palettes is required." };
+    }
+    const palettesTool = workspaceDocument.tools.palettes;
+    if (!palettesTool || typeof palettesTool !== "object" || Array.isArray(palettesTool)) {
+      return { ok: false, message: "tools.palettes must be an object." };
+    }
+    const palettesToolKeys = Object.keys(palettesTool);
+    const allowedPalettesToolKeys = new Set(["activePalette"]);
+    for (const key of palettesToolKeys) {
+      if (!allowedPalettesToolKeys.has(key)) {
+        return { ok: false, message: `tools.palettes.${key} is not allowed.` };
+      }
+    }
+    if (!Object.prototype.hasOwnProperty.call(palettesTool, "activePalette")) {
+      return { ok: false, message: "tools.palettes.activePalette is required." };
+    }
+    if (!palettesTool.activePalette || typeof palettesTool.activePalette !== "object" || Array.isArray(palettesTool.activePalette)) {
+      return { ok: false, message: "tools.palettes.activePalette must be an object." };
+    }
+    const activePaletteKeys = Object.keys(palettesTool.activePalette);
+    const allowedActivePaletteKeys = new Set(["swatches"]);
+    for (const key of activePaletteKeys) {
+      if (!allowedActivePaletteKeys.has(key)) {
+        return { ok: false, message: `tools.palettes.activePalette.${key} is not allowed.` };
+      }
+    }
+    const activePaletteSwatchValidation = this.validatePaletteSwatchesForWorkspaceExport(
+      palettesTool.activePalette.swatches,
+      "tools.palettes.activePalette.swatches"
+    );
+    if (!activePaletteSwatchValidation.ok) {
+      return activePaletteSwatchValidation;
+    }
     if (!Object.prototype.hasOwnProperty.call(workspaceDocument.tools, "workspace-v2")) {
       return { ok: false, message: "tools.workspace-v2 is required." };
     }