Skip to content

Commit 6ca539b

Browse files
author
DavidQ
committed
Clarify Workspace V2 session actions with explicit save, load, overwrite, and diff messaging - PR_11_273
1 parent 8637300 commit 6ca539b

8 files changed

Lines changed: 253 additions & 24 deletions

‎docs/dev/reports/PR_11_273_workspace_v2_wording_clarity_report.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# PR_11_273 Workspace V2 Wording Clarity Report
2+
3+
## Scope
4+
Workspace V2 only: Session Library + Session Diff Viewer + status messaging.
5+
6+
## Files Changed
7+
- tools/workspace-v2/index.html
8+
- tools/workspace-v2/index.js
9+
- tests/runtime/V2SessionLibraryActions.test.mjs
10+
- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
11+
- tests/runtime/V2DiffViewerMessaging.test.mjs
12+
- docs/pr/PLAN_PR_11_273_WORKSPACE_V2_WORDING_CLARITY.md
13+
- docs/pr/BUILD_PR_11_273_WORKSPACE_V2_WORDING_CLARITY.md
14+
- docs/dev/reports/PR_11_273_workspace_v2_wording_clarity_report.md
15+
16+
## Implementation Summary
17+
- Session Library helper text now explicitly explains overwrite intent:
18+
- `Overwrite replaces this saved session with what you are currently working on.`
19+
- Save messaging updated:
20+
- create: `Saved session '<ID>' created.`
21+
- duplicate: `That session ID already exists. Use the saved session card to Load or Overwrite it.`
22+
- Overwrite messaging updated:
23+
- `Saved session '<ID>' overwritten with current workspace state.`
24+
- Load messaging updated:
25+
- `Loaded '<ID>' into the current workspace.`
26+
- Diff completion messaging updated:
27+
- identical: `No differences. The selected sessions are identical.`
28+
- different: `Differences detected between selected sessions.`
29+
- Removed vague phrase `Saved session updated.` from Workspace V2 session messaging.
30+
31+
## Validation Commands
32+
1. `node --check tools/workspace-v2/index.js`
33+
- PASS
34+
2. `node --check tests/runtime/V2SessionLibraryActions.test.mjs`
35+
- PASS
36+
3. `node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
37+
- PASS
38+
4. `node --check tests/runtime/V2DiffViewerMessaging.test.mjs`
39+
- PASS
40+
5. `node tests/runtime/V2SessionLibraryActions.test.mjs`
41+
- PASS
42+
- Results: `tmp/v2-session-library-actions-results.json`
43+
6. `node tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
44+
- PASS
45+
- Results: `tmp/v2-session-library-action-cleanup-results.json`
46+
7. `node tests/runtime/V2DiffViewerMessaging.test.mjs`
47+
- PASS
48+
- Results: `tmp/v2-diff-viewer-messaging-results.json`
49+
50+
## Full Samples Smoke Decision
51+
- Skipped full samples smoke test.
52+
- Reason: PR scope is wording-only in Workspace V2 Session Library/Diff messaging and is covered by targeted runtime checks.

‎docs/pr/BUILD_PR_11_273_WORKSPACE_V2_WORDING_CLARITY.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# BUILD_PR_11_273_WORKSPACE_V2_WORDING_CLARITY
2+
3+
## Purpose
4+
Implement text-only wording clarity updates for Workspace V2 Session Library and Session Diff Viewer.
5+
6+
## Files
7+
- tools/workspace-v2/index.html
8+
- tools/workspace-v2/index.js
9+
- tests/runtime/V2SessionLibraryActions.test.mjs
10+
- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
11+
- tests/runtime/V2DiffViewerMessaging.test.mjs
12+
- docs/dev/reports/PR_11_273_workspace_v2_wording_clarity_report.md
13+
14+
## Implementation
15+
1. Update Session Library helper copy to clarify overwrite behavior.
16+
2. Update Session Library statuses:
17+
- Save success includes session ID.
18+
- Overwrite success includes session ID and current workspace state wording.
19+
- Load success includes session ID.
20+
- Duplicate save guidance points to Load/Overwrite on saved card.
21+
3. Replace diff completion wording:
22+
- identical sessions -> explicit no-differences message
23+
- non-identical sessions -> explicit differences-detected message
24+
4. Remove vague phrase `Saved session updated.` from Workspace V2 session messaging.
25+
5. Update targeted runtime tests for new wording and add a focused diff-messaging runtime test.
26+
27+
## Acceptance
28+
- Session Library Save/Overwrite/Load statuses are explicit and include session IDs.
29+
- Duplicate save messaging is actionable and unambiguous.
30+
- Diff Viewer messaging is explicit for identical vs different sessions.
31+
- No behavior-path changes to save/overwrite/load/diff execution.
32+
33+
## Validation
34+
- node --check tools/workspace-v2/index.js
35+
- node --check tests/runtime/V2SessionLibraryActions.test.mjs
36+
- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
37+
- node --check tests/runtime/V2DiffViewerMessaging.test.mjs
38+
- node tests/runtime/V2SessionLibraryActions.test.mjs
39+
- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
40+
- node tests/runtime/V2DiffViewerMessaging.test.mjs

