Add launch-mode-specific NAV behavior to first-class tool template - PR_26126_068-tool-template-launch-mode-nav

Author: DavidQ

docs/dev/reports/playwright_v8_coverage_report.txt

@@ -13,12 +13,15 @@ Note: coverage entries are aggregated across every page/tool where coverageRepor
 Exercised tool entry points detected:
 (84%) Preview Generator V2 - exercised 19 runtime JS files
 (49%) Palette Manager - exercised 12 runtime JS files
-(89%) First-Class Tool Starter Template - exercised 10 runtime JS files
+(84%) First-Class Tool Starter Template - exercised 10 runtime JS files
 (0%) Workspace V2 - not exercised by this Playwright run
 (0%) Workspace Manager - not exercised by this Playwright run
 
 Changed runtime JS files covered:
-(100%) none changed - no changed runtime JS files
+(50%) tools/templates/first-class-tool-starter/js/ToolStarterApp.js - executed lines 98/98; executed functions 8/16
+(88%) tools/templates/first-class-tool-starter/js/controls/SourceInputControl.js - executed lines 33/33; executed functions 7/8
+(100%) tools/templates/first-class-tool-starter/js/bootstrap.js - executed lines 48/48; executed functions 4/4
+(100%) tools/templates/first-class-tool-starter/js/controls/ActionNavControl.js - executed lines 51/51; executed functions 5/5
 
 Files with executed line/function counts where available:
 (2%) src/engine/input/ActionInputService.js - executed lines 397/397; executed functions 1/51
@@ -85,6 +88,7 @@ Files with executed line/function counts where available:
 (50%) tools/common/PaletteUsageService.js - executed lines 5/5; executed functions 1/2
 (50%) tools/palette-manager-v2/main.js - executed lines 88/88; executed functions 3/6
 (50%) tools/palette-manager-v2/modules/PaletteHistoryStack.js - executed lines 54/54; executed functions 5/10
+(50%) tools/templates/first-class-tool-starter/js/ToolStarterApp.js - executed lines 98/98; executed functions 8/16
 (50%) tools/toolRegistry.js - executed lines 425/425; executed functions 4/8
 (55%) tools/palette-manager-v2/modules/SwatchRow.js - executed lines 115/115; executed functions 6/11
 (56%) src/engine/logging/Logger.js - executed lines 56/56; executed functions 5/9
@@ -97,7 +101,6 @@ Files with executed line/function counts where available:
 (65%) tools/palette-manager-v2/controls/SourcePaletteBrowserControl.js - executed lines 121/121; executed functions 15/23
 (67%) src/shared/number/numberUtils.js - executed lines 14/14; executed functions 2/3
 (67%) tools/preview-generator-v2/PreviewGeneratorV2ShellControl.js - executed lines 117/117; executed functions 8/12
-(67%) tools/templates/first-class-tool-starter/js/ToolStarterApp.js - executed lines 69/69; executed functions 8/12
 (71%) tools/palette-manager-v2/controls/PaletteValidationErrorControl.js - executed lines 30/30; executed functions 5/7
 (73%) src/engine/theme/mount-shared-header.js - executed lines 143/143; executed functions 8/11
 (75%) src/engine/core/FixedTicker.js - executed lines 36/36; executed functions 3/4
@@ -146,15 +149,20 @@ Files with executed line/function counts where available:
 (100%) tools/preview-generator-v2/PreviewGeneratorV2Logger.js - executed lines 19/19; executed functions 5/5
 (100%) tools/preview-generator-v2/PreviewGeneratorV2RepoAccess.js - executed lines 21/21; executed functions 5/5
 (100%) tools/preview-generator-v2/PreviewGeneratorV2Ui.js - executed lines 48/48; executed functions 9/9
