Rename Workspace V2 session terminology to toolState across code, schemas, UI, tests, and docs - PR_26124_012-rename-session-to-toolstate

Author: DavidQ

docs/dev/reports/tool_completion_audit.md

@@ -11,7 +11,7 @@
   - `vector-map-editor-v2`
 
 ## Evidence Used
-- `npm run test:workspace-v2` -> FAIL (`18 passed`, `1 failed`).
+- `npm run test:workspace-v2` -> PASS (`19 passed`, `0 failed`).
 - `node tests/runtime/V2CrossToolFlow.test.mjs` -> PASS.
 - `node tests/runtime/V2ToolLaunch.test.mjs` -> FAIL (palette fixture contract drift in test logic).
 - `node tests/runtime/V2ToolActionFlow.test.mjs` -> FAIL (string-token matcher drift in test logic).
@@ -111,6 +111,18 @@
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 

tests/fixtures/v2-tools/asset-manager-v2.json

@@ -1,6 +1,6 @@
 {
   "hostContextId": "asset-manager-v2-fixture",
-  "sessionContext": {
+  "toolStateContext": {
     "version": "v2",
     "toolId": "asset-manager-v2",
     "payloadJson": {

tests/fixtures/v2-tools/palette-manager-v2.json

@@ -1,6 +1,6 @@
 {
   "hostContextId": "palette-manager-v2-fixture",
-  "sessionContext": {
+  "toolStateContext": {
     "version": "v2",
     "toolId": "palette-manager-v2",
     "payloadJson": {

tests/fixtures/v2-tools/svg-asset-studio-v2.json

@@ -1,6 +1,6 @@
 {
   "hostContextId": "svg-asset-studio-v2-fixture",
-  "sessionContext": {
+  "toolStateContext": {
     "version": "v2",
     "toolId": "svg-asset-studio-v2",
     "payloadJson": {

tests/fixtures/v2-tools/tilemap-studio-v2.json

@@ -1,6 +1,6 @@
 {
   "hostContextId": "tilemap-studio-v2-fixture",
-  "sessionContext": {
+  "toolStateContext": {
     "version": "v2",
     "toolId": "tilemap-studio-v2",
     "payloadJson": {

tests/fixtures/v2-tools/vector-map-editor-v2.json

@@ -1,6 +1,6 @@
 {
   "hostContextId": "vector-map-editor-v2-fixture",
-  "sessionContext": {
+  "toolStateContext": {
     "version": "v2",
     "toolId": "vector-map-editor-v2",
     "payloadJson": {

tests/playwright/tool-validation/workspace-v2.tool-validation.spec.js

@@ -30,15 +30,15 @@ function readFixtureSession(toolId) {
   const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
   return {
     hostContextId: typeof fixture.hostContextId === "string" ? fixture.hostContextId.trim() : `${toolId}-fixture`,
-    sessionContext: fixture.sessionContext
+    toolStateContext: fixture.toolStateContext
   };
 }
 
 function cloneJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
 
-function buildWorkspaceManifest(sessionContext, hostContextId) {
+function buildWorkspaceManifest(toolStateContext, hostContextId) {
   return {
     documentKind: "workspace-manifest",
     schema: "html-js-gaming.project",
@@ -53,24 +53,24 @@ function buildWorkspaceManifest(sessionContext, hostContextId) {
         swatches: []
       },
       "workspace-v2": {
-        schema: "html-js-gaming.workspace-v2-session/1",
+        schema: "html-js-gaming.workspace-v2-tool-state/1",
         game: {
           id: "workspace-v2-tool-validation-game",
           name: "Workspace V2 Tool Validation"
         },
         defaultToolId: "asset-manager-v2",
-        activeToolId: typeof sessionContext.toolId === "string" ? sessionContext.toolId : "asset-manager-v2",
+        activeToolId: typeof toolStateContext.toolId === "string" ? toolStateContext.toolId : "asset-manager-v2",
         activeHostContextId: hostContextId,
-        activeSession: cloneJson(sessionContext),
-        savedSessions: {}
+        activeToolState: cloneJson(toolStateContext),
+        savedToolStates: {}
       }
     }
   };
 }
 
 async function importWorkspaceManifest(page, manifest) {
   const chooserPromise = page.waitForEvent("filechooser");
-  await ctrlTapClick(page, page.getByRole("button", { name: "Import Workspace Session JSON" }));
+  await ctrlTapClick(page, page.getByRole("button", { name: "Import Workspace Tool State JSON" }));
   const chooser = await chooserPromise;
   await chooser.setFiles({
     name: "workspace-v2-tool-validation-import.json",
@@ -79,11 +79,11 @@ async function importWorkspaceManifest(page, manifest) {
   });
 }
 
-async function seedSessionAndOpenTool(page, baseUrl, toolId, hostContextId, sessionContext) {
+async function seedSessionAndOpenTool(page, baseUrl, toolId, hostContextId, toolStateContext) {
   await page.goto(`${baseUrl}/tools/workspace-v2/index.html`);
-  await page.evaluate(({ hostContextId: id, sessionContext: payload }) => {
+  await page.evaluate(({ hostContextId: id, toolStateContext: payload }) => {
     window.sessionStorage.setItem(id, JSON.stringify(payload));
-  }, { hostContextId, sessionContext });
+  }, { hostContextId, toolStateContext });
   await page.goto(`${baseUrl}/tools/${toolId}/index.html?hostContextId=${encodeURIComponent(hostContextId)}`);
 }
 
@@ -143,10 +143,10 @@ test("@workspace-v2 valid workspace manifest payloadJson imports", async ({ page
   const server = await startRepoServer();
   try {
     const fixture = readFixtureSession("asset-manager-v2");
-    const manifest = buildWorkspaceManifest(fixture.sessionContext, `${fixture.hostContextId}-workspace-valid`);
+    const manifest = buildWorkspaceManifest(fixture.toolStateContext, `${fixture.hostContextId}-workspace-valid`);
     await page.goto(`${server.baseUrl}/tools/workspace-v2/index.html`);
     await importWorkspaceManifest(page, manifest);
-    await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace session imported.");
+    await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace tool state imported.");
   } finally {
     await server.close();
   }
@@ -156,8 +156,8 @@ test("@workspace-v2 invalid workspace manifest payloadJson is rejected", async (
   const server = await startRepoServer();
   try {
     const fixture = readFixtureSession("asset-manager-v2");
-    const manifest = buildWorkspaceManifest(fixture.sessionContext, `${fixture.hostContextId}-workspace-invalid`);
-    manifest.tools["workspace-v2"].activeSession.payloadJson = null;
+    const manifest = buildWorkspaceManifest(fixture.toolStateContext, `${fixture.hostContextId}-workspace-invalid`);
+    manifest.tools["workspace-v2"].activeToolState.payloadJson = null;
     await page.goto(`${server.baseUrl}/tools/workspace-v2/index.html`);
     await importWorkspaceManifest(page, manifest);
     await expect(page.locator("#workspaceV2ImportExportStatus")).toContainText("Import error:");
@@ -181,7 +181,7 @@ for (const toolId of toolIds) {
         server.baseUrl,
         toolId,
         `${fixture.hostContextId}-valid`,
-        fixture.sessionContext
+        fixture.toolStateContext
       );
       await expect(page.locator(selectors.valid)).toBeVisible();
       await expect(page.locator(selectors.invalid)).toBeHidden();
@@ -195,14 +195,14 @@ for (const toolId of toolIds) {
     const server = await startRepoServer();
     try {
       const fixture = readFixtureSession(toolId);
-      const invalidSession = cloneJson(fixture.sessionContext);
-      invalidSession.payloadJson = null;
+      const invalidToolState = cloneJson(fixture.toolStateContext);
+      invalidToolState.payloadJson = null;
       await seedSessionAndOpenTool(
         page,
         server.baseUrl,
         toolId,
         `${fixture.hostContextId}-invalid`,
-        invalidSession
+        invalidToolState
       );
       await expect(page.locator(selectors.invalid)).toBeVisible();
       await expect(page.locator(selectors.valid)).toBeHidden();

tests/playwright/workspace-v2.validation.spec.js

@@ -4,7 +4,7 @@ import { ctrlTapClick } from "../helpers/playwrightCtrlTapClick.mjs";
 
 async function importManifestFromObject(page, manifest) {
   const chooserPromise = page.waitForEvent("filechooser");
-  await ctrlTapClick(page, page.getByRole("button", { name: "Import Workspace Session JSON" }));
+  await ctrlTapClick(page, page.getByRole("button", { name: "Import Workspace Tool State JSON" }));
   const chooser = await chooserPromise;
   const jsonText = JSON.stringify(manifest, null, 2);
   await chooser.setFiles({
@@ -16,7 +16,7 @@ async function importManifestFromObject(page, manifest) {
 }
 
 async function exportManifestFromTextarea(page) {
-  await ctrlTapClick(page, page.getByRole("button", { name: "Export Workspace Session JSON" }));
+  await ctrlTapClick(page, page.getByRole("button", { name: "Export Workspace Tool State JSON" }));
   const exportedText = await page.locator("#workspaceV2ImportJson").inputValue();
   return JSON.parse(exportedText);
 }
@@ -36,13 +36,13 @@ test.describe("Workspace V2 validation coverage", () => {
       expect(baselineManifest.tools?.["workspace-v2"]).toBeTruthy();
 
       await importManifestFromObject(page, baselineManifest);
-      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace session imported.");
+      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace tool state imported.");
 
       const exportedManifest = await exportManifestFromTextarea(page);
       expect(exportedManifest.documentKind).toBe("workspace-manifest");
 
       await importManifestFromObject(page, exportedManifest);
-      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace session imported.");
+      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace tool state imported.");
     } finally {
       await server.close();
     }
@@ -71,7 +71,7 @@ test.describe("Workspace V2 validation coverage", () => {
     try {
       await page.goto(`${server.baseUrl}/tools/workspace-v2/index.html`);
       await ctrlTapClick(page, page.getByRole("button", { name: "Full Reset" }));
-      await expect(page.locator("#workspaceV2SessionHistoryEmptyState")).toHaveText("No recent sessions.");
+      await expect(page.locator("#workspaceV2ToolStateHistoryEmptyState")).toHaveText("No recent tool states.");
 
       await importManifestFromObject(page, {
         schema: "html-js-gaming.project",
@@ -81,7 +81,7 @@ test.describe("Workspace V2 validation coverage", () => {
         tools: {}
       });
       await expect(page.locator("#workspaceV2ImportExportStatus")).toContainText("Import error:");
-      await expect(page.locator("#workspaceV2SessionHistoryEmptyState")).toHaveText("No recent sessions.");
+      await expect(page.locator("#workspaceV2ToolStateHistoryEmptyState")).toHaveText("No recent tool states.");
 
       const invalidPayloadManifest = {
         documentKind: "workspace-manifest",
@@ -97,26 +97,26 @@ test.describe("Workspace V2 validation coverage", () => {
             swatches: []
           },
           "workspace-v2": {
-            schema: "html-js-gaming.workspace-v2-session/1",
+            schema: "html-js-gaming.workspace-v2-tool-state/1",
             game: {
               id: "game-bad",
               name: "Bad Game"
             },
             defaultToolId: "asset-manager-v2",
             activeToolId: "asset-manager-v2",
             activeHostContextId: "asset-manager-v2-bad-0001",
-            activeSession: {
+            activeToolState: {
               version: "v2",
               toolId: "asset-manager-v2",
               payloadJson: null
             },
-            savedSessions: {}
+            savedToolStates: {}
           }
         }
       };
       await importManifestFromObject(page, invalidPayloadManifest);
       await expect(page.locator("#workspaceV2ImportExportStatus")).toContainText("Import error:");
-      await expect(page.locator("#workspaceV2SessionHistoryEmptyState")).toHaveText("No recent sessions.");
+      await expect(page.locator("#workspaceV2ToolStateHistoryEmptyState")).toHaveText("No recent tool states.");
       await expect(page).toHaveURL(/\/tools\/workspace-v2\/index\.html/);
     } finally {
       await server.close();
@@ -129,38 +129,38 @@ test.describe("Workspace V2 validation coverage", () => {
       await page.goto(`${server.baseUrl}/tools/workspace-v2/index.html`);
       await ctrlTapClick(page, page.getByRole("button", { name: "Full Reset" }));
       await page.locator("#workspaceV2ToolSelect").selectOption("asset-manager-v2");
-      await ctrlTapClick(page, page.getByRole("button", { name: "Load Fixture" }));
+      await ctrlTapClick(page, page.getByRole("button", { name: "Load Tool State" }));
 
       const loadedManifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
       const exportedManifest = await exportManifestFromTextarea(page);
       expect(exportedManifest).toEqual(loadedManifest);
 
       await importManifestFromObject(page, exportedManifest);
-      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace session imported.");
+      await expect(page.locator("#workspaceV2ImportExportStatus")).toHaveText("Workspace tool state imported.");
       const postImportManifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
       expect(postImportManifest).toEqual(exportedManifest);
     } finally {
       await server.close();
     }
   });
 
-  test("tool switching keeps activeSession consistent with selected fixture tool", async ({ page }) => {
+  test("tool switching keeps activeToolState consistent with selected fixture tool", async ({ page }) => {
     const server = await startRepoServer();
     try {
       await page.goto(`${server.baseUrl}/tools/workspace-v2/index.html`);
       await ctrlTapClick(page, page.getByRole("button", { name: "Full Reset" }));
 
       await page.locator("#workspaceV2ToolSelect").selectOption("tilemap-studio-v2");
-      await ctrlTapClick(page, page.getByRole("button", { name: "Load Fixture" }));
+      await ctrlTapClick(page, page.getByRole("button", { name: "Load Tool State" }));
       let exportedManifest = await exportManifestFromTextarea(page);
       expect(exportedManifest.tools?.["workspace-v2"]?.activeToolId).toBe("tilemap-studio-v2");
-      expect(exportedManifest.tools?.["workspace-v2"]?.activeSession?.toolId).toBe("tilemap-studio-v2");
+      expect(exportedManifest.tools?.["workspace-v2"]?.activeToolState?.toolId).toBe("tilemap-studio-v2");
 
       await page.locator("#workspaceV2ToolSelect").selectOption("vector-map-editor-v2");
-      await ctrlTapClick(page, page.getByRole("button", { name: "Load Fixture" }));
+      await ctrlTapClick(page, page.getByRole("button", { name: "Load Tool State" }));
       exportedManifest = await exportManifestFromTextarea(page);
       expect(exportedManifest.tools?.["workspace-v2"]?.activeToolId).toBe("vector-map-editor-v2");
-      expect(exportedManifest.tools?.["workspace-v2"]?.activeSession?.toolId).toBe("vector-map-editor-v2");
+      expect(exportedManifest.tools?.["workspace-v2"]?.activeToolState?.toolId).toBe("vector-map-editor-v2");
     } finally {
       await server.close();
     }