‎docs/pr/PLAN_PR_11_273_WORKSPACE_V2_WORDING_CLARITY.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# PLAN_PR_11_273_WORKSPACE_V2_WORDING_CLARITY
2+
3+
## Purpose
4+
Improve Workspace V2 wording clarity for Session Library and Session Diff Viewer with text-only updates.
5+
6+
## Scope
7+
- tools/workspace-v2/index.html
8+
- tools/workspace-v2/index.js
9+
- tests/runtime/V2SessionLibraryActions.test.mjs
10+
- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
11+
- tests/runtime/V2DiffViewerMessaging.test.mjs
12+
- docs/report only
13+
14+
## Goals
15+
- Replace Save/Overwrite/Load status text with explicit action + session ID + result wording.
16+
- Replace duplicate-save guidance with clear Load/Overwrite direction.
17+
- Add overwrite helper text in Session Library copy.
18+
- Replace vague diff completion messaging with explicit identical-vs-different messages.
19+
- Remove lingering vague phrase `Saved session updated.`
20+
- Keep behavior unchanged.
21+
22+
## Out of Scope
23+
- No merge/diff algorithm changes.
24+
- No schema/sample/game/workspace-v1 changes.
25+
- No cross-tool changes.
26+
27+
## Validation
28+
- node --check tools/workspace-v2/index.js
29+
- node --check tests/runtime/V2SessionLibraryActions.test.mjs
30+
- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
31+
- node --check tests/runtime/V2DiffViewerMessaging.test.mjs
32+
- node tests/runtime/V2SessionLibraryActions.test.mjs
33+
- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
34+
- node tests/runtime/V2DiffViewerMessaging.test.mjs

‎tests/runtime/V2DiffViewerMessaging.test.mjs‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
import assert from "node:assert/strict";
2+
import fs from "node:fs";
3+
import path from "node:path";
4+
import { execFileSync } from "node:child_process";
5+
import { fileURLToPath, pathToFileURL } from "node:url";
6+
7+
const __filename = fileURLToPath(import.meta.url);
8+
const __dirname = path.dirname(__filename);
9+
const repoRoot = path.resolve(__dirname, "..", "..");
10+
const jsPath = path.join(repoRoot, "tools", "workspace-v2", "index.js");
11+
const testPath = path.join(repoRoot, "tests", "runtime", "V2DiffViewerMessaging.test.mjs");
12+
const resultsPath = path.join(repoRoot, "tmp", "v2-diff-viewer-messaging-results.json");
13+
14+
function checkSyntax(filePath) {
15+
try {
16+
execFileSync(process.execPath, ["--check", filePath], {
17+
cwd: repoRoot,
18+
stdio: ["ignore", "pipe", "pipe"]
19+
});
20+
return { ok: true, error: "" };
21+
} catch (error) {
22+
return { ok: false, error: (error?.stderr || error?.stdout || error?.message || "").toString().trim() };
23+
}
24+
}
25+
26+
function diffStatusMessage(diff) {
27+
if (
28+
Object.keys(diff.added).length === 0 &&
29+
Object.keys(diff.removed).length === 0 &&
30+
Object.keys(diff.changed).length === 0
31+
) {
32+
return "No differences. The selected sessions are identical.";
33+
}
34+
return "Differences detected between selected sessions.";
35+
}
36+
37+
export function run() {
38+
const failures = [];
39+
const jsExists = fs.existsSync(jsPath);
40+
const js = jsExists ? fs.readFileSync(jsPath, "utf8") : "";
41+
const jsSyntax = checkSyntax(jsPath);
42+
const testSyntax = checkSyntax(testPath);
43+
44+
if (!jsExists) failures.push("Missing tools/workspace-v2/index.js.");
45+
if (!jsSyntax.ok) failures.push("tools/workspace-v2/index.js failed syntax check.");
46+
if (!testSyntax.ok) failures.push("tests/runtime/V2DiffViewerMessaging.test.mjs failed syntax check.");
47+
48+
if (!js.includes("No differences. The selected sessions are identical.")) {
49+
failures.push("Missing empty-diff message.");
50+
}
51+
if (!js.includes("Differences detected between selected sessions.")) {
52+
failures.push("Missing non-empty diff message.");
53+
}
54+
if (js.includes("Session diff computed.")) {
55+
failures.push("Legacy vague diff message should be removed.");
56+
}
57+
58+
const emptyDiffMessage = diffStatusMessage({ added: {}, removed: {}, changed: {} });
59+
const changedDiffMessage = diffStatusMessage({ added: {}, removed: {}, changed: { key: { from: 1, to: 2 } } });
60+
if (emptyDiffMessage !== "No differences. The selected sessions are identical.") {
61+
failures.push("Empty diff status message mismatch.");
62+
}
63+
if (changedDiffMessage !== "Differences detected between selected sessions.") {
64+
failures.push("Changed diff status message mismatch.");
65+
}
66+
67+
fs.mkdirSync(path.dirname(resultsPath), { recursive: true });
68+
fs.writeFileSync(resultsPath, `${JSON.stringify({
69+
generatedAt: new Date().toISOString(),
70+
failures,
71+
checks: {
72+
jsExists,
73+
jsSyntax,
74+
testSyntax
75+
},
76+
scenarios: {
77+
emptyDiffMessage,
78+
changedDiffMessage
79+
}
80+
}, null, 2)}
81+
`, "utf8");
82+
83+
console.log(`v2 diff-viewer messaging results: ${resultsPath}`);
84+
assert.equal(failures.length, 0, `V2 diff-viewer messaging failures: ${failures.join(" | ")}`);
85+
return { failures };
86+
}
87+
88+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
89+
try {
90+
const summary = run();
91+
console.log(JSON.stringify(summary, null, 2));
92+
} catch (error) {
93+
console.error(error);
94+
process.exitCode = 1;
95+
}
96+
}