-(100%) tools/templates/first-class-tool-starter/js/bootstrap.js - executed lines 42/42; executed functions 4/4
+(100%) tools/templates/first-class-tool-starter/js/bootstrap.js - executed lines 48/48; executed functions 4/4
 (100%) tools/templates/first-class-tool-starter/js/controls/AccordionSection.js - executed lines 27/27; executed functions 5/5
-(100%) tools/templates/first-class-tool-starter/js/controls/ActionNavControl.js - executed lines 16/16; executed functions 4/4
+(100%) tools/templates/first-class-tool-starter/js/controls/ActionNavControl.js - executed lines 51/51; executed functions 5/5
 (100%) tools/templates/first-class-tool-starter/js/controls/InspectorControl.js - executed lines 8/8; executed functions 3/3
 (100%) tools/templates/first-class-tool-starter/js/controls/PreviewPanelControl.js - executed lines 23/23; executed functions 5/5
 (100%) tools/templates/first-class-tool-starter/js/services/ToolStateSerializer.js - executed lines 13/13; executed functions 3/3
 
 Uncovered or low-coverage changed JS files:
-(100%) none changed - no changed runtime JS files
+(100%) none - no low-coverage changed runtime JS files
 
 Changed JS files considered:
-(100%) none - no changed JS files
+(0%) tests/playwright/PreviewGeneratorV2Baseline.spec.mjs - changed JS file not collected as browser runtime coverage
+(0%) tools/templates/first-class-tool-starter/tests/playwright/FirstClassToolStarter.spec.mjs - changed JS file not collected as browser runtime coverage
+(50%) tools/templates/first-class-tool-starter/js/ToolStarterApp.js - changed JS file with browser V8 coverage
+(88%) tools/templates/first-class-tool-starter/js/controls/SourceInputControl.js - changed JS file with browser V8 coverage
+(100%) tools/templates/first-class-tool-starter/js/bootstrap.js - changed JS file with browser V8 coverage
+(100%) tools/templates/first-class-tool-starter/js/controls/ActionNavControl.js - changed JS file with browser V8 coverage

docs/dev/reports/tool_template_launch_mode_nav.txt

@@ -0,0 +1,56 @@
+PR_26126_068-tool-template-launch-mode-nav
+
+Scope:
+- Updated the official first-class tool starter at tools/templates/first-class-tool-starter/.
+- Updated existing Playwright coverage for the starter launch-mode NAV behavior.
+- No live tools, samples, schemas, roadmap, start_of_day folders, or tools/shared files were modified.
+
+Changes:
+- Added separate tool-mode and workspace-mode NAV sections.
+- Default launch mode is tool mode.
+- ?launch=workspace switches visibility to the workspace NAV.
+- Tool NAV uses class tool-starter__tool__menu, aria-label Tool actions, and buttons:
+  - Export
+  - Copy JSON
+  - Export toolState
+- Workspace NAV uses class tool-starter__workspace__menu, aria-label Workspace actions, and buttons:
+  - Import manifest
+  - Copy manifest
+  - Export manifest
+- Added hidden-state CSS so only one NAV displays at a time.
+- Kept Preview Generator V2 color-match styling and src/engine/theme usage.
+- Preserved no tools/shared runtime dependency.
+- Preserved external CSS/JS only; no inline style block, inline script block, or inline event handlers were added.
+
+Validation:
+- node --check tools/templates/first-class-tool-starter/js/controls/ActionNavControl.js
+- node --check tools/templates/first-class-tool-starter/js/ToolStarterApp.js
+- node --check tools/templates/first-class-tool-starter/js/bootstrap.js
+- node --check tools/templates/first-class-tool-starter/js/controls/SourceInputControl.js
+- node --check tests/playwright/PreviewGeneratorV2Baseline.spec.mjs
+- node --check tools/templates/first-class-tool-starter/tests/playwright/FirstClassToolStarter.spec.mjs
+- rg check confirmed tools/templates/first-class-tool-starter/index.html has no inline style block, inline script block, or inline event handlers.
+- git diff --check
+- npm run test:workspace-v2
+- npx playwright test --config tools/templates/first-class-tool-starter/playwright.config.mjs --reporter=list
+
+Playwright impacted: Yes
+- This PR changes template UI controls/interactions and launch-mode state.
+- npm run test:workspace-v2 passed.
+- Template-local Playwright passed.
+
+Playwright behavior validated:
+- Official starter entry point defaults to tool NAV.
+- Official starter entry point with ?launch=workspace shows workspace NAV.
+- Only one launch-mode NAV is visible for each launch mode.
+- Tool and workspace NAV labels and button text match the required casing.
+- Duplicate button IDs are not present.
+- Existing starter accordion, required-field gating, primary action, and status clear behaviors still work.
+
+Manual test notes:
+- Open tools/templates/first-class-tool-starter/index.html and confirm only Tool actions is visible with Export, Copy JSON, and Export toolState.
+- Open tools/templates/first-class-tool-starter/index.html?launch=workspace and confirm only Workspace actions is visible with Import manifest, Copy manifest, and Export manifest.
+- The official starter path is tools/templates/first-class-tool-starter/index.html; tools/templates/README.md designates that folder as the starter entry point.
+
+Full samples smoke test:
+- Skipped. This PR only changes the first-class tool starter template and its targeted tests.

