Add explicit Promote to Tools actions for active and saved Workspace V2 toolStates - PR_26124_017-promote-selected-toolstate-to-tools

Author: DavidQ

docs/dev/reports/PR_26124_017_explicit_promote_to_tools_report.md

@@ -0,0 +1,33 @@
+# PR_26124_017
+
+## Scope
+- `tools/workspace-v2/index.html`
+- `tools/workspace-v2/index.js`
+- `tests/ui/workspace-v2.asset-manager.spec.js`
+- `tests/playwright/workspace-v2.validation.spec.js`
+
+## Changes
+- Added explicit active promotion action in Workspace V2 Producer:
+  - `Promote Active Tool State to Tools`
+- Added explicit saved-entry promotion action per Tool State Library row:
+  - `Promote to Tools`
+- Promotion behavior:
+  - validates selected tool state
+  - reads `toolState.toolId`
+  - reads `toolState.payloadJson`
+  - writes cloned payload into `tools[toolId]` in workspace manifest JSON
+- Guard behavior:
+  - blocks `palette-manager-v2` promotion
+  - blocks invalid tool states
+  - keeps `tools.workspace-v2` and `tools.palette-browser` intact
+  - keeps `activeToolState` and `savedToolStates` unchanged
+  - no auto-promotion on save/export
+
+## Validation
+- `node --check tools/workspace-v2/index.js` -> pass
+- `node --check tests/ui/workspace-v2.asset-manager.spec.js` -> pass
+- `node --check tests/playwright/workspace-v2.validation.spec.js` -> pass
+- `npm run test:workspace-v2` -> pass (`20 passed`, `0 failed`)
+
+## Notes
+- Full samples smoke was skipped because this PR is limited to Workspace V2 tool-state promotion actions and Playwright coverage updates.

docs/dev/reports/tool_completion_audit.md

@@ -11,7 +11,7 @@
   - `vector-map-editor-v2`
 
 ## Evidence Used