‎tests/runtime/V2SessionLibraryActionCleanup.test.mjs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,15 +44,15 @@ export function run() {
4444
'<button id="workspaceV2OverwriteSessionButton" type="button" hidden>Overwrite Session</button>',
4545
'<button id="workspaceV2LoadSessionButton" type="button" hidden>Load Session</button>',
4646
'<button id="workspaceV2DeleteSessionButton" type="button" hidden>Delete Saved Session</button>',
47-
'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.'
47+
"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 replaces this saved session with what you are currently working on. Delete removes the saved copy only."
4848
];
4949
requiredHtmlTokens.forEach((token) => {
5050
if (!html.includes(token)) failures.push(`Missing expected Session Library cleanup HTML token: ${token}`);
5151
});
5252

5353
const requiredJsTokens = [
54-
'this.setLibraryStatus("That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.");',
55-
'Saved session created. Manage this session from its Saved Sessions card.',
54+
'this.setLibraryStatus("That session ID already exists. Use the saved session card to Load or Overwrite it.");',
55+
"Saved session '${sessionName}' created.",
5656
'loadButton.textContent = "Load";',
5757
'overwriteButton.textContent = "Overwrite";',
5858
'deleteSavedButton.textContent = "Delete Saved";',

‎tests/runtime/V2SessionLibraryActions.test.mjs‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,10 @@ function evaluateSaveAction(inputId, activePayload, library) {
3737
return { message: "No active Workspace V2 session is available to save.", library: libraryMap };
3838
}
3939
if (Object.prototype.hasOwnProperty.call(libraryMap, sessionId)) {
40-
return { message: "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.", library: libraryMap };
40+
return { message: "That session ID already exists. Use the saved session card to Load or Overwrite it.", library: libraryMap };
4141
}
4242
libraryMap[sessionId] = activePayload;
43-
return { message: "Saved session created. Manage this session from its Saved Sessions card.", library: libraryMap };
43+
return { message: `Saved session '${sessionId}' created.`, library: libraryMap };
4444
}
4545

4646
function evaluateOverwriteAction(inputId, activePayload, library) {
@@ -56,7 +56,7 @@ function evaluateOverwriteAction(inputId, activePayload, library) {
5656
return { message: "Saved session not found. Use Save Session to create it first.", library: libraryMap };
5757
}
5858
libraryMap[sessionId] = activePayload;
59-
return { message: "Saved session overwritten.", library: libraryMap };
59+
return { message: `Saved session '${sessionId}' overwritten with current workspace state.`, library: libraryMap };
6060
}
6161