tests/playwright/PreviewGeneratorV2Baseline.spec.mjs

@@ -120,10 +120,10 @@ async function openPaletteManager(page) {
   return server;
 }
 
-async function openToolTemplate(page) {
+async function openToolTemplate(page, query = "") {
   const server = await startRepoServer();
   await coverageReporter.start(page);
-  await page.goto(`${server.baseUrl}/tools/templates/first-class-tool-starter/index.html`, { waitUntil: "networkidle" });
+  await page.goto(`${server.baseUrl}/tools/templates/first-class-tool-starter/index.html${query}`, { waitUntil: "networkidle" });
   return server;
 }
 
@@ -466,6 +466,18 @@ test.describe("Preview Generator V2 baseline", () => {
       await expect(page.locator("#shared-theme-header")).toBeAttached();
       await expect(page.locator("[data-tool-starter-header]")).toContainText("First-Class Tool Starter");
       await expect(page.locator("[data-tool-starter-summary]")).toHaveAttribute("data-tools-platform-summary-active", "1");
+      await expect(page.locator(".tool-starter__tool__menu")).toBeVisible();
+      await expect(page.locator(".tool-starter__tool__menu")).toHaveAttribute("aria-label", "Tool actions");
+      await expect(page.locator(".tool-starter__workspace__menu")).toBeHidden();
+      await expect(page.locator("#toolExportButton")).toHaveText("Export");
+      await expect(page.locator("#toolCopyJsonButton")).toHaveText("Copy JSON");
+      await expect(page.locator("#toolExportToolStateButton")).toHaveText("Export toolState");
+
+      const duplicateIds = await page.evaluate(() => {
+        const ids = [...document.querySelectorAll("[id]")].map((element) => element.id);
+        return ids.filter((id, index) => ids.indexOf(id) !== index);
+      });
+      expect(duplicateIds).toEqual([]);
 
       const sharedReferences = await page.evaluate(() => [
         ...document.querySelectorAll("script[src],link[href]")
@@ -482,17 +494,23 @@ test.describe("Preview Generator V2 baseline", () => {
 
       await expectAccordionToggles(page, "sourceInputContent");
 
-      const runButton = page.locator("#runToolButton");
-      await expect(runButton).toBeDisabled();
+      const exportButton = page.locator("#toolExportButton");
+      const copyJsonButton = page.locator("#toolCopyJsonButton");
+      const exportToolStateButton = page.locator("#toolExportToolStateButton");
+      await expect(exportButton).toBeDisabled();
+      await expect(copyJsonButton).toBeDisabled();
+      await expect(exportToolStateButton).toBeDisabled();
       await page.locator("#sourceInput").fill("starter value");
-      await expect(runButton).toBeEnabled();
-      await runButton.click();
+      await expect(exportButton).toBeEnabled();
+      await expect(copyJsonButton).toBeEnabled();
+      await expect(exportToolStateButton).toBeEnabled();
+      await exportButton.click();
       await expect(page.locator("#statusLog")).toHaveValue(/Processed source value/);
       await page.locator("#clearStatusButton").click();
       await expect(page.locator("#statusLog")).toHaveValue("");
 
       await page.locator("#sourceInput").fill("");
-      await expect(runButton).toBeDisabled();
+      await expect(exportButton).toBeDisabled();
       await expect(page.locator("#sourceValidationMessage")).toContainText("Input is required");
 
       expect(pageErrors).toEqual([]);
@@ -501,4 +519,26 @@ test.describe("Preview Generator V2 baseline", () => {
       await server.close();
     }
   });
+
+  test("launches first-class tool starter template in workspace nav mode", async ({ page }) => {
+    const server = await openToolTemplate(page, "?launch=workspace");
+    const pageErrors = [];
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    try {
+      await expect(page.locator(".tool-starter__tool__menu")).toBeHidden();
+      await expect(page.locator(".tool-starter__workspace__menu")).toBeVisible();
+      await expect(page.locator(".tool-starter__workspace__menu")).toHaveAttribute("aria-label", "Workspace actions");
+      await expect(page.locator("#workspaceImportManifestButton")).toHaveText("Import manifest");
+      await expect(page.locator("#workspaceCopyManifestButton")).toHaveText("Copy manifest");
+      await expect(page.locator("#workspaceExportManifestButton")).toHaveText("Export manifest");
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
 });

tools/templates/first-class-tool-starter/index.html

@@ -36,10 +36,16 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface</h2>
       </div>
     </details>
 
-    <nav class="tool-starter__menu" aria-label="Tool actions">
-      <button id="runToolButton" type="button">Run</button>
-      <button id="resetToolButton" type="button">Reset</button>
-      <button id="exportToolStateButton" type="button">Export toolState</button>
+    <nav class="tool-starter__menu tool-starter__tool__menu" aria-label="Tool actions" data-launch-mode-nav="tool">
+      <button id="toolExportButton" type="button">Export</button>
+      <button id="toolCopyJsonButton" type="button">Copy JSON</button>
+      <button id="toolExportToolStateButton" type="button">Export toolState</button>
+    </nav>
+
+    <nav class="tool-starter__menu tool-starter__workspace__menu" aria-label="Workspace actions" data-launch-mode-nav="workspace" hidden>
+      <button id="workspaceImportManifestButton" type="button">Import manifest</button>
+      <button id="workspaceCopyManifestButton" type="button">Copy manifest</button>
+      <button id="workspaceExportManifestButton" type="button">Export manifest</button>
     </nav>
 
     <main class="tool-starter app-shell" data-tool-id="first-class-tool-starter">
@@ -54,7 +60,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface</h2>
               <span>Source value</span>
               <input id="sourceInput" type="text" autocomplete="off" placeholder="Enter a value to process">
             </label>
-            <p id="sourceValidationMessage" class="tool-starter__hint">Input is required before Run can process.</p>
+            <p id="sourceValidationMessage" class="tool-starter__hint">Input is required before Export can process.</p>
           </div>
         </section>
 

tools/templates/first-class-tool-starter/js/ToolStarterApp.js

@@ -1,5 +1,5 @@
 export class ToolStarterApp {
-  constructor({ accordions, actionNav, inspector, preview, serializer, shell, sourceInput, statusLog }) {
+  constructor({ accordions, actionNav, inspector, preview, serializer, shell, sourceInput, statusLog, windowRef = window }) {
     this.accordions = accordions;
     this.actionNav = actionNav;
     this.inspector = inspector;
@@ -8,15 +8,21 @@ export class ToolStarterApp {
     this.shell = shell;
     this.sourceInput = sourceInput;
     this.statusLog = statusLog;
+    this.window = windowRef;
   }
 
   start() {
     this.shell.mount();
     this.accordions.forEach((accordion) => accordion.mount());
     this.actionNav.mount({
-      onExport: () => this.exportToolState(),
-      onReset: () => this.reset(),
-      onRun: () => this.run()
+      onToolCopyJson: () => {
+        void this.copyJson();
+      },
+      onToolExport: () => this.run(),
+      onToolExportToolState: () => this.exportToolState(),
+      onWorkspaceCopyManifest: () => this.statusLog.write("Copy manifest action ready for workspace wiring."),
+      onWorkspaceExportManifest: () => this.statusLog.write("Export manifest action ready for workspace wiring."),
+      onWorkspaceImportManifest: () => this.statusLog.write("Import manifest action ready for workspace wiring.")
     });
     this.sourceInput.mount({
       onChange: () => this.refreshActions()
@@ -66,11 +72,37 @@ export class ToolStarterApp {
     this.refreshActions();
   }
 
+  async copyJson() {
+    const validation = this.sourceInput.validate();
+    if (!validation.valid) {
+      this.statusLog.error(validation.message);
+      this.refreshActions();
+      return;
+    }
+
+    const toolState = this.serializer.createToolState({ sourceValue: validation.value });
+    this.inspector.showObject(toolState);
+    const json = JSON.stringify(toolState, null, 2);
+    if (typeof this.window.navigator?.clipboard?.writeText !== "function") {
+      this.statusLog.write("toolState JSON preview written to Output Summary. Clipboard API is unavailable.");
+      this.refreshActions();
+      return;
+    }
+
+    try {
+      await this.window.navigator.clipboard.writeText(json);
+      this.statusLog.write("toolState JSON copied.");
+    } catch (error) {
+      this.statusLog.error(`Copy JSON failed: ${error.message}`);
+    }
+    this.refreshActions();
+  }
+
   refreshActions() {
     const hasValue = this.sourceInput.hasValue();
     if (!hasValue) {
-      this.sourceInput.showMessage("Input is required before Run can process.", false);
+      this.sourceInput.showMessage("Input is required before Export can process.", false);
     }
-    this.actionNav.setRunEnabled(hasValue);
+    this.actionNav.setToolActionsEnabled(hasValue);
   }
 }

tools/templates/first-class-tool-starter/js/bootstrap.js

@@ -29,16 +29,22 @@ window.addEventListener("DOMContentLoaded", () => {
   const app = new ToolStarterApp({
     accordions,
     actionNav: new ActionNavControl({
-      runButton: requireElement("#runToolButton"),
-      resetButton: requireElement("#resetToolButton"),
-      exportButton: requireElement("#exportToolStateButton")
+      toolCopyJsonButton: requireElement("#toolCopyJsonButton"),
+      toolExportButton: requireElement("#toolExportButton"),
+      toolExportToolStateButton: requireElement("#toolExportToolStateButton"),
+      toolNav: requireElement(".tool-starter__tool__menu"),
+      workspaceCopyManifestButton: requireElement("#workspaceCopyManifestButton"),
+      workspaceExportManifestButton: requireElement("#workspaceExportManifestButton"),
+      workspaceImportManifestButton: requireElement("#workspaceImportManifestButton"),
+      workspaceNav: requireElement(".tool-starter__workspace__menu")
     }),
     inspector: new InspectorControl(requireElement("#inspectorOutput")),
     preview: new PreviewPanelControl(requireElement("#previewOutput")),
     serializer: new ToolStateSerializer("first-class-tool-starter"),
     shell: new ToolStarterShellControl(),
     sourceInput,
-    statusLog
+    statusLog,
+    windowRef: window
   });
 
   app.start();