-- `npm run test:workspace-v2` -> PASS (`19 passed`, `0 failed`).
+- `npm run test:workspace-v2` -> PASS (`20 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).
@@ -154,6 +154,24 @@
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 

tests/playwright.zip

@@ -176,12 +176,46 @@ test.describe("Workspace V2 validation coverage", () => {
       let manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
       expect(manifest.tools?.["workspace-v2"]?.activeToolId).toBe("tilemap-studio-v2");
       expect(manifest.tools?.["workspace-v2"]?.activeToolState?.toolId).toBe("tilemap-studio-v2");
+      expect(Object.prototype.hasOwnProperty.call(manifest.tools || {}, "tilemap-studio-v2")).toBe(false);
 
       await page.locator("#workspaceV2ToolSelect").selectOption("vector-map-editor-v2");
       await page.locator("#workspaceV2LoadFixtureButton").click();
       manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
       expect(manifest.tools?.["workspace-v2"]?.activeToolId).toBe("vector-map-editor-v2");
       expect(manifest.tools?.["workspace-v2"]?.activeToolState?.toolId).toBe("vector-map-editor-v2");
+      expect(Object.prototype.hasOwnProperty.call(manifest.tools || {}, "vector-map-editor-v2")).toBe(false);
+    } finally {
+      await server.close();
+    }
+  });
+
+  test("promote to tools is explicit for active and saved tool states", 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 page.locator("#workspaceV2LoadFixtureButton").click();
+      await page.locator("#workspaceV2ToolStateName").fill("tile-state-a");
+      await page.locator("#workspaceV2SaveToolStateButton").click();
+
+      let manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
+      expect(Object.prototype.hasOwnProperty.call(manifest.tools || {}, "tilemap-studio-v2")).toBe(false);
+
+      await page.getByRole("button", { name: "Promote Active Tool State to Tools" }).click();
+      manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
+      expect(manifest.tools?.["tilemap-studio-v2"]?.tileMapDocument).toBeTruthy();
+
+      await page.locator("#workspaceV2ToolSelect").selectOption("vector-map-editor-v2");
+      await page.locator("#workspaceV2LoadFixtureButton").click();
+      manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
+      expect(Object.prototype.hasOwnProperty.call(manifest.tools || {}, "vector-map-editor-v2")).toBe(false);
+
+      await page.getByRole("button", { name: "Promote to Tools" }).first().click();
+      manifest = JSON.parse(await page.locator("#workspaceV2ImportJson").inputValue());
+      expect(manifest.tools?.["tilemap-studio-v2"]?.tileMapDocument).toBeTruthy();
+      expect(Object.prototype.hasOwnProperty.call(manifest.tools || {}, "vector-map-editor-v2")).toBe(false);
     } finally {
       await server.close();
     }

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

@@ -67,6 +67,12 @@ test("workspace v2 launches asset manager and add/remove is reflected in export"
     await ctrlTapClick(page, page.getByRole("button", { name: /Back to Workspace V2/ }));
     await expect(page).toHaveURL(/\/tools\/workspace-v2\/index\.html/);
     await ctrlTapClick(page, page.getByRole("button", { name: "Export Workspace Tool State JSON" }));
+    const manifestBeforePromoteText = await page.locator("#workspaceV2ImportJson").inputValue();
+    const manifestBeforePromote = JSON.parse(manifestBeforePromoteText);
+    expect(Object.prototype.hasOwnProperty.call(manifestBeforePromote.tools || {}, "asset-manager-v2")).toBe(false);
+    await ctrlTapClick(page, page.getByRole("button", { name: "Promote Active Tool State to Tools" }));
+    await expect(page.locator("#workspaceV2Status")).toContainText("promoted to tools.asset-manager-v2");
+    await ctrlTapClick(page, page.getByRole("button", { name: "Export Workspace Tool State JSON" }));
     const exportedJsonText = await page.locator("#workspaceV2ImportJson").inputValue();
     const exported = JSON.parse(exportedJsonText);
     const entries = exported?.tools?.["workspace-v2"]?.activeToolState?.payloadJson?.assetCatalog?.entries;
@@ -79,9 +85,15 @@ test("workspace v2 launches asset manager and add/remove is reflected in export"
     expect(exported.tools?.["workspace-v2"]?.activeToolState?.toolId).toBe("asset-manager-v2");
     expect(entries.some((entry) => entry?.id === "asset-001")).toBe(true);
     expect(entries.some((entry) => entry?.id === "asset-002")).toBe(false);
+    const promotedEntries = exported?.tools?.["asset-manager-v2"]?.assetCatalog?.entries;
+    if (!Array.isArray(promotedEntries)) {
+      throw new Error("Exported manifest is missing tools.asset-manager-v2.assetCatalog.entries after promotion.");
+    }
+    expect(promotedEntries.some((entry) => entry?.id === "asset-001")).toBe(true);
+    expect(promotedEntries.some((entry) => entry?.id === "asset-002")).toBe(false);
     expect(Object.prototype.hasOwnProperty.call(exported, "workspaceSession")).toBe(false);
     expect(Object.prototype.hasOwnProperty.call(exported, "games")).toBe(false);
-    expect(Object.prototype.hasOwnProperty.call(exported.tools || {}, "asset-manager-v2")).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(exported.tools || {}, "asset-manager-v2")).toBe(true);
     const exportedString = JSON.stringify(exported);
     expect(exportedString.includes("selectedAssetId")).toBe(false);
     expect(exportedString.includes("assetBrowserV2Detail")).toBe(false);

tests/ui/workspace-v2.asset-manager.spec.js

@@ -29,6 +29,7 @@ <h2>Producer</h2>
         <div>
           <button id="workspaceV2LoadFixtureButton" type="button">Load Tool State</button>
           <button id="workspaceV2LaunchButton" type="button">Create & Open Tool State</button>
+          <button id="workspaceV2PromoteActiveToolStateButton" type="button">Promote Active Tool State to Tools</button>
         </div>
       </section>
 

tools/workspace-v2.zip

@@ -22,6 +22,7 @@ class WorkspaceV2ToolStateProducer {
     this.backButton = document.getElementById("workspaceV2BackButton");
     this.loadFixtureButton = document.getElementById("workspaceV2LoadFixtureButton");
     this.launchButton = document.getElementById("workspaceV2LaunchButton");
+    this.promoteActiveToolStateButton = document.getElementById("workspaceV2PromoteActiveToolStateButton");
     this.openAssetManagerButton = document.getElementById("workspaceV2OpenAssetManagerButton");
     this.importJsonNode = document.getElementById("workspaceV2ImportJson");
     this.importFileNode = document.getElementById("workspaceV2ImportFile");
@@ -101,6 +102,9 @@ class WorkspaceV2ToolStateProducer {
     this.launchButton.addEventListener("click", () => {
       this.createToolStateAndLaunch();
     });
+    this.promoteActiveToolStateButton.addEventListener("click", () => {
+      this.promoteActiveToolStateToWorkspaceTools();
+    });
     this.openAssetManagerButton.addEventListener("click", () => {
       this.openAssetManagerFromWorkspace();
     });
@@ -1275,6 +1279,62 @@ class WorkspaceV2ToolStateProducer {
     return this.readActiveToolStatePayloadForLibraryActions();
   }
 
+  validateToolStatePromotionPayload(toolStatePayload, toolStatePath) {
+    if (!this.isValidToolStatePayload(toolStatePayload)) {
+      return { ok: false, message: `${toolStatePath} is invalid.`, toolId: "", payloadJson: null };
+    }
+    const payloadValidation = this.validateWorkspaceToolStatePayload(toolStatePayload, toolStatePath);
+    if (!payloadValidation.ok) {
+      return { ok: false, message: payloadValidation.message, toolId: "", payloadJson: null };
+    }
+    const toolId = typeof toolStatePayload.toolId === "string" ? toolStatePayload.toolId.trim() : "";
+    if (!toolId) {
+      return { ok: false, message: `${toolStatePath}.toolId is required for promotion.`, toolId: "", payloadJson: null };
+    }
+    if (toolId === "palette-manager-v2") {
+      return { ok: false, message: "Promotion blocked. palette-manager-v2 cannot be promoted to tools; palette is workspace-owned at tools.palette-browser.", toolId: "", payloadJson: null };
+    }
+    if (!toolStatePayload.payloadJson || typeof toolStatePayload.payloadJson !== "object" || Array.isArray(toolStatePayload.payloadJson)) {
+      return { ok: false, message: `${toolStatePath}.payloadJson must be an object for promotion.`, toolId: "", payloadJson: null };
+    }
+    return {
+      ok: true,
+      message: "",
+      toolId,
+      payloadJson: this.cloneToolStateValue(toolStatePayload.payloadJson)
+    };
+  }
+
+  promoteToolStatePayloadToWorkspaceTools(toolStatePayload, toolStatePath, successPrefix) {
+    const promotionValidation = this.validateToolStatePromotionPayload(toolStatePayload, toolStatePath);
+    if (!promotionValidation.ok) {
+      this.statusNode.textContent = promotionValidation.message;
+      return false;
+    }
+    this.workspaceImportedToolEntries[promotionValidation.toolId] = promotionValidation.payloadJson;
+    if (!this.syncWorkspaceManifestTextarea()) {
+      this.statusNode.textContent = "Promotion failed. Workspace manifest sync failed.";
+      return false;
+    }
+    this.renderWorkspaceToolsSummary();
+    this.statusNode.textContent = `${successPrefix} promoted to tools.${promotionValidation.toolId}.`;
+    return true;
+  }
+
+  promoteActiveToolStateToWorkspaceTools() {
+    const activeToolState = this.readActiveToolStatePayloadForLibraryActions();
+    if (!this.isValidToolStatePayload(activeToolState)) {
+      this.statusNode.textContent = "Promotion blocked. No active tool state is available.";
+      return;
+    }
+    const activeToolId = typeof activeToolState.toolId === "string" ? activeToolState.toolId.trim() : "";
+    this.promoteToolStatePayloadToWorkspaceTools(
+      activeToolState,
+      "tools.workspace-v2.activeToolState",
+      `Active tool state '${activeToolId || "unknown"}'`
+    );
+  }
+
   readToolStatePayloadFromRecentToolStateId(toolStateId) {
     if (typeof toolStateId !== "string" || !toolStateId.trim()) {
       return null;
@@ -1700,6 +1760,7 @@ class WorkspaceV2ToolStateProducer {
       const idCode = document.createElement("code");
       const copyIdButton = document.createElement("button");
       const useInLibraryButton = document.createElement("button");
+      const promoteToToolsButton = document.createElement("button");
       const loadButton = document.createElement("button");
       const overwriteButton = document.createElement("button");
       const deleteSavedButton = document.createElement("button");
@@ -1726,6 +1787,11 @@ class WorkspaceV2ToolStateProducer {
       useInLibraryButton.addEventListener("click", () => {
         this.useSavedToolStateIdInLibraryInput(toolStateName);
       });
+      promoteToToolsButton.type = "button";
+      promoteToToolsButton.textContent = "Promote to Tools";
+      promoteToToolsButton.addEventListener("click", () => {
+        this.promoteSavedToolStateById(toolStateName);
+      });
       loadButton.type = "button";
       loadButton.textContent = "Load";
       loadButton.disabled = paletteRowLocked;
@@ -1743,7 +1809,7 @@ class WorkspaceV2ToolStateProducer {
       deleteSavedButton.addEventListener("click", () => {
         this.deleteSavedToolStateById(toolStateName);
       });
-      item.append(label, idLine, copyIdButton, useInLibraryButton, loadButton, overwriteButton, deleteSavedButton);
+      item.append(label, idLine, copyIdButton, useInLibraryButton, promoteToToolsButton, loadButton, overwriteButton, deleteSavedButton);
       this.toolStateListNode.appendChild(item);
     });
     this.renderToolStateDiffInputs();
@@ -1779,6 +1845,31 @@ class WorkspaceV2ToolStateProducer {
     this.setLibraryStatus(`Saved tool state ID ready for Diff/Merge and Library actions: ${toolStateId.trim()}`);
   }
 
+  promoteSavedToolStateById(toolStateId) {
+    if (typeof toolStateId !== "string" || !toolStateId.trim()) {
+      this.setLibraryStatus("Promotion blocked. Enter a saved tool state ID before promoting.");
+      return;
+    }
+    const library = this.readToolStateLibrary();
+    if (library === null) {
+      return;
+    }
+    if (!Object.prototype.hasOwnProperty.call(library, toolStateId.trim())) {
+      this.setLibraryStatus("Promotion blocked. Saved tool state not found.");
+      return;
+    }
+    const savedToolStatePayload = library[toolStateId.trim()];
+    const promoted = this.promoteToolStatePayloadToWorkspaceTools(
+      savedToolStatePayload,
+      `tools.workspace-v2.savedToolStates.${toolStateId.trim()}`,
+      `Saved tool state '${toolStateId.trim()}'`
+    );
+    if (!promoted) {
+      return;
+    }
+    this.setLibraryStatus(`Saved tool state '${toolStateId.trim()}' promoted to tools.`);
+  }
+
   loadSavedToolStateById(toolStateId) {
     if (typeof toolStateId !== "string" || !toolStateId.trim()) {
       this.setLibraryStatus("Enter a saved tool state ID before loading.");