Disable duplicate new-session saves and clarify Session Library load semantics - PR_11_269

Author: DavidQ

docs/dev/reports/PR_11_269_workspace_v2_session_library_save_guard_load_explanation_report.md

@@ -0,0 +1,72 @@
+# PR_11_269 Workspace V2 Session Library Save Guard + Load Explanation UX Report
+
+## Scope
+Workspace V2 Session Library only.
+
+## Files Changed
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/pr/PLAN_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX.md
+- docs/pr/BUILD_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX.md
+- docs/dev/reports/PR_11_269_workspace_v2_session_library_save_guard_load_explanation_report.md
+
+## Implementation Summary
+- Added Save Session guard logic in state model and UI wiring.
+
+### Save Session enablement
+Save is enabled only when all are true:
+- active Workspace V2 session exists (`currentHostContextId` + valid payload)
+- New Session ID is valid (non-empty, pattern-validated)
+- New Session ID does not already exist in saved library
+
+Save is disabled when:
+- ID is empty
+- ID is invalid
+- ID already exists
+- no active Workspace V2 session exists
+
+### Existing saved-session behavior
+- Existing saved sessions remain managed from Saved Session cards.
+- Load from card path continues to:
+  - load saved session as active Workspace V2 session
+  - avoid creating duplicate saved entries
+  - avoid mutating saved library copy
+  - recompute UI state through model refresh after load
+
+### UX helper text
+- Updated Session Library helper text to explain:
+  - Save creates new saved copy from active Workspace V2 session
+  - Load makes saved session active
+  - Overwrite (when available on cards) updates saved copy
+  - Delete removes saved copy only
+
+### Status text
+- Added exact required duplicate-ID message in current-state feedback:
+  - `That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.`
+- Library state updates now set current-state guidance text and avoid stale messages.
+
+## Validation Commands
+1. `node --check tools/workspace-v2/index.js`
+   - PASS
+2. `node --check tests/runtime/V2SessionLibrarySaveGuard.test.mjs`
+   - PASS
+3. `node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
+   - PASS
+4. `node --check tests/runtime/V2SessionLibraryActions.test.mjs`
+   - PASS
+5. `node tests/runtime/V2SessionLibrarySaveGuard.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-save-guard-results.json`
+6. `node tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-action-cleanup-results.json`
+7. `node tests/runtime/V2SessionLibraryActions.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-actions-results.json`
+
+## Full Samples Smoke Decision
+- Skipped full samples smoke test.
+- Reason: changes are scoped to Workspace V2 Session Library save guard and UX copy, with targeted runtime test coverage.

docs/pr/BUILD_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX.md

@@ -0,0 +1,39 @@
+# BUILD_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX
+
+## Purpose
+Enforce save-button guard conditions for new session IDs and improve Session Library Load explanation UX.
+
+## Files
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/dev/reports/PR_11_269_workspace_v2_session_library_save_guard_load_explanation_report.md
+
+## Implementation
+1. Add save-guard state helpers:
+   - active-session availability
+   - new session ID validity
+   - duplicate saved-session ID detection
+2. Extend state model with save-guard fields and wire Save button enablement to `libraryCanSave`.
+3. Keep top hidden non-save buttons disabled.
+4. Add duplicate-ID current-state status text exactly as required.
+5. Ensure load-from-card path retains existing non-duplicate/non-mutation behavior and recomputes UI state from loaded payload.
+6. Update Session Library helper text to explain Save/Load/Overwrite/Delete behavior.
+7. Update/add targeted runtime tests.
+
+## Acceptance
+- Save button guard conditions enforced exactly.
+- Duplicate-ID message shown exactly.
+- Card-level load/delete/overwrite authority unchanged.
+- No stale/misleading Session Library status text.
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node --check tests/runtime/V2SessionLibraryActions.test.mjs
+- node tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node tests/runtime/V2SessionLibraryActions.test.mjs

docs/pr/PLAN_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX.md

@@ -0,0 +1,37 @@
+# PLAN_PR_11_269_WORKSPACE_V2_SESSION_LIBRARY_SAVE_GUARD_AND_LOAD_EXPLANATION_UX
+
+## Purpose
+Add Workspace V2 Session Library new-session save guard rules and clarify load/save UX messaging.
+
+## Scope
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/report only
+
+## Goals
+- Save Session enabled only when:
+  - active Workspace V2 session exists
+  - new session ID is valid
+  - ID does not already exist in saved sessions
+- Save Session disabled for empty, invalid, or duplicate IDs.
+- Existing saved session management remains card-level authoritative.
+- Load from saved card loads active session without mutating or duplicating saved copy.
+- Add concise helper text explaining Save/Load/Overwrite/Delete behavior.
+- Show required duplicate-ID status text.
+
+## Out of Scope
+- No schema changes
+- No cross-tool changes
+- No merge/diff behavior changes beyond state recompute wiring
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node --check tests/runtime/V2SessionLibraryActions.test.mjs
+- node tests/runtime/V2SessionLibrarySaveGuard.test.mjs
+- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node tests/runtime/V2SessionLibraryActions.test.mjs

tests/runtime/V2SessionLibraryActionCleanup.test.mjs

@@ -44,14 +44,14 @@ export function run() {
     '<button id="workspaceV2OverwriteSessionButton" type="button" hidden>Overwrite Session</button>',
     '<button id="workspaceV2LoadSessionButton" type="button" hidden>Load Session</button>',
     '<button id="workspaceV2DeleteSessionButton" type="button" hidden>Delete Saved Session</button>',
-    'Use Save Session to create a new saved entry. Manage existing saved sessions from their Saved Sessions cards.'
+    'Save creates a new saved copy from the active Workspace V2 session. Load from a saved card makes that saved session the active Workspace V2 session. Overwrite (when available on cards) updates an existing saved copy, and Delete removes the saved copy only.'
   ];
   requiredHtmlTokens.forEach((token) => {
     if (!html.includes(token)) failures.push(`Missing expected Session Library cleanup HTML token: ${token}`);
   });
 
   const requiredJsTokens = [
-    'this.setLibraryStatus("Saved session already exists. Manage it from its Saved Sessions card.");',
+    'this.setLibraryStatus("That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.");',
     'Saved session created. Manage this session from its Saved Sessions card.',
     'loadButton.textContent = "Load";',
     'deleteSavedButton.textContent = "Delete Saved";',

tests/runtime/V2SessionLibraryActions.test.mjs

@@ -37,7 +37,7 @@ function evaluateSaveAction(inputId, activePayload, library) {
     return { message: "No active Workspace V2 session is available to save.", library: libraryMap };
   }
   if (Object.prototype.hasOwnProperty.call(libraryMap, sessionId)) {
-    return { message: "Saved session already exists. Manage it from its Saved Sessions card.", library: libraryMap };
+    return { message: "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.", library: libraryMap };
   }
   libraryMap[sessionId] = activePayload;
   return { message: "Saved session created. Manage this session from its Saved Sessions card.", library: libraryMap };
@@ -131,7 +131,7 @@ export function run() {
   const requiredMessages = [
     "Enter a session ID before saving.",
     "No active Workspace V2 session is available to save.",
-    "Saved session already exists. Manage it from its Saved Sessions card.",
+    "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.",
     "Saved session created. Manage this session from its Saved Sessions card.",
     "Enter a session ID before overwriting.",
     "No active Workspace V2 session is available to overwrite from.",
@@ -179,7 +179,7 @@ export function run() {
   }
 
   const duplicateSave = evaluateSaveAction("saved-a", activePayload, { "saved-a": { toolId: "palette-manager-v2", version: "v2" } });
-  if (duplicateSave.message !== "Saved session already exists. Manage it from its Saved Sessions card.") {
+  if (duplicateSave.message !== "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.") {
     failures.push("Duplicate save should be blocked with overwrite guidance.");
   }
 

tests/runtime/V2SessionLibrarySaveGuard.test.mjs

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..");
+const jsPath = path.join(repoRoot, "tools", "workspace-v2", "index.js");
+const testPath = path.join(repoRoot, "tests", "runtime", "V2SessionLibrarySaveGuard.test.mjs");
+const resultsPath = path.join(repoRoot, "tmp", "v2-session-library-save-guard-results.json");
+
+function checkSyntax(filePath) {
+  try {
+    execFileSync(process.execPath, ["--check", filePath], {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return { ok: true, error: "" };
+  } catch (error) {
+    return { ok: false, error: (error?.stderr || error?.stdout || error?.message || "").toString().trim() };
+  }
+}
+
+function canSaveSession({ hasActiveSession, newId, idValid, idExists }) {
+  return Boolean(Boolean(newId) && idValid && !idExists && hasActiveSession);
+}
+
+export function run() {
+  const failures = [];
+  const jsExists = fs.existsSync(jsPath);
+  const js = jsExists ? fs.readFileSync(jsPath, "utf8") : "";
+  const jsSyntax = checkSyntax(jsPath);
+  const testSyntax = checkSyntax(testPath);
+
+  if (!jsExists) failures.push("Missing tools/workspace-v2/index.js.");
+  if (!jsSyntax.ok) failures.push("tools/workspace-v2/index.js failed syntax check.");
+  if (!testSyntax.ok) failures.push("tests/runtime/V2SessionLibrarySaveGuard.test.mjs failed syntax check.");
+
+  const requiredTokens = [
+    "hasActiveWorkspaceSessionForSave()",
+    "isValidNewSessionId(sessionId)",
+    "savedSessionIdExists(sessionId)",
+    "libraryCanSave",
+    "this.saveSessionButton.disabled = !model.libraryCanSave;",
+    "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.",
+    "loadSavedSessionById(sessionId)",
+    "this.loadNamedSession();",
+    "this.syncDiffAndMergeSelectionSlotsFromContextId(sessionId.trim());"
+  ];
+  requiredTokens.forEach((token) => {
+    if (!js.includes(token)) failures.push(`Missing required save-guard token: ${token}`);
+  });
+
+  const scenarios = {
+    emptyIdDisabled: canSaveSession({ hasActiveSession: true, newId: "", idValid: false, idExists: false }),
+    invalidIdDisabled: canSaveSession({ hasActiveSession: true, newId: "bad id", idValid: false, idExists: false }),
+    duplicateIdDisabled: canSaveSession({ hasActiveSession: true, newId: "session-a", idValid: true, idExists: true }),
+    noActiveSessionDisabled: canSaveSession({ hasActiveSession: false, newId: "session-a", idValid: true, idExists: false }),
+    validEnabled: canSaveSession({ hasActiveSession: true, newId: "session-a", idValid: true, idExists: false })
+  };
+
+  if (scenarios.emptyIdDisabled) failures.push("Save should be disabled for empty ID.");
+  if (scenarios.invalidIdDisabled) failures.push("Save should be disabled for invalid ID.");
+  if (scenarios.duplicateIdDisabled) failures.push("Save should be disabled for duplicate ID.");
+  if (scenarios.noActiveSessionDisabled) failures.push("Save should be disabled without active session.");
+  if (!scenarios.validEnabled) failures.push("Save should be enabled only for valid new ID with active session.");
+
+  fs.mkdirSync(path.dirname(resultsPath), { recursive: true });
+  fs.writeFileSync(resultsPath, `${JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    failures,
+    checks: { jsExists, jsSyntax, testSyntax },
+    scenarios
+  }, null, 2)}
+`, "utf8");
+
+  console.log(`v2 session-library-save-guard results: ${resultsPath}`);
+  assert.equal(failures.length, 0, `V2 session-library-save-guard failures: ${failures.join(" | ")}`);
+  return { failures };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const summary = run();
+    console.log(JSON.stringify(summary, null, 2));
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+}

tools/workspace-v2/index.html

@@ -59,7 +59,7 @@ <h2>Share Session Link</h2>
         <h2>Session Library</h2>
         <label for="workspaceV2SessionName">New Session ID (Save Session)</label>
         <input id="workspaceV2SessionName" type="text" placeholder="session-id" />
-        <p>Use Save Session to create a new saved entry. Manage existing saved sessions from their Saved Sessions cards.</p>
+        <p>Save creates a new saved copy from the active Workspace V2 session. Load from a saved card makes that saved session the active Workspace V2 session. Overwrite (when available on cards) updates an existing saved copy, and Delete removes the saved copy only.</p>
         <div>
           <button id="workspaceV2SaveSessionButton" type="button">Save Session</button>
           <button id="workspaceV2OverwriteSessionButton" type="button" hidden>Overwrite Session</button>