6262
function evaluateLoadAction(inputId, library) {
@@ -67,7 +67,7 @@ function evaluateLoadAction(inputId, library) {
6767
if (!Object.prototype.hasOwnProperty.call(library, sessionId)) {
6868
return { message: "Saved session not found.", loaded: false };
6969
}
70-
return { message: "Saved session loaded.", loaded: true, payload: library[sessionId] };
70+
return { message: `Loaded '${sessionId}' into the current workspace.`, loaded: true, payload: library[sessionId] };
7171
}
7272

7373
function evaluateDeleteSavedAction(inputId, library, historyEntries, sessionStorageMap) {
@@ -131,15 +131,14 @@ export function run() {
131131
const requiredMessages = [
132132
"Enter a session ID before saving.",
133133
"No active Workspace V2 session is available to save.",
134-
"That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.",
135-
"Saved session created. Manage this session from its Saved Sessions card.",
134+
"That session ID already exists. Use the saved session card to Load or Overwrite it.",
135+
"Saved session '${sessionName}' created.",
136136
"Enter a session ID before overwriting.",
137137
"No active Workspace V2 session is available to overwrite from.",
138138
"Saved session not found. Use Save Session to create it first.",
139-
"Saved session overwritten.",
140-
"Saved session updated.",
139+
"Saved session '${sessionName}' overwritten with current workspace state.",
141140
"Enter a saved session ID before loading.",
142-
"Saved session loaded.",
141+
"Loaded '${sessionName}' into the current workspace.",
143142
"Enter a saved session ID before deleting.",
144143
"No saved sessions exist. Use Delete on Recent Sessions to remove temporary sessions.",
145144
"Session ID is not saved in Session Library. Use Delete on Recent Sessions to remove temporary sessions.",
@@ -175,12 +174,12 @@ export function run() {
175174
if (emptyDelete.message !== "Enter a saved session ID before deleting.") failures.push("Delete empty input message mismatch.");
176175

177176
const saveCreated = evaluateSaveAction("saved-a", activePayload, {});
178-
if (saveCreated.message !== "Saved session created. Manage this session from its Saved Sessions card." || !Object.prototype.hasOwnProperty.call(saveCreated.library, "saved-a")) {
177+
if (saveCreated.message !== "Saved session 'saved-a' created." || !Object.prototype.hasOwnProperty.call(saveCreated.library, "saved-a")) {
179178
failures.push("Save with valid active payload should create library entry.");
180179
}
181180

182181
const duplicateSave = evaluateSaveAction("saved-a", activePayload, { "saved-a": { toolId: "palette-manager-v2", version: "v2" } });
183-
if (duplicateSave.message !== "That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.") {
182+
if (duplicateSave.message !== "That session ID already exists. Use the saved session card to Load or Overwrite it.") {
184183
failures.push("Duplicate save should be blocked with overwrite guidance.");
185184
}
186185

@@ -190,7 +189,7 @@ export function run() {
190189
}
191190

192191
const overwriteExisting = evaluateOverwriteAction("saved-a", activePayload, { "saved-a": { toolId: "palette-manager-v2", version: "v2", payloadJson: { old: true } } });
193-
if (overwriteExisting.message !== "Saved session overwritten." || overwriteExisting.library["saved-a"].payloadJson?.ok !== true) {
192+
if (overwriteExisting.message !== "Saved session 'saved-a' overwritten with current workspace state." || overwriteExisting.library["saved-a"].payloadJson?.ok !== true) {
194193
failures.push("Overwrite existing entry should succeed.");
195194
}
196195

@@ -200,7 +199,7 @@ export function run() {
200199
}
201200

202201
const loadExisting = evaluateLoadAction("saved-a", { "saved-a": activePayload });
203-
if (loadExisting.message !== "Saved session loaded." || !loadExisting.loaded) {
202+
if (loadExisting.message !== "Loaded 'saved-a' into the current workspace." || !loadExisting.loaded) {
204203
failures.push("Load existing entry should succeed.");
205204
}
206205

‎tools/workspace-v2/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ <h2>Share Session Link</h2>
5959
<h2>Session Library</h2>
6060
<label for="workspaceV2SessionName">New Session ID (Save Session)</label>
6161
<input id="workspaceV2SessionName" type="text" placeholder="session-id" />
62-
<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>
62+
<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 replaces this saved session with what you are currently working on. Delete removes the saved copy only.</p>
6363
<div>
6464
<button id="workspaceV2SaveSessionButton" type="button">Save Session</button>
6565
<button id="workspaceV2OverwriteSessionButton" type="button" hidden>Overwrite Session</button>

0 commit comments

Comments
 